Gitmem README

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

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

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

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

CLI Commands

Pro Tier

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

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 <your-license-key>

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

See 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:

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 for full development setup.

License

MIT — see LICENSE.