gitmem



⚡ The Problem

AI coding agents (Claude Code, Cursor, Windsurf, Antigravity) lose their memory between sessions. Every time you open a new conversation, change branches, or have a teammate pull the code:

• Architectural decisions are forgotten.

• Past bugs and lessons are repeated.

• Complex multi-step task graphs get lost.

Beads introduced versioned agent memory, but requires a heavy Go binary and an external Dolt SQL database daemon running on your machine.

gitmem gives your agents persistent, dependency-aware memory stored as plain JSON and Markdown committed directly into your repository.

Related MCP server: ITHZ MCP

🥊 Beads vs. gitmem

🚀 30-Second Quickstart

In your repository root:

npx gitmem init

That's it! gitmem will scaffold .gitmem/ and automatically configure your Cursor (.cursor/mcp.json) or Claude Desktop environment.

Attach to Claude Code

claude mcp add gitmem npx -y gitmem mcp

Attach to Cursor / Windsurf

Add this to your MCP configuration (.cursor/mcp.json or settings):

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

🛠️ MCP Tools for Agents

When attached to an agent, gitmem exposes these standard MCP tools:

• gitmem_context: Dumps instant project briefing (tech stack, conventions, critical gotchas, and top unblocked tasks).

• gitmem_remember: Records an architectural decision, lesson, or preference.

• gitmem_recall: Fuzzy-searches past decisions and gotchas to avoid repeating mistakes.

• gitmem_task_create: Adds a task with dependency tracking (blockedBy: ["task-1"]).

• gitmem_task_claim: Claims a task for the active agent session.

• gitmem_task_complete: Marks task complete and automatically unblocks downstream tasks.

• gitmem_task_list: Queries tasks (e.g. --ready for unblocked tasks only).

💻 CLI Usage

You can also use gitmem directly from your terminal:

Remember a Decision

npx gitmem remember "Use Argon2 for password hashing" \
  --category decision \
  --message "Argon2id is memory-hard and prevents ASIC/GPU attacks." \
  --tags auth security

Recall Memories

npx gitmem recall "password"

Manage Task Dependency Graph

# 1. Create root task
npx gitmem tasks create "Design database schema" --priority high

# 2. Create dependent task (blocked by task-1)
npx gitmem tasks create "Build authentication API" --blocked-by task-1

# 3. View task board
npx gitmem tasks list

# 4. Complete root task (unblocks task-2)
npx gitmem tasks done task-1 --outcome "Prisma schema created"

Instant Agent Bootstrap

# Dump formatted project context to terminal or clipboard
npx gitmem context

📂 Repository Layout

Everything is stored inside your repository under .gitmem/:

your-repo/
├── .gitmem/
│   ├── config.json         # gitmem settings (auto-commit, prefix)
│   ├── memories.json       # Structured decisions, lessons, context
│   ├── MEMORIES.md         # Auto-generated human-readable memory log
│   ├── tasks.json          # Dependency graph (blockedBy, claimedBy)
│   ├── TASKS.md            # Auto-generated markdown task board
│   └── context.json        # Stack, conventions & non-negotiables

Because it lives in git:

• Branch-aware: Branches keep their own context or inherit from main.

• Team-shared: Every git pull updates your local agent's memory.

• Reviewable: You can see every AI agent decision in standard GitHub pull requests!

📜 License

MIT © KuraPiee — Built with ❤️ by the Docwyrm Team.