Gitmem

io.github.gitmem-devPublished by GitHub account gitmem-devv1.2.1Updated Oct 24, 2026

Persistent institutional memory for AI coding agents. Memory that compounds.

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

GitMem is a local MCP server that gives AI coding agents persistent memory of past sessions — mistakes, wins, patterns, decisions and unfinished work.

What you can do
Recall relevant lessons from earlier sessions before the agent acts, and surface scars automatically when similar work comes up again. Record what happened as scars (mistakes), wins, patterns, decisions and open threads, with counter-arguments attached to scars. Run a closing reflection at the end of a session so context carries into the next one. Search and manage stored memory, track unfinished threads, and coordinate multiple agents. Set up the server and client config through a CLI wizard that merges into existing config files.
When to use it
Use it when you work with an AI coding agent on the same project across many sessions and want it to stop repeating known mistakes and to keep architectural decisions and unfinished work in view. Best suited to solo or team coding work in Claude Code, Cursor, VS Code, Windsurf or another MCP client.
Requirements
Runs locally over stdio via the npm package gitmem-mcp, so Node.js and npx are needed. The free tier stores data locally in a .gitmem/ directory and needs no account. The optional Pro tier is self-hosted on your own Supabase project and requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY, plus a license key for activation.
Before you install
The Pro tier asks for a Supabase service role key, which grants broad access to that project; keep it out of shared config. Pro setup also references an OpenRouter API key and a paid license key. The setup wizard writes to and merges MCP config files, instruction files and git hooks in your repository, so preview changes with the dry-run option first. Stored memory may contain code and project details; Pro cloud persistence moves it off your machine.

Installation

In SourceWeft

  1. Open Gitmem in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[GitMem — Institutional memory for AI coding agents]

[npm version] [npm downloads] [MIT License] [Build] [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-interactivenpx gitmem-mcp init --dry-run            # Preview changesnpx 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

TypePurposeExample
ScarsMistakes to avoid"Always validate UUID format before DB lookup"
WinsApproaches that worked"Parallel agent spawning cut review time by 60%"
PatternsReusable strategies"5-tier test pyramid for MCP servers"
DecisionsArchitectural choices with rationale"Chose JWT over session cookies for stateless auth"
ThreadsUnfinished 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

ClientSetupHooks
Claude Codenpx gitmem-mcp initFull (session, recall, credential guard)
Cursornpx gitmem-mcp init --client cursorPartial (session, recall)
VS Code (Copilot)npx gitmem-mcp init --client vscodeInstructions-based
Windsurfnpx gitmem-mcp init --client windsurfInstructions-based
Claude DesktopAdd to claude_desktop_config.jsonManual
Any MCP clientnpx gitmem-mcp init --client genericInstructions-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"]    }  }}
ClientConfig file
Claude Code.mcp.json
Cursor.cursor/mcp.json
VS Code.vscode/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json

CLI Commands

CommandDescription
npx gitmem-mcp initInteractive setup wizard (auto-detects IDE)
npx gitmem-mcp init --client <name>Setup for specific client (claude, cursor, vscode, windsurf, generic)
npx gitmem-mcp init --yesNon-interactive setup
npx gitmem-mcp init --dry-runPreview changes
npx gitmem-mcp activate <key>Activate Pro tier (auto-applies schema)
npx gitmem-mcp deactivateRemove Pro credentials, free device slot
npx gitmem-mcp setupOutput schema SQL (for manual Supabase setup)
npx gitmem-mcp uninstallClean removal (preserves .gitmem/ data)
npx gitmem-mcp uninstall --allFull removal including data
npx gitmem-mcp checkDiagnostic health check

Pro Tier

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

What you getWhy your agent cares
Semantic searchRecall returns the right scars, not keyword noise
Session analyticsSpot patterns in what keeps going wrong
Sub-agent briefingHand institutional context to sub-agents automatically
Cloud persistenceMemory survives machine changes, shareable across team
A/B testing analyticsMeasure which scar phrasings actually change agent behavior

Quick start

bash
npx supabase login                                          # one timeexport 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.mdGitMem
LoadedEvery turn (system prompt)On-demand (tool calls)
Best forPreferences, shortcuts, quick referenceEarned lessons, unfinished work, decisions
UpdatesAgent writes directlySession 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.gitcd gitmemnpm installnpm run buildnpm test

See CONTRIBUTING.md for full development setup.

License

MIT — see LICENSE.

Source: README.md at commit 2e3dee2

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.2.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts