Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: document install-hooks --scope project
Talysson de Oliveira Cassianoe78157f8c4d8
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ce893e3d..c6827ec6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- Added `install-hooks --agent claude-code --scope project`, which writes the+ hook configuration to the checkout's gitignored `.claude/settings.local.json`+ (at the git root, where Claude Code reads it) instead of the user-level+ `settings.json`, so capture is opted in per repository. The installer warns+ when that file is not ignored by git and refuses the inline-token fallback+ for it; `uninstall` run inside the checkout sweeps it; `upgrade` and the+ `ai-memory run` auto-wire no longer add user-level Claude Code hooks on top+ of a project-scoped install. (#NNN)- Added explicit MCP behavior annotations (title, read-only, destructive,idempotent, and open-world hints) to all 23 tools. Reordered the MCP serverinstructions so scope selection, untrusted-memory handling, deliberatediff --git a/docs/cookbook.md b/docs/cookbook.mdindex bb141562..0a2a206c 100644--- a/docs/cookbook.md+++ b/docs/cookbook.md@@ -240,6 +240,24 @@ ai-memory run --yolo claudeSee [`design-yolo-safety-ai-jail.md`](design-yolo-safety-ai-jail.md) for thefull contract.+## Recipe: capture only some repositories++`install-hooks --agent claude-code --apply` wires the hooks user-wide+(`~/.claude/settings.json`), so every Claude Code session is captured and you+exclude paths with `[capture] ignore_paths` in `.ai-memory.toml`. To opt in+per repository instead, run from inside the checkout:++```bash+ai-memory install-hooks --agent claude-code --scope project --apply+```++This writes the repository's gitignored `.claude/settings.local.json` (at the+git root, where Claude Code reads it) and leaves the user-level file alone.+Pick one scope per machine: Claude Code merges project and user hooks. The+installer warns when the file is not git-ignored, and `ai-memory uninstall+--only hooks --apply` from inside the checkout removes the entries again.+Claude Code only; other harnesses keep their user-level hook files.+## Recipe: send different repositories to different serversOne machine, several organisations, each with its own ai-memory server.diff --git a/docs/install.md b/docs/install.mdindex 0066cfce..f6a83213 100644--- a/docs/install.md+++ b/docs/install.md@@ -91,6 +91,31 @@ ai-memory install-mcp --client claude-code --applyai-memory install-hooks --agent claude-code --apply```+That wires the hooks user-wide (`~/.claude/settings.json`), so every Claude+Code session is captured. To opt in per repository instead, run from inside+the checkout:++```bash+ai-memory install-hooks --agent claude-code --scope project --apply+```++This writes the repository's gitignored `.claude/settings.local.json` at the+git root (the main checkout's root from a worktree), which is where Claude Code+reads that file even when launched from a subdirectory — see+[where Claude Code looks for each file](https://code.claude.com/docs/en/settings#where-claude-code-looks-for-each-file);+on Windows it reads the launch directory instead, so launch from the root+there. The user-level file is left alone. Claude Code merges the project+file's hooks with any user-level ones, so pick one scope per machine.+The installer warns when the file is not ignored by git (Claude Code adds it+to your global excludes only when it creates the file itself) and refuses to+embed a bearer token in it when the token cannot be persisted under the data+dir. `ai-memory uninstall --only hooks --apply` run from inside the checkout+removes the entries again; run elsewhere it does not reach into the+repository. `upgrade` and the `ai-memory run` auto-wire leave the user-level+file alone while a project-scoped install is the only one present.+`setup-agent` and `backup-agents` only know the user-level file. Claude Code+only; other agents keep their user-level hook files.+`--session-aware` is an optional Claude Code MCP mode:```bash@@ -111,7 +136,9 @@ own config resolution: `install-mcp` writes the MCP registration to(instead of `~/.claude/settings.json`), and `install-skills --scope global`uses `$CLAUDE_CONFIG_DIR/skills` (instead of `~/.claude/skills`). `uninstall`sweeps the active relocated paths alongside the home defaults. It cannot-discover an older arbitrary `CLAUDE_CONFIG_DIR` that is no longer set. The+discover an older arbitrary `CLAUDE_CONFIG_DIR` that is no longer set.+`install-hooks --scope project` ignores the variable: Claude Code resolves+project files from the checkout, not from the config dir. TheDocker wrapper forwards the variable for config roots under its existing`$HOME` bind mount; use the native binary when the relocated root is outside`$HOME`.@@ -1175,8 +1202,10 @@ Pool reads lifecycle hooks from a project-scoped `.poolside/settings.yaml` atthe root of each repository it runs in — there is no user-global hook file forai-memory to merge. `install-hooks --agent pool` (alias `poolside`) thereforestages the hook scripts to the stable user-global location and prints a-ready-to-paste `hooks:` snippet; ai-memory deliberately does not write files-inside your repositories.+ready-to-paste `hooks:` snippet; ai-memory deliberately does not write+committed files inside your repositories (the gitignored+`.claude/settings.local.json` that `--scope project` writes for Claude Code is+the one exception).```bash# Stage the scripts and print the snippet to paste into@@ -2248,7 +2277,7 @@ docker run --rm akitaonrails/ai-memory:latest --help # full subcommand tree| `auth login copilot` | same data volume as the server | Store a GitHub token for the optional `copilot` LLM provider || `auth login oidc-device` | same developer data dir as native hooks and thin-client CLI commands | Store a per-developer OIDC device token for native hook authentication and HTTP CLI fallback auth || `install-mcp --client` | `docker run --rm` | MCP-config snippet per client |-| `install-hooks --agent` | `docker run --rm` | Hook-config snippet for an existing hooks dir |+| `install-hooks --agent [--scope project]` | `docker run --rm` | Hook-config snippet for an existing hooks dir; `--scope project` targets the checkout's `.claude/settings.local.json` (Claude Code only) || `setup-agent --agent --to --host-prefix` | `docker run --rm -v` | Extract bundled scripts + print config (one-shot) || `install-instructions [--target] [--print] [--no-skills]` | same host environment used for the agent prompt files | Install or update the slim CLAUDE.md / AGENTS.md routing block and, by default, the managed ai-memory Agent Skills || `install-skills [--scope] [--agent]` | same host environment used for the agent skill dirs | Install or update only the managed ai-memory Agent Skills |diff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex 99587fb5..a9379906 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -33,7 +33,7 @@| ZCode | Supported | `install-mcp --client zcode --apply` merges a native HTTP entry (strict schema: `type`/`url`/`headers` only) into the `mcp.servers` map of `~/.zcode/cli/config.json`, preserving sibling servers. ZCode (z.ai, `zcode`, alias `zai`). Lifecycle-hook capture via `install-hooks --agent zcode --apply`: exec-form native commands (`type: "process"`, no shell) merged into the root `hooks` block of `~/.zcode/cli/config.json` around any third-party hooks; native commands enforce capture exclusions. Six documented triggers (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`); `PostToolUseFailure` fires instead of `PostToolUse` when a tool throws and lands on the same capture channel with the error preserved. `PermissionRequest` is deliberately not installed — its hook chain races the interactive permission client, so passive capture of that event is unreliable by design. No true session-end — `Stop` is a per-turn boundary, so run `ai-memory finalize-session --agent zcode` after the final turn. Unlike Pool and Zero, `SessionStart` stdout injection works (`hookSpecificOutput.additionalContext`, verified live against the embedded engine v0.16.5), so the prior session's handoff is delivered automatically. No first-party `install-mcp` client and no managed workstream are claimed yet. || Kimi Code | Supported | MCP config (`url` entry in `~/.kimi-code/mcp.json`) + lifecycle hooks (`[[hooks]]` in `~/.kimi-code/config.toml`, 10 events including subagent start/stop and `PostToolUseFailure` for tool-failure capture); both paths honor `$KIMI_CODE_HOME`. Handoffs inject via `UserPromptSubmit` stdout (Kimi Code discards `SessionStart` hook stdout); `ai-memory run kimi` adds managed workstream resume. || Kiro CLI | Supported | MCP config uses `install-mcp --client kiro-cli` (alias `kiro`) and Kiro's Bedrock-compatible schema flavor. `install-hooks --agent kiro-cli` merges v2 hooks into existing agent configs; the explicit `--agent kiro-cli-v3` target writes the incompatible standalone v3 registration. Both preserve unrelated entries, honor `$KIRO_HOME`, enforce capture exclusions, and inject pending handoffs at session start. Kiro has no true SessionEnd hook; use `ai-memory finalize-session --agent kiro-cli`, with `--session-id <uuid>` for concurrent sessions, unless it is an interactive session launched with `ai-memory run kiro`, which finalizes it automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `ai-memory run kiro` manages v2; add `--v3`, `--mode`, or `--agent-engine v3` for version-safe v3 resume. |-| Pool | Hooks-only | Poolside Agent CLI (`pool`). Lifecycle-hook capture via `install-hooks --agent pool` (alias `poolside`): Pool reads project-scoped hooks from the repo-root `.poolside/settings.yaml`, so ai-memory stages the scripts and prints a ready-to-paste `hooks:` snippet rather than writing project-local files; native commands enforce capture exclusions. Five Claude-shaped events (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) and no true session-end — `Stop` is a turn boundary, so run `ai-memory finalize-session --agent pool` after the final turn. `SessionStart` stdout injection is not demonstrated, so capture works but handoff injection does not — recover handoffs via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. No first-party `install-mcp` client and no managed workstream (`ai-memory run pool`) are claimed: Pool's native session-store contract is not demonstrated (see [`docs/managed-harness-contributions.md`](managed-harness-contributions.md)). Verified against Poolside CLI v1.0.16. |+| Pool | Hooks-only | Poolside Agent CLI (`pool`). Lifecycle-hook capture via `install-hooks --agent pool` (alias `poolside`): Pool reads project-scoped hooks from the repo-root `.poolside/settings.yaml`, so ai-memory stages the scripts and prints a ready-to-paste `hooks:` snippet rather than writing committed project files; native commands enforce capture exclusions. Five Claude-shaped events (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) and no true session-end — `Stop` is a turn boundary, so run `ai-memory finalize-session --agent pool` after the final turn. `SessionStart` stdout injection is not demonstrated, so capture works but handoff injection does not — recover handoffs via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. No first-party `install-mcp` client and no managed workstream (`ai-memory run pool`) are claimed: Pool's native session-store contract is not demonstrated (see [`docs/managed-harness-contributions.md`](managed-harness-contributions.md)). Verified against Poolside CLI v1.0.16. || VS Code Copilot | MCP-only | `.vscode/mcp.json` for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet). || Zed | MCP-only | Native remote MCP under `context_servers` in Zed's user `settings.json`; no lifecycle hooks or managed-workstream support. || Muse Code | MCP-only | `install-mcp --client muse` merges a native streamable-HTTP entry with bearer `headers` into the snake_case `mcp_servers` map of `~/.config/muse/settings.json`, preserving sibling servers. The writer adds the mandatory `"schema_version": 1` when absent (without it every `muse` command fails at startup) and never rewrites an existing value, and it sets `"mode": "optional"` because Muse's default `required` aborts the whole run when the server is unreachable. Skills need no extra step: Muse reads `~/.agents/skills`, which `install-skills` already writes. Lifecycle capture and managed workstreams are not claimed — Muse documents a hook surface, but the output contract of its `SessionStart` event is not specified. |