Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: reconcile 2.6 user-surface findings
AkitaOnRails73fe2a30fbb8
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 44a4d48b..75a72da7 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -2368,9 +2368,9 @@ pub enum AgentChoice {/// existing key-based extraction applies (#1040). No bare `copilot`/// alias: that word is already `install-mcp --client copilot`'s alias for/// the unrelated VS Code MCP client. NOTE: Copilot CLI reads a top-level- /// `additionalContext` on `SessionStart`, not Claude Code's envelope, so- /// capture works but handoff injection does not yet — recover the prior- /// session's handoff via the MCP `memory_handoff_accept` tool.+ /// `additionalContext` on `SessionStart`, not Claude Code's envelope, and+ /// the hook prints exactly that, so both capture and handoff injection+ /// work.#[value(name = "copilot-cli")]CopilotCli,}@@ -2607,7 +2607,9 @@ pub enum McpClient {/// GitHub Copilot CLI — `$COPILOT_HOME/mcp-config.json` (default/// `~/.copilot/mcp-config.json`), servers under the root `mcpServers` map/// with `type: "http"` + `url` + optional `headers` (#1040). Pair with- /// `install-hooks --agent copilot-cli` for lifecycle capture. Not to be+ /// `install-hooks --agent copilot-cli` for lifecycle capture and+ /// `SessionStart` handoff delivery via Copilot's top-level+ /// `additionalContext`. Not to be/// confused with `vscode-copilot` (alias `copilot`), the VS Code agent/// mode client.#[value(name = "copilot-cli")]diff --git a/docs/install.md b/docs/install.mdindex a22ce10d..8c9e5231 100644--- a/docs/install.md+++ b/docs/install.md@@ -709,7 +709,10 @@ agent's environment; no `install-hooks` rerun is needed:| `AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS` | 8 failed passes | non-negative integer | failed drain passes before dropping an event; `0` disables only attempt-count drops |The retry setting can also be written as `max_attempts` under `[hook_spool]` in-`<data_dir>/config.toml`; the runtime environment wins when both are set. A zero+`<data_dir>/config.toml`; the runtime environment wins when both are set. A set+but invalid `AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS` value (non-numeric) falls back to+the built-in default of 8, overriding any `config.toml` value — same convention+as the timing vars. A zerovalue still leaves the 7-day age limit and 10,000-file spool cap active.Timing values must be positive whole minutes. Missing, empty, non-numeric, ordiff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.mdindex 272fb1e9..7fb7f17a 100644--- a/docs/lifecycle-ops.md+++ b/docs/lifecycle-ops.md@@ -21,6 +21,7 @@ on a homelab box where mistakes are harder to undo.| `reclaim-ledger-versions` | ✅ yes | superseded pre-#660 ledger page *versions* only | no (the latest page version stays) | Dry-run by default; needs `--confirm` to delete. Online through the writer actor, safe alongside the live writer. Content-gated: only non-latest, non-decay `log.md`/`log-YYYY-MM.md` versions whose body opens with a ledger hook entry are removed; a real page that merely shares the name is untouched. `--compact` additionally rebuilds FTS and `VACUUM`s to reclaim the freed bytes. || `checkpoints` | ✅ yes | no | n/a | Lists recent wiki git checkpoints. Read-only. || `restore-page --path --from` | ✅ yes | overwrites one markdown page version | yes (restore another checkpoint) | Restores one page from wiki git history, reindexes it into SQLite, and writes a post-restore checkpoint. Does not restore DB-only state. |+| `backup-agents --to` / `restore-agents --from <tarball>` | ✅ yes (client-side; never touches the server or its data dir) | no | yes (`restore-agents --apply` keeps timestamped copies of overwritten files) | Agent-config assets, not wiki/db: MCP configs (redacted unless `--include-secrets`), hook configs, instructions, skills, plugins. `restore-agents` is a dry run by default; `--apply` writes to disk and `--force` overwrites existing or differing targets. Non-MCP assets are restored verbatim and may contain secrets — only `--apply` an archive whose source you trust. || `restore --from <tarball>` | ❌ **stop the server first** | overwrites the data dir | no (without prior backup) | Refuses if any sibling `ai-memory` process is alive (sysinfo guard). Stages and verifies the archive before swapping it in, so a failed restore leaves `wiki/` and `db/` as they were. || `reset --confirm` | ❌ **stop the server first** | yes, all data | no | Refuses if any sibling `ai-memory` process is alive (sysinfo guard). || `reindex` | ❌ **stop the server first** | no wiki wipe; requires a clean DB | only with prior DB backup | Rebuilds pages/links/FTS from `wiki/` using `_meta.md` manifests. Refuses if SQLite already has rows so stale DB-only state cannot survive silently. |diff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex dd114010..dbf8d5f4 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -152,7 +152,7 @@ metadata.> **One-shot tip:** every snippet below is also reachable from the> CLI:> ```bash-> ai-memory install-mcp --client gemini-cli # or cursor / claude-desktop / openclaw / omp / pi / antigravity-cli / grok / kimi-code / kiro-cli / command-code / swival / devin / zero / zcode / vscode-copilot / zed / muse+> ai-memory install-mcp --client gemini-cli # or cursor / claude-desktop / openclaw / omp / pi / antigravity-cli / grok / kimi-code / kiro-cli / command-code / swival / devin / zero / zcode / copilot-cli / vscode-copilot / zed / muse> ```---@@ -280,10 +280,11 @@ run without `--server-url` reads the URL and token back from this entry.The hook installer wires Claude Code's nine events plus `PostToolUseFailure`with PascalCase names, which makes Copilot send its VS Code/Claude-compatible-payload; native installs spool events locally and enforce capture exclusions.-Copilot reads a top-level `additionalContext` from `SessionStart` stdout, not-the `hookSpecificOutput` envelope ai-memory prints, so the prior session's-handoff is recovered with `memory_handoff_list` and `memory_handoff_accept`.+payload; native installs spool events locally and enforce capture exclusions. The+`SessionStart` hook delivers the prior session's handoff: Copilot reads a+top-level `additionalContext` from `SessionStart` stdout (not Claude Code's+`hookSpecificOutput` envelope), and the hook prints exactly that, or `{}` when+nothing is pending.- Sources: <https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers>,<https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference>,diff --git a/docs/wiki-migrations.md b/docs/wiki-migrations.mdindex 2e5dc66a..38a76f6a 100644--- a/docs/wiki-migrations.md+++ b/docs/wiki-migrations.md@@ -153,7 +153,7 @@ command or a consolidation job, not a migration.If a migration needs to update the SQLite index alongside the file moves, use`WriterHandle` methods. Never open a second `Connection`; never call`ops::*` directly from a migration. This upholds invariant #2 (single-writer-actor) from `CLAUDE.md`.+actor) from `AGENTS.md`.## Tracking