feat: cross-session memory via MCP memory server

[DavidROliverBA]

Summary

Adds cross-session memory to ArcKit using the @anthropic-ai/claude-code-mcp-memory MCP server. This allows Claude to persist and recall project decisions, vendor insights, research findings, and session summaries across sessions.

• Session learner hook (session-learner.mjs): Stop hook that analyses recent git commits, detects ArcKit artifact types (REQ, ADR, HLDR, etc.), classifies the session (governance/research/procurement/review/general), and writes JSON manifests
• Session start enhancement: arckit-session.mjs now reads pending manifests and surfaces them as context, instructing Claude to process via mcp__memory__create_entities
• MCP memory server: Bundled in .mcp.json with auto-allow for mcp__memory__* tools
• Memory search: memory-search.mjs provides unified search across active memory and markdown archive
• Memory prune: memory-prune.mjs prunes ephemeral SessionSummary entities while archiving to markdown
• Documentation: Comprehensive guide covering entity types, design principles, write triggers, size management, and troubleshooting

Architecture

Session N ends
  └── session-learner.mjs analyses git commits
       └── writes .arckit/memory/pending-{session_id}.json

Session N+1 starts
  └── arckit-session.mjs reads pending manifests
       └── surfaces context for Claude to process via MCP

MCP tools are not available inside hooks, hence the two-stage manifest approach.

Entity Types

Type	Purpose
ProjectDecision	ADR outcomes, technology choices
VendorInsight	Vendor evaluation findings
ReviewOutcome	HLD/DLD review results
ResearchFinding	Market observations
RecurringRequirement	Cross-project patterns
LessonLearned	Operational discoveries
SessionSummary	Auto-captured session data (ephemeral)

Files Changed

File	Change
arckit-plugin/.mcp.json	Add memory MCP server
arckit-plugin/hooks/session-learner.mjs	New — Stop hook
arckit-plugin/hooks/arckit-session.mjs	Enhanced — manifest surfacing
arckit-plugin/hooks/allow-mcp-tools.mjs	Add mcp__memory__ prefix
arckit-plugin/hooks/hooks.json	Add Stop hook registration
arckit-plugin/scripts/memory-search.mjs	New — search utility
arckit-plugin/scripts/memory-prune.mjs	New — prune utility
docs/guides/cross-session-memory.md	New — comprehensive guide

Test plan

• Start a session in a project with .arckit/ — verify no errors from session hook
• Make commits and end session — verify pending-*.json created in .arckit/memory/
• Start a new session — verify pending manifests surfaced in context
• Run memory-search.mjs --stats — verify statistics output
• Run memory-prune.mjs --dry-run — verify preview output
• Verify mcp__memory__* tools auto-allowed without permission prompt

🤖 Generated with Claude Code

[tractorjuice]

Review: PR #104 vs Claude Code Built-in Auto Memory

Claude Code now ships with a built-in auto memory system (~/.claude/projects/<project>/memory/) that handles much of what this PR implements. This feature wasn't available when the PR was originally written, so it's worth reassessing the overlap.

---

What auto memory already does natively (zero config, built-in)

Capability	Auto Memory (built-in)	This PR (MCP-based)
Persist decisions across sessions	MEMORY.md + topic files	MCP entities (ProjectDecision, LessonLearned)
Session-start context loading	First 200 lines of MEMORY.md auto-loaded	Pending manifests surfaced via hook
Save triggers	Automatic (Claude decides) + manual ("remember X")	Stop hook (git commits) + inline MCP calls
Storage	~/.claude/projects/<project>/memory/	.arckit/memory.jsonl
Search	Claude reads topic files on demand	memory-search.mjs + mcp__memory__search_nodes

What this PR adds beyond auto memory

Feature	Auto Memory	This PR
Structured entity types (ProjectDecision, VendorInsight, ReviewOutcome, etc.)	Freeform markdown	Typed entities with named observations
Git-commit-based session capture	Claude decides what to save	Stop hook auto-analyses commits and artifact types
Session classification (governance/research/procurement/review)	None	Auto-classified by artifact type
Team sharing (memory in repo)	Machine-local only (~/.claude/)	.arckit/memory.jsonl can be committed to git
Prune/archive lifecycle	Manual file editing	memory-prune.mjs with archival to archive.md
Relational graph (entities + relations)	None	MCP knowledge graph with search_nodes

Concerns

1. Significant overlap — The core use case (remember decisions, surface them next session) is now handled by auto memory out of the box.

2. Extra MCP server dependency — Adds @anthropic-ai/claude-code-mcp-memory via npx to every plugin user. That's an extra process spawned on every session start, even if unused.

3. Competing memory systems — Users would have auto memory AND MCP memory running simultaneously with no coordination. Claude might save the same insight to both, or search one and miss the other.

4. The unique value is narrow — The genuinely additive features are: structured entity types, git-based session capture, session classification, and team-shareable storage. But auto memory's topic files (e.g., decisions.md, vendor-insights.md) can achieve similar organization without a separate MCP server.

Recommendation

Two options to consider:

Option A — Adapt to auto memory: Strip down to just the session-learner.mjs Stop hook, but have it write summaries to auto memory topic files (~/.claude/projects/<project>/memory/) instead of MCP entities. This leverages the native system rather than adding a parallel one. Drop the MCP server dependency, memory-search.mjs, and memory-prune.mjs.

Option B — Close and document: Close the PR and instead document how to use Claude Code's built-in auto memory with ArcKit-specific topic file conventions (e.g., decisions.md, vendor-insights.md, session-log.md). This gives users structured memory with zero additional dependencies.

Either way, the session-learner hook concept (auto-capturing what happened via git analysis) is genuinely useful — it's the MCP server layer on top that's now redundant.