agents-memory

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

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) to all modern agents.
• 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 │
 └─────────────────────────────┘ └─────────────────────────────┘

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.

CLI 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/MCP.md — Tool 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.