Skip to content

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.rs
index 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.md
index 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 zero
value 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, or
diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.md
index 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.md
index 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.md
index 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