ai-memory: Persistent Cross-Agent Long-Term Memory for Coding CLIs

AI coding agents have revolutionized day-to-day software development, but they have introduced a frustrating new bottleneck: agent amnesia.

As developers increasingly juggle multiple coding harnesses—using Claude Code for architecture planning, Cursor for frontend adjustments, and Codex or OpenCode for automated refactors—they quickly discover that each tool operates in a completely isolated silo:

• Memory notes created by one agent live on a single local machine.
• Context is stored in proprietary, vendor-specific formats that cannot be read by other tools.
• Switching between agents or moving from a desktop to a laptop forces the developer to repeatedly re-explain the system architecture, discarded approaches, and unresolved bugs.

ai-memory (akitaonrails/ai-memory) was created to break down these walls. Built in Rust as a single, self-contained binary, it provides a vendor-neutral, git-backed long-term memory server that bridges more than 20 AI coding harnesses.

Here is a technical overview of how ai-memory works, its zero-LLM architecture, and how it handles cross-agent handoffs.

---

The Problem with Siloed Agent Memory

Most coding assistants provide some flavor of built-in memory. Claude Code creates local project notes, Cursor maintains workspace indexes, and various plugins offer per-session scratchpads.

However, these implementations share three critical flaws:

1. Vendor Lock-in: If you build an extensive memory base with one provider, none of that knowledge transfers when you switch to an alternative CLI.
2. Opaque Storage: Notes are often locked inside hosted vector clouds or proprietary binary stores that developers cannot inspect, edit, or version-control.
3. Continuous API Costs: Many third-party memory systems make expensive LLM extraction calls on every single user prompt, dramatically inflating token bills.

---

How ai-memory Works: The Four-Stage Pipeline

ai-memory separates memory management into four distinct, observable stages:

┌─────────────────────────────────────────────────────────────┐
│                       AI Coding Agent                       │
│    (Claude Code / Cursor / Codex / Antigravity CLI / etc.)   │
└──────────────────────────────┬──────────────────────────────┘
                               │
            [ 1. Capture (Silent Lifecycle Hooks) ]
                               │
                               ▼
           [ 2. Consolidate (Git-Backed Markdown) ]
                               │
                               ▼
               [ 3. Recall (FTS5 + Entity Search) ]
                               │
                               ▼
        [ 4. Cross-Agent Handoff (Typed & Claim-Once) ]

1. Silent Lifecycle Capture

Rather than forcing developers into awkward "please remember this" ceremonies, ai-memory utilizes native agent lifecycle hooks. As you work, sanitized observations (prompts, tool invocations, session milestones) are streamed through a typed privacy boundary.

2. Plain Markdown as the Source of Truth

The central invariant of ai-memory is that the human developer owns the data.

Memory is compiled into an ordinary, git-backed wiki composed of human-readable .md files. You can:

• Open your memory wiki in Obsidian or VS Code.
• Search it with standard unix tools like grep or ripgrep.
• Edit, amend, or delete memory pages directly by hand.
• Synchronize memory across machines using standard git push or rsync.

The underlying database is strictly a derived index (SQLite FTS5) that can be completely wiped and reconstructed from the markdown files at any time.

3. Zero-LLM Default Retrieval

By default, ai-memory operates with zero LLM API calls.

Capture, indexing, and recall use high-performance full-text search (SQLite FTS5), entity extraction, and link graphs. A developer can run ai-memory completely offline with zero API keys and zero recurring expenses. For users who want it, optional background LLM consolidation and local vector embeddings can be toggled on.

4. Typed Cross-Agent Handoffs

When you terminate a session in Claude Code, ai-memory records where the task halted, which hypotheses failed, and what tasks remain open.

When you launch Codex or Cursor in that same repository, the new agent claims the pending handoff token exactly once, immediately injecting a compact, high-signal brief into the prompt context.

---

Supported Agents and Harnesses

ai-memory provides first-party integration (via MCP server registration, lifecycle hooks, or both) across major platforms:

• CLI Agents: Claude Code, Codex, Antigravity CLI, Gemini CLI, OpenCode, Devin CLI, Grok Build, Kimi Code.
• IDE Environments: Cursor, VS Code Copilot, Zed, Claude Desktop.
• Platforms: Linux (native and AUR), macOS (Apple Silicon & Intel), Windows (WSL2 & experimental native), Docker/Podman.

---

Quick Start: Running ai-memory Locally

You can run ai-memory on any workstation using the pre-built Docker container:

# Start the local memory daemon (binds to loopback 127.0.0.1:49374)
docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    akitaonrails/ai-memory:latest

Registering with Your Coding Agent

To connect ai-memory to Claude Code, simply install the MCP bridge and hooks:

ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply

Now, any observations, architectural choices, and unresolved debugging questions will automatically persist into your project's local markdown wiki, ready to be retrieved by whichever agent you open next.

---

Summary

ai-memory treats developer memory the way developer tools ought to be built: local-first, transparent, git-versioned, and completely independent of any single model vendor.

By eliminating the cognitive tax of re-explaining systems to every new tool, it makes a multi-agent coding workflow genuinely seamless.

• GitHub Repository: https://github.com/akitaonrails/ai-memory
• License: MIT
• Maintained by: Fabio Akita and contributors