{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/banner.svg\" alt=\"GitMem — Institutional memory for AI coding agents\" width=\"700\" />\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/gitmem-mcp\"><img src=\"https://img.shields.io/npm/v/gitmem-mcp?style=flat-square&color=c41920&label=npm\" alt=\"npm version\" /></a>\n  <a href=\"https://www.npmjs.com/package/gitmem-mcp\"><img src=\"https://img.shields.io/npm/dm/gitmem-mcp?style=flat-square&color=333333&label=downloads\" alt=\"npm downloads\" /></a>\n  <a href=\"https://github.com/gitmem-dev/gitmem/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/gitmem-dev/gitmem?style=flat-square&color=c41920\" alt=\"MIT License\" /></a>\n  <a href=\"https://github.com/gitmem-dev/gitmem/actions/workflows/ci.yml\"><img src=\"https://img.shields.io/github/actions/workflow/status/gitmem-dev/gitmem/ci.yml?style=flat-square&color=333333&label=build\" alt=\"Build\" /></a>\n  <img src=\"https://img.shields.io/badge/node-%3E%3D18-c41920?style=flat-square\" alt=\"Node.js >= 18\" />\n</p>\n\n<p align=\"center\">\n  <a href=\"https://gitmem.ai/docs\"><strong>Documentation</strong></a> &middot;\n  <a href=\"https://www.npmjs.com/package/gitmem-mcp\"><strong>npm</strong></a> &middot;\n  <a href=\"https://gitmem.ai/docs/getting-started\"><strong>Getting Started</strong></a> &middot;\n  <a href=\"https://gitmem.ai/docs/tools\"><strong>Tool Reference</strong></a>\n</p>\n\n---\n\nGitMem is an [MCP server](https://modelcontextprotocol.io/) 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.\n\n> **What's MCP?** [Model Context Protocol](https://modelcontextprotocol.io/) is how AI coding tools connect to external capabilities. GitMem is an MCP server — install it once and your agent gains persistent memory.\n\nWorks with **Claude Code**, **Cursor**, **VS Code (Copilot)**, **Windsurf**, and any MCP-compatible client.\n\n## Quick Start\n\n```bash\nnpx gitmem-mcp init\n```\n\nOne command. The wizard auto-detects your IDE and sets up everything:\n- `.gitmem/` directory with starter scars\n- MCP server config (`.mcp.json`, `.vscode/mcp.json`, `.cursor/mcp.json`, etc.)\n- Instructions file (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`)\n- Lifecycle hooks (where supported)\n- `.gitignore` updated\n\nAlready have existing config? The wizard merges without destroying anything. Re-running is safe.\n\n```bash\nnpx gitmem-mcp init --yes                # Non-interactive\nnpx gitmem-mcp init --dry-run            # Preview changes\nnpx gitmem-mcp init --client vscode      # Force specific client\n```\n\n## How It Works\n\n```\nrecall  -->  work  -->  learn  -->  close  -->  recall  -->  ...\n```\n\n1. **Recall** — Before acting, the agent checks memory for relevant lessons from past sessions\n2. **Work** — The agent does the task, applying past lessons automatically\n3. **Learn** — Mistakes become **scars**, successes become **wins**, strategies become **patterns**\n4. **Close** — Session reflection persists context for next time\n\nEvery scar includes **counter-arguments** — reasons why someone might reasonably ignore it. This prevents memory from becoming a pile of rigid rules.\n\n## What Gets Remembered\n\n| Type | Purpose | Example |\n|------|---------|---------|\n| **Scars** | Mistakes to avoid | \"Always validate UUID format before DB lookup\" |\n| **Wins** | Approaches that worked | \"Parallel agent spawning cut review time by 60%\" |\n| **Patterns** | Reusable strategies | \"5-tier test pyramid for MCP servers\" |\n| **Decisions** | Architectural choices with rationale | \"Chose JWT over session cookies for stateless auth\" |\n| **Threads** | Unfinished work that carries across sessions | \"Rate limiting still needs implementation\" |\n\n## Key Features\n\n- **Automatic Recall** — Scars surface before the agent takes similar actions\n- **Session Continuity** — Context, threads, and rapport carry across sessions\n- **Closing Ceremony** — Structured reflection captures what broke, what worked, and what to do differently\n- **20+ MCP Tools** — Full toolkit for memory management, search, threads, and multi-agent coordination\n- **Zero Config** — `npx gitmem-mcp init` and you're running\n- **Non-Destructive** — Merges with your existing `.mcp.json`, `CLAUDE.md`, and hooks\n\n## Supported Clients\n\n| Client | Setup | Hooks |\n|--------|-------|-------|\n| **Claude Code** | `npx gitmem-mcp init` | Full (session, recall, credential guard) |\n| **Cursor** | `npx gitmem-mcp init --client cursor` | Partial (session, recall) |\n| **VS Code (Copilot)** | `npx gitmem-mcp init --client vscode` | Instructions-based |\n| **Windsurf** | `npx gitmem-mcp init --client windsurf` | Instructions-based |\n| **Claude Desktop** | Add to `claude_desktop_config.json` | Manual |\n| **Any MCP client** | `npx gitmem-mcp init --client generic` | Instructions-based |\n\nThe wizard auto-detects your IDE. Use `--client` to override.\n\n<details>\n<summary><strong>Manual MCP configuration</strong></summary>\n\nAdd this to your MCP client's config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"gitmem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"gitmem-mcp@latest\"]\n    }\n  }\n}\n```\n\n| Client | Config file |\n|--------|-------------|\n| Claude Code | `.mcp.json` |\n| Cursor | `.cursor/mcp.json` |\n| VS Code | `.vscode/mcp.json` |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` |\n\n</details>\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `npx gitmem-mcp init` | Interactive setup wizard (auto-detects IDE) |\n| `npx gitmem-mcp init --client <name>` | Setup for specific client (`claude`, `cursor`, `vscode`, `windsurf`, `generic`) |\n| `npx gitmem-mcp init --yes` | Non-interactive setup |\n| `npx gitmem-mcp init --dry-run` | Preview changes |\n| `npx gitmem-mcp activate <key>` | Activate Pro tier (auto-applies schema) |\n| `npx gitmem-mcp deactivate` | Remove Pro credentials, free device slot |\n| `npx gitmem-mcp setup` | Output schema SQL (for manual Supabase setup) |\n| `npx gitmem-mcp uninstall` | Clean removal (preserves `.gitmem/` data) |\n| `npx gitmem-mcp uninstall --all` | Full removal including data |\n| `npx gitmem-mcp check` | Diagnostic health check |\n\n## Pro Tier\n\nSelf-hosted on your own Supabase. You bring the infrastructure, gitmem sets it up.\n\n| What you get | Why your agent cares |\n|-------------|---------------------|\n| **Semantic search** | Recall returns the *right* scars, not keyword noise |\n| **Session analytics** | Spot patterns in what keeps going wrong |\n| **Sub-agent briefing** | Hand institutional context to sub-agents automatically |\n| **Cloud persistence** | Memory survives machine changes, shareable across team |\n| **A/B testing analytics** | Measure which scar phrasings actually change agent behavior |\n\n### Quick start\n\n```bash\nnpx supabase login                                          # one time\nexport SUPABASE_URL=\"https://yourproject.supabase.co\"\nexport SUPABASE_SERVICE_ROLE_KEY=\"eyJ...\"\nexport OPENROUTER_API_KEY=\"sk-or-v1-...\"\nnpx gitmem-mcp activate <your-license-key>\n```\n\nThe activate command creates all tables, views, RPC functions, and indexes automatically. No manual SQL needed.\n\nSee **[docs/pro-setup-guide.md](docs/pro-setup-guide.md)** for the full guide.\n\nThe free tier gives you everything for solo projects. Pro makes recall smarter and memory portable.\n\n## GitMem + MEMORY.md\n\nYour AI agent likely has its own memory file (MEMORY.md, .cursorrules, etc.). Here's how they work together:\n\n| | MEMORY.md | GitMem |\n|---|-----------|--------|\n| **Loaded** | Every turn (system prompt) | On-demand (tool calls) |\n| **Best for** | Preferences, shortcuts, quick reference | Earned lessons, unfinished work, decisions |\n| **Updates** | Agent writes directly | Session lifecycle (close ceremony) |\n| **Example** | \"User prefers terse output\" | \"Always validate UUID before DB lookup\" |\n\n**Tip:** Include `.gitmem/agent-briefing.md` in your MEMORY.md for a lightweight bridge between the two systems.\n\n## Privacy & Data\n\n- **Local-first** — All data stored in `.gitmem/` on your machine by default\n- **No telemetry** — GitMem does not collect usage data or phone home\n- **Cloud opt-in** — Pro tier Supabase backend requires explicit configuration via environment variables\n- **Your data** — Sessions, scars, and decisions belong to you. Delete `.gitmem/` to remove everything\n\n## Development\n\n```bash\ngit clone https://github.com/gitmem-dev/gitmem.git\ncd gitmem\nnpm install\nnpm run build\nnpm test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for full development setup.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 8665,
  "sha": "bf7c963b9d7344e93042933847b39232ee2bb4f48a27bb62142ca98d0b1d7231",
  "repo_slug": "gitmem-dev/gitmem",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gitmem_dev_gitmem_fbb7f96f/readme"
}