agents-memory

Local markdown memory & cross-agent context engine for AI coding assistants.
One persistent identity, shared across Claude Code, Cursor, Antigravity, and Zed.

Quickstart

1-Step Setup

pip install agents-memory && agents-memory sync --init

Scaffolds ~/.agents/memory/, autowires MCP configurations into your installed IDEs, and registers assistant skills.

[!TIP] 🤖 Agent-Driven Setup (Zero Friction):
Simply tell your coding agent: "Install and set up agents-memory for me."
The agent installs the package, asks your stack preferences once, fills your USER.md profile, and registers your repositories autonomously.

Source checkouts can also be installed and managed using vand.

Why .agents/memory?

The name agents-memory comes directly from its universal storage standard: .agents/memory.

• Global: ~/.agents/memory/ stores your persistent identity, stack defaults, durable concepts, and project index.
• Repository: <repo>/.agents/memory/ stores repo-specific facts, architecture ADRs, and staging inboxes.

While AI vendors fragment their configuration across proprietary stores, .agents/ provides a single, open, vendor-neutral filesystem hub for all agent configurations and shared intelligence.

agents-memory delivers this with a pure Markdown-first architecture:

• Local & Offline: Your identity and repo memory live in plain files (~/.agents/memory/ and <repo>/.agents/memory/).
• Human-Readable & Git-Friendly: Edit with any text editor, diff with git, commit when you want.
• Universal MCP Server: Exposes memory tools (search_memory, add_memory, get_project_memories, distill_batch, get_baton, set_baton, append_chronicle, session_snap, session_grep, search_hybrid, get_related, suggest_links, check_memory_freshness) to all modern agents.
• Ranked Hybrid Retrieval: Exact-substring precision first with SQLite FTS5 fallback and bidirectional wikilink relation navigation.
• Autonomous Ingest & Distillation: Extracts durable rules and architecture decisions from session logs (OpenAI, Claude, Cursor, Copilot, Antigravity, Pi).

Architecture & Flow

 ┌─────────────────────────────────────────────────────────────┐
 │                       SESSION INGEST                        │
 │  OpenAI Exports · Claude JSONL · Cursor · Antigravity · Pi  │
 └──────────────────────────────┬──────────────────────────────┘
                                │  ingest catalog / extract
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                       STAGING INBOX                         │
 │        Raw captured bullets & noise-filtered facts          │
 └──────────────────────────────┬──────────────────────────────┘
                                │  distill_batch / skill
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                     LOCAL MEMORY STORE                      │
 │   ~/.agents/memory/USER.md     ~/.agents/memory/PROJECTS.md │
 │   ~/.agents/memory/concepts/   <repo>/.agents/memory/       │
 └──────────────┬───────────────────────────────┬──────────────┘
                │                               │
                ▼                               ▼
 ┌─────────────────────────────┐ ┌─────────────────────────────┐
 │       IDE INJECTION         │ │     MCP SERVER & CLERK      │
 │  Cursor Rules · Zed Context │ │  search_memory · add_memory │
 │  Antigravity AGENTS.md      │ │  Universal Tool Integration │
 └─────────────────────────────┘ └─────────────────────────────┘

CLI Reference

MCP Tools Reference

Supported Ecosystem

• Claude Code: Bound via symlink / canonical AGENTS.md and MCP server.
• Google Antigravity: Integrated via .gemini/config rules and agents-memory MCP.
• Cursor: Automatically injects rules and configures .cursor/mcp.json.
• Zed: Configures context_servers and mirrors assistant skills.
• VS Code / Copilot: Ingests session history from local state databases.

Also compatible with: Windsurf, Cline, Roo-Code, Aider, Continue.dev, OpenAI ChatGPT, Pi, Goose, and any MCP-compliant AI assistant.

Open ABI Specification

The formal, implementation-agnostic layout specification lives in abi/:

• abi/WHY.md — Architecture decisions & why Markdown wins over RAG.
• abi/LAYOUT.md — Directory taxonomy and path contracts.
• abi/KINDS.md — Typed memory taxonomy (concepts, facts, decisions).
• abi/HYGIENE.md — Store hygiene doctrine, anti-bloat rules, and health checks.
• abi/MCP.md — Tool surface definitions and request/response specifications.
• abi/INGEST.md — Catalog, extract, and distillation pipeline.
• abi/INJECTION.md — Host rule injection mechanisms.

Testing & Verification

Run the comprehensive test suite and distillation benchmark:

python tests/run_all_tests.py

License

MIT License. See LICENSE for details.