memory

English | 中文

The problem

Every AI coding tool starts from zero.

You spend a week with Claude Code designing an architecture, switch to Codex next week, and it knows nothing about what you decided or why. You paste context again. You re-explain the project. Three tools later, the same conversation has happened five times, and none of it is searchable.

cross-agent-memory fixes this. It runs a small local memory service that:

1. Ingests your session history from any AI tool (Claude Code / Codex-style CLIs / OpenCode / ZCode / …) and any project folder you point it at.

2. Indexes everything with local embeddings into a single searchable store.

3. Serves it back to every agent through an HTTP API or directly as MCP tools — so any MCP-capable agent can recall what every other agent (and you) already figured out.

No cloud. No accounts. Nothing ever leaves your machine.

Related MCP server: Project Context MCP

Features

• 🔒 Local-first, private by design — embeddings and search run on your machine (Ollama + SQLite + sqlite-vec). Airplane mode is a supported mode.

• 🧠 Cross-tool by design — connectors for Claude Code, OpenCode and ZCode session stores, plus a generic file watcher for any project/docs folder. Agents share one memory regardless of which tool produced it.

• 🔌 One-line MCP integration — memory_search, memory_write and memory_stats are exposed over the Model Context Protocol. Claude Code, Codex CLI, Cursor and anything else MCP-capable can use them today.

• ⚡ Fast at real scale — built for large corpora: sqlite-vec vec0 KNN with a 1-bit coarse recall prefilter and hot/warm/cold tiering. The reference deployment searches 2,000,000+ chunks in 0.36–1.20 s (see measured numbers).

• 🛠 Ops included — health/monitor endpoints, rolling-window degradation detection, backups & restore, snapshot archiving, tier maintenance scripts.

• 📈 Battle-tested — extracted from a continuously running multi-agent system where four different AI tools share one memory daily, with millions of chunks and daily incremental indexing.

Architecture

        Claude Code      Codex-style CLI     OpenCode / ZCode      any project
             │                  │                  │                  │
             ▼                  ▼                  ▼                  ▼
      ┌────────────────────────────────────────────────────────────────────┐
      │                         Connectors / Indexers                      │
      │   incremental watermarks · content-hash dedup · active-session     │
      │   skip · unified chunker · local embeddings (Ollama, e.g. bge-m3)  │
      └────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
      ┌────────────────────────────────────────────────────────────────────┐
      │                      SQLite memory store (single file)             │
      │   chunks (source of truth)  ├─ vec0 KNN index (sqlite-vec)         │
      │   FTS-ready metadata        ├─ 1-bit recall codes (Hamming)        │
      │                             └─ hot / warm / cold tier tables       │
      └────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┴───────────────────┐
                    ▼                                     ▼
        HTTP API (port 5370)                    MCP server (stdio)
        /api/search /api/memories               memory_search
        /api/stats  /api/health ...             memory_write / memory_stats
                    ▲                                     ▲
                    └─────────────────┬───────────────────┘
                                      │
                    every agent you use, in any language/tool

Design notes and the full retrieval pipeline are documented in docs/ARCHITECTURE.md.

🤖 Let your AI agent install it (one paste)

The fastest path: open this repository in your AI coding assistant and paste the block below. It installs everything locally — venv, dependencies, a fresh isolated database — verifies a real write/search round trip, and reports back with exact commands and results. Nothing is sent anywhere; the agent works on your machine only.

Install this repository locally. Read AGENTS.md and INSTALL-FOR-AI.md first.
Use ./install.sh --dry-run, then ./install.sh. Keep all runtime data isolated
from existing databases and bind only 127.0.0.1. Verify initialization twice,
Ollama bge-m3, health, and a real write/search round trip using examples/run.py.
Add the client instructions from examples/client-instructions.md. Report exact
commands, results and blockers; do not claim success from health alone.
Do not import personal projects, restore backups or change system services.

Prefer doing it yourself? The manual path is right below. The same protocol is documented for agents in INSTALL-FOR-AI.md and AGENTS.md.

Quickstart

0. Prerequisites

• macOS or Linux (Windows is not supported yet — connectors use POSIX file locks)

• Python 3.10+

• Ollama running locally (for embeddings)

ollama pull bge-m3            # ~1.2 GB, good multilingual embedding model

1. Install

git clone https://github.com/indamices/cross-agent-memory.git
cd cross-agent-memory
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

2. Start the service

python3 server.py
# Server listening on 127.0.0.1:5370

3. Give it something to remember

Register any project folder (docs, decisions, notes):

curl -s -X POST http://127.0.0.1:5370/api/register \
  -H 'Content-Type: application/json' \
  -d '{"root": "/path/to/your/project"}'

