io.github.gitmem-dev/gitmem — Model Context Protocol (MCP) Server

This MCP server provides “Persistent institutional memory for AI coding agents,” described as memory that “compounds.” The package is identified as io.github.gitmem-dev/gitmem, with focus on agent session handling and long-lived memory for coding workflows.

🛠️ Key Features

Persistent institutional memory for AI coding agents
Session-management support (as reflected by included topics)
MCP server for integrating memory into agent workflows
Includes MCP-related package branding (gitmem-mcp in excerpts)

🚀 Use Cases

Maintain consistent context across agent sessions
Support AI coding agents that need ongoing project memory
Improve continuity for tools and agent runtimes involved in coding

⚡ Developer Benefits

Aligns with MCP tooling (mcp, mcp-server topics)
Facilitates “institutional-memory” patterns for agentic AI
Targets AI coding ecosystems (topics include claude-code, cursor)

⚠️ Limitations

Only partial documentation is available in the provided excerpt; specific tools and behaviors aren’t detailed here.

GitMem — Institutional memory for AI coding agents

Node.js >= 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

bash

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.

bash

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

code

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

Recall — Before acting, the agent checks memory for relevant lessons from past sessions
Work — The agent does the task, applying past lessons automatically
Learn — Mistakes become scars, successes become wins, strategies become patterns
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:

json

{
  "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 <name>`	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 <key>`	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

bash

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:

	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

bash

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.

io.github.gitmem-dev/gitmem