Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: add memory migration checklist

AkitaOnRails3dd2216c93e1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 09bd6962..a93c0873 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+- Documented a migration checklist for users replacing another memory tool:
+ export first, scrub secrets, curate legacy material into reviewed Markdown,
+ configure one client at a time, and remove stale hooks/plugins/MCP servers only
+ after ai-memory capture and retrieval are verified. (issue #115)
+
### Fixed
- Handoff selection no longer strands a detailed manual handoff behind a vague
auto one. A manual handoff (`memory_handoff_begin`) typically has no cwd while
diff --git a/README.md b/README.md
index 0cd0e622..4572864e 100644
--- a/README.md
+++ b/README.md
@@ -558,7 +558,7 @@ diagram, crate breakdown, schema notes, and invariants.
| File | What it is |
|---|---|
| [`docs/install.md`](docs/install.md) | **Installation cookbook.** Every agent CLI, every alternative (curl, source build, no-docker, no-auth), and the server-on-a-different-machine (homelab/LAN) walkthrough. Read after the Quick start if your setup doesn't match the happy path. |
-| [`docs/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, routing snippet, web UI, raw-wiki inspection, and rules-vs-facts workflow. |
+| [`docs/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, routing snippet, migration from other memory tools, web UI, raw-wiki inspection, and rules-vs-facts workflow. |
| [`docs/marker-file.md`](docs/marker-file.md) | `.ai-memory.toml` workspace/project routing for multi-client trees, mono-repos, worktrees, and work/personal separation. |
| [`docs/auto-scope.md`](docs/auto-scope.md) | `[auto_scope]` modes for shared servers: default single-slot routing, session-aware isolation, and multi-user `per_actor` behavior. |
| [`docs/macos.md`](docs/macos.md) | macOS install paths: native release binary (recommended), source build, the Docker wrapper, hook-platform notes, and current macOS limitations. |
diff --git a/docs/install.md b/docs/install.md
index b798b848..d4be146a 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1112,7 +1112,7 @@ write to `~/.local/share/ai-memory/hooks/`.
- [`docs/deploy.md`](deploy.md) - homelab deploy walkthrough
(`bin/deploy`, cloudflared TLS, env-file management)
- [`docs/usage.md`](usage.md) - handoffs, proactive querying, web UI,
- routing snippet, and raw-wiki inspection
+ routing snippet, migration from other memory tools, and raw-wiki inspection
- [`docs/mcp-install.md`](mcp-install.md) - per-client MCP config
reference for Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw, OMP, VS Code Copilot
- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) - what's actually
diff --git a/docs/usage.md b/docs/usage.md
index 6e5e8d85..eba0f52d 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -111,6 +111,50 @@ sources to the running server. It requires an LLM provider on the
server. See [Installation cookbook - bootstrap mid-project](install.md#bootstrap-mid-project)
for flags, token budgets, and source priority.
+## Migrate from another memory tool
+
+When replacing an existing memory system, treat the old data as untrusted
+historical input until you curate it. Do not pipe raw transcripts or old memory
+stores directly into ai-memory.
+
+Migration checklist:
+
+1. Export the old memory or history before changing hooks.
+2. Keep the raw export as an archive, not as current project truth.
+3. Scrub secrets, tokens, credentials, API keys, and raw logs that should not
+ become durable memory.
+4. Curate the useful material into reviewed Markdown pages under a temporary
+ docs directory or directly into `concepts/`, `decisions/`, `gotchas/`,
+ `procedures/`, `notes/`, or `_rules/`.
+5. If this checkout might be ambiguous, add `.ai-memory.toml` to pin the intended
+ workspace/project before importing or installing hooks.
+6. Start `ai-memory serve` locally and confirm `ai-memory status` can reach the
+ server before touching existing client configs.
+7. Import curated material first; avoid importing the full legacy raw history.
+8. Verify expected pages are searchable with `memory_query` or `ai-memory search`.
+9. Configure MCP and lifecycle hooks for one client at a time.
+10. Only after ai-memory capture and retrieval work, disable the old memory
+ hooks, plugins, or MCP servers.
+11. Search each client config for stale references to the old tool and remove
+ stale `Authorization` headers or env vars if bearer auth changed.
+12. Restart each agent CLI after changing hooks, plugins, or MCP config.
+
+Client cleanup hints:
+
+- Claude Code: check plugins, hooks, old SessionStart injection, and MCP servers.
+- Codex: check MCP config plus session/user-prompt/tool/compaction/stop hooks.
+- Gemini CLI and Antigravity CLI: check `settings.json` or equivalent hook/MCP
+ config files.
+- OpenCode, OpenClaw, and OMP: check MCP config and plugin/extension directories;
+ move old memory plugins to a disabled/quarantine directory before deleting.
+- VS Code Copilot and Claude Desktop: these are usually MCP-only, so confirm
+ whether the old tool was providing capture hooks elsewhere.
+
+If you want a visible startup reminder during the transition, keep it small. A
+rules-file note such as “Active memory: ai-memory; legacy export is historical
+reference only; use memory_query for retrieval” is safer than dumping large
+legacy context into every session.
+
If you use the ChatGPT/Codex OAuth provider, sign in once before starting the
server with `AI_MEMORY_LLM_PROVIDER=openai-oauth`: