memgit

memgit — git for AI memory

Your AI assistants forget everything when the session ends. memgit fixes that.

Version-controlled, cross-AI context that persists, diffs, rolls back, and syncs like code. Switch from Claude to Cursor to ChatGPT mid-project — your context is already there.

---

Why not claude.md? Why not mem-search?

You've probably already tried both. Here's why they hit a ceiling:

---

Proof — context costs you can measure

Run this on your own store to see the actual numbers (measured where possible; estimates labeled):

$ memgit stats

Total memories: 108 (41 feedback · 23 user · 19 project · 12 reference · 8 convention · 5 lesson) Priority: 3 critical · 67 medium · 38 low

Context footprint (measured where possible; estimates labeled)

Surface Tokens Full store (every memory as context) 12,840 Resume digest (measured render) 540 Recall block (estimate: top-3 rules ≈ chars/4) ~60

per-session injected ≈ 600 tokens (estimate) vs 12,840 tokens if the full store were loaded

Why such a big difference? claude.md loads *all* context every session. memgit injects a bounded resume digest plus BM25-matched recall — *only what is relevant to this session*, not everything you've ever recorded. The digest is measured by actually rendering it, and the store total is the real corpus size; nothing here is a simulated benchmark.

---

The git analogy is literal

memgit's data model maps exactly to git:

This is not metaphorical — memgit uses a content-addressed object store (SHA-256 blobs) identical to git's architecture. Every memory has a stable SHA. Identical content has identical SHAs. Old state is always recoverable.

---

The store IS a git repo

Every memory is a readable .toon file under memories/. Push your entire memory set to GitHub with standard git:

memgit git init --remote git@github.com:yourteam/ai-memory.git

memgit git push

Teammates pull and start with your AI's learned rules from session 1:

git clone git@github.com:yourteam/ai-memory.git ~/.claude/memgit-store

memgit setup all

You can grep, git blame, and git diff your memories just like code:

grep -rl "database" ~/.claude/memgit-store/memories/

git log --follow memories/no-db-mock.toon git diff HEAD~7 memories/

---

Install

Mac / Linux:

pip install memgit

Mac (Homebrew):

brew tap code4161/tap && brew install memgit

Windows:

choco install memgit

or

pip install memgit

(The Chocolatey package is live on community.chocolatey.org; newly pushed versions can take a few days to clear moderation — `pip install memgit` always has the latest.)

Any AI tool config (no Python needed — npx auto-installs on first run):

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

---

Quickstart (3 minutes)

# 1. Install and initialize

pip install memgit memgit init # auto-detects the best location, finds your existing

Claude Code memories, and offers to import them

2. Register with your AI tools (interactive picker)

memgit setup

3. See your token savings

memgit stats

init walks you through it — no paths to hunt down. (Importing later is one command with no arguments: memgit sync auto-finds ~/.claude/projects/*/memory.)

Restart your AI tool — it now searches your memory store at the start of every session.

---

Adopting memgit mid-project

Memory tools have a cold-start problem: install one halfway through a project and it knows *nothing* — there's no initial point, and context only trickles in from future sessions. memgit solves this with a one-time seeding pass:

cd your-project

memgit onboard # mines the repo, prints the bootstrap brief

onboard first extracts a repo digest deterministically — git history (recent commit subjects, hot files/directories by churn, authors, branch, tags), detected stack from manifests, and the docs worth reading — using bounded, read-only probes that stay near-instant even on huge repositories. The brief then tells your AI agent exactly what to do with it: read only the listed files (no tree crawling), extract 10–20 durable facts (purpose, architecture, conventions, current state, gotchas), save each as a typed memory, and checkpoint the seed set. Paste it into a session — or don't: if the AI searches memory in a project that has none, the MCP server itself replies with the bootstrap instructions instead of a bare "no results."

Memories are project-scoped, filter-by-default (v0.7.0): each carries the workspace it belongs to, and searches, recall injections, and the resume digest (recent memories, checkpoints, depth hints) are filtered to the current project's family plus explicitly-global memories — another project's content never leaks in. Widen deliberately with memgit search --all-projects / all_projects: true (every hit then carries its project label), or hard-filter one project with --project. A memory with no project is explicitly global (applies everywhere): save one with memgit add --global or project: "". A save whose project *cannot be determined* is never silently global — it's quarantined under _unknown (visible in list as [?project], flagged by lint, surfaced nowhere) until you relabel it with memgit doctor --relabel.

---

Resume where you left off

Ask an AI "can we proceed on the pending tasks?" in a fresh session and it will guess from whatever file happens to be open. memgit resume replaces the guess with the record:

memgit resume            # last checkpoints, work in flight, recent + critical memories

memgit resume --plain # plain text, for piping into an AI context memgit resume --json # for tooling

Wire it into Claude Code so memory becomes automatic — no tool call, no judgment required:

memgit setup hooks       # installs all six hooks (~/.claude/settings.json)

Why hooks and not just good tool descriptions? We measured it: across 166 real sessions, hook-injected context was delivered in 100% of them while voluntary memory-tool calls happened in 6%. What a hook enforces happens.

The resume digest is deliberately bounded (~350 tokens measured on a 500-memory store): rules are clipped, the critical list is capped, and full text is one get_memory call away.

---

Scale to 10,000+ sessions

After months of use, your checkpoint history grows. Squash compresses it, gc reclaims the disk:

memgit squash --keep-last 100    # keep last 100 checkpoints, squash everything older

memgit squash --older-than 30 # squash everything older than 30 days memgit squash --dry-run # preview first

memgit gc # delete unreachable objects, trim reflogs memgit gc --dry-run # preview memgit gc --squash-keep 200 # compact history, then sweep

The current memory state is always preserved — and squash is lossless-in-substance: every collapsed checkpoint leaves a one-line record (time, author, diff, message) in an append-only archive under .memgit/logs/archive/ that gc never touches. Benchmark on a 2,000-checkpoint store: 94% smaller (39.5 MB → 2.2 MB), fsck clean. History operations stay O(1) as the chain grows (SHA resolution and checkpoint counting measured at ~0.08 ms at 2,000 checkpoints).

---

Multiple agents, one memory

All writes go through a git-style store lock (0.08 ms overhead), so concurrent agents can't corrupt the store or lose each other's updates. Two patterns:

Shared thread — agents write concurrently; if one commits while another has work staged, the second commit auto-merges (three-way, against the recorded base) instead of clobbering. Set MEMGIT_AUTHOR=agent-name so each checkpoint says who did it.

Thread per agent — isolate, then integrate:

memgit thread create agent-1     # branch off for each agent

... agents work on their own threads ...

memgit merge agent-1 # three-way merge back (common-ancestor based)

Conflicts (same memory changed on both sides) resolve to the newest version; an edit always beats a delete. Both histories are preserved.

---

What the AI sees

Once registered via MCP, every AI tool gets 6 tools:

The tool descriptions teach the AI judgment — "does this request depend on state you don't have in context?" — rather than keyword triggers. Measu