Gitmem

= 18" />

Documentation · npm · Getting Started · Tool Reference

---

GitMem is an MCP server that gives your AI coding agent persistent learning memory across agent sessions. It remembers mistakes (scars), successes (wins), and decisions — so your agent learns from experience instead of starting from scratch every time.

> What's MCP? Model Context Protocol is how AI coding tools connect to external capabilities. GitMem is an MCP server — install it once and your agent gains persistent memory.

Works with Claude Code, Cursor, VS Code (Copilot), Windsurf, and any MCP-compatible client.

Quick Start

npx gitmem-mcp init

One command. The wizard auto-detects your IDE and sets up everything:

• .gitmem/ directory with starter scars
• MCP server config (.mcp.json, .vscode/mcp.json, .cursor/mcp.json, etc.)
• Instructions file (CLAUDE.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md)
• Lifecycle hooks (where supported)
• .gitignore updated

Already have existing config? The wizard merges without destroying anything. Re-running is safe.

npx gitmem-mcp init --yes                # Non-interactive
npx gitmem-mcp init --dry-run            # Preview changes
npx gitmem-mcp init --client vscode      # Force specific client

How It Works

recall  -->  work  -->  learn  -->  close  -->  recall  -->  ...

1. Recall — Before acting, the agent checks memory for relevant lessons from past sessions
2. Work — The agent does the task, applying past lessons automatically
3. Learn — Mistakes become scars, successes become wins, strategies become patterns
4. Close — Session reflection persists context for next time

Every scar includes counter-arguments — reasons why someone might reasonably ignore it. This prevents memory from becoming a pile of rigid rules.

What Gets Remembered

| Type | Purpose | Example | |------|---------|---------| | Scars | Mistakes to avoid | "Always validate UUID format before DB lookup" | | Wins | Approaches that worked | "Parallel agent spawning cut review time by 60%" | | Patterns | Reusable strategies | "5-tier test pyramid for MCP servers" | | Decisions | Architectural choices with rationale | "Chose JWT over session cookies for stateless auth" | | Threads | Unfinished work that carries across sessions | "Rate limiting still needs implementation" |

Key Features

• Automatic Recall — Scars surface before the agent takes similar actions
• Session Continuity — Context, threads, and rapport carry across sessions
• Closing Ceremony — Structured reflection captures what broke, what worked, and what to do differently
• 20+ MCP Tools — Full toolkit for memory management, search, threads, and multi-agent coordination
• Zero Config — npx gitmem-mcp init and you're running
• Non-Destructive — Merges with your existing .mcp.json, CLAUDE.md, and hooks

Supported Clients

| Client | Setup | Hooks | |--------|-------|-------| | Claude Code | npx gitmem-mcp init | Full (session, recall, credential guard) | | Cursor | npx gitmem-mcp init --client cursor | Partial (session, recall) | | VS Code (Copilot) | npx gitmem-mcp init --client vscode | Instructions-based | | Windsurf | npx gitmem-mcp init --client windsurf | Instructions-based | | Claude Desktop | Add to claude_desktop_config.json | Manual | | Any MCP client | npx gitmem-mcp init --client generic | Instructions-based |

The wizard auto-detects your IDE. Use --client to override.

Manual MCP configuration

Add this to your MCP client's config file:

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

| Client | Config file | |--------|-------------| | Claude Code | .mcp.json | | Cursor | .cursor/mcp.json | | VS Code | .vscode/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json |

CLI Commands

| Command | Description | |---------|-------------| | npx gitmem-mcp init | Interactive setup wizard (auto-detects IDE) | | npx gitmem-mcp init --client | Setup for specific client (claude, cursor, vscode, windsurf, generic) | | npx gitmem-mcp init --yes | Non-interactive setup | | npx gitmem-mcp init --dry-run | Preview changes | | npx gitmem-mcp activate | Activate Pro tier (auto-applies schema) | | npx gitmem-mcp deactivate | Remove Pro credentials, free device slot | | npx gitmem-mcp setup | Output schema SQL (for manual Supabase setup) | | npx gitmem-mcp uninstall | Clean removal (preserves .gitmem/ data) | | npx gitmem-mcp uninstall --all | Full removal including data | | npx gitmem-mcp check | Diagnostic health check |

Pro Tier

Self-hosted on your own Supabase. You bring the infrastructure, gitmem sets it up.

| What you get | Why your agent cares | |-------------|---------------------| | Semantic search | Recall returns the right scars, not keyword noise | | Session analytics | Spot patterns in what keeps going wrong | | Sub-agent briefing | Hand institutional context to sub-agents automatically | | Cloud persistence | Memory survives machine changes, shareable across team | | A/B testing analytics | Measure which scar phrasings actually change agent behavior |

Quick start

npx supabase login                                          # one time
export SUPABASE_URL="https://yourproject.supabase.co"
export SUPABASE_SERVICE_ROLE_KEY="eyJ..."
export OPENROUTER_API_KEY="sk-or-v1-..."
npx gitmem-mcp activate 

The activate command creates all tables, views, RPC functions, and indexes automatically. No manual SQL needed.

See [docs/pro-setup-guide.md](docs/pro-setup-guide.md) for the full guide.

The free tier gives you everything for solo projects. Pro makes recall smarter and memory portable.

GitMem + MEMORY.md

Your AI agent likely has its own memory file (MEMORY.md, .cursorrules, etc.). Here's how they work together:

| | MEMORY.md | GitMem | |---|-----------|--------| | Loaded | Every turn (system prompt) | On-demand (tool calls) | | Best for | Preferences, shortcuts, quick reference | Earned lessons, unfinished work, decisions | | Updates | Agent writes directly | Session lifecycle (close ceremony) | | Example | "User prefers terse output" | "Always validate UUID before DB lookup" |

Tip: Include .gitmem/agent-briefing.md in your MEMORY.md for a lightweight bridge between the two systems.

Privacy & Data

• Local-first — All data stored in .gitmem/ on your machine by default
• No telemetry — GitMem does not collect usage data or phone home
• Cloud opt-in — Pro tier Supabase backend requires explicit configuration via environment variables
• Your data — Sessions, scars, and decisions belong to you. Delete .gitmem/ to remove everything

Development

git clone https://github.com/gitmem-dev/gitmem.git
cd gitmem
npm install
npm run build
npm test

See [CONTRIBUTING.md](CONTRIBUTING.md) for full development setup.

License

MIT — see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gitmem-dev
• Source: gitmem-dev/gitmem
• License: MIT
• Homepage: https://gitmem.ai

Install and usage instructions live in the source repository linked above.