claude-project-memory

Persistent project memory for AI coding tools — Claude Code, Cursor, Windsurf, Cline, and Gemini CLI. Remembers session context across conversations via MCP (Model Context Protocol).

Git-aware, branch-scoped, self-maintaining — context is stored per branch with automatic cleanup, search, bookmarks, and export. Shared across all your AI coding tools.

Why?

AI coding tools start every session fresh. This MCP server gives them a memory — plans, tasks, notes, decisions, errors, bookmarks, and session history persist between conversations so your AI assistant can pick up where it left off.

Quick Start

Single tool (Claude Code)

# 1. Register the MCP server
npx claude-project-memory --setup

# 2. Add the protocol to your project
cd your-project
npx claude-project-memory --init

# 3. Restart Claude Code — done!

All detected tools at once

# 1. Register in all detected tool configs
npx claude-project-memory --setup-all

# 2. Add protocol sections for all detected tools
cd your-project
npx claude-project-memory --init-all

# 3. Restart your tools — done!

Specific tool

# Register for Cursor only
npx claude-project-memory --setup --tool cursor

# Add .cursorrules to your project
cd your-project
npx claude-project-memory --init --tool cursor

Supported Tools

| Tool | Instruction File | MCP Config Location | |------|-----------------|---------------------| | Claude Code | CLAUDE.md | ~/.claude/settings.json | | Cursor | .cursorrules | ~/.cursor/mcp.json | | Windsurf | .windsurfrules | ~/.codeium/windsurf/mcp_config.json | | Cline | .clinerules | VS Code globalStorage (platform-dependent) | | Gemini CLI | GEMINI.md | ~/.gemini/settings.json |

What Happens

Once set up, your AI coding tool will automatically:

1. Load context at the start of each session — detects git branch, captures git status, auto-prunes stale data, detects merged branches
2. Track progress as it works — plans, tasks, notes, decisions, errors, bookmarks
3. Save context when the session ends — records session duration, updates file hotspots, tagged to current branch

Context is shared — if you use Claude Code to plan and Cursor to implement, both see the same project memory.

CLI Commands

| Command | Description | |---------|-------------| | --setup | Register MCP server for Claude Code (default) | | --setup --tool <name> | Register for a specific tool | | --setup-all | Register for all detected tools | | --uninstall | Remove from Claude Code config (default) | | --uninstall --tool <name> | Remove from a specific tool's config | | --uninstall-all | Remove from all detected tools | | --init | Add protocol section to ./CLAUDE.md (default) | | --init --tool <name> | Add protocol section for a specific tool | | --init-all | Add protocol sections for all detected tools | | --help | Show usage info | | (no flags) | Start MCP server (stdio mode) |

Available Tools (28)

Core Tools

| Tool | Description | |------|-------------| | get_context | Load saved context. Auto-detects branch, captures git state, auto-prunes old data, shows session diff | | save_context | Persist session state. Records session duration, updates file hotspots | | update_plan | Create or replace the current plan (saved to root + branch) | | add_task | Add a new task (saved to root + branch) | | update_task | Update task status (searches root + branch) | | add_note | Save a note or insight (saved to root + branch) | | get_summary | Readable overview with git state, branches, decisions, errors, bookmarks, hotspots, session timing | | clear_context | Reset all context for a project |

Git & Branch Tools

| Tool | Description | |------|-------------| | get_git_state | Force-refresh git state (branch, status, commits, stash, upstream) | | add_decision | Log an architectural decision with reasoning and alternatives | | log_error | Log an error for future reference | | resolve_error | Mark an error as resolved | | switch_branch_context | View another branch's context without changing git branch | | set_branch_purpose | Set what a branch is for |

Search, Bookmarks & Export

| Tool | Description | |------|-------------| | prune_branches | Remove stored context for branches that no longer exist in git | | search_context | Search across all branches for notes, decisions, errors, tasks by keyword | | add_bookmark | Save a file:line reference with a label for quick navigation | | remove_bookmark | Remove a bookmark by ID | | link_pr | Link a GitHub PR URL/number to a branch context | | export_context | Export project or branch context as clean markdown |

Workspaces

| Tool | Description | |------|-------------| | list_workspaces | List all workspaces for a project | | select_workspace | Switch to a named workspace for isolated context |

Multi-Agent Collaboration

| Tool | Description | |------|-------------| | register_agent | Register as a named agent (lead or worker) with heartbeat | | list_agents | List all registered agents and their status | | send_message | Send a message to a specific agent or broadcast to all | | check_messages | Read unread messages for this agent (also heartbeat) | | assign_task | Assign an existing task to a specific agent | | claim_task | Worker claims an unassigned pending task |

Features

Git-Aware

• Automatic branch detection and per-branch context storage
• Git state capture: modified/staged/untracked files, commits, stash, upstream status
• Uncommitted change warnings and upstream drift alerts
• Cross-branch context lookup

Auto-Maintenance

• Auto-prune: Completed tasks and resolved errors older than 30 days are automatically cleaned up on session start
• Stale branch cleanup: prune_branches removes context for deleted git branches
• Branch merge tracking: When a branch is detected as merged, its decisions/notes/errors are auto-copied to the target branch
• Capacity limits: All collections are capped to prevent unbounded growth

Session Intelligence

• Session timing: Records start/end time for each session; shows duration in summaries
• Session diff: On load, shows new commits since last session
• File hotspots: Tracks how frequently files appear across sessions, surfaces "most-touched" files

Search & Bookmarks

• Full-text search: search_context searches notes, decisions, errors, tasks across all branches
• Bookmarks: Save file:line references with labels, persisted across sessions

PR Integration

• Link PRs: Associate a GitHub PR URL/number with a branch context
• Shown in summaries: PR links appear in get_summary and get_context output

Export

• Markdown export: Clean, formatted markdown of entire project or a single branch — useful for handoff docs

Multi-Agent Collaboration

• Lead/worker pattern: One agent acts as lead (creates tasks, assigns work), others act as workers (claim tasks, report results)
• Agent registry: Agents register with register_agent, tracked with heartbeats; stale agents (>10 min) auto-marked as done
• Message board: Agents communicate via send_message / check_messages — supports task assignments, status updates, questions/answers, results
• Task assignment: Lead assigns tasks with assign_task; workers claim unassigned work with claim_task
• Separate coordination file: Agent data stored in a separate {hash}-agents.json file to avoid contention with the main context file

Example setup with two terminals:

Terminal 1 (Lead - Claude Code):
  register_agent(role='lead', tool='claude-code')
  → create tasks with add_task → assign with assign_task
  → periodically check_messages for worker updates

Terminal 2 (Worker - Cursor):
  register_agent(role='worker', tool='cursor')
  → check_messages for assignments → claim_task for unassigned work
  → send_message(type='result') when done

Data Storage

Context is stored in ~/.claude-project-memory/data/ as JSON files, one per project (hashed by path).

Limits:

• Max 20 project files (oldest evicted)
• Max 50 session history entries per project
• Max 100 notes per project, 50 per branch
• Max 50 tasks per branch
• Max 50 decisions per project/branch
• Max 100 errors per project/branch
• Max 50 bookmarks per project
• Max 10 stored commits per refresh
• Auto-prune: completed tasks/resolved errors >30 days

Requirements

• Node.js >= 18
• One or more supported AI coding tools (Claude Code, Cursor, Windsurf, Cline, Gemini CLI)
• Git (for git-aware features; works without git too)

License

MIT