Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
Merge PR #711: add Muse Code as an MCP-only install-mcp client (#659)
AkitaOnRails817cde174b92
diff --cc CHANGELOG.mdindex 4c736a77,5b28e272..95ec65d4--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -8,74 -8,19 +8,87 @@@ and this project adheres to [Semantic V## [Unreleased]### Added+- Page-grain ingestion windows (`pages.valid_from` / `valid_to`, V62) and+ a second `as_of` stream: `memory_query(as_of=T)` now fuses the entity+ timeline with version-filtered full-text search over the page versions+ alive at T, using the default path's RRF (k=60) plus the same bounded+ authority adjustment — current-index relevance over knowledge valid at T. This+ answers entity-less pages and paraphrased audit questions ("which+ database were we on during the outage?") that the entity-only lookup+ missed. `explain=true` reports both streams (`streams_active:+ ["entity", "fts"]`) with per-stream ranks and RRF contributions.+ Vector, graph, and the raw-observation fallback stay out of audit mode;+ the default (no `as_of`) path is unchanged. Every retire path+ (supersede, decay, reorg graveyard, move-regenerate) closes both grains+ in the same transaction, and the V62 backfill closes successor-less+ retirements at the decay marker, existing entity-link close, or+ `updated_at` fallback, preserving recorded reorg/move history.+ Phase B world-time stays deferred. (#656)+- `[retrieval]` section with two opt-in ranking signals, both off by default+ so unconfigured stores rank exactly as before. `query_intent` routes+ lexically session-recall queries ("上次 / 之前那次…的会话 / last time /+ yesterday …") past the default session-page authority penalty+ (×0.77 combined kind/tier), with `session_recall_bonus` (default 0.25)+ sizing the lift; `abstract_vectors` adds a fifth RRF stream over the new+ `page_abstract_embeddings` table (V61) — the L0 layer: a page's+ frontmatter `abstract:` line is embedded on its own, at write time when an+ embedder is attached and by the same backfill as the body otherwise+ (a one-line summary embeds far more sharply than a+ multi-thousand-character body). Measured on a 138-query golden set over a+ production two-year wiki (FTS5 + entity + vector + graph, mis-tei+ Qwen3-Embedding-8B): hit@1 0.609 → 0.746 (+22%), NDCG@10 0.782 → 0.879+ (+12%) with both enabled; every unrouted category keeps its exact+ baseline ordering. Cross-checked on an independently built 99-query+ golden set against the same store: hit@1 0.556 → 0.626, NDCG@10+ 0.712 → 0.779 (+9.4%). Both signals are visible per hit in+ `memory_query(explain=true)` (`intent`, `intent_boost`,+ `abstract_rank`, `rrf.abstract`). (#672)+- `memory_handoff_list` lets no-stdout and MCP-only clients inspect open+ project handoffs without claiming or expiring them, then+ `memory_handoff_accept` can claim that exact `handoff_id` once. Grok,+ Zero, and other clients that discard SessionStart stdout no longer have+ to recover a baton by blindly accepting the latest row. Listing is+ owner-filtered like accept (own plus shared; root-only `any_owner`);+ it is not a second claim path, and Grok SessionStart still does not+ fetch `/handoff`. (#664)+- `install-instructions --compact` writes a slimmer managed routing block for+ projects that already have the detailed ai-memory Agent Skills installed. The+ compact block keeps the same start/end markers (so refresh/uninstall still+ find it), the untrusted-history security scaffold, and the cross-harness+ memory-of-record guidance; `full_block` and the default remain unchanged.+ (#675)+- `memory_install_self_routing` accepts `compact: Option<bool>` so agent-driven+ refreshes of a compact-installed file preserve the compact routing block+ instead of rewriting it back to full. (#685)+- The `openai-compat` provider now sends OpenRouter's app-attribution+ headers (`HTTP-Referer`, `X-Title`) by default when its base URL points+ at `openrouter.ai`, so ai-memory's usage shows up on OpenRouter's app+ leaderboard. An explicit `AI_MEMORY_LLM_HEADERS` entry for either header+ still wins, and a non-OpenRouter compat endpoint (Ollama, vLLM, LM+ Studio) never receives them. (#686)+- `ai-memory run` now accepts any `claude*`-prefixed harness name+ (`claude-corp`, `claude-personal`, ...), all resolving to the same+ `ManagedHarness::Claude`/`AgentKind::ClaudeCode` — no new session store,+ migration, or agent kind. This is for callers juggling more than one+ Claude account (e.g. Corporate and Personal): name each account's `PATH`+ wrapper script `claude-<account>` and pair it with `--executable+ claude-<account>` (bare names already resolve through `PATH`) so+ `ai-memory run claude-corp --executable claude-corp` and `ai-memory run+ claude-personal --executable claude-personal` each launch the right+ binary while reading clearly in shell history (#687).+ - `install-mcp --client muse` registers ai-memory with Meta's Muse Code,+ merging a native streamable-HTTP entry with bearer `headers` into the+ snake_case `mcp_servers` map of `~/.config/muse/settings.json` and+ preserving sibling servers. The writer adds the mandatory+ `"schema_version": 1` when it is absent — without that key every `muse`+ command fails at startup with `malformed settings file` — and never+ rewrites an existing value, so a future schema is not downgraded. The entry+ sets `"mode": "optional"` because Muse defaults it to `required`, which+ aborts the whole run when the memory server is unreachable. MCP-only:+ Muse documents a lifecycle hook surface, but the output contract of its+ `SessionStart` event is not specified, so capture and managed workstreams+ are not claimed. Skills need no extra step — Muse reads `~/.agents/skills`,+ which `install-skills` already writes (#659).### Changed- The managed routing snippet distinguishes a reviewed decision record kept indiff --cc docs/support-matrix.mdindex 917f45cd,59488f14..85d3e546--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@@ -31,9 -31,10 +31,10 @@@| 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. `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_accept`. 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`](docs/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 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`](docs/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. || Hermes Agent | Community | Core hook ingestion recognizes `agent=hermes` and Hermes' documented shell-hook `tool_name` / `tool_input` payload for concrete session attribution, tool-family titles, and capture exclusions. A community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is available, but no first-party installer is shipped; review its compatibility matrix, install/uninstall scripts, and secret handling before using it. Hermes ignores session-start hook stdout, so recover handoffs through MCP. || LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode (Go and Zen), OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. || Embedding providers | Supported | OpenAI, Voyage, Google Gemini, and keyless OpenAI-compatible endpoints such as Ollama, LM Studio, and vLLM. |