The folder needs a .memory-service.yaml or sensible defaults are used — see examples/. Files are indexed immediately; later changes are batched by a debounce window (default 1 hour, MEMSVC_WATCH_DEBOUNCE). For instant pickup: POST /api/reindex {"project": "..."} or start with MEMSVC_WATCH_DEBOUNCE=0.

Or ingest AI-tool session history with a connector:

python3 connectors/index_claude_code.py     # ~/.claude/projects/**/*.jsonl
python3 connectors/index_opencode.py        # ~/.local/share/opencode/opencode.db
python3 connectors/index_zcode.py           # ~/.zcode/v2/tasks-index.sqlite

4. Search from anywhere

curl -s -X POST http://127.0.0.1:5370/api/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "why did we choose the tiered storage design", "n_results": 5}'

Or write a memory directly (decisions, insights — great for agent hooks):

curl -s -X POST http://127.0.0.1:5370/api/memories \
  -H 'Content-Type: application/json' \
  -d '{"items": [{"type": "decision", "content": "We picked sqlite-vec over a server-based vector DB for local-first operation."}]}'

Connect your agents (MCP)

mcp_server.py is a zero-dependency MCP (stdio) server that exposes the memory API as tools. Point your agent at it:

Claude Code

claude mcp add memory -- python3 /ABS/PATH/cross-agent-memory/mcp_server.py

or in .mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "python3",
      "args": ["/ABS/PATH/cross-agent-memory/mcp_server.py"],
      "env": { "MEMORY_SERVICE_URL": "http://127.0.0.1:5370" }
    }
  }
}

Codex CLI (~/.codex/config.toml)

[mcp_servers.memory]
command = "python3"
args = ["/ABS/PATH/cross-agent-memory/mcp_server.py"]
env = { MEMORY_SERVICE_URL = "http://127.0.0.1:5370" }

Cursor / other MCP agents — same server command and args in that tool's MCP settings. If you started the service with MEMSVC_TOKEN set, also set MEMORY_SERVICE_TOKEN for the MCP server.

Once connected, your agent gets:

How retrieval works

Each /api/search request runs a staged pipeline:

1. Query embedding — computed locally (Ollama), cached by text hash.

2. Coarse recall — a 1-bit-per-dimension code per chunk is prefiltered by Hamming distance (skipped automatically for small collections).

3. Exact KNN — sqlite-vec vec0 cosine KNN over the shortlist (falls back to a numpy brute-force path when sqlite-vec is unavailable).

4. Re-ranking — time decay (30-day half-life) + MMR diversity + a small helpful feedback factor.

5. Result — text + source + distance + score per hit.

Under the hood it also handles the boring-but-critical parts: content-hash deduplication, per-connector increment watermarks, skipping sessions that are still being written, batch-write pacing, WAL tuning, and stale-index self-healing.

Measured numbers

From the reference deployment (a Mac mini M4 Pro running this service 24/7 for a multi-agent setup):

These are real numbers from a heavy, messy, constantly-growing corpus — not a toy benchmark. Your numbers will vary with corpus size and hardware; on a fresh database everything is sub-100 ms.

API overview

Full reference with request/response examples: docs/API.md.

Configuration

Everything works with defaults; tune via environment variables when needed:

Operations

• Health: GET /api/health reports status, disk usage, embedding availability and degraded reasons (e.g. slow queries, disk pressure) — designed to be scraped by a cron/monitor without false alarms.

• Backups: scripts/backup_silent.py (cron-friendly) or POST /api/backup. Restore with POST /api/restore.

• Tiering (optional): scripts/migrate_to_vec0.py builds the vec0 index; scripts/tier_rebuild.py builds hot/warm/cold tier tables to keep the hot set small on very large corpora.

• Snapshot archiving: scripts/archive_silent.py.

• Health cron with alerts: scripts/health_check.py (optional Feishu webhook support is built in — configure .alert.env).

Design choices (and non-goals)

• SQLite, not a vector server. One file, zero services, trivially backed up, works offline. The vec index is derived and rebuildable.

• Local embeddings, not an API. Privacy and zero marginal cost; swap the model in config.py if you prefer something else.

• Files are the source of truth. Everything indexed can be re-ingested from its source; deleting the database loses nothing that lives on disk.

• Not a cloud sync product. This is a local service for one machine (multiple agents, one memory). Multi-user/server mode is on the roadmap.

• Not a vector database benchmark entry. It prioritizes a small dependency surface and operability over raw ANN throughput.

Roadmap

• Web console (browse / search / curate memories)

• More connectors: Codex CLI session store, Cursor, Aider, generic JSONL

• First-class memory types (facts / lessons / code-change context) with extraction pipelines

• Multi-machine sync for people who work across hardware

• Python package / Docker image for one-command installs

Issues and PRs are welcome — especially new connectors. See CONTRIBUTING.md.

Acknowledgements

Built on the shoulders of excellent tools: SQLite, sqlite-vec, Ollama, numpy, watchdog.

License

MIT © 2026 indamices