Skip to main content
Glama

ο»Ώ


⚑ 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

Feature

Beads

🧠 gitmem

Runtime

Go binary

Node.js / TypeScript Native

Storage Engine

Dolt SQL Database Daemon

Plain Git (JSON + Readable Markdown)

Installation

Heavy custom install / Dolt setup

npx gitmem init (Zero-config)

Install Size

~150 MB+

< 3 MB

PR & Code Review

Hidden in Dolt binary storage

Clean, reviewable .gitmem/ diffs

MCP Standard

Custom protocol wrappers

Native @modelcontextprotocol/sdk

Human Readable

Requires SQL queries

Auto-syncs MEMORIES.md & TASKS.md


πŸš€ 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Local-first memory layer for AI coding agents β€” captures issues, attempts, fixes, and decisions, and warns at git commit before you repeat a mistake.
      17
      723 PyPI
      879
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Local-first deterministic project memory for AI coding agents, with context packs, decisions, gates, risks, scoped claims and explicit checkpoints in project-owned files.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Local-first project memory for AI coding agents. Records failed attempts, fragile files, and decisions per repo, and warns the agent via hooks before it repeats a recorded mistake.
      6
      69 npm
      MIT