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

.claude-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "pam",
+  "displayName": "Portable Agent Memory",
+  "version": "0.4.0",
+  "description": "Persistent, portable memory workspace for AI agents: graph + markdown logs, hygiene tooling, and Claude Code integration (MCP server, agents, slash commands, hooks).",
+  "author": {
+    "name": "Stefano Guerrini"
+  },
+  "repository": "https://github.com/NestDevLab/portable-agent-memory",
+  "license": "MIT",
+  "keywords": [
+    "memory",
+    "mcp",
+    "agents",
+    "knowledge-graph",
+    "claude-code"
+  ],
+  "commands": [
+    "tools/claude/commands/dream.md",
+    "tools/claude/commands/enable-status-line.md",
+    "tools/claude/commands/explain.md",
+    "tools/claude/commands/status.md"
+  ],
+  "agents": "tools/claude/agents",
+  "hooks": "tools/claude/hooks/hooks.json",
+  "mcpServers": {
+    "pam": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/tools/pam-mcp-server.mjs"
+      ]
+    }
+  }
+}

.gitignore

@@ -4,4 +4,7 @@ node_modules/
 .env.*
 *.log
 memory/maintenance/nightly-cron.log
+memory/.session/
+memory/maintenance/proposals/
+.claude/settings.local.json
 tmp/

AGENT_BOOTSTRAP.md

@@ -124,6 +124,88 @@ assuming Codex. The command may be Codex, Claude CLI, OpenClaw, Ollama, a local
 script, or any other agent command that can work from a temporary workspace.
 ```
 
+## Optional Agent Layer (Claude Code Plugin)
+
+For Claude Code users, PAM ships as a plugin that bundles the MCP server,
+reference subagents (curator + scribe), slash commands (`/pam:dream`,
+`/pam:pam-status`), and lifecycle hooks. The portable markdown + JSONL contract
+is unchanged, and agents reading `memory/` by hand keep working exactly as
+before.
+
+### Install the PAM plugin (Claude Code)
+
+```text
+Install the Portable Agent Memory plugin in Claude Code.
+
+Steps:
+- run `/plugin install NestDevLab/portable-agent-memory@github`;
+- confirm `/agents` lists `curator` and `scribe` under the `pam` plugin;
+- confirm `/dream` and `/pam:pam-status` are available;
+- run `/dream` from inside a PAM workspace and confirm it returns a report.
+
+Report every step with a colored marker: 🟢 PASS, 🟡 PARTIAL, 🔵 DEFERRED,
+🔴 BLOCKED, or ⚪ N/A.
+```
+
+### Use the curator subagent
+
+```text
+Run the curator to audit this PAM workspace.
+
+Steps:
+- confirm the plugin is installed (see previous prompt);
+- invoke the subagent (`/pam:curator` in Claude Code) and ask it to audit
+  memory;
+- confirm the agent only produces a Findings report and proposal artifacts
+  under memory/maintenance/proposals/, never edits files elsewhere.
+
+The curator never auto-applies edits. Review each proposal before deciding to
+apply it (via the memory_apply_proposal MCP tool).
+
+Report every step with a colored marker: 🟢 PASS, 🟡 PARTIAL, 🔵 DEFERRED,
+🔴 BLOCKED, or ⚪ N/A.
+```
+
+### Use the scribe subagent
+
+```text
+Run the scribe at session end to record durable knowledge.
+
+Steps:
+- confirm the plugin is installed and the curator can run;
+- invoke the subagent (`/pam:scribe` in Claude Code) at session end and ask
+  it to record any durable knowledge from the conversation;
+- confirm the agent only produces a Recorded report and appends dated
+  sections to memory/knowledge-log.md or memory/conversation-log.md, never
+  edits existing entries.
+
+The scribe is append-only and cannot apply curator proposals. Use it for
+recording new facts/decisions; use the curator for hygiene.
+
+Report every step with a colored marker: 🟢 PASS, 🟡 PARTIAL, 🔵 DEFERRED,
+🔴 BLOCKED, or ⚪ N/A.
+```
+
+### Other MCP hosts (Cursor, Codex, OpenClaw, etc.)
+
+The plugin format is Claude Code-specific. For other hosts, add a stdio MCP
+server entry pointing at `tools/pam-mcp-server.mjs`. See
+[docs/mcp-server.md](docs/mcp-server.md) for host-specific snippets.
+
+### Kimi Code CLI
+
+```text
+Install PAM for Kimi Code CLI.
+
+Steps:
+- run `node tools/kimi/install-mcp.mjs --apply` from the PAM workspace root;
+- run `kimi mcp test pam` and confirm the server responds with tool names;
+- start a Kimi session in the same workspace and ask it to read `memory/pam.version.json`.
+
+Report every step with a colored marker: 🟢 PASS, 🟡 PARTIAL, 🔵 DEFERRED,
+🔴 BLOCKED, or ⚪ N/A.
+```
+
 ## Ongoing Session Closeout Prompt
 
 ```text

CHANGELOG.md

@@ -2,6 +2,120 @@
 
 ## Unreleased
 
+## 0.4.0 - 2026-05-28
+
+PAM 0.4.0 ships the optional agent layer end-to-end: a local stdio MCP
+server, the curator and scribe reference subagents, and a Claude Code
+plugin that wires the MCP server, agents, slash commands, and hooks into a
+single installable unit. The markdown + JSONL contract is unchanged;
+existing 0.3.0 graph-v1 workspaces work without modification.
+
+### Added: MCP server
+
+- Local MCP server (`tools/pam-mcp-server.mjs`) that exposes PAM as 15 typed
+  tools over stdio. Hand-rolled JSON-RPC 2.0 transport with zero new runtime
+  dependencies. Includes `--smoke` mode (`npm run mcp:smoke`) for verifying
+  the server starts without configuring a host.
+- Read surface: `pam_version`, `memory_state`, `memory_list`, `memory_read`,
+  `memory_search`, `graph_query`, `graph_stats`, `graph_validate`,
+  `maintenance_config`, `memory_audit`.
+- Hygiene mutation surface: `graph_reindex` (rewrites
+  `memory/graph/catalog.json` from JSONL sources), `maintenance_run`
+  (config-gated).
+- Write surface: `memory_propose_edit` (records JSON proposals under
+  `memory/maintenance/proposals/`, never mutates targets directly);
+  `memory_append` (appends a dated `## YYYY-MM-DD - <title>` section to a
+  managed log declared in `config.managedLogs`, newest-first);
+  `memory_apply_proposal` (re-validates path safety + re-applies the diff,
+  rejects drift, archives successful applies as `<id>.applied.json`).
+- `memory_audit` hygiene checks: duplicate-knowledge-entry, link-rot,
+  graph-source-link-rot, dangling-alias, stale-wiki-page, rotation-candidate,
+  contradiction, oversized-digest, orphan-source.
+
+### Added: Subagents
+
+- `curator`: read-mostly hygiene auditor. Tool whitelist enforces no
+  `Write`, `Edit`, `Bash`, `maintenance_run`, `graph_reindex`,
+  `memory_append`, or `memory_apply_proposal`. Emits proposals; never
+  applies.
+- `scribe`: session-end closeout. Uses `memory_search` to dedup-check, then
+  `memory_append` to record durable knowledge into `knowledge-log` or
+  `conversation-log`. Append-only.
+
+### Added: Claude Code plugin
+
+- `.claude-plugin/plugin.json` declares the plugin (name `pam`, version
+  0.4.0) and inlines the `mcpServers` config; installing the plugin starts
+  the PAM MCP server automatically.
+- `tools/claude/commands/`: `/pam:dream` (hygiene pass: `graph_validate` +
+  `graph_reindex` + `memory_audit`), `/pam:status` (read-only workspace
+  snapshot), `/pam:explain` (inlined shell block that prints the status-line
+  legend with live values; zero LLM reasoning per invocation),
+  `/pam:enable-status-line` (toggle the statusline by renaming the
+  `statusLine` key in `settings.json` to/from `_pamDisabledStatusLine`).
+- `tools/claude/agents/`: `curator` and `scribe`.
+- `tools/claude/hooks/hooks.json` wires `SessionStart` (catalog-freshness check, pending-
+  proposal nag, statusline-style summary) and `PostToolUse` matching
+  `mcp__pam__memory_append` (per-session append counter at
+  `memory/.session/<session_id>.json`).
+- Statusline (`tools/claude/templates/statusline/pam-statusline.sh`)
+  shows `🧠 PAM <version> · <glyph> <N>n/<M>e · 📋 <pending> · 💤 <age> ·
+  ✍️ <appends>`. Pending-proposal count excludes `*.applied.json`.
+- `tools/claude/install-statusline.mjs` (`npm run claude:statusline:install`) for
+  users who want only the statusline without the full plugin.
+
+### Added: Kimi Code CLI integration
+
+- `tools/kimi/install-mcp.mjs` registers the PAM MCP server with Kimi Code
+  CLI by writing an absolute-path entry into `~/.kimi/mcp.json`.
+- `tools/kimi/templates/mcp.fragment.json` is the config template used by
+  the installer.
+- `tools/kimi/docs/pam-kimi-layer.md` covers install, verify, uninstall,
+  and ad-hoc `--mcp-config-file` usage.
+- `npm run kimi:mcp:install` shortcut for the installer.
+- `docs/mcp-server.md` and `AGENT_BOOTSTRAP.md` gain Kimi-specific
+  sections.
+
+### Added: Docs and tests
+
+- `docs/mcp-server.md` (generic MCP docs), `tools/claude/docs/curator-agent.md`,
+  `tools/claude/docs/scribe-agent.md`, `tools/claude/docs/pam-claude-layer.md`.
+- `AGENT_BOOTSTRAP.md` gains an "Optional Agent Layer (PAM 0.4.0+)" section
+  with copy/paste install prompts.
+- Tests: `test-mcp-transport.mjs`, `test-memory-audit.mjs`,
+  `test-memory-proposals.mjs`, `test-memory-append.mjs`,
+  `test-memory-apply-proposal.mjs`, `test-pam-mcp-server.mjs` (66 subtests).
+
+### Compatibility
+
+The markdown + JSONL contract is unchanged; the new layer is additive
+runtime. Existing 0.3.1 graph-v1 workspaces work unchanged, including agents
+that read `memory/` by hand without the MCP server. See
+`migrations/0.3.1-to-0.4.0-agent-layer.md` for the version-bump checklist.
+
+### Privacy
+
+`memory_propose_edit` proposal artifacts and applied-proposal archives
+(`memory/maintenance/proposals/`) may quote memory content. `memory_append`
+quotes whatever the scribe provides as `body`; the scribe's prompt contract
+requires summarizing secrets/PII rather than copying them. Treat all
+proposal artifacts with the same care as existing maintenance run reports.
+
+### Out of scope
+
+- Bootstrap (`pam-bootstrap`) and Query (`pam-query`) subagents.
+- Cursor / Codex / OpenClaw subagent presets (Claude Code only).
+- Remote MCP transport (HTTP/SSE/WebSocket).
+- Vector or semantic search.
+- Direct graph-mutation tools beyond `graph_reindex` (derived) and
+  `maintenance_run` (config-gated).
+- Auto-rotation of `memory/maintenance/proposals/`.
+- Apply-batch (`memory_apply_proposals(ids: [...])`).
+- Auto-invocation hooks for `scribe` (session-end hook). Manual invocation
+  only.
+- `memory_replace` / `memory_delete` for managed logs. Use
+  `memory_propose_edit` + `memory_apply_proposal` instead.
+
 ## 0.3.1 - 2026-05-27
 
 PAM 0.3.1 adds automated semantic migration enforcement. The graph schema