Agent Memory

Centralized knowledge graph for Claude Code agents. Any agent, in any project, can store and retrieve knowledge through a shared MCP server.

Architecture

Claude Code Agent (any project)
       │
       │  MCP protocol (HTTP)
       ▼
┌─────────────────────────┐
│  Graphiti MCP Server    │  Tools: add_episode, search_nodes,
│  (port 19400)           │  search_facts, get_episodes, get_status
├─────────────────────────┤
│  FalkorDB               │  Graph DB (entities + relationships)
│  (port 19401)           │  Temporal edges (valid_from / valid_to)
│  Browser UI (19402)     │
└─────────────────────────┘
     zepai/knowledge-graph-mcp:latest

Stack: Graphiti (by Zep) + FalkorDB + Ollama (fully local, no API keys)

Why Graphiti

• Incremental writes — purpose-built for continuous agent memory (unlike batch-oriented alternatives like Microsoft GraphRAG)
• Temporal model — relationships have valid_from/valid_to, supports point-in-time queries
• Native MCP server — Claude Code sees memory tools as first-class tools
• Hybrid retrieval — semantic embeddings + BM25 keyword search + graph traversal

Setup

1. Install and start Ollama

brew install ollama
ollama serve &
ollama pull qwen2.5:14b        # Entity extraction (~9GB)
ollama pull nomic-embed-text    # Embeddings (~274MB)

2. Configure environment

cp .env.example .env
# Default config uses Ollama — no changes needed for local setup

3. Start the server

docker compose up -d
sleep 15 && curl http://localhost:19400/health

4. Browse the graph

open http://localhost:19402

5. (Optional) Import existing docs

pip3 install -r scripts/requirements.txt
python3 scripts/ingest_md_files.py --dry-run   # Preview what will be imported
python3 scripts/ingest_md_files.py              # Run the import

MCP Integration

Each project has a .mcp.json that connects Claude Code to the memory server:

{
  "mcpServers": {
    "agent-memory": {
      "type": "url",
      "url": "http://localhost:19400/mcp/"
    }
  }
}

Copy this file into any new project directory to give its agents access to the shared memory.

Memory Organization

Knowledge is namespaced by group_id:

group_id	Scope
global	Cross-project knowledge, personal preferences
intuition-v2	Monorepo: web, mobile, agents, CLI
be_v3	Rust backend, Redis Streams, blockchain indexing
intuition-rs	Rust SDK, protocol specifics
intuition-docs	Documentation site (Docusaurus)
intuition-contracts-v2	Smart contracts
(others)	One per project as needed

Episode Naming Conventions

Prefix	Use for
[ADR]	Architecture decisions and rationale
[DEBUG]	Bug investigations, root causes, fixes
[SESSION]	Session summaries
[DOCS]	API docs, schemas, flows
[PATTERN]	Recurring patterns and conventions
[PROC]	Procedures, runbooks, how-to guides
[PREF]	User preferences and workflow choices

Models

Role	Model	Size	Notes
Entity extraction	qwen2.5:14b	~9GB	Good structured output, fits 16GB RAM
Embeddings	nomic-embed-text	~274MB	768 dimensions, fast

Both run locally via Ollama. Entity extraction is slower (~5-15s/episode vs ~1-2s with cloud) but completely free and private. To use OpenAI instead, update .env with your API key and endpoint.