#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
Detailed, self-updating skills covering the whole system (#854)
Rohit Ghumare45de643cd208
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex b9671280..ed53c6da 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -66,4 +66,5 @@ jobs:- run: npm install --package-lock-only --legacy-peer-deps --no-audit --no-fund- run: npm ci --legacy-peer-deps --no-audit --no-fund- run: npm run build+ - run: npm run skills:check- run: npm testdiff --git a/README.md b/README.mdindex c5acc359..7b4e989d 100644--- a/README.md+++ b/README.md@@ -101,7 +101,7 @@ agentmemory # start the memory server on :3agentmemory demo # seed sample sessions + prove recallagentmemory demo --serve # one command: boot server, run demo, tear down (no second terminal)agentmemory connect claude-code # wire MCP into your agent (also: copilot-cli, codex, cursor, gemini-cli, ...)-npx skills add rohitg00/agentmemory -y # install 8 native skills so your agent knows when to use the tools+npx skills add rohitg00/agentmemory -y # install 15 native skills (8 you can invoke, 7 reference) so your agent knows when to use the tools```Or via `npx` (no install):@@ -451,7 +451,7 @@ Implementation details live in `src/cli.ts` (see `runUpgrade` around the `src/cl### Claude Code (one block, paste it)```text-Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 8 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.+Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 15 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 53 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.```#### Claude Code without the plugin install (MCP-standalone path)@@ -482,7 +482,7 @@ The Codex plugin ships from the same `plugin/` directory as the Claude Code plug- `@agentmemory/mcp` as an MCP server (proxies all 53 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable)- 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`-- 8 skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/commit-context`, `/commit-history`+- 8 invocable skills: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/commit-context`, `/commit-history`, plus 7 reference skills the agent loads on demand (MCP tools, REST API, config, agents, hooks, architecture, and the skill-authoring guide)Codex's hook engine injects `CLAUDE_PLUGIN_ROOT` into hook subprocesses (per [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), so the same hook scripts work across both hosts without duplication. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events are Claude-Code-only and are not registered for Codex.@@ -562,7 +562,7 @@ Start the memory server: `npx @agentmemory/agentmemory`#### Native skills via `npx skills add` (50+ agents)-agentmemory ships 8 skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) in the Claude-Code-style `<dir>/SKILL.md` format. The [`skills`](https://npmjs.com/package/skills) CLI by vercel-labs auto-installs them into the calling agent's native skill directory across 50+ agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, and more):+agentmemory ships 15 skills in the Claude-Code-style `<dir>/SKILL.md` format: 8 invocable action skills (`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`) and 7 reference skills the agent loads on demand (`agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`). The reference skills carry data tables generated from source, so they never drift. The [`skills`](https://npmjs.com/package/skills) CLI by vercel-labs auto-installs them into the calling agent's native skill directory across 50+ agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, and more):```bashnpx skills add rohitg00/agentmemory -y # auto-detects the calling agent@@ -575,7 +575,7 @@ This is **complementary** to `agentmemory connect <agent>`:- `agentmemory connect <agent>` writes the MCP server config so the tools are available.- `npx skills add rohitg00/agentmemory` installs the skills so the agent knows when to call them.-For the few agents the skills CLI doesn't cover yet (Zed v1.3.x and below), drop the 8 SKILL.md files under the agent's native skill directory yourself — same format works everywhere.+For the few agents the skills CLI doesn't cover yet (Zed v1.3.x and below), drop the 15 SKILL.md files under the agent's native skill directory yourself — same format works everywhere.#### Standard MCP block@@ -605,7 +605,7 @@ The agentmemory entry is the **same MCP server block** across every host that us| **GitHub Copilot CLI (full plugin)** | Copilot plugin install | `copilot plugin install rohitg00/agentmemory:plugin` for the plugin from the GitHub subdir. || **OpenClaw** | OpenClaw MCP config | Same `mcpServers` block, or use the deeper [memory plugin](integrations/openclaw/). || **Codex CLI (MCP only)** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, or add `[mcp_servers.agentmemory]` manually. |-| **Codex CLI (full plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` then `codex plugin add agentmemory@agentmemory`. Registers MCP + 6 lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 8 skills. On Codex Desktop, also run `agentmemory connect codex --with-hooks` until [openai/codex#16430](https://github.com/openai/codex/issues/16430) lands — plugin hooks are currently silent there. |+| **Codex CLI (full plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` then `codex plugin add agentmemory@agentmemory`. Registers MCP + 6 lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 15 skills. On Codex Desktop, also run `agentmemory connect codex --with-hooks` until [openai/codex#16430](https://github.com/openai/codex/issues/16430) lands — plugin hooks are currently silent there. || **OpenCode (MCP only)** | `opencode.json` | Different shape — top-level `mcp` key, command as array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. || **OpenCode (full plugin)** | `plugin/opencode/` | 22 auto-capture hooks covering session lifecycle, messages, tools, errors. Two slash commands (`/recall`, `/remember`). Copy `plugin/opencode/` into your OpenCode workspace and add the plugin entry to `opencode.json`. See [`plugin/opencode/README.md`](plugin/opencode/README.md) for the full hook table + gap analysis. || **pi** | `~/.pi/agent/extensions/agentmemory` | Copy [`integrations/pi`](integrations/pi/) and restart pi. |@@ -896,7 +896,7 @@ npm install @xenova/transformers<h2 id="mcp-server"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-mcp.svg"><img src="assets/tags/section-mcp.svg" alt="MCP Server" height="32" /></picture></h2>-53 tools, 6 resources, 3 prompts, and 8 skills — the most comprehensive MCP memory toolkit for any agent.+53 tools, 6 resources, 3 prompts, and 15 skills, the most comprehensive MCP memory toolkit for any agent.> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the full 53-tool surface **only when it can reach a running agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). The `AGENTMEMORY_TOOLS=core|all` env var is a *server-side* flag — setting it in the shim's `env` block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`.diff --git a/package.json b/package.jsonindex 3a4fb950..3c7cb537 100644--- a/package.json+++ b/package.json@@ -25,6 +25,8 @@"test:watch": "vitest --exclude test/integration.test.ts","test:integration": "vitest run test/integration.test.ts","test:all": "vitest run",+ "skills:gen": "tsx scripts/skills/generate.ts",+ "skills:check": "tsx scripts/skills/generate.ts --check && tsx scripts/skills/check.ts","bench:load": "node --import tsx benchmark/load-100k.ts","eval:longmemeval": "tsx eval/runner/longmemeval.ts","eval:coding-life": "tsx eval/runner/coding-life.ts"diff --git a/plugin/plugin.json b/plugin/plugin.jsonindex 5cb13fe8..9d0751a7 100644--- a/plugin/plugin.json+++ b/plugin/plugin.json@@ -1,7 +1,7 @@{"name": "agentmemory","version": "0.9.27",- "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 53 MCP tools, 8 skills, real-time viewer.",+ "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 53 MCP tools, 15 skills, real-time viewer.","author": {"name": "Rohit Ghumare","url": "https://github.com/rohitg00"diff --git a/plugin/skills/_shared/TROUBLESHOOTING.md b/plugin/skills/_shared/TROUBLESHOOTING.mdnew file mode 100644index 00000000..ee082d0c--- /dev/null+++ b/plugin/skills/_shared/TROUBLESHOOTING.md@@ -0,0 +1,38 @@+# Troubleshooting agentmemory skills++Shared recovery steps for all user-invocable agentmemory skills. Each skill's+Troubleshooting section points here instead of duplicating the block.++## "MCP tool not available"++If a `memory_*` MCP tool does not appear, the stdio MCP shim never started.+Walk these in order:++1. Run `/plugin list` in the host and confirm `agentmemory` shows as enabled.+2. Restart the host. The plugin's `.mcp.json` is only read on startup, so a+ freshly installed or re-enabled plugin will not register tools mid-session.+3. Check `/mcp` and confirm the `agentmemory` server shows a live connection.++## REST fallback++When the MCP tools stay unavailable but the daemon is running, call the REST+API directly:++1. Set `AGENTMEMORY_URL` to the daemon base URL (default `http://localhost:3111`).+2. Add `Authorization: Bearer $AGENTMEMORY_SECRET` ONLY when `AGENTMEMORY_SECRET`+ is set. The default localhost daemon is open and rejects a stray header.++Endpoint map by skill:++| Skill | REST call |+| --------------- | --------------------------------------------------------------- |+| remember | `POST /agentmemory/remember` |+| recall | `POST /agentmemory/smart-search` |+| recap | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search` |+| handoff | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search` |+| session-history | `GET /agentmemory/sessions` |+| commit-context | `GET /agentmemory/session/by-commit?sha=<sha>` |+| commit-history | `GET /agentmemory/commits` (URL-encode every query param) |++The daemon reads `.mcp.json` on startup only, so any port or auth change needs a+restart before either transport sees it.diff --git a/plugin/skills/agentmemory-agents/REFERENCE.md b/plugin/skills/agentmemory-agents/REFERENCE.mdnew file mode 100644index 00000000..7be76713--- /dev/null+++ b/plugin/skills/agentmemory-agents/REFERENCE.md@@ -0,0 +1,27 @@+# agentmemory connect adapters reference++Generated from `src/cli/connect/index.ts`. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing an adapter.++<!-- AUTOGEN:agents START - generated by scripts/skills/generate.ts, do not edit by hand -->+`agentmemory connect <agent>` wires the memory server into a host agent. 17 adapters:++| Agent | Name | Protocol |+| --- | --- | --- |+| Antigravity | `antigravity` | Using MCP via mcp_config.json. Antigravity replaces Gemini CLI (sunset 2026-06-18). |+| Claude Code | `claude-code` | Using MCP. Hooks are also available, see docs/claude-code.md. |+| Cline | `cline` | Using MCP via ~/.cline/mcp.json (CLI). VS Code users: add the same block via Cline Settings → MCP Servers → Edit JSON. |+| Codex CLI | `codex` | Using MCP. Hooks ship via the Codex plugin; on Codex Desktop, also pass --with-hooks to install the global hooks.json workaround for openai/codex#16430. |+| Continue | `continue` | Using MCP via ~/.continue/config.yaml (preferred) or config.json (legacy, only when no yaml). |+| GitHub Copilot CLI | `copilot-cli` | Using MCP. Install the plugin too for full hooks/skills coverage. |+| Cursor | `cursor` | Using MCP (the only protocol Cursor speaks). Memory bridge runs at :3111 underneath. |+| Droid (Factory.ai) | `droid` | Using MCP via ~/.factory/mcp.json. The `/mcp` slash command inside droid lists configured servers. |+| Gemini CLI | `gemini-cli` | Using MCP (the only protocol Gemini CLI speaks). Memory bridge runs at :3111 underneath. |+| Hermes Agent | `hermes` | Using MCP. Hooks are also available, see docs/hermes.md. |+| Kiro | `kiro` | Using MCP via ~/.kiro/settings/mcp.json (user-level). Workspace overrides live in .kiro/settings/mcp.json. |+| OpenClaw | `openclaw` | Using MCP. Hooks are also available, see docs/openclaw.md. |+| OpenHuman | `openhuman` | Using native hooks (REST API at :3111). MCP not required. |+| pi | `pi` | Using native hooks (REST API at :3111). MCP not required. |+| Qwen Code | `qwen` | Using MCP via ~/.qwen/settings.json. Qwen Code's hook system can also be wired separately, see docs. |+| Warp | `warp` | Using MCP via ~/.warp/.mcp.json. Skills auto-discover from .claude/skills/ if the Claude Code plugin is also installed. |+| Zed | `zed` | Using MCP via ~/.config/zed/settings.json (key: context_servers). |+<!-- AUTOGEN:agents END -->diff --git a/plugin/skills/agentmemory-agents/SKILL.md b/plugin/skills/agentmemory-agents/SKILL.mdnew file mode 100644index 00000000..e4cda491--- /dev/null+++ b/plugin/skills/agentmemory-agents/SKILL.md@@ -0,0 +1,34 @@+---+name: agentmemory-agents+description: How agentmemory wires into host coding agents via the connect command. Use when installing agentmemory into a specific agent, when asked which agents are supported, or when a connect adapter writes the wrong config path.+user-invocable: false+---++`agentmemory connect <agent>` merges the memory server into a host agent's config and preserves any existing servers. REST is the underlying protocol; for MCP-only hosts the adapter wires the stdio MCP bridge.++## Quick start++```bash+agentmemory connect claude-code # or cursor, codex, gemini-cli, ...+```++After wiring, restart the host or run its MCP reload (for example `/mcp` in Claude Code) so it picks up the server. Then confirm the agent lists agentmemory's tools.++## Workflow++1. Detect the calling agent. If unknown, default to `claude-code`.+2. Run `agentmemory connect <name>` using a name from the table in REFERENCE.md.+3. Verify: the host should show the full tool set with a server running. Only 7 tools means the MCP shim could not reach a server (see ../_shared/TROUBLESHOOTING.md).++## Notes++- The action skills (remember, recall, and the rest) are installed separately with `npx skills add rohitg00/agentmemory`. `connect` makes tools available; skills teach the agent when to use them.+- Windows: use WSL2. Native Windows runs the server but `connect` is not supported there.++## See also++- agentmemory-mcp-tools, agentmemory-rest-api, agentmemory-hooks.++## Reference++The full adapter list with display names and protocol notes lives in REFERENCE.md, generated from `src/cli/connect/`.diff --git a/plugin/skills/agentmemory-architecture/SKILL.md b/plugin/skills/agentmemory-architecture/SKILL.mdnew file mode 100644index 00000000..431c2603--- /dev/null+++ b/plugin/skills/agentmemory-architecture/SKILL.md@@ -0,0 +1,33 @@+---+name: agentmemory-architecture+description: How agentmemory is built, the iii engine primitives it runs on, its storage model, ports, and the viewer. Use when reasoning about how memory is stored or retrieved end to end, when extending the system, or when answering how agentmemory works under the hood.+user-invocable: false+---++agentmemory is a memory server for coding agents. It runs locally, captures observations, indexes them for hybrid retrieval, and serves them back over REST and MCP. It is built on the iii engine.++## iii primitives++Everything is a function, a trigger, or worker state on the iii engine. There is no separate plugin system; the worker registers functions (`mem::*`) and HTTP triggers (`api::*`) and the engine routes calls. agentmemory does not bypass iii; new capability is a new function plus a trigger.++## Retrieval model++Recall is hybrid: BM25 keyword search plus vector similarity plus graph expansion over linked concepts. The default install needs no API key because embeddings run on-device and BM25 needs none. An LLM provider only adds richer summaries and auto-injection, both opt-in.++## Storage and lifecycle++Memories carry content, concepts, files, importance, and timestamps, grouped into sessions and optionally linked to commits. A lifecycle of capture, compress, consolidate, and forget keeps the store useful over time rather than letting it grow unbounded.++## Ports++REST is the anchor at 3111. Streams = N+1 (3112), viewer = N+2 (3113), engine = N+46023 (49134). `--instance N` shifts the whole block by N*100.++## Viewer++A real-time web viewer at `http://localhost:3113` shows memory building as sessions run. Useful for demos and for confirming capture is working.++## See also++- agentmemory-mcp-tools and agentmemory-rest-api for the surfaces.+- agentmemory-hooks for automatic capture.+- agentmemory-config for ports and feature flags.diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.mdnew file mode 100644index 00000000..08c873a4--- /dev/null+++ b/plugin/skills/agentmemory-config/REFERENCE.md@@ -0,0 +1,42 @@+# agentmemory configuration reference++Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded.++<!-- AUTOGEN:env START - generated by scripts/skills/generate.ts, do not edit by hand -->+Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 34 recognized variables:++- `AGENTMEMORY_AGENT_SCOPE`+- `AGENTMEMORY_ALLOW_AGENT_SDK`+- `AGENTMEMORY_AUTO_COMPRESS`+- `AGENTMEMORY_COMMIT_SHA`+- `AGENTMEMORY_COPILOT_MCP_BLOCK`+- `AGENTMEMORY_CWD`+- `AGENTMEMORY_DEBUG`+- `AGENTMEMORY_DROP_STALE_INDEX`+- `AGENTMEMORY_EXPORT_ROOT`+- `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS`+- `AGENTMEMORY_FORCE_PROXY`+- `AGENTMEMORY_GRAPH_WEIGHT`+- `AGENTMEMORY_III_CONFIG`+- `AGENTMEMORY_III_VERSION`+- `AGENTMEMORY_IMAGE_EMBEDDINGS`+- `AGENTMEMORY_IMAGE_STORE_MAX_BYTES`+- `AGENTMEMORY_INJECT_CONTEXT`+- `AGENTMEMORY_LLM_TIMEOUT_MS`+- `AGENTMEMORY_MCP_BLOCK`+- `AGENTMEMORY_PROBE_TIMEOUT_MS`+- `AGENTMEMORY_PROJECT_NAME`+- `AGENTMEMORY_PROVIDER`+- `AGENTMEMORY_REFLECT`+- `AGENTMEMORY_SDK_CHILD`+- `AGENTMEMORY_SECRET`+- `AGENTMEMORY_SESSION_ID`+- `AGENTMEMORY_SLOTS`+- `AGENTMEMORY_SUPPRESS_COST_WARNING`+- `AGENTMEMORY_TOOLS`+- `AGENTMEMORY_URL`+- `AGENTMEMORY_USE_DOCKER`+- `AGENTMEMORY_VERBOSE`+- `AGENTMEMORY_VIEWER_HOST`+- `AGENTMEMORY_VIEWER_URL`+<!-- AUTOGEN:env END -->diff --git a/plugin/skills/agentmemory-config/SKILL.md b/plugin/skills/agentmemory-config/SKILL.mdnew file mode 100644index 00000000..aea78c9b--- /dev/null+++ b/plugin/skills/agentmemory-config/SKILL.md@@ -0,0 +1,37 @@+---+name: agentmemory-config+description: agentmemory configuration, environment variables, ports, and feature flags. Use when enabling a feature, changing ports, setting an API key, configuring auth, or explaining why a feature is off by default.+user-invocable: false+---++agentmemory reads configuration from the environment and from `~/.agentmemory/.env` (one `KEY=value` per line, no `export` prefix). Restart the server after changing it.++## Quick start++Enable richer memory and set a provider key in `~/.agentmemory/.env`:++```env+ANTHROPIC_API_KEY=sk-ant-...+AGENTMEMORY_AUTO_COMPRESS=true+AGENTMEMORY_INJECT_CONTEXT=true+```++## Defaults worth knowing++- No API key is required. Without one, agentmemory runs zero-LLM with BM25 plus local embeddings.+- Token-spending features ship OFF on purpose: `AGENTMEMORY_AUTO_COMPRESS` (LLM summaries) and `AGENTMEMORY_INJECT_CONTEXT` (auto context injection) both cost tokens proportional to tool-use frequency.+- Tool visibility: `AGENTMEMORY_TOOLS=all` (default) or `core` for the lean set.+- Auth: set `AGENTMEMORY_SECRET` to require `Authorization: Bearer` on the REST API.++## Ports++REST is the anchor at 3111. Streams = N+1 (3112), viewer = N+2 (3113), engine = N+46023 (49134). Relocate the whole block with `--port <N>` or `--instance <N>`.++## See also++- agentmemory-rest-api for how the secret is used.+- agentmemory-architecture for the port quartet rationale.++## Reference++The full recognized-variable list lives in REFERENCE.md, generated by scanning `src/`.diff --git a/plugin/skills/agentmemory-hooks/REFERENCE.md b/plugin/skills/agentmemory-hooks/REFERENCE.mdnew file mode 100644index 00000000..2cf2dcec--- /dev/null+++ b/plugin/skills/agentmemory-hooks/REFERENCE.md@@ -0,0 +1,20 @@+# agentmemory hooks reference++Generated from `plugin/hooks/hooks.json`. Do not edit the block below by hand; run `npm run skills:gen` after changing the hook registration.++<!-- AUTOGEN:hooks START - generated by scripts/skills/generate.ts, do not edit by hand -->+The Claude Code plugin registers hooks on 12 lifecycle events to capture observations automatically:++- `Notification`+- `PostToolUse`+- `PostToolUseFailure`+- `PreCompact`+- `PreToolUse`+- `SessionEnd`+- `SessionStart`+- `Stop`+- `SubagentStart`+- `SubagentStop`+- `TaskCompleted`+- `UserPromptSubmit`+<!-- AUTOGEN:hooks END -->diff --git a/plugin/skills/agentmemory-hooks/SKILL.md b/plugin/skills/agentmemory-hooks/SKILL.mdnew file mode 100644index 00000000..b8127f3f--- /dev/null+++ b/plugin/skills/agentmemory-hooks/SKILL.md@@ -0,0 +1,39 @@+---+name: agentmemory-hooks+description: The agentmemory plugin hooks that capture observations automatically across the agent session lifecycle. Use when explaining how memory gets captured without manual saves, when debugging missing observations, or when tuning what gets recorded.+user-invocable: false+---++The Claude Code plugin registers lifecycle hooks so memory is captured automatically. You do not have to call `memory_save` for routine work; the hooks observe tool use, prompts, and session boundaries and write observations for you.++## Quick start++Install the plugin and the hooks register themselves:++```bash+/plugin marketplace add rohitg00/agentmemory+/plugin install agentmemory+```++Watch observations land live at `http://localhost:3113`.++## What the hooks do++- Session start and end frame each unit of work and let `handoff` resume it.+- Tool-use hooks capture what changed and why, the raw material for `recall` and `recap`.+- Prompt-submit captures intent. Pre-compact preserves context before the host trims it.+- A post-commit hook links commits to sessions, which powers `commit-context` and `commit-history`.++## Important++- Capture is on by default and is zero-LLM. Turning observations into LLM summaries (`AGENTMEMORY_AUTO_COMPRESS`) and injecting them back into context (`AGENTMEMORY_INJECT_CONTEXT`) are separate opt-ins because they spend tokens.+- If observations are missing, confirm the plugin is enabled and the server is running. See ../_shared/TROUBLESHOOTING.md.++## See also++- agentmemory-config for the capture and injection flags.+- The handoff, recap, and session-history skills consume what these hooks record.++## Reference++The exact registered hook events live in REFERENCE.md, generated from `plugin/hooks/hooks.json`.diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.mdnew file mode 100644index 00000000..0c556fc7--- /dev/null+++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md@@ -0,0 +1,65 @@+# agentmemory MCP tools reference++Generated from `src/mcp/tools-registry.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registry.++<!-- AUTOGEN:tools START - generated by scripts/skills/generate.ts, do not edit by hand -->+agentmemory exposes 53 MCP tools. 8 are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default).++| Tool | Core | Parameters | Purpose |+| --- | --- | --- | --- |+| `memory_action_create` | | `title`*: string, `description`: string, `priority`: number, `project`: string, `tags`: string, `parentId`: string, `requires`: string | Create an actionable work item with typed dependencies. Actions track what agents need to do and how work items relate to each other. |+| `memory_action_update` | | `actionId`*: string, `status`: string, `result`: string, `priority`: number | Update an action's status, priority, or details. Set status to 'done' to complete it and unblock dependent actions. |+| `memory_audit` | | `operation`: string, `limit`: number | View the audit trail of memory operations. |+| `memory_checkpoint` | | `operation`*: string, `name`: string, `checkpointId`: string, `status`: string, `type`: string, `linkedActionIds`: string | Create or resolve an external checkpoint (CI result, approval, deploy status) that gates action progress. |+| `memory_claude_bridge_sync` | | `direction`*: string | Sync memory state to/from Claude Code's native MEMORY.md file. |+| `memory_commit_lookup` | | `sha`*: string | Look up the agent session(s) that produced a specific git commit, given its SHA. Returns the commit metadata and linked sessions. |+| `memory_commits` | | `branch`: string, `repo`: string, `limit`: number | List recent commits linked to agent sessions, optionally filtered by branch or repo. |+| `memory_compress_file` | | `filePath`*: string | Compress a markdown file to reduce token usage while preserving headings, URLs, and code blocks. Creates a .original.md backup before writing. |+| `memory_consolidate` | yes | `tier`: string | Run the 4-tier memory consolidation pipeline (working -> episodic -> semantic -> procedural). |+| `memory_crystallize` | | `actionIds`*: string, `project`: string, `sessionId`: string | Compress completed action chains into compact crystal digests using LLM summarization. Extracts narrative, key outcomes, files affected, and lessons. |+| `memory_diagnose` | yes | `categories`: string | Run health checks across all subsystems (actions, leases, sentinels, sketches, signals, sessions, memories, mesh). Identifies stuck, orphaned, and inconsistent state. |+| `memory_export` | | none | Export all memory data as JSON. |+| `memory_facet_query` | | `matchAll`: string, `matchAny`: string, `targetType`: string | Query targets by facet tags with AND/OR logic. Find all actions tagged priority:urgent AND team:backend. |+| `memory_facet_tag` | | `targetId`*: string, `targetType`*: string, `dimension`*: string, `value`*: string | Attach a structured tag (dimension:value) to an action, memory, or observation for multi-dimensional categorization. |+| `memory_file_history` | | `files`*: string, `sessionId`: string | Get past observations about specific files. |+| `memory_frontier` | | `project`: string, `agentId`: string, `limit`: number | Get all unblocked actions ranked by priority and urgency. Returns the frontier of actionable work with no unsatisfied dependencies. |+| `memory_governance_delete` | | `memoryIds`*: string, `reason`: string | Delete specific memories with audit trail. |+| `memory_graph_query` | | `startNodeId`: string, `nodeType`: string, `maxDepth`: number, `query`: string | Query the knowledge graph for entities and relationships. |+| `memory_heal` | | `categories`: string, `dryRun`: string | Auto-fix all fixable issues found by diagnostics. Unblocks stuck actions, expires stale leases, cleans up orphaned data. |+| `memory_insight_list` | | `project`: string, `minConfidence`: number, `limit`: number | List synthesized insights, higher-order observations derived from patterns across memories, lessons, and crystals. |+| `memory_lease` | | `actionId`*: string, `agentId`*: string, `operation`*: string, `result`: string, `ttlMs`: number | Acquire, release, or renew an exclusive lease on an action. Prevents multiple agents from working on the same thing. |+| `memory_lesson_recall` | | `query`*: string, `project`: string, `minConfidence`: number, `limit`: number | Search lessons by query. Returns lessons sorted by confidence and recency. Use to check what the agent has learned before making decisions. |+| `memory_lesson_save` | yes | `content`*: string, `context`: string, `confidence`: number, `project`: string, `tags`: string | Save a lesson learned from this session. Lessons have confidence scores that strengthen when reinforced and decay when not used. Duplicate content auto-strengthens the existing lesson. |+| `memory_mesh_sync` | | `peerId`: string, `direction`: string | Sync memories and actions with peer agentmemory instances for multi-agent collaboration. |+| `memory_next` | | `project`: string, `agentId`: string | Get the single most important next action to work on. Combines dependency resolution, priority, and recency into a score. |+| `memory_obsidian_export` | | `vaultDir`: string, `types`: string | Export memories, lessons, and crystals as Obsidian-compatible Markdown files with YAML frontmatter and wikilinks for graph view. |+| `memory_patterns` | | `project`: string | Detect recurring patterns across sessions. |+| `memory_profile` | | `project`*: string, `refresh`: string | User/project profile with top concepts and file patterns. |+| `memory_recall` | yes | `query`*: string, `limit`: number, `format`: string, `token_budget`: number | Search past session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before. |+| `memory_reflect` | yes | `project`: string, `maxClusters`: number | Traverse the knowledge graph, group related memories by concept clusters, and synthesize higher-order insights via LLM. Returns new and reinforced insights. |+| `memory_relations` | | `memoryId`*: string, `maxHops`: number, `minConfidence`: number | Query the memory relationship graph. |+| `memory_routine_run` | | `routineId`*: string, `project`: string, `initiatedBy`: string | Instantiate a frozen workflow routine, creating actions for each step with proper dependencies. |+| `memory_save` | yes | `content`*: string, `type`: string, `concepts`: string, `files`: string, `project`: string | Explicitly save an important insight, decision, or pattern to long-term memory. |+| `memory_sentinel_create` | | `name`*: string, `type`*: string, `config`: string, `linkedActionIds`: string, `expiresInMs`: number | Create an event-driven sentinel that watches for conditions (webhook, timer, threshold, pattern, approval) and auto-unblocks gated actions when triggered. |+| `memory_sentinel_trigger` | | `sentinelId`*: string, `result`: string | Externally fire a sentinel, providing an optional result payload. Unblocks any gated actions. |+| `memory_sessions` | yes | none | List recent sessions with their status and observation counts. |+| `memory_signal_read` | | `agentId`*: string, `unreadOnly`: string, `threadId`: string, `limit`: number | Read messages for an agent. Marks delivered messages as read. |+| `memory_signal_send` | | `from`*: string, `to`: string, `content`*: string, `type`: string, `replyTo`: string | Send a message to another agent or broadcast. Supports threading, typed messages, and TTL expiration. |+| `memory_sketch_create` | | `title`*: string, `description`: string, `expiresInMs`: number, `project`: string | Create an ephemeral action graph for exploratory work. Auto-expires after TTL. Can be promoted to permanent actions or discarded. |+| `memory_sketch_promote` | | `sketchId`*: string, `project`: string | Promote a sketch's ephemeral actions to permanent actions. Makes the exploratory work official. |+| `memory_slot_append` | | `label`*: string, `text`*: string | Append text to an existing slot. Fails with 413 if the append would exceed the slot's sizeLimit, agent must compact via memory_slot_replace first. |+| `memory_slot_create` | | `label`*: string, `content`: string, `sizeLimit`: number, `description`: string, `pinned`: string, `scope`: string | Create a new slot. Reject if a slot with the same label already exists. |+| `memory_slot_delete` | | `label`*: string | Delete a slot. Seeded default slots can be deleted unless marked readOnly. |+| `memory_slot_get` | | `label`*: string | Read a single slot by label. |+| `memory_slot_list` | | none | List all memory slots (pinned + project + global). Slots are editable, size-limited memory units the agent can read and modify across sessions. |+| `memory_slot_replace` | | `label`*: string, `content`*: string | Replace slot content in place. Fails if content exceeds sizeLimit. |+| `memory_smart_search` | yes | `query`*: string, `expandIds`: string, `limit`: number | Hybrid semantic+keyword search with progressive disclosure. |+| `memory_snapshot_create` | | `message`: string | Create a git-versioned snapshot of current memory state. |+| `memory_team_feed` | | `limit`: number | Get recent shared items from all team members. |+| `memory_team_share` | | `itemId`*: string, `itemType`*: string | Share a memory or observation with team members. |+| `memory_timeline` | | `anchor`*: string, `project`: string, `before`: number, `after`: number | Chronological observations around an anchor point. |+| `memory_verify` | | `id`*: string | Verify a memory or observation by tracing its citation chain back to source observations and session context. Returns provenance information including confidence scores. |+| `memory_vision_search` | | `queryText`: string, `queryImageRef`: string, `queryImageBase64`: string, `topK`: number, `sessionId`: string | Cross-modal image search via CLIP embeddings. Pass queryText to find screenshots matching a description, or queryImageBase64/queryImageRef to find similar images. Requires AGENTMEMORY_IMAGE_EMBEDDINGS=true. |++`*` marks required parameters.+<!-- AUTOGEN:tools END -->diff --git a/plugin/skills/agentmemory-mcp-tools/SKILL.md b/plugin/skills/agentmemory-mcp-tools/SKILL.mdnew file mode 100644index 00000000..00445ef3--- /dev/null+++ b/plugin/skills/agentmemory-mcp-tools/SKILL.md@@ -0,0 +1,39 @@+---+name: agentmemory-mcp-tools+description: Map of every agentmemory MCP tool, what each does, and its parameters. Use when choosing which memory tool to call, when a tool name or argument is unclear, or when answering what agentmemory can do via MCP.+user-invocable: false+---++agentmemory exposes its full capability set as MCP tools. This skill is the index: it tells you which tool to reach for and where to find exact parameters.++## Quick start++Save then recall:++1. `memory_save` with `content` (the insight), `concepts` (comma-separated keywords), `files` (comma-separated paths).+2. `memory_smart_search` with `query` and `limit` to retrieve it later. This runs hybrid BM25 plus vector plus graph-expanded search.++## Tool families++- Capture: `memory_save`, `memory_observe` flows, `memory_compress_file`.+- Retrieve: `memory_smart_search`, `memory_recall`, `memory_file_history`, `memory_timeline`, `memory_vision_search`.+- Sessions and commits: `memory_sessions`, `memory_commits`, `memory_commit_lookup`.+- Knowledge and graph: `memory_lesson_save`, `memory_lesson_recall`, `memory_graph_query`, `memory_relations`, `memory_patterns`, `memory_crystallize`.+- Structured slots: `memory_slot_create`, `memory_slot_append`, `memory_slot_get`, `memory_slot_list`, `memory_slot_replace`, `memory_slot_delete`.+- Governance and health: `memory_governance_delete`, `memory_audit`, `memory_verify`, `memory_heal`, `memory_diagnose`.++## Workflow++1. Pick the narrowest tool for the task. Prefer `memory_smart_search` for open recall, `memory_recall` when you already have a focused query, `memory_sessions` for session listings.+2. Look up exact parameter names and which are required in REFERENCE.md before calling.+3. Pass only documented fields. REST handlers whitelist fields and drop unknown ones.++## See also++- agentmemory-rest-api for the HTTP equivalents.+- agentmemory-config for tool-visibility and feature flags.+- The user-invocable action skills (remember, recall, recap, handoff, forget) wrap the most common tools.++## Reference++Full tool table with parameters and the core-set marking lives in REFERENCE.md, generated from source so it never drifts.diff --git a/plugin/skills/agentmemory-rest-api/REFERENCE.md b/plugin/skills/agentmemory-rest-api/REFERENCE.mdnew file mode 100644index 00000000..d36171de--- /dev/null+++ b/plugin/skills/agentmemory-rest-api/REFERENCE.md@@ -0,0 +1,129 @@+# agentmemory REST API reference++Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registered endpoints.++<!-- AUTOGEN:rest START - generated by scripts/skills/generate.ts, do not edit by hand -->+The REST API is the primary surface. All paths are under `http://localhost:3111` (override with `--port`). When `AGENTMEMORY_SECRET` is set, send `Authorization: Bearer $AGENTMEMORY_SECRET`; localhost is otherwise open.++117 registered endpoints:++| Method | Path |+| --- | --- |+| POST | `/agentmemory/actions` |+| POST | `/agentmemory/actions/edges` |+| GET | `/agentmemory/actions/get` |+| POST | `/agentmemory/actions/update` |+| GET | `/agentmemory/audit` |+| POST | `/agentmemory/auto-forget` |+| GET | `/agentmemory/branch/detect` |+| GET | `/agentmemory/branch/sessions` |+| GET | `/agentmemory/branch/worktrees` |+| POST | `/agentmemory/cascade-update` |+| POST | `/agentmemory/checkpoints` |+| POST | `/agentmemory/checkpoints/resolve` |+| GET | `/agentmemory/claude-bridge/read` |+| POST | `/agentmemory/claude-bridge/sync` |+| GET | `/agentmemory/commits` |+| POST | `/agentmemory/compress-file` |+| GET | `/agentmemory/config/flags` |+| POST | `/agentmemory/consolidate` |+| POST | `/agentmemory/consolidate-pipeline` |+| POST | `/agentmemory/context` |+| GET | `/agentmemory/crystals` |+| POST | `/agentmemory/crystals/auto` |+| POST | `/agentmemory/crystals/create` |+| POST | `/agentmemory/diagnostics` |+| GET | `/agentmemory/diagnostics/followup` |+| POST | `/agentmemory/diagnostics/heal` |+| POST | `/agentmemory/enrich` |+| POST | `/agentmemory/evict` |+| POST | `/agentmemory/evolve` |+| GET | `/agentmemory/export` |+| POST | `/agentmemory/facets` |+| POST | `/agentmemory/facets/query` |+| POST | `/agentmemory/facets/remove` |+| GET | `/agentmemory/facets/stats` |+| POST | `/agentmemory/file-context` |+| POST | `/agentmemory/flow/compress` |+| POST | `/agentmemory/forget` |+| GET | `/agentmemory/frontier` |+| POST | `/agentmemory/generate-rules` |+| POST | `/agentmemory/governance/bulk-delete` |+| DELETE | `/agentmemory/governance/memories` |+| POST | `/agentmemory/graph/build` |+| POST | `/agentmemory/graph/extract` |+| POST | `/agentmemory/graph/query` |+| POST | `/agentmemory/graph/reset` |+| POST | `/agentmemory/graph/snapshot-rebuild` |+| GET | `/agentmemory/graph/stats` |+| GET | `/agentmemory/health` |+| POST | `/agentmemory/import` |+| GET | `/agentmemory/insights` |+| POST | `/agentmemory/insights/search` |+| POST | `/agentmemory/leases/acquire` |+| POST | `/agentmemory/leases/release` |+| POST | `/agentmemory/leases/renew` |+| POST | `/agentmemory/lessons` |+| POST | `/agentmemory/lessons/search` |+| POST | `/agentmemory/lessons/strengthen` |+| GET | `/agentmemory/livez` |+| GET | `/agentmemory/memories` |+| GET | `/agentmemory/memories/:id` |+| GET | `/agentmemory/mesh/export` |+| POST | `/agentmemory/mesh/peers` |+| POST | `/agentmemory/mesh/receive` |+| POST | `/agentmemory/mesh/sync` |+| POST | `/agentmemory/migrate` |+| GET | `/agentmemory/next` |+| GET | `/agentmemory/observations` |+| POST | `/agentmemory/observe` |+| POST | `/agentmemory/obsidian/export` |+| POST | `/agentmemory/patterns` |+| GET | `/agentmemory/procedural` |+| GET | `/agentmemory/profile` |+| POST | `/agentmemory/reflect` |+| POST | `/agentmemory/relations` |+| POST | `/agentmemory/remember` |+| POST | `/agentmemory/replay/import-jsonl` |+| GET | `/agentmemory/replay/load` |+| GET | `/agentmemory/replay/sessions` |+| POST | `/agentmemory/routines` |+| POST | `/agentmemory/routines/run` |+| GET | `/agentmemory/routines/status` |+| POST | `/agentmemory/search` |+| GET | `/agentmemory/semantic` |+| POST | `/agentmemory/sentinels` |+| POST | `/agentmemory/sentinels/cancel` |+| POST | `/agentmemory/sentinels/check` |+| POST | `/agentmemory/sentinels/trigger` |+| GET | `/agentmemory/session/by-commit` |+| POST | `/agentmemory/session/commit` |+| POST | `/agentmemory/session/end` |+| POST | `/agentmemory/session/start` |+| GET | `/agentmemory/sessions` |+| GET | `/agentmemory/signals` |+| POST | `/agentmemory/signals/send` |+| POST | `/agentmemory/sketches` |+| POST | `/agentmemory/sketches/add` |+| POST | `/agentmemory/sketches/discard` |+| POST | `/agentmemory/sketches/gc` |+| POST | `/agentmemory/sketches/promote` |+| GET | `/agentmemory/slot` |+| POST | `/agentmemory/slot/append` |+| POST | `/agentmemory/slot/reflect` |+| POST | `/agentmemory/slot/replace` |+| GET | `/agentmemory/slots` |+| POST | `/agentmemory/smart-search` |+| POST | `/agentmemory/snapshot/create` |+| POST | `/agentmemory/snapshot/restore` |+| GET | `/agentmemory/snapshots` |+| POST | `/agentmemory/summarize` |+| GET | `/agentmemory/team/feed` |+| GET | `/agentmemory/team/profile` |+| POST | `/agentmemory/team/share` |+| POST | `/agentmemory/timeline` |+| POST | `/agentmemory/verify` |+| GET | `/agentmemory/viewer` |+| POST | `/agentmemory/vision-embed` |+| POST | `/agentmemory/vision-search` |+<!-- AUTOGEN:rest END -->diff --git a/plugin/skills/agentmemory-rest-api/SKILL.md b/plugin/skills/agentmemory-rest-api/SKILL.mdnew file mode 100644index 00000000..898e94a6--- /dev/null+++ b/plugin/skills/agentmemory-rest-api/SKILL.md@@ -0,0 +1,43 @@+---+name: agentmemory-rest-api+description: The agentmemory HTTP REST API surface, the primary protocol for talking to the memory server. Use when calling agentmemory over HTTP, when MCP is unavailable and you need a fallback, or when integrating a host that does not speak MCP.+user-invocable: false+---++REST is agentmemory's primary surface. MCP is a bridge on top of it. Every memory operation has an HTTP endpoint under `http://localhost:3111/agentmemory/*`.++## Quick start++```bash+# liveness+curl -fsS http://localhost:3111/agentmemory/livez++# save+curl -X POST http://localhost:3111/agentmemory/remember \+ -H "Content-Type: application/json" \+ -d '{"content":"chose JWT refresh rotation","concepts":["jwt-refresh-rotation"]}'++# recall+curl -X POST http://localhost:3111/agentmemory/smart-search \+ -H "Content-Type: application/json" \+ -d '{"query":"auth token strategy","limit":5}'+```++## Auth++By default localhost is open and no auth is needed. When `AGENTMEMORY_SECRET` is set, every request needs `Authorization: Bearer $AGENTMEMORY_SECRET`. See agentmemory-config.++## Conventions++- Save returns `201`, reads return `200`, validation errors return `400`.+- Handlers whitelist body fields and drop unknown ones, so passing extra keys is safe but ignored.+- The port is configurable with `--port` or `--instance`; streams, viewer, and engine derive from it.++## See also++- agentmemory-mcp-tools for the MCP equivalents.+- agentmemory-config for the port quartet and the secret.++## Reference++The full endpoint list with methods lives in REFERENCE.md, generated from `src/triggers/api.ts`.diff --git a/plugin/skills/commit-context/EXAMPLES.md b/plugin/skills/commit-context/EXAMPLES.mdnew file mode 100644index 00000000..a0fe52cb--- /dev/null+++ b/plugin/skills/commit-context/EXAMPLES.md@@ -0,0 +1,71 @@+# commit-context worked examples++## 1. Line range with a linked session++User: "Why is this retry loop here?" (pointing at lines 40-52 of refresh.ts)++Find the SHA:++```bash+git blame -L 40,52 src/auth/refresh.ts+# 9a1b2c3d (dev 2026-06-07) ... retry on revoked token+```++Look it up:++```json+memory_commit_lookup { "sha": "9a1b2c3d4e5f60718293a4b5c6d7e8f901234567" }+```++Response:++```json+{+ "commit": { "sha": "9a1b2c3d...", "short": "9a1b2c3", "branch": "main",+ "author": "dev", "message": "rotate refresh tokens" },+ "sessions": [ { "id": "7f3a9c21", "project": "app", "observationCount": 14,+ "summary": "Reworked refresh rotation" } ]+}+```++Present:++> `9a1b2c3` on `main` by dev: "rotate refresh tokens". Linked to session+> `7f3a9c2` "Auth refresh rework" (14 obs). The retry loop handles a token+> revoked mid-flight, per the session's high-importance observations.++## 2. Function lookup, commit predates linking++User: "What was the agent doing when it wrote validateScope?"++```bash+git log -L :validateScope:src/auth/scope.ts -n 1+# 1122aabb ...+```++```json+memory_commit_lookup { "sha": "1122aabbccddeeff00112233445566778899aabb" }+```++Response:++```json+{ "commit": null }+```++Present:++> `1122aab` predates agent session linking, so there is no recorded session.+> From `git show`: it added `validateScope` to enforce per-token scopes. I can+> show the full diff if useful.++## 3. Bare path++User: "Give me context on src/middleware/limit.ts."++```bash+git log -n 1 -- src/middleware/limit.ts+```++Take the SHA, run `memory_commit_lookup`, present commit plus linked session in+the same shape as example 1.diff --git a/plugin/skills/commit-context/SKILL.md b/plugin/skills/commit-context/SKILL.mdindex 9ec0dae3..fa782ef5 100644--- a/plugin/skills/commit-context/SKILL.md+++ b/plugin/skills/commit-context/SKILL.md@@ -1,19 +1,64 @@---name: commit-context-description: Trace a file, function, or line back to the agent session that produced its current commit. Use when the user asks "why is this code here", "what was the agent doing when this changed", or wants context on a specific location in the codebase.+description: Trace a file, function, or line back to the agent session that produced its current commit. Use when the user asks "why is this code here", "what was the agent doing when this changed", "who wrote this", or wants context on a specific location in the codebase.argument-hint: "[file, function, or line]"user-invocable: true---The user wants commit context for: $ARGUMENTS-Run `git blame` (or `git log -L`) on the target file, function, or line in $ARGUMENTS to extract the most recent commit SHA that touched it. Use `git blame -L <start>,<end> <file>` when a line range is given, `git log -L :<function>:<file>` when a function name is given, and `git log -n 1 -- <file>` when only a path is given.+## Quick start-With the SHA in hand, look up the linked agent session via the `memory_commit_lookup` MCP tool with `sha: "<full-sha>"`. If the MCP tool is unavailable, fall back to HTTP: `GET $AGENTMEMORY_URL/agentmemory/session/by-commit?sha=<sha>` with `Authorization: Bearer $AGENTMEMORY_SECRET` when the secret is set.+```bash+git blame -L 40,52 src/auth/refresh.ts # -> SHA 9a1b2c3d+```-Present the result as:-- The commit SHA, short SHA, branch, author, message-- The linked session(s): id, project, started/ended timestamps, observation count, summary if any-- A short list of the most important observations from that session (importance >= 7) when available via `memory_recall`+```json+memory_commit_lookup { "sha": "9a1b2c3d4e5f60718293a4b5c6d7e8f901234567" }+```-Do not fabricate intent. If the commit has no linked session, say so plainly and surface only what `git show` reveals. If `memory_commit_lookup` returns an empty `commit: null` body, that means the commit predates session linking — do not invent a session.+Expected output:++```text+9a1b2c3 on main by dev: "rotate refresh tokens"+Linked session 7f3a9c2 "Auth refresh rework", 14 obs.+```++## Why++Report only what git and the lookup return. When the lookup gives `commit: null`,+the commit predates session linking; do not invent intent.++## Workflow++1. Find the SHA: `git blame -L <start>,<end> <file>` for a line range;+ `git log -L :<function>:<file>` for a function; `git log -n 1 -- <file>` for a+ bare path.+2. Look it up: `memory_commit_lookup { "sha": "<full-sha>" }`.+3. Present the commit (sha, short sha, branch, author, message), the linked+ session(s) (id, project, started/ended, observation count, summary), and the+ importance >= 7 observations via `memory_recall` when available.++## Anti-patterns++WRONG: lookup returns `{ "commit": null }`, you narrate "the agent was+refactoring auth" from the diff alone.++RIGHT: "This commit predates session linking, so there is no recorded agent+session. From `git show`: it changed token rotation in refresh.ts."++## Checklist++- SHA came from git blame/log, not a guess.+- `commit: null` reported as "predates linking", no fabricated session.+- Session details quote the lookup response verbatim.+- No intent claimed beyond what observations state.++## See also++- `commit-history`: list many agent-linked commits at once.+- `recall`: dig deeper into the linked session's observations.++## Troubleshooting++See ../_shared/TROUBLESHOOTING.md if `memory_commit_lookup` is not available.diff --git a/plugin/skills/commit-history/EXAMPLES.md b/plugin/skills/commit-history/EXAMPLES.mdnew file mode 100644index 00000000..d04a6bb6--- /dev/null+++ b/plugin/skills/commit-history/EXAMPLES.md@@ -0,0 +1,71 @@+# commit-history worked examples++## 1. Branch filter++User: "Show agent commits on main."++Invocation:++```json+memory_commits { "branch": "main", "limit": 100 }+```++Response:++```json+{+ "commits": [+ { "short": "9a1b2c3", "branch": "main", "authoredAt": "2026-06-07T09:12:00Z",+ "message": "rotate refresh tokens", "sessionIds": ["7f3a9c21"],+ "observationCount": 14, "files": 3 },+ { "short": "b21d004", "branch": "main", "authoredAt": "2026-06-05T14:40:00Z",+ "message": "rate limiter audit", "sessionIds": ["b21d004e"],+ "observationCount": 9, "files": 1 }+ ]+}+```++Present:++> - `9a1b2c3` main 2026-06-07 "rotate refresh tokens", session `7f3a9c2` (14 obs, 3 files)+> - `b21d004` main 2026-06-05 "rate limiter audit", session `b21d004` (9 obs, 1 file)++## 2. Bare number as limit++User: "commit-history 5"++Treat `5` as the limit:++```json+memory_commits { "limit": 5 }+```++Render the five newest linked commits in the same format.++## 3. Empty result++User: "Show agent commits on release-2.0."++```json+memory_commits { "branch": "release-2.0", "limit": 100 }+```++Response:++```json+{ "commits": [] }+```++Present:++> No agent-linked commits on `release-2.0`. Drop the branch filter to see all+> linked commits, or try a different branch.++REST fallback for this same call, with encoding:++```http+GET /agentmemory/commits?branch=release-2.0&limit=100+```++Build it with `URLSearchParams` so a branch like `feat/a&b` becomes+`feat%2Fa%26b` rather than breaking the query.diff --git a/plugin/skills/commit-history/SKILL.md b/plugin/skills/commit-history/SKILL.mdindex 599c3220..b05c0036 100644--- a/plugin/skills/commit-history/SKILL.md+++ b/plugin/skills/commit-history/SKILL.md@@ -1,20 +1,62 @@---name: commit-history-description: List recent git commits that are linked to agent sessions, optionally filtered by branch or repo. Use when the user asks "show agent commits", "what has the agent shipped", or wants a list of commits with their session context.+description: List recent git commits linked to agent sessions, optionally filtered by branch or repo. Use when the user asks "show agent commits", "what has the agent shipped", "list linked commits", or wants commits with their session context.argument-hint: "[branch=... repo=... limit=...]"user-invocable: true---The user wants a list of agent-linked commits. Filter args: $ARGUMENTS-Parse `$ARGUMENTS` for optional `branch=<name>`, `repo=<url-or-fragment>`, and `limit=<n>` tokens. A bare numeric token becomes the limit. Defaults: no branch filter, no repo filter, limit 100, max 500.+## Quick start-Call the `memory_commits` MCP tool with the parsed filters. If the MCP tool is unavailable, fall back to HTTP: build `GET $AGENTMEMORY_URL/agentmemory/commits` and append each filter as a URL-encoded query parameter (use `URLSearchParams` or `encodeURIComponent` on `branch`, `repo`, and `limit`) so values containing `?`, `&`, or `#` cannot corrupt the request. Include `Authorization: Bearer $AGENTMEMORY_SECRET` when set.+```json+memory_commits { "branch": "main", "limit": 20 }+```-Render the result as a reverse-chronological list:-- Short SHA, branch, authored timestamp-- Commit message first line-- Linked session id(s) (first 8 chars each) and observation counts where present-- File count when `files` is provided+Expected output:-If the result is empty, tell the user the filter matched no commits and suggest dropping the branch/repo filter. Do not invent commits.+```text+9a1b2c3 main 2026-06-07 "rotate refresh tokens" · session 7f3a9c2 (14 obs)+b21d004 main 2026-06-05 "rate limiter audit" · session b21d004 (9 obs)+```++## Why++Render only the commits the tool returned, newest first. An empty result means+the filter matched nothing, not that work is missing.++## Workflow++1. Parse `$ARGUMENTS` for `branch=<name>`, `repo=<url-or-fragment>`,+ `limit=<n>`. A bare numeric token is the limit. Defaults: no branch, no repo,+ limit 100, max 500.+2. Call `memory_commits` with the parsed filters.+3. Render reverse-chronologically: short sha, branch, authored timestamp, first+ line of the message, linked session id(s) (first 8) with observation counts,+ and file count when `files` is present.+4. Empty result: tell the user the filter matched nothing and suggest dropping+ the branch or repo filter.++## Anti-patterns++WRONG (REST fallback): concatenate `?branch=` + raw branch name, so a name with+`?`, `&`, or `#` corrupts the query string.++RIGHT: URL-encode every value with `URLSearchParams`/`encodeURIComponent` before+appending to `GET /agentmemory/commits`.++## Checklist++- Filters parsed; bare number treated as limit; limit capped at 500.+- Output is reverse-chronological.+- Session ids and observation counts come straight from the response.+- REST fallback URL-encodes branch, repo, and limit.++## See also++- `commit-context`: drill into one commit's session.+- `recall`: search the observations behind a linked session.++## Troubleshooting++See ../_shared/TROUBLESHOOTING.md if `memory_commits` is not available.diff --git a/plugin/skills/forget/EXAMPLES.md b/plugin/skills/forget/EXAMPLES.mdnew file mode 100644index 00000000..c391bda0--- /dev/null+++ b/plugin/skills/forget/EXAMPLES.md@@ -0,0 +1,75 @@+# forget worked examples++## 1. Delete a leaked secret++User: "Forget that note where I pasted the API key."++Search:++```json+memory_smart_search { "query": "api key", "limit": 20 }+```++Response:++```json+{+ "results": [+ { "id": "abc12345", "sessionId": "7f3a9c21", "title": "Pasted staging API key",+ "narrative": "STAGING_KEY=sk-live-..." }+ ]+}+```++Present and gate:++> Found 1 match:+> - `abc12345` (session `7f3a9c2`) "Pasted staging API key"+>+> Delete this memory? (yes/no)++After the user says yes:++```json+memory_governance_delete { "memoryIds": ["abc12345"], "reason": "user privacy request" }+```++Response:++```json+{ "deleted": 1 }+```++Present:++> Deleted 1 memory (`abc12345`).++## 2. Drop a whole session's observations++User: "Delete everything from the throwaway spike session."++Search, identify the session, then collect every memory id in it:++```json+memory_smart_search { "query": "spike prototype throwaway", "limit": 20 }+```++Response has 4 results all with `sessionId: c98f1100`. Show all four, get a yes,+then pass every id:++```json+memory_governance_delete {+ "memoryIds": ["m1", "m2", "m3", "m4"],+ "reason": "drop throwaway spike session"+}+```++Never send `{ "sessionId": "c98f1100" }`; the MCP deletes by memory id only.++## 3. User declines++User: "Actually, on second thought, keep them."++Do not call delete. Confirm:++> Understood, nothing deleted. The 4 memories from session `c98f110` are intact.diff --git a/plugin/skills/forget/SKILL.md b/plugin/skills/forget/SKILL.mdindex 067d564c..32ec5396 100644--- a/plugin/skills/forget/SKILL.md+++ b/plugin/skills/forget/SKILL.md@@ -1,26 +1,66 @@---name: forget-description: Delete specific observations or sessions from agentmemory. Use when user says "forget this", "delete memory", or wants to remove specific data for privacy.+description: Delete specific observations from agentmemory after showing them and getting explicit confirmation. Use when the user says "forget this", "delete memory", "remove that note", or wants to scrub specific data for privacy.argument-hint: "[what to forget - session ID, file path, or search term]"user-invocable: true---The user wants to remove data from agentmemory: $ARGUMENTS-**IMPORTANT**: This is a destructive operation. Always confirm with the user before deleting.+## Quick start-Steps:+```json+memory_smart_search { "query": "old api key in config", "limit": 20 }+```-1. First search for matching observations with the `memory_smart_search` MCP tool (provided by the agentmemory server this plugin wires up via `.mcp.json`). Use the user's input as the `query` with `limit: 20`.-2. Show the user what was found — session IDs, observation IDs, titles — and ask for explicit confirmation before deleting.-3. Once confirmed, call `memory_governance_delete` with:- - `memoryIds: [<id>, ...]` — an array (or comma-separated string) of the memory IDs returned by the search in step 1- - `reason: "<short reason>"` — optional, defaults to `"plugin skill request"`+Show the matches, get a yes, then:- If the user wants to drop an entire session's observations, collect every memory ID in that session from the search results and pass them all via `memoryIds`. The standalone MCP doesn't accept a bare `sessionId` argument — it deletes by memory ID only.-4. Confirm the deletion count back to the user.+```json+memory_governance_delete { "memoryIds": ["abc12345", "def67890"], "reason": "user privacy request" }+```-**Never delete without explicit user confirmation.** If the MCP tools aren't available, the stdio MCP shim didn't start — tell the user to:-1. Run `/plugin list` in Claude Code and confirm `agentmemory` shows as enabled.-2. Restart Claude Code (the plugin's `.mcp.json` is only read on startup).-3. Check `/mcp` to see whether the `agentmemory` MCP server is connected.+Expected output:++```text+Found 2 matching memories. Confirmed. Deleted 2 memories.+```++## Why++This is destructive and irreversible. Show exactly what will be deleted and get+an explicit yes before calling delete. Delete by memory ID, never a bare session.++## Workflow++1. Search with `memory_smart_search`, the user's text as `query`, `limit: 20`.+2. Show what matched: session ids, memory ids, titles. Ask for explicit+ confirmation. Do not proceed on silence or a vague "sure, whatever".+3. On confirmation, call `memory_governance_delete` with `memoryIds` (array or+ comma-separated string) and optional `reason` (default `plugin skill request`).+4. To drop a whole session, collect every memory id in that session from the+ search results and pass them all. The MCP does not accept a bare `sessionId`.+5. Report the deletion count back.++## Anti-patterns++WRONG: search returns matches, you immediately call `memory_governance_delete`+without showing them or waiting for a yes.++RIGHT: list the matches, ask "Delete these 2? (yes/no)", and only delete after+an explicit yes.++## Checklist++- Matches were shown to the user before any delete.+- An explicit yes was received, not assumed.+- `memoryIds` holds real ids from the search, never a bare `sessionId`.+- Final message states the actual count deleted.++## See also++- `remember`: the write side; forget is its undo.+- `recall`: find the exact memory id before deleting.++## Troubleshooting++See ../_shared/TROUBLESHOOTING.md if `memory_smart_search` or `memory_governance_delete` is not available.diff --git a/plugin/skills/handoff/EXAMPLES.md b/plugin/skills/handoff/EXAMPLES.mdnew file mode 100644index 00000000..11e1d584--- /dev/null+++ b/plugin/skills/handoff/EXAMPLES.md@@ -0,0 +1,56 @@+# handoff worked examples++## 1. Resume with an open question++User: "Where were we?"++Project cwd: `/Users/dev/app`. Invocation:++```json+memory_sessions { "limit": 20 }+```++Response:++```json+{+ "sessions": [+ { "id": "7f3a9c21", "cwd": "/Users/dev/app", "title": "Auth refresh rework",+ "status": "completed", "startedAt": "2026-06-07T09:00:00Z",+ "summary": "Reworked refresh rotation. Open: should logout revoke all device tokens?",+ "concepts": ["jwt-refresh-rotation", "logout"] }+ ]+}+```++Pull supporting context:++```json+memory_recall { "query": "jwt-refresh-rotation logout", "limit": 10 }+```++Present:++> Resuming `7f3a9c2` "Auth refresh rework".+> **Open question:** should logout revoke all device tokens or just the current one?+> Touched `auth/refresh.ts`, `auth/logout.ts`. Refresh rotation is done.+> **Next step:** decide the revoke scope, then finish `auth/logout.ts`.++## 2. Sibling-repo guard++Project cwd: `/Users/dev/repo-a`. Sessions include one with `cwd:+/Users/dev/repo-a-staging`.++A raw prefix would match `repo-a-staging`. The boundary check rejects it because+`/Users/dev/repo-a-staging` does not equal `/Users/dev/repo-a` and does not start+with `/Users/dev/repo-a/`. Pick the real `repo-a` session instead, or fall back+to the most recent session overall if none matches.++## 3. Empty session++User: "Resume."++If the matched session has zero observations:++> The most recent session `c98f110` for this project has no recorded+> observations. Nothing to hand off. Want to start fresh from the current state?diff --git a/plugin/skills/handoff/SKILL.md b/plugin/skills/handoff/SKILL.mdindex 63437001..3b4e5149 100644--- a/plugin/skills/handoff/SKILL.md+++ b/plugin/skills/handoff/SKILL.md@@ -1,21 +1,68 @@---name: handoff-description: Resume the most recent agent session for the current working directory. Use when the user says "where were we", "resume", "handoff", "pick up where I left off", or starts a session with no fresh context.+description: Resume the most recent agent session for the current working directory, leading with any unanswered question. Use when the user says "where were we", "resume", "handoff", "pick up where I left off", or starts a session with no fresh context.argument-hint: "[optional cwd override]"user-invocable: true---The user wants to resume work. Optional cwd override: $ARGUMENTS-Determine the current project path: if `$ARGUMENTS` is provided, resolve it to an absolute, normalized path (accept relative inputs, e.g. `path.resolve(process.cwd(), $ARGUMENTS)`); otherwise use the current working directory.+## Quick start-Call the `memory_sessions` MCP tool. From the result, pick the most recent session whose normalized `cwd` matches the project path with a directory-boundary check — equality OR `session.cwd.startsWith(projectPath + path.sep)` OR `projectPath.startsWith(session.cwd + path.sep)`. Do NOT use a raw string prefix match: it produces false positives across unrelated repos that share a path prefix (e.g. `/repo-a` vs `/repo-a-staging`). Prefer sessions with status `completed` over `abandoned`. If nothing matches, fall back to the single most recent session overall.+```json+memory_sessions { "limit": 20 }+```-Once a session is selected:-1. If the session ended on an unanswered user-facing question, surface that question FIRST as the lead. Look for it in `summary` or in the last few observations (type `conversation` with `narrative` ending in `?`).-2. Then summarize the session: title/summary, key files touched, key decisions or errors. Use `memory_recall` with a query derived from the session's top concepts to fetch supporting observations, limit 10.-3. End with a short "next step?" pointer the user can act on.+Pick the most recent session whose `cwd` matches this project, then:+`memory_recall { "query": "<session top concepts>", "limit": 10 }`.-If neither MCP tool is available, fall back to HTTP: `GET $AGENTMEMORY_URL/agentmemory/sessions` and `POST $AGENTMEMORY_URL/agentmemory/recall` with `Authorization: Bearer $AGENTMEMORY_SECRET` when set.+Expected output:-Do not invent observations. If the most recent session has zero observations, say so and offer to start fresh.+```text+Resuming 7f3a9c2 "Auth refresh rework".+Open question: should logout revoke all device tokens or just the current one?+Next step: decide revoke scope, then update auth/logout.ts.+```++## Why++Match the session by directory boundary, not raw prefix, so a sibling repo never+gets mistaken for this one. Never invent observations for an empty session.++## Workflow++1. Resolve the project path: if `$ARGUMENTS` is given, normalize it to absolute+ (`path.resolve(process.cwd(), $ARGUMENTS)`); else use the cwd.+2. Call `memory_sessions`. Pick the most recent session whose normalized `cwd`+ matches by directory boundary: equality, OR `cwd.startsWith(projectPath + sep)`,+ OR `projectPath.startsWith(cwd + sep)`. Prefer `completed` over `abandoned`.+ No match: fall back to the single most recent session overall.+3. If the session ended on an unanswered user-facing question, surface it FIRST.+ Look in `summary` or recent `conversation` observations whose `narrative`+ ends in `?`.+4. Summarize: title/summary, key files, key decisions or errors, using+ `memory_recall` on the top concepts, limit 10.+5. End with one concrete "next step?" pointer.++## Anti-patterns++WRONG: `session.cwd.startsWith(projectPath)` matches `/repo-a-staging` when the+project is `/repo-a`, resuming the wrong repo's session.++RIGHT: `session.cwd === projectPath || session.cwd.startsWith(projectPath + sep)`,+a directory-boundary check that cannot cross sibling repos.++## Checklist++- cwd override resolved to an absolute, normalized path.+- Match used a directory-boundary check, not a raw prefix.+- Unanswered question (if any) leads the response.+- Empty session is reported plainly, with an offer to start fresh.++## See also++- `recap`, `session-history`, `recall`: same session data, broader views.++## Troubleshooting++See ../_shared/TROUBLESHOOTING.md if `memory_sessions` or `memory_recall` is not available.diff --git a/plugin/skills/recall/EXAMPLES.md b/plugin/skills/recall/EXAMPLES.mdnew file mode 100644index 00000000..8e58c56d--- /dev/null+++ b/plugin/skills/recall/EXAMPLES.md@@ -0,0 +1,74 @@+# recall worked examples++## 1. Hit on a past decision++User: "Did we ever decide how to cache sessions?"++Invocation:++```json+memory_smart_search { "query": "session caching decision", "limit": 10 }+```++Response:++```json+{+ "results": [+ { "sessionId": "7f3a9c21", "type": "decision", "title": "Drop Redis for iii state store",+ "narrative": "We decided to drop Redis and use the iii-engine state store for session caching.",+ "importance": 8 }+ ]+}+```++Present:++> Yes. In session `7f3a9c21` you decided to drop Redis and use the iii-engine+> state store for session caching (importance 8).++## 2. Multiple results across sessions++User: "Recall anything about the rate limiter."++Invocation:++```json+memory_smart_search { "query": "rate limiter", "limit": 10 }+```++Response:++```json+{+ "results": [+ { "sessionId": "b21d004e", "type": "code", "title": "limit.ts counts per-IP",+ "narrative": "Rate limiter counts per-IP, not per-user.", "importance": 6 },+ { "sessionId": "c98f1100", "type": "conversation", "title": "Discussed sliding window",+ "narrative": "Considered a sliding-window limiter, deferred.", "importance": 4 }+ ]+}+```++Present them grouped by session, leading with the per-IP code note.++## 3. No results++User: "Recall the GraphQL schema migration."++Invocation:++```json+memory_smart_search { "query": "graphql schema migration", "limit": 10 }+```++Response:++```json+{ "results": [] }+```++Present:++> No memories matched that. Try `schema change`, `graphql`, or `migration` as+> narrower terms, or `recap this week` to scan recent sessions.diff --git a/plugin/skills/recall/SKILL.md b/plugin/skills/recall/SKILL.mdindex 113b3c04..00f71fc2 100644--- a/plugin/skills/recall/SKILL.md+++ b/plugin/skills/recall/SKILL.md@@ -1,21 +1,60 @@---name: recall-description: Search agentmemory for past observations, sessions, and learnings about a topic. Use when the user says "recall", "remember", "what did we do", or needs context from past sessions.+description: Search agentmemory for past observations, sessions, and learnings about a topic using hybrid BM25 plus vector plus graph search. Use when the user says "recall", "what did we do about", "did we ever", "have we seen", or needs context from past sessions.argument-hint: "[search query]"user-invocable: true---The user wants to recall past context about: $ARGUMENTS-Use the `memory_smart_search` MCP tool (provided by the agentmemory server that this plugin wires up automatically via `.mcp.json`) with the user's query as the `query` argument and `limit: 10`. The tool runs hybrid BM25 + vector + graph-expanded search over captured observations and returns ranked results.+## Quick start-Present the returned results to the user in a readable format:-- Group by session-- For each observation show its type, title, and narrative-- Highlight the most important observations (importance >= 7)-- If no results come back, suggest 2-3 alternative search terms the user could try+```json+memory_smart_search { "query": "jwt refresh token rotation", "limit": 10 }+```-**Do NOT make up or hallucinate observations.** Only present what the MCP tool actually returned. If `memory_smart_search` isn't available, the stdio MCP shim didn't start — tell the user to:-1. Run `/plugin list` in Claude Code and confirm `agentmemory` shows as enabled.-2. Restart Claude Code (the plugin's `.mcp.json` is only read on startup).-3. Check `/mcp` to see whether the `agentmemory` MCP server is connected.+Expected output:++```text+2 results across 2 sessions.+[importance 8] decision · "Rotate refresh tokens on every use" (session 7f3a9c21)+[importance 5] code · "limit.ts counts per-IP" (session b21d004e)+```++## Why++Only surface what the tool returned. Never fabricate an observation, a session+id, or an importance score. If nothing comes back, say so.++## Workflow++1. Call `memory_smart_search` with the user's text as `query` and `limit: 10`.+ Pass `project` when the user scopes to a specific repo.+2. Group results by session.+3. For each observation show its type, title, and narrative.+4. Lead with the high-signal observations (importance >= 7).+5. If zero results, suggest 2-3 alternative search terms and stop. Do not guess.++## Anti-patterns++WRONG: results are empty, so you write "We probably discussed token expiry last+week" from assumption.++RIGHT: "No memories matched that query. Try `refresh token`, `session expiry`,+or `auth rotation`."++## Checklist++- Every observation shown came from the tool response.+- Results grouped by session, high-importance first.+- Empty results trigger alternative-term suggestions, not invention.+- No session id or score was paraphrased or rounded.++## See also++- `remember`: the write side; recall retrieves what it stores.+- `recap`, `handoff`, `session-history`: session-scoped views of the same data.++## Troubleshooting++See ../_shared/TROUBLESHOOTING.md if `memory_smart_search` is not available.diff --git a/plugin/skills/recap/EXAMPLES.md b/plugin/skills/recap/EXAMPLES.mdnew file mode 100644index 00000000..4426c8cb--- /dev/null+++ b/plugin/skills/recap/EXAMPLES.md@@ -0,0 +1,60 @@+# recap worked examples++## 1. This week++User: "Recap this week."++Window: last 7 days. Invocation:++```json+memory_sessions { "limit": 30 }+```++Response (after filtering to cwd and the 7-day window):++```json+{+ "sessions": [+ { "id": "7f3a9c21", "cwd": "/Users/dev/app", "title": "Auth refresh rework",+ "startedAt": "2026-06-07T09:00:00Z", "observationCount": 14, "status": "completed",+ "concepts": ["jwt-refresh-rotation", "auth-flow"] },+ { "id": "b21d004e", "cwd": "/Users/dev/app", "title": "Rate limiter audit",+ "startedAt": "2026-06-05T14:00:00Z", "observationCount": 9, "status": "completed",+ "concepts": ["rate-limiter", "per-ip-bug"] }+ ]+}+```++Per session, pull highlights:++```json+memory_recall { "query": "jwt-refresh-rotation auth-flow", "limit": 3 }+```++Present:++> **2026-06-07**+> - `7f3a9c2` Auth refresh rework, 14 obs, completed+> - [8] Rotate refresh tokens on every use+>+> **2026-06-05**+> - `b21d004e` Rate limiter audit, 9 obs, completed+> - [7] limit.ts counts per-IP, not per-user+>+> 2 sessions across 2 days, 23 observations.++## 2. Bare number++User: "recap 3"++Treat as `last 3`. Call `memory_sessions { "limit": 3 }`, group by date, same format.++## 3. Empty window++User: "Recap today."++If `memory_sessions` returns no session whose `startedAt` is today and whose+`cwd` matches:++> No sessions today for this project. The most recent was yesterday, `7f3a9c2`+> Auth refresh rework. Want a recap of that instead?diff --git a/plugin/skills/recap/SKILL.md b/plugin/skills/recap/SKILL.mdindex eec5acc4..b3ea5e9c 100644--- a/plugin/skills/recap/SKILL.md+++ b/plugin/skills/recap/SKILL.md@@ -1,25 +1,63 @@---name: recap-description: Summarize the last N agent sessions for the current project, grouped by date. Use when the user asks "recap", "what have we been doing", "this week", "today", or wants a rollup of recent work.+description: Summarize the last N agent sessions for the current project, grouped by date, with highlight observations per session. Use when the user asks "recap", "what have we been doing", "today", "this week", or wants a rollup of recent work.argument-hint: "[last N | today | this week]"user-invocable: true---The user wants a recap. Time window args: $ARGUMENTS-Parse `$ARGUMENTS` to determine the window:-- `today` -> sessions started on the current local date-- `this week` -> sessions started in the last 7 days-- `last <n>` -> the most recent N sessions-- bare numeric -> treat as `last <n>`-- empty -> default to `last 10`+## Quick start-Call the `memory_sessions` MCP tool, then filter to the current project (match by `cwd` against the working directory). Apply the time window. Sort by `startedAt` descending.+```json+memory_sessions { "limit": 30 }+```-Group the surviving sessions by their local calendar date (YYYY-MM-DD). For each date:-- List each session: id (first 8 chars), title or first prompt, observation count, status-- Indent two or three highlight observations per session (importance >= 7) drawn from `memory_recall` with a per-session query, limit 3+Then per surviving session: `memory_recall { "query": "<top concepts>", "limit": 3 }`.-End with a one-line total: "N sessions across M days, K observations."+Expected output:-If MCP tools are unavailable, fall back to HTTP: `GET $AGENTMEMORY_URL/agentmemory/sessions` and `POST $AGENTMEMORY_URL/agentmemory/recall` with `Authorization: Bearer $AGENTMEMORY_SECRET` when set. Do not invent sessions; if the window is empty, say so.+```text+2026-06-07+ 7f3a9c2 · "Auth refresh rework" · 14 obs · completed+ - [8] Rotate refresh tokens on every use+3 sessions across 2 days, 41 observations.+```++## Why++Only summarize sessions and observations the tools returned. An empty window is+a real answer, not a prompt to invent activity.++## Workflow++1. Parse `$ARGUMENTS`: `today` = current local date; `this week` = last 7 days;+ `last <n>` or bare numeric = most recent N; empty = `last 10`.+2. Call `memory_sessions`, filter to the current project (match `cwd` against the+ working directory), apply the window, sort by `startedAt` descending.+3. Group survivors by local calendar date (YYYY-MM-DD).+4. Per session list id (first 8), title or first prompt, observation count,+ status. Indent 2-3 highlights (importance >= 7) from `memory_recall`.+5. End with "N sessions across M days, K observations."++## Anti-patterns++WRONG: window is empty, so you summarize "a productive week of auth work" from+memory of the conversation.++RIGHT: "No sessions in the last 7 days for this project."++## Checklist++- Window parsed correctly from the argument.+- Sessions filtered to the current project's cwd.+- Highlights come from `memory_recall`, not paraphrase.+- Totals line reflects the actual counts shown.++## See also++- `handoff`, `session-history`, `recall`: same session data, different lens.++## Troubleshooting++See ../_shared/TROUBLESHOOTING.md if `memory_sessions` or `memory_recall` is not available.diff --git a/plugin/skills/remember/EXAMPLES.md b/plugin/skills/remember/EXAMPLES.mdnew file mode 100644index 00000000..e220cb79--- /dev/null+++ b/plugin/skills/remember/EXAMPLES.md@@ -0,0 +1,67 @@+# remember worked examples++## 1. Saving a decision++User: "Remember that we decided to drop Redis and use the iii-engine state store for session caching."++Invocation:++```json+memory_save {+ "content": "We decided to drop Redis and use the iii-engine state store for session caching to remove a moving part.",+ "concepts": "session-caching, iii-state-store, dropped-redis",+ "files": ""+}+```++Response:++```json+{ "id": "7f3a9c21", "concepts": ["session-caching", "iii-state-store", "dropped-redis"], "saved": true }+```++Present:++> Saved. Tagged it `session-caching`, `iii-state-store`, `dropped-redis`, so a+> later recall on caching or Redis will surface this decision.++## 2. Saving a code-specific gotcha++User: "Save this: the rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide."++Invocation:++```json+memory_save {+ "content": "The rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide.",+ "concepts": "rate-limiter, per-ip-bug, shared-ip-collision",+ "files": "src/middleware/limit.ts"+}+```++Response:++```json+{ "id": "b21d004e", "concepts": ["rate-limiter", "per-ip-bug", "shared-ip-collision"], "saved": true }+```++Present:++> Saved memory `b21d004e` referencing `src/middleware/limit.ts`. Concepts:+> `rate-limiter`, `per-ip-bug`, `shared-ip-collision`.++## 3. Vague request, no files++User: "Remember this for later."++Ask once for the substance, then save:++```json+memory_save {+ "content": "Staging deploys must run the migration job before the app rollout, never after.",+ "concepts": "staging-deploy, migration-ordering, rollout-sequence",+ "files": ""+}+```++Present the confirmation with the concepts echoed back.diff --git a/plugin/skills/remember/SKILL.md b/plugin/skills/remember/SKILL.mdindex aa85103e..83e950d6 100644--- a/plugin/skills/remember/SKILL.md+++ b/plugin/skills/remember/SKILL.md@@ -1,25 +1,61 @@---name: remember-description: Explicitly save an insight, decision, or learning to agentmemory's long-term storage. Use when the user says "remember this", "save this", or wants to preserve knowledge for future sessions.+description: Save an insight, decision, or learning to agentmemory's long-term storage with searchable concept tags. Use when the user says "remember this", "save this", "note that", "don't forget", or wants to preserve knowledge for future sessions.argument-hint: "[what to remember]"user-invocable: true---The user wants to save this to long-term memory: $ARGUMENTS-Use the `memory_save` MCP tool (provided by the agentmemory server that this plugin wires up automatically via `.mcp.json`) to persist it.--Steps:-1. Analyze what the user wants to remember — pull out the core insight, decision, or fact.-2. Extract 2-5 searchable `concepts` (lowercased keyword phrases) that capture what the memory is about. Prefer specific terms over generic ones (`"jwt-refresh-rotation"` beats `"auth"`).-3. Extract any relevant `files` — absolute or repo-relative paths the memory references.-4. Call `memory_save` with the fields:- - `content` — the full text to remember (preserve the user's phrasing as much as possible)- - `concepts` — the extracted concept list- - `files` — the extracted file list (empty array if none apply)-5. Confirm to the user that the memory was saved and show the concepts you tagged so they know what terms will retrieve it later.--If `memory_save` isn't available, the stdio MCP shim didn't start — tell the user to:-1. Run `/plugin list` in Claude Code and confirm `agentmemory` shows as enabled.-2. Restart Claude Code (the plugin's `.mcp.json` is only read on startup).-3. Check `/mcp` to see whether the `agentmemory` MCP server is connected.+## Quick start++```json+memory_save {+ "content": "We rotate JWT refresh tokens on every use; the old token is revoked server-side in auth/refresh.ts.",+ "concepts": "jwt-refresh-rotation, token-revocation, auth-flow",+ "files": "src/auth/refresh.ts"+}+```++Expected output:++```text+Saved memory abc12345 with 3 concepts: jwt-refresh-rotation, token-revocation, auth-flow.+```++## Why++A memory is only as useful as the terms that retrieve it. Tag with specific+concepts so a future `recall` finds it, and preserve the user's own phrasing.++## Workflow++1. Pull the core insight, decision, or fact out of `$ARGUMENTS`.+2. Extract 2-5 lowercased concept phrases. Prefer specific over generic+ (`jwt-refresh-rotation` beats `auth`).+3. Extract referenced file paths (absolute or repo-relative). Empty if none.+4. Call `memory_save` with `content`, `concepts` (comma-separated string), and+ `files` (comma-separated string).+5. Confirm the save and echo the concepts so the user knows the retrieval terms.++## Anti-patterns++WRONG: `concepts: "stuff, code, notes"` (generic tags nothing can find later).++RIGHT: `concepts: "jwt-refresh-rotation, token-revocation"` (specific, retrievable).++## Checklist++- Content preserves the user's phrasing, not a paraphrase.+- Concepts are specific, lowercased, 2-5 items.+- File paths are real references, not guesses.+- Confirmation echoes the exact concepts tagged.++## See also++- `recall`: retrieve what you save here (the pair to this skill).+- `forget`: remove a memory you saved by mistake.++## Troubleshooting++See ../_shared/TROUBLESHOOTING.md if `memory_save` is not available.diff --git a/plugin/skills/session-history/EXAMPLES.md b/plugin/skills/session-history/EXAMPLES.mdnew file mode 100644index 00000000..e58654f6--- /dev/null+++ b/plugin/skills/session-history/EXAMPLES.md@@ -0,0 +1,59 @@+# session-history worked examples++## 1. Standard timeline++User: "Show me the session history."++Invocation:++```json+memory_sessions { "limit": 20 }+```++Response:++```json+{+ "sessions": [+ { "id": "7f3a9c21", "project": "app", "startedAt": "2026-06-07T09:00:00Z",+ "status": "completed", "observationCount": 14,+ "summary": "Reworked refresh rotation",+ "highlights": [ { "type": "decision", "title": "Rotate refresh tokens on every use" } ] },+ { "id": "b21d004e", "project": "app", "startedAt": "2026-06-05T14:00:00Z",+ "status": "completed", "observationCount": 9,+ "highlights": [ { "type": "code", "title": "limit.ts counts per-IP" } ] }+ ]+}+```++Present:++> - `7f3a9c2` app, 2026-06-07 09:00, completed, 14 obs+> - decision: Rotate refresh tokens on every use (summary: Reworked refresh rotation)+> - `b21d004` app, 2026-06-05 14:00, completed, 9 obs+> - code: limit.ts counts per-IP++## 2. Session with no observations++If a returned session has `observationCount: 0`, list it but say so:++> - `c98f110` app, 2026-06-04 11:00, abandoned, 0 obs (no recorded work)++## 3. Empty history++User: "What did we do last time?"++```json+memory_sessions { "limit": 20 }+```++Response:++```json+{ "sessions": [] }+```++Present:++> No recorded sessions yet for this project. Once you work with memory capture+> on, they will show here. Use `remember` to save a note now.diff --git a/plugin/skills/session-history/SKILL.md b/plugin/skills/session-history/SKILL.mdindex c33a1fe5..dd514798 100644--- a/plugin/skills/session-history/SKILL.md+++ b/plugin/skills/session-history/SKILL.md@@ -1,18 +1,61 @@---name: session-history-description: Show what happened in recent past sessions on this project. Use when user asks "what did we do last time", "session history", "past sessions", or wants an overview of previous work.+description: Show what happened in recent past sessions on this project as a clean timeline. Use when the user asks "what did we do last time", "session history", "past sessions", or wants an overview of previous work.user-invocable: true----Fetch recent session history using the `memory_sessions` MCP tool (provided by the agentmemory server that this plugin wires up automatically via `.mcp.json`). Pass `limit: 20` to get a meaningful window.+The user wants an overview of recent sessions on this project.-Present the returned sessions in reverse chronological order:-- Show the session ID (first 8 chars), project, start time, and status-- For each session with observations, show the key highlights (type + title)-- Note the total observation count per session-- If a session summary exists, surface the title and the key decisions+## Quick start-Format as a clean timeline. **Do NOT make up sessions** — only show what the MCP tool actually returned. If `memory_sessions` isn't available, the stdio MCP shim didn't start — tell the user to:-1. Run `/plugin list` in Claude Code and confirm `agentmemory` shows as enabled.-2. Restart Claude Code (the plugin's `.mcp.json` is only read on startup).-3. Check `/mcp` to see whether the `agentmemory` MCP server is connected.+```json+memory_sessions { "limit": 20 }+```++Expected output:++```text+7f3a9c2 · app · 2026-06-07 09:00 · completed · 14 obs+ - decision: Rotate refresh tokens on every use+b21d004 · app · 2026-06-05 14:00 · completed · 9 obs+ - code: limit.ts counts per-IP+```++## Why++Only show sessions and observations the tool returned. An empty history is a+real answer, never a cue to invent past work.++## Workflow++1. Call `memory_sessions` with `limit: 20` for a meaningful window.+2. Present in reverse chronological order: session id (first 8), project, start+ time, status.+3. For sessions with observations, show the key highlights (type plus title).+4. Note the total observation count per session.+5. When a session summary exists, surface its title and the key decisions.++## Anti-patterns++WRONG: the tool returns two sessions, you describe "several sessions of steady+progress" and add ones you remember from the conversation.++RIGHT: show exactly the two sessions returned, each with its real id, status, and+observation count.++## Checklist++- Every session shown came from the tool response.+- Order is reverse-chronological.+- Per-session observation counts match the response.+- No session or highlight was invented or merged.++## See also++- `recap`: same data grouped by date with highlights.+- `handoff`: jump straight into the most recent session.+- `recall`: search across all sessions by topic.++## Troubleshooting++See ../_shared/TROUBLESHOOTING.md if `memory_sessions` is not available.diff --git a/plugin/skills/write-agentmemory-skill/SKILL.md b/plugin/skills/write-agentmemory-skill/SKILL.mdnew file mode 100644index 00000000..d46a1910--- /dev/null+++ b/plugin/skills/write-agentmemory-skill/SKILL.md@@ -0,0 +1,40 @@+---+name: write-agentmemory-skill+description: The house format and rules for writing or updating an agentmemory skill. Use when adding a new skill, restructuring an existing one, or reviewing a skill contribution for consistency.+user-invocable: false+---++agentmemory skills follow one tiered format so they stay skimmable, accurate, and current. Match it exactly.++## Directory layout++```text+plugin/skills/<name>/+ SKILL.md (required, under 100 lines)+ REFERENCE.md (optional, dense facts; auto-generate data tables)+ EXAMPLES.md (optional, worked transcripts)+```++## SKILL.md rules++- Frontmatter: `name`, `description`, optional `argument-hint`, and `user-invocable`. Set `user-invocable: true` only for skills the user runs as a slash command; reference and knowledge skills are `false`.+- Description is two sentences and the only thing the agent sees when deciding to load the skill. Sentence one states the capability. Sentence two starts "Use when" and lists concrete triggers. Keep it distinct from sibling skills, under 1024 chars, third person.+- Body order: Quick start (one concrete example), Why (the governing principle), Workflow (numbered steps with decision gates), Anti-patterns (a WRONG vs RIGHT callout for the top mistake), Checklist, See also (cross-link siblings), Reference or Troubleshooting pointer.+- Stay under 100 lines. Move dense facts to REFERENCE.md and examples to EXAMPLES.md.+- Cross-references link one level deep only. Shared recovery steps live in `../_shared/TROUBLESHOOTING.md`, never inlined.++## Keep it current++Facts that exist in source (tool names and parameters, REST endpoints, env vars, connect adapters, hook events) are generated, never hand-typed. Edit the source, then run `npm run skills:gen`. CI runs `npm run skills:check` and fails on drift, so generated tables cannot fall behind the code.++## Style++No external or competitor product names. No emojis. No em-dashes. No filler. State the thing and stop.++## Checklist++- Description has a "Use when" sentence with real triggers.+- SKILL.md is under 100 lines.+- No time-sensitive claims and no duplicated troubleshooting block.+- Concrete example present; generated facts come from the generator.+- Cross-links resolve and go one level deep.diff --git a/scripts/skills/check.ts b/scripts/skills/check.tsnew file mode 100644index 00000000..860e1e78--- /dev/null+++ b/scripts/skills/check.ts@@ -0,0 +1,80 @@+import { readFileSync, readdirSync, existsSync } from "node:fs";+import { join, dirname } from "node:path";+import { fileURLToPath } from "node:url";++const HERE = dirname(fileURLToPath(import.meta.url));+const ROOT = join(HERE, "..", "..");+const SKILLS = join(ROOT, "plugin", "skills");++const errors: string[] = [];+const MAX_LINES = 100;+const DUP_MARKER = "/plugin list";++function parseFrontmatter(text: string): Record<string, string> | null {+ if (!text.startsWith("---")) return null;+ const end = text.indexOf("\n---", 3);+ if (end === -1) return null;+ const body = text.slice(3, end);+ const out: Record<string, string> = {};+ for (const line of body.split("\n")) {+ const m = /^([a-zA-Z_-]+):\s*(.*)$/.exec(line.trim());+ if (m) out[m[1]] = m[2];+ }+ return out;+}++const dirs = readdirSync(SKILLS, { withFileTypes: true })+ .filter((e) => e.isDirectory() && !e.name.startsWith("_"))+ .map((e) => e.name);++for (const name of dirs) {+ const skillFile = join(SKILLS, name, "SKILL.md");+ if (!existsSync(skillFile)) {+ errors.push(`${name}: missing SKILL.md`);+ continue;+ }+ const text = readFileSync(skillFile, "utf8");+ const rel = `plugin/skills/${name}/SKILL.md`;++ const fm = parseFrontmatter(text);+ if (!fm) {+ errors.push(`${rel}: missing or malformed frontmatter`);+ } else {+ if (!fm.name) errors.push(`${rel}: frontmatter missing 'name'`);+ if (fm.name && fm.name !== name) errors.push(`${rel}: frontmatter name '${fm.name}' != dir '${name}'`);+ if (!fm.description) errors.push(`${rel}: frontmatter missing 'description'`);+ else {+ if (!/use when/i.test(fm.description)) errors.push(`${rel}: description must contain a "Use when ..." trigger sentence`);+ if (fm.description.length > 1024) errors.push(`${rel}: description exceeds 1024 chars`);+ }+ }++ const lines = text.split("\n").length;+ if (lines > MAX_LINES) errors.push(`${rel}: ${lines} lines (max ${MAX_LINES}); move detail into REFERENCE.md or EXAMPLES.md`);++ const body = fm ? text.slice(text.indexOf("\n---", 3) + 4) : text;+ if (body.includes(DUP_MARKER)) {+ errors.push(`${rel}: inlines the shared troubleshooting block; reference ../_shared/TROUBLESHOOTING.md instead`);+ }+}++if (!existsSync(join(SKILLS, "_shared", "TROUBLESHOOTING.md"))) {+ errors.push(`_shared/TROUBLESHOOTING.md is missing`);+}++const pluginJson = join(ROOT, "plugin", "plugin.json");+if (existsSync(pluginJson)) {+ const desc = (JSON.parse(readFileSync(pluginJson, "utf8")).description as string) ?? "";+ const m = /(\d+)\s+skills/.exec(desc);+ if (!m) errors.push(`plugin/plugin.json: description should state the skill count as "N skills"`);+ else if (Number(m[1]) !== dirs.length) {+ errors.push(`plugin/plugin.json: description says ${m[1]} skills but ${dirs.length} skill dirs exist`);+ }+}++if (errors.length) {+ console.error("Skill lint failed:");+ for (const e of errors) console.error(` - ${e}`);+ process.exit(1);+}+console.log(`Skill lint passed: ${dirs.length} skills checked.`);diff --git a/scripts/skills/generate.ts b/scripts/skills/generate.tsnew file mode 100644index 00000000..44ccf941--- /dev/null+++ b/scripts/skills/generate.ts@@ -0,0 +1,170 @@+import { readFileSync, writeFileSync, readdirSync, existsSync } from "node:fs";+import { join, dirname } from "node:path";+import { fileURLToPath } from "node:url";+import { getAllTools, ESSENTIAL_TOOLS } from "../../src/mcp/tools-registry.js";+import { ADAPTERS } from "../../src/cli/connect/index.js";++const HERE = dirname(fileURLToPath(import.meta.url));+const ROOT = join(HERE, "..", "..");+const SKILLS = join(ROOT, "plugin", "skills");+const SRC = join(ROOT, "src");++const check = process.argv.includes("--check");++function clean(s: string): string {+ return s.replace(/\s*[—–]\s*/g, ", ");+}++function block(key: string, body: string): { open: string; close: string; full: string } {+ const open = `<!-- AUTOGEN:${key} START - generated by scripts/skills/generate.ts, do not edit by hand -->`;+ const close = `<!-- AUTOGEN:${key} END -->`;+ return { open, close, full: `${open}\n${body.trim()}\n${close}` };+}++function applyBlock(file: string, key: string, body: string): void {+ const { open, close, full } = block(key, body);+ const existing = existsSync(file) ? readFileSync(file, "utf8") : "";+ let next: string;+ if (existing.includes(open) && existing.includes(close)) {+ const start = existing.indexOf(open);+ const end = existing.indexOf(close) + close.length;+ next = existing.slice(0, start) + full + existing.slice(end);+ } else if (existing.trim()) {+ next = `${existing.trimEnd()}\n\n${full}\n`;+ } else {+ next = `${full}\n`;+ }+ if (check) {+ if (existing !== next) {+ console.error(`DRIFT: ${file.replace(ROOT + "/", "")} (AUTOGEN:${key} out of date — run \`npm run skills:gen\`)`);+ process.exitCode = 1;+ }+ return;+ }+ if (existing !== next) {+ writeFileSync(file, next);+ console.log(`wrote AUTOGEN:${key} -> ${file.replace(ROOT + "/", "")}`);+ }+}++function walk(dir: string, out: string[] = []): string[] {+ for (const e of readdirSync(dir, { withFileTypes: true })) {+ const full = join(dir, e.name);+ if (e.isDirectory()) {+ if (e.name === "node_modules" || e.name === "dist") continue;+ walk(full, out);+ } else if (e.name.endsWith(".ts")) {+ out.push(full);+ }+ }+ return out;+}++function mdEscape(s: string): string {+ return clean(s.replace(/\|/g, "\\|").replace(/\n/g, " ")).trim();+}++function tools(): string {+ const all = getAllTools();+ const lines = [+ `agentmemory exposes ${all.length} MCP tools. ${ESSENTIAL_TOOLS.size} are in the lean core set (\`--tools core\` or \`AGENTMEMORY_TOOLS=core\`); the rest load with \`--tools all\` (default).`,+ "",+ "| Tool | Core | Parameters | Purpose |",+ "| --- | --- | --- | --- |",+ ];+ for (const t of all.sort((a, b) => a.name.localeCompare(b.name))) {+ const required = new Set(t.inputSchema.required ?? []);+ const params = Object.entries(t.inputSchema.properties ?? {})+ .map(([n, s]) => `\`${n}\`${required.has(n) ? "*" : ""}: ${s.type}`)+ .join(", ") || "none";+ const core = ESSENTIAL_TOOLS.has(t.name) ? "yes" : "";+ lines.push(`| \`${t.name}\` | ${core} | ${mdEscape(params)} | ${mdEscape(t.description)} |`);+ }+ lines.push("", "`*` marks required parameters.");+ return lines.join("\n");+}++function rest(): string {+ const text = readFileSync(join(SRC, "triggers", "api.ts"), "utf8");+ const found: { path: string; method: string }[] = [];+ const re = /api_path:\s*"([^"]+)"/g;+ let m: RegExpExecArray | null;+ while ((m = re.exec(text)) !== null) {+ const path = m[1];+ const win = text.slice(Math.max(0, m.index - 140), m.index + 140);+ const mm = /http_method:\s*"([A-Z]+)"/.exec(win);+ found.push({ path, method: mm ? mm[1] : "POST" });+ }+ const seen = new Set<string>();+ const rows = found+ .filter((e) => (seen.has(e.path) ? false : (seen.add(e.path), true)))+ .sort((a, b) => a.path.localeCompare(b.path));+ const lines = [+ `The REST API is the primary surface. All paths are under \`http://localhost:3111\` (override with \`--port\`). When \`AGENTMEMORY_SECRET\` is set, send \`Authorization: Bearer $AGENTMEMORY_SECRET\`; localhost is otherwise open.`,+ "",+ `${rows.length} registered endpoints:`,+ "",+ "| Method | Path |",+ "| --- | --- |",+ ...rows.map((e) => `| ${e.method} | \`${e.path}\` |`),+ ];+ return lines.join("\n");+}++function env(): string {+ const files = walk(SRC);+ const vars = new Set<string>();+ for (const f of files) {+ const text = readFileSync(f, "utf8");+ const re = /AGENTMEMORY_[A-Z0-9_]+/g;+ let m: RegExpExecArray | null;+ while ((m = re.exec(text)) !== null) {+ if (!m[0].endsWith("__")) vars.add(m[0]);+ }+ }+ const sorted = [...vars].sort();+ const lines = [+ `Configuration is read from the environment and from \`~/.agentmemory/.env\` (no \`export\` prefix). ${sorted.length} recognized variables:`,+ "",+ ...sorted.map((v) => `- \`${v}\``),+ ];+ return lines.join("\n");+}++function agents(): string {+ const lines = [+ `\`agentmemory connect <agent>\` wires the memory server into a host agent. ${ADAPTERS.length} adapters:`,+ "",+ "| Agent | Name | Protocol |",+ "| --- | --- | --- |",+ ];+ for (const a of [...ADAPTERS].sort((x, y) => x.name.localeCompare(y.name))) {+ const note = (a.protocolNote ?? "").replace(/^[→\s]+/, "");+ lines.push(`| ${mdEscape(a.displayName)} | \`${a.name}\` | ${mdEscape(note) || "MCP"} |`);+ }+ return lines.join("\n");+}++function hooks(): string {+ const file = join(ROOT, "plugin", "hooks", "hooks.json");+ const json = JSON.parse(readFileSync(file, "utf8")) as { hooks?: Record<string, unknown> };+ const events = Object.keys(json.hooks ?? {}).sort();+ const lines = [+ `The Claude Code plugin registers hooks on ${events.length} lifecycle events to capture observations automatically:`,+ "",+ ...events.map((e) => `- \`${e}\``),+ ];+ return lines.join("\n");+}++applyBlock(join(SKILLS, "agentmemory-mcp-tools", "REFERENCE.md"), "tools", tools());+applyBlock(join(SKILLS, "agentmemory-rest-api", "REFERENCE.md"), "rest", rest());+applyBlock(join(SKILLS, "agentmemory-config", "REFERENCE.md"), "env", env());+applyBlock(join(SKILLS, "agentmemory-agents", "REFERENCE.md"), "agents", agents());+applyBlock(join(SKILLS, "agentmemory-hooks", "REFERENCE.md"), "hooks", hooks());++if (check && process.exitCode) {+ console.error("\nSkill reference docs are stale. Run: npm run skills:gen");+} else if (!check) {+ console.log("skills reference generation complete");+}