The Problem

Every conversation, your AI agent starts from scratch. You copy-paste context, repeat instructions, and watch tokens burn. Knowledge gets lost between sessions.

The Solution

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   Before: Load everything → 🔥 Token explosion                  │
│                                                                 │
│   After:  Query what you need → ⚡ Sub-ms response              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Agent Memory is an MCP server that gives AI agents persistent, structured memory. Instead of stuffing context, agents query specific knowledge on-demand.

Agent Memory is the high-speed memory layer for AI agents—persistent, permissioned, and enforceable—so your agents remember the right things, at the right time, without bloating context.

What makes it different:

• Hierarchical scopes with inheritance (global → org → project → session)
• Action-based MCP tool suite (plus optional REST API) for storing/querying memory
• Built-in governance: permissions, auditability, conflict handling, file locks, verification hooks
• Fast search stack: SQLite WAL/FTS plus optional semantic search (embeddings)

⚡ Quick Start

One command. That's it.

npx agent-memory@latest mcp

Add to your MCP client config:

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "agent-memory@latest", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "agent-memory@latest", "mcp"]
    }
  }
}

{
  "mcp.servers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "agent-memory@latest", "mcp"]
    }
  }
}

Restart your client. Done.

🏗️ Architecture

                    ┌─────────────────────────────────────┐
                    │           HIERARCHICAL SCOPES       │
                    └─────────────────────────────────────┘

     ┌──────────────────────────────────────────────────────────────┐
     │  GLOBAL                                                      │
     │  └── Security best practices, universal patterns             │
     │      │                                                       │
     │      ├── ORGANIZATION                                        │
     │      │   └── Team standards, shared tooling                  │
     │      │       │                                               │
     │      │       ├── PROJECT                                     │
     │      │       │   └── Architecture decisions, code style      │
     │      │       │       │                                       │
     │      │       │       └── SESSION                             │
     │      │       │           └── Current working context         │
     │      │       │                                               │
     └──────┴───────┴───────────────────────────────────────────────┘

                         Queries inherit up the chain

🎯 Three Memory Types

🚀 Performance

Built for speed. SQLite WAL mode + intelligent caching.

✨ Features

🪝 IDE Hooks

Runtime enforcement via pre/post tool call checks. Hooks intercept MCP tool execution and validate against critical guidelines.

┌─────────────────────────────────────────────────────────────────┐
│  Agent tries to edit file                                       │
│         ↓                                                       │
│  PreToolUse hook fires → Checks critical guidelines             │
│         ↓                                                       │
│  Violation? → ❌ BLOCKED with explanation                       │
│  Clean?     → ✅ Proceed with edit                              │
└─────────────────────────────────────────────────────────────────┘

Install hooks for Claude Code:

npx agent-memory hook install --ide claude --project-path .

→ Hooks Guide

📐 Rules Sync

Agent guidelines for interacting with the MCP server. Rules teach AI assistants the memory workflow — synced directly to your IDE.

# Sync to Claude Code (writes to ~/.claude/CLAUDE.md)
npm run sync-rules -- --ide claude

# Sync to Cursor (writes .mdc files to .cursor/rules/)
npm run sync-rules -- --ide cursor

# Watch mode — auto-sync on changes
npm run sync-rules:watch

What gets synced:

→ Rules Sync Guide

🔌 Server Modes

# MCP Server (default) — Claude Desktop, Cursor, etc.
npx agent-memory mcp

# REST API — Custom integrations
AGENT_MEMORY_REST_ENABLED=true AGENT_MEMORY_REST_API_KEY=secret npx agent-memory rest

# Both simultaneously
AGENT_MEMORY_REST_ENABLED=true AGENT_MEMORY_REST_API_KEY=secret npx agent-memory both

⚙️ Configuration

# Where to store data (default: ~/.agent-memory for npm installs, ./data for development)
AGENT_MEMORY_DATA_DIR=~/.agent-memory

# Enable semantic search (optional)
AGENT_MEMORY_OPENAI_API_KEY=sk-...

# REST API (disabled by default)
AGENT_MEMORY_REST_ENABLED=true
AGENT_MEMORY_REST_API_KEY=your-secret

# Single-agent mode (skip permissions)
AGENT_MEMORY_PERMISSIONS_MODE=permissive

→ Full configuration reference

📚 Documentation

🗺️ Roadmap

Request a feature

🛠️ Development

git clone https://github.com/anthropics/agent-memory.git
cd agent-memory
npm install
npm run build
npm run validate  # lint + typecheck + tests

📄 License

MIT — see LICENSE