feat: add cross-session memory via MCP memory server

[DavidROliverBA]

Summary

• Adds @modelcontextprotocol/server-memory as bundled stdio MCP server with project-local .arckit/memory.jsonl storage
• New session-learner.sh Stop hook analyses commits, detects artifact types, classifies sessions, writes JSON manifests
• Enhanced arckit-session.sh reads pending manifests and surfaces them as context with MCP tool instructions
• Auto-allows mcp__memory__* tools via updated allow-mcp-tools.sh
• Defines 7 entity types: ProjectDecision, VendorInsight, ReviewOutcome, ResearchFinding, RecurringRequirement, LessonLearned, SessionSummary

Motivation

ArcKit sessions have no memory between sessions. Knowledge discovered in one session is lost. This adds a two-stage memory system: hooks write manifests to disk, session-start surfaces them for Claude to process via MCP memory tools.

Test plan

• Verify .mcp.json valid with stdio-type memory server
• Verify session-learner.sh exits cleanly with no recent commits
• Verify session-learner.sh writes valid JSON manifest
• Verify arckit-session.sh surfaces pending manifests
• End-to-end: create artifacts → stop → manifest → new session → context surfaced

🤖 Generated with Claude Code

[tractorjuice]

PR #58 Review: Cross-Session Memory via MCP Memory Server

+537 / -6 across 7 files

---

Summary

Adds a two-stage cross-session memory system:

1. Stop hook (session-learner.sh) analyses recent git commits when a session ends, writes a JSON manifest
2. SessionStart hook (extended arckit-session.sh) surfaces pending manifests as context, instructing Claude to store them via @modelcontextprotocol/server-memory MCP

Well-conceived feature with solid documentation. However, there are several critical issues that need addressing before merge.

---

Critical Issues

1. Stale base branch — will regress security hooks

The PR was branched before the security hooks were added to main. The diff for hooks.json is based on an older version that's missing:

• secret-detection.py (UserPromptSubmit)
• file-protection.py (PreToolUse)
• secret-file-scanner.py (PreToolUse)

Current main description:

"ArcKit hooks: session init, project context injection, filename enforcement, MCP tool auto-allow, and security protection (file protection, secret detection, secret file scanning)"

PR base description:

"ArcKit hooks: session init, project context injection, filename enforcement, and MCP tool auto-allow"

Merging as-is would silently remove all security hooks. The branch needs to be rebased onto current main.

2. allow-mcp-tools.sh is also stale

The PR base is missing the mcp__plugin_microsoft-docs_microsoft-learn__* pattern that exists on current main. Another merge conflict / regression risk.

3. Missing plugin guide copy

Guide is created at docs/guides/cross-session-memory.md but not at arckit-plugin/docs/guides/cross-session-memory.md. Per repo conventions, guides should exist in both locations (even for plugin-only features, since the plugin serves its own guides).

---

Design Concerns

4. Auto-allowing write MCP tools is a security model change

The existing allow-mcp-tools.sh explicitly documents it auto-allows read-only documentation tools. This PR adds mcp__memory__* which includes write operations (create_entities, delete_entities, delete_observations). The PR updates the comment correctly but this is a meaningful policy change — Claude can now silently modify persistent state. Worth an explicit acknowledgment in the PR description.

5. Manifest cleanup relies on Claude compliance

The session-start hook tells Claude: "After processing, delete the pending manifest files." If Claude doesn't comply (context window pressure, user interrupts, etc.), manifests accumulate and re-surface every session. Consider adding a fallback — e.g., the session-learner could clean up manifests older than 7 days, or the session-start hook could archive processed files with a timestamp rename.

6. Node.js runtime dependency

All existing MCP servers are HTTP-based (zero local dependencies). The memory server requires Node.js 18+ and npx. This should be documented as a prerequisite in the plugin README or checked at session start with a graceful fallback if Node.js is absent.

---

Minor Issues

7. Hardcoded 2-hour window (session-learner.sh:46)

SINCE="2 hours ago"

If a session runs longer than 2 hours, later commits are captured but earlier ones are missed. Consider using the session start timestamp (if available in hook input) or a broader window.

8. No automated entity pruning

The guide correctly warns about the ~50 entity cap, but there's no automated cleanup. SessionSummary entities will accumulate indefinitely. A simple age-based pruning in the session-learner (delete manifests referencing sessions > 30 days old) would help.

9. hooks.json — Notification event format

"Notification": [
  {
    "matcher": "stop",
    ...
  }
]

This is a newer hook event type not currently used by the plugin. Confirm this is the correct event/matcher format for session-end notifications.

---

Code Quality — Positive Notes

• session-learner.sh is well-crafted: proper set -euo pipefail, shopt -s nullglob, jq-based JSON construction, bash 3.2-compatible associative array workaround
• Doc type mapping is comprehensive (covers all 40+ ArcKit document types)
• Session classification logic is sensible and matches the existing artifact taxonomy
• Guide (cross-session-memory.md) is excellent — thorough coverage of entity types, design principles, troubleshooting, and manual operations
• CHANGELOG uses proper [Unreleased] section per Keep a Changelog

---

Verdict

Needs work before merge. The stale base branch is the blocker — it would regress security hooks. After rebasing onto current main and addressing the missing plugin guide copy, the remaining items are improvements that could be follow-ups.

Required before merge:

1. Rebase onto current main (resolves hooks.json + allow-mcp-tools.sh conflicts)
2. Add arckit-plugin/docs/guides/cross-session-memory.md

Recommended (can be follow-up):
3. Add manifest age-based cleanup fallback
4. Check for Node.js availability at session start
5. Update MEMORY.md hook event count

---

🤖 Generated with Claude Code

[tractorjuice]

Closing — superseded by #104, which is a v2 rewrite using .mjs hooks instead of .sh. All functionality from this PR is covered in the updated version.