Persistent memory for Claude Code. The longer you use it, the smarter it gets.
- doc/DEVELOPMENT.md — Development setup
- doc/PROJECT_VISION.md — Full conceptual architecture
- doc/NEO4J_COOKBOOK.md — Query recipes for exploring the graph
- doc/TELEMETRY.md — Enterprise metrics framework
- doc/IMPLEMENTATION_PLAN.md — Phase 1 build specs
Inspired by AI's trillion-dollar opportunity: Context graphs by Gupta & Garg.
Every AI conversation starts from zero. You explain your project, your preferences, your constraints—then the session ends and it's all forgotten. Tomorrow, you're talking to a stranger again.
ccmemory fixes this. Decisions, corrections, and context accumulate over time. Session 50 is dramatically more effective than session 1.
- Docker
- Claude Code CLI
# 1. Clone and start the containers
git clone https://github.com/patrickkidd/ccmemory
cd ccmemory
docker compose up -d
# 2. Install the Claude Code plugin
/plugin marketplace add patrickkidd/ccmemory
/plugin install ccmemory@patrickkidd/ccmemoryThat's it. Start a new Claude Code session and ccmemory is active.
Have a conversation with a decision:
You: "Let's use Postgres instead of SQLite — we need concurrent writes"
Claude: [implements the change]
ccmemory automatically detects and stores the decision. Start a new session and it resurfaces:
# Context Graph: your-project
## Recent Decisions
- Use Postgres for concurrent write support (Jan 4)
Once containers are running, access:
- Dashboard: http://localhost:8765 — Browse and manage stored memories
- Neo4j Browser: http://localhost:7474 — Direct graph database access
In Neo4j Browser (http://localhost:7474), try these queries:
// Your decision history — sessions with their decisions
MATCH (s:Session {project: 'your-project'})-[:DECIDED]->(d:Decision)
RETURN s, d
// Full knowledge graph — sessions, decisions, corrections, insights
MATCH (s:Session {project: 'your-project'})-[r]->(n)
RETURN s, r, n
LIMIT 100
// Learning from mistakes — corrections over time
MATCH (s:Session {project: 'your-project'})-[:CORRECTED]->(c:Correction)
RETURN s, cClick any node to expand connections. See doc/NEO4J_COOKBOOK.md for more queries.
| Type | Example | Value |
|---|---|---|
| Decision | "Let's use retry with fixed delays" | Future sessions know why |
| Correction | "Actually, that endpoint returns JSON, not XML" | Claude doesn't repeat mistake |
| Exception | "Skip the linter for this file, it's generated" | Rule-breaking is justified |
| Failed Approach | "Tried async but race conditions killed it" | Don't repeat failed experiments |
For shared memory across a team, point everyone at the same Neo4j:
# Each developer adds to ~/.bashrc or ~/.zshrc
export CCMEMORY_USER_ID="$(git config user.email)"
export CCMEMORY_NEO4J_URI="bolt://your-team-server:7687"
export CCMEMORY_NEO4J_PASSWORD="your-team-password"Decisions start as developmental (private). Promote to curated (team-visible) via the dashboard.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Claude Code │────▶│ MCP Server │────▶│ Neo4j │
│ │ │ (container) │ │ (container) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ Hooks detect │ Stores decisions,
│ decisions/corrections │ corrections, insights
Both Neo4j and the MCP server run in Docker containers. The Claude Code plugin connects to the MCP server via HTTP.
docker compose up -d # Start
docker compose down # Stop
docker compose logs -f # View logsImport existing conversations and documentation into the context graph.
Copy this prompt exactly:
Use the ccmemory_backfill_conversation tool to import my Claude Code conversation history for THIS project only. The JSONL files are at ~/.claude/projects/ in a folder matching my current directory path with slashes replaced by dashes (e.g., /Users/patrick/myapp -> -Users-patrick-myapp). Read each JSONL file from that folder and call the tool with the project name (basename of cwd), session_id (filename without .jsonl), and the file content.
Important: Only import from the folder matching your current working directory. Do NOT import from other project folders.
Copy this prompt exactly:
Use the ccmemory_backfill_markdown tool to import my project's markdown files. Read each .md file and call the tool with project name, relative file path, and the file content.
Files with ## YYYY-MM-DD: Title entries are parsed into Decision nodes:
## 2025-01-15: Use JWT for Authentication
**Context:** Need stateless auth for horizontal scaling
**Options considered:** Sessions, JWT, OAuth tokens
**Decision:** JWT with short expiry + refresh tokens
**Reasoning:** Stateless required for K8s deployment
**Revisit trigger:** If we need real-time session revocationOther markdown is chunked and indexed as reference knowledge.
Apache 2.0