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. Installation

Install directly via pip:

pip install agents-memory

Or install from source in editable mode:

git clone https://github.com/Lolaplex/agents-memory.git
cd agents-memory
pip install -e .

2. Initialize & Sync

# Scaffold initial directories and wire into host IDEs / MCP configs
agents-memory sync --init

# Audit and register local repositories
agents-memory inventory

Fill in ~/.agents/memory/USER.md with your profile and stack preferences. Reload your agent to connect to the MCP server.

---

CLI Reference

Command	Purpose
agents-memory sync	Updates canonical AGENTS.md, host rules, and MCP registrations
agents-memory sync --init	First-time scaffolding and host discovery
agents-memory inventory	Discovers unregistered local repositories across workspace roots
agents-memory inventory --register SLUG PATH ROLE STACK	Registers a new repository
agents-memory ingest catalog	Indexes local chat transcripts across all supported providers
agents-memory ingest extract	Runs heuristic filters to extract durable facts into staging
agents-memory consolidate	Ensures no private state leaked into working repository

---

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.

---

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.