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.mdindex 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 vagueauto one. A manual handoff (`memory_handoff_begin`) typically has no cwd whilediff --git a/README.md b/README.mdindex 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.mdindex 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 configreference for Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw, OMP, VS Code Copilot- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) - what's actuallydiff --git a/docs/usage.md b/docs/usage.mdindex 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 theserver. 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 theserver with `AI_MEMORY_LLM_PROVIDER=openai-oauth`: