feat: PAM 0.4.0 — Claude & Kimi agent layers, MCP server

[StefanoGuerrini]

Summary

PAM 0.4.0 ships the optional agent layer end-to-end:

• MCP server (tools/pam-mcp-server.mjs) exposes 15 typed tools over stdio: pam_version, memory_state, memory_list/read/search, graph_query/stats/validate/reindex, memory_audit, memory_propose_edit, memory_append, memory_apply_proposal, maintenance_config/run.
• Subagents: curator (read-mostly hygiene auditor, emits proposals only) and scribe (session-end closeout, append-only via memory_append).
• Claude Code plugin (.claude-plugin/plugin.json + .claude/{agents,commands}/ + hooks/) wires the MCP server, agents, slash commands, and lifecycle hooks into a single installable unit. Slash commands: /pam:dream, /pam:status, /pam:explain, /pam:enable-status-line.
• Statusline + hooks: SessionStart freshness/proposal nag, PostToolUse append counter, statusline showing graph health and session activity.

The markdown + JSONL contract is unchanged; existing 0.3.0 graph-v1 workspaces work without modification.

Notable correctness fixes in this commit

• memory_apply_proposal now uses the validated input proposalId for the archive path (not record.proposalId), closing a hand-crafted-artifact traversal risk. Archive is written before the target so an interrupted apply leaves the proposal recoverable.
• /dream calls graph_reindex (not graph_validate) to actually refresh memory/graph/catalog.json.
• Statusline and session-start hook exclude *.applied.json from the pending-proposal count.
• hooks/post-memory-append.sh rejects session IDs containing /, \\, or .. before using them as a filename.

Test plan

• npm test (66/66 subtests pass)
• npm run mcp:smoke (MCP server starts cleanly)
• Plugin loads in Claude Code; slash commands work
• pr-reviewer self-review: APPROVE
• Reviewer: spot-check the new MCP write surface
• Reviewer: confirm the curator/scribe agent prompts read sensibly

[Yehonal]

Thanks for the PR. I would not approve this yet: the Claude/MCP layer is useful as a standalone base, but there are a few correctness issues that should be fixed before merge.

Findings:

1. Blocking: the Claude plugin appears to use the plugin repository as the PAM workspace.

.claude-plugin/plugin.json starts the MCP server from ${CLAUDE_PLUGIN_ROOT}/tools/pam-mcp-server.mjs, while tools/lib/workspace.mjs defaults the workspace from the script path. When installed as a plugin, this means pam_version, memory_append, /pam:dream, curator/scribe, etc. can operate on the plugin copy instead of the user project. Please pass the actual Claude project directory as --workspace, or change the hosted-server default to resolve to the opened project/current working directory instead of the script location.

2. High: memory_append does not enforce protectedPaths.

tools/lib/memory-append.mjs accepts any config.managedLogs[].source inside the workspace and writes to it without checking config.protectedPaths. This contradicts the MCP docs, which say there is no MCP write path for protected files such as AGENTS.md, CLAUDE.md, and memory/agent-memory/. A wrong or malicious config can route appends into protected paths. Please apply the same protected-path guard before writing append entries.

3. Medium: unified diff application is fragile for multi-hunk patches.

tools/lib/memory-proposals.mjs applies hunks in forward order using the original oldStart values against already-mutated content. If an earlier hunk adds/removes lines, later hunks can fail with a mismatch or target the wrong location. Please apply hunks from bottom to top, or track a cumulative line delta while applying them.

4. Low: /pam:status counts already-applied proposals as pending.

.claude/commands/status.md uses ls memory/maintenance/proposals/*.json, which includes *.applied.json. Other status surfaces exclude applied proposals correctly. Please filter those out, e.g. with find ... -name '*.json' ! -name '*.applied.json'.

Validation I ran locally:

• npm test: 66/66 passed
• npm run memory:graph:validate: ok
• npm run mcp:smoke: ok
• git diff --check origin/main...HEAD: ok

[StefanoGuerrini]

Hi @Yehonal, thanks for the thorough review. All four findings have been addressed in the latest push:

1. Blocking (workspace root): Changed DEFAULT_WORKSPACE_ROOT in tools/lib/workspace.mjs from __dirname-based resolution to process.cwd(). This ensures the MCP server operates on the opened project when launched by the Claude Code plugin, rather than on the plugin installation cache.

2. High (protectedPaths in memory_append): tools/lib/memory-append.mjs now checks config.protectedPaths before writing. A managed log that routes to a protected path (e.g. AGENTS.md, memory/agent-memory/) is rejected with a clear error. Added a test to cover this.

3. Medium (multi-hunk diff fragility): tools/lib/memory-proposals.mjs now sorts hunks by oldStart descending (bottom-to-top) before applying them. This prevents line-drift mismatches when earlier hunks add or remove lines. Added a multi-hunk test with two deletions to verify correctness.

4. Low (status counting applied proposals): Updated the shell snippet in tools/claude/commands/status.md to use find ... ! -name '*.applied.json', so already-applied proposal archives are excluded from the pending count.

Additional refactor: All Claude-specific artifacts have been consolidated under tools/claude/ (agents, commands, hooks, templates, docs, and the statusline installer). The root .claude-plugin/plugin.json now uses explicit commands / agents / hooks paths so Claude Code can discover them from the new location. This keeps the root clean and makes room for future tools/codex/ and tools/kimi/ layers.

Verification:

• npm test: 68/68 passed (66 existing + 2 new)
• npm run memory:graph:validate: ok
• npm run mcp:smoke: ok
• git diff --check: clean

Could you take another look when you have a moment?

[StefanoGuerrini]

Bonus: Added a tools/kimi/ integration layer in the latest push.

Kimi Code CLI has supported MCP since late 2025. The new tools/kimi/install-mcp.mjs registers PAM with Kimi by writing an absolute-path entry into ~/.kimi/mcp.json:

node tools/kimi/install-mcp.mjs --apply
kimi mcp test pam

• Dry-run by default, --apply to write, --uninstall --apply to remove
• Backs up existing ~/.kimi/mcp.json
• Update-safe: git pull updates the server without touching Kimi's config

Docs live in tools/kimi/docs/pam-kimi-layer.md and the MCP server doc now covers Kimi too.

[Yehonal]

Looks good to merge from my side. The symlink containment issue discussed in review appears to be pre-existing rather than introduced by this PR, so I would track it as a separate security follow-up unless this PR expands the production trust boundary.\n\nVerified locally: npm test passes (68/68), and git diff --check is clean.

[Yehonal]

Heads up: we split semantic migration enforcement into PR #8 so it can land before this feature branch.

After #8 merges, this PR should be rebased onto updated main and adjusted as the next semantic migration step:

• keep this feature as PAM 0.4.0
• add/rename the migration guide to start from 0.3.1, e.g. migrations/0.3.1-to-0.4.0-agent-layer.md
• run npm run migrations:check in addition to the existing tests
• keep package.json and memory/pam.version.json aligned at 0.4.0

This preserves the intended ordered upgrade chain for agents migrating older workspaces:
0.3.0 -> 0.3.1 -> 0.4.0 -> 0.4.1 -> 0.5.0.