GitMem

GitMem is an MCP server that provides your AI coding agent with persistent memory across sessions. It records mistakes, wins, and decisions so your agent learns from experience rather than starting anew each time, enabling smarter recall and continuity across tools that support the Model Context Protocol (MCP).

How to use

You use GitMem by pairing it with an MCP-compatible client. Install the MCP server once, then initialize memory integration for your chosen client. The server will handle recalling relevant past lessons, applying past lessons during work, recording new lessons as scars and wins, and persisting context for future sessions.

How to install

Prerequisites: you need Node.js installed on your machine. You may also want a supported MCP client installed, such as Claude Code, Cursor, VS Code Copilot, Windsurf, or any MCP-compatible client.

# Quick start: initialize GitMem MCP integration for your environment
npx gitmem-mcp init

This interactive wizard detects your IDE and configures everything, including the .gitmem/ directory, MCP server config files, instruction files for your client, lifecycle hooks where supported, and updates to .gitignore. If you already have existing configuration, the wizard merges without destroying anything. For non-interactive setup, you can run:

npx gitmem-mcp init --yes

To preview changes before applying them, use:

npx gitmem-mcp init --dry-run

To force setup for a specific client, for example VS Code, run:

npx gitmem-mcp init --client vscode

Manual MCP configuration is also supported. You can add a simple MCP config snippet to your client configuration to point at GitMem. This example shows how to configure a generic MCP client to run GitMem via npx.

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

Note: The exact file name for your client’s MCP configuration may vary (for example .mcp.json, .cursor/mcp.json, .vscode/mcp.json, or other client-specific paths). Use the example above as a guide to set the GitMem MCP server as a tool endpoint for your client.

## Additional features and notes

GitMem integrates with a variety of MCP clients and provides features that help your agent learn from experience and maintain continuity across sessions. Key capabilities include automatic recall of relevant lessons, session continuity of context and threads, a structured closing ceremony for reflection, and a broad toolkit for memory management and coordination across multiple agents.

## CLI Commands

The following commands help you manage GitMem MCP integration from the command line.

npx gitmem-mcp init # Interactive setup (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 uninstall # Clean removal (preserves data) npx gitmem-mcp uninstall --all # Full removal including data npx gitmem-mcp check # Diagnostic health check

## Pro Tier — Coming Soon

Future enhancements include semantic search for returning the most relevant scars, session analytics to identify recurring failure patterns, sub-agent briefing to share institutional context, cloud persistence for cross-device memory, and analytics to measure scar phrasing effectiveness during testing.

## Privacy & Data

GitMem stores data locally by default in the .gitmem/ directory. It does not collect telemetry. The Pro tier can use a Supabase backend with explicit environment variable configuration. Your sessions, scars, and decisions belong to you, and you can delete .gitmem/ to remove everything.

## Development

To contribute or explore the project locally, clone the repository, install dependencies, build, and run tests.

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

## License

MIT — see the license for details.

## Available tools

### Automatic Recall

Automatically surface relevant scars and lessons before the agent acts, guiding decisions with past experiences.

### Session Continuity

Preserve context, threads, and rapport across sessions for seamless multi-session work.

### Closing Ceremony

Provide a structured reflection at the end of a session to capture what broke, what worked, and what to do differently.

### Memory Toolkit

A toolkit for managing scars, wins, patterns, and decisions across the agent’s memory.