Everything you need to use memgit — installation, commands, IDE integrations, and the TOON format spec.
Get memgit running in under 30 seconds:
What this does: memgit creates a content-addressed object store for your AI assistant's memory files (CLAUDE.md, .cursorrules, etc.). Instead of loading all memories every session, your AI loads only the top-8 relevant ones via BM25 — saving 95% of tokens.
The primary distribution — works on macOS, Linux, and Windows.
The npm package memgit-mcp is the MCP server for Node.js-based AI tool configs. You don't install it globally — just reference it via npx in your MCP config:
Package on npm: npmjs.com/package/memgit-mcp
Uses a custom tap hosted at github.com/code4161/homebrew-tap:
Install from the VS Code Marketplace: code416-memgit.memgit. The extension shows your memgit log in the Activity Bar and runs memgit commit on file save.
winget support is planned for a future release (requires a standalone Windows executable). Use pip in the meantime.
Live on the Chocolatey community feed (newly pushed versions can take a few days to clear moderation; pip always has the latest):
Initialize a memgit store. With no argument it auto-picks the best location (Claude Code, Cursor, or Windsurf store paths, else ~/.memgit-store). It then automatically finds any existing Claude Code memories (~/.claude/projects/*/memory), tells you how many across how many projects, and offers to import them on the spot — no paths to hunt down.
Adopt memgit on an existing codebase. A store installed mid-project starts empty — there is no initial point for the AI to build on. onboard prints a bootstrap brief for your AI agent: read the README/docs/manifests and recent git history, extract 10–20 durable facts (purpose, architecture, conventions, current state, gotchas), save each as a typed memory, and checkpoint the seed set. Run it once per project; the MCP server also surfaces these instructions automatically when a search misses in a project that has zero memories.
Add or update a mnemonic: a kebab-case slug plus the fact itself, with optional type, why/when context, tags, priority, long-form body, and project scope. The one-line rule stays searchable; --body holds the full lossless detail.
Create a checkpoint of the current memory state. memgit sync can also pull from Claude Code memory files and auto-checkpoint in one step.
Show the checkpoint history. Each entry shows a short SHA, message, timestamp, and memory delta.
Show what changed between two checkpoints. Uses git-compatible short SHA refs.
BM25 relevance search, filtered by default to the current project's family plus explicitly-global memories (v0.7.0) — another project's content never leaks in. Widen deliberately with --all-projects (every hit then carries its project label), or hard-filter one project with --project. Results include the project field in both table and --json output.
Store hygiene (v0.7.0). With no options it reports quarantined _unknown and explicitly-global memories grouped by tag, stale session caches, and dangling usage-ledger entries. The repair flags act on exactly what the report names.
Revert to a previous checkpoint. Creates a new commit for traceability — history is never lost.
The "where we left off" digest: last checkpoints, staged work in flight, recently updated memories, and critical rules — bounded to ~350 tokens regardless of store size. This is what an AI should read before acting on "continue" or "proceed on the pending tasks". Available to agents as the resume_session MCP tool; wire it into every Claude Code session start with memgit setup hooks.
One command wires memory into Claude Code so it happens without the model deciding to act. We measured why this matters: across 166 real sessions, hook-injected context was delivered in 100% of them while the model voluntarily called a memory tool in 6%. What a hook enforces happens; what a tool description suggests mostly doesn't.
SessionStart injects the resume digest. UserPromptSubmit BM25-matches each prompt against the store and injects the relevant memories — silent when nothing clears the relevance bar, never repeating within a session. Stop runs a capture guard (a substantive session that saved nothing gets one nudge to record durable facts) plus an async sync to checkpoint markdown memories. All hooks fail silent — a broken store never blocks a session.
Keep the store small at any history length. squash collapses old checkpoints (each one leaves a one-line record in an append-only archive — nothing is silently lost); gc mark-and-sweeps objects that are provably unreachable from every thread, tag, and the staging index. Reachable history and staged memories are never touched. You rarely need to remember these: resume/status/stats print a maintenance hint naming the exact command once history passes 500 checkpoints or 50 MB.
Three-way merge another thread into the current one (common-ancestor based) — the multi-agent workflow: give each agent its own thread, then merge the results back. Same-memory conflicts resolve to the newest version; an edit always beats a delete. All writes are serialized by a store-wide lock, and set MEMGIT_AUTHOR=agent-name so checkpoints say who did what.
Show token usage comparison between loading all memories vs. memgit's BM25 top-N approach, plus checkpoint count and disk usage. --json for machine output.
Manage memory threads. Threads let you maintain separate memory contexts (e.g. per project or per client).
Register memgit with an installed AI tool by writing the MCP server entry into that tool's config.
memgit integrates via the MCP (Model Context Protocol) stdio server. Run:
The first command registers the memgit MCP server in ~/.claude.json (user scope) — Claude Code then searches and saves memories through the 6 MCP tools. The second installs a SessionStart hook in ~/.claude/settings.json so every new session (including after /clear) begins with the memgit resume digest already in context — the model doesn't have to decide to look.
Registers the memgit MCP server in ~/.cursor/mcp.json:
Install the VS Code extension and configure the path to your memgit repository:
Then add to settings.json:
Registers the memgit MCP server in ~/.windsurf/mcp.json.
Use Gemini function calling against the HTTP server with the tool definitions in llm-tool-definitions.json from the memgit repo.
Any LLM that supports HTTP function calling can use the memgit HTTP server (port 7474 by default):
The OpenAPI spec is at openapi.json in the memgit repo root. Use it to configure ChatGPT Custom Actions or any OpenAPI-compatible client.
memgit organizes memories into eight types:
feedback (fb)Rules and preferences about how the AI should behave — avoid X, prefer Y approach.
user (us)Facts about you — your role, expertise level, and preferences.
project (pj)Project context — decisions, deadlines, architecture choices.
reference (rf)Pointers to external systems — Linear projects, Grafana dashboards, API endpoints.
convention (cn)Code style, naming, and architecture rules.
lesson (lx)Lessons learned and post-mortems — ‘we got burned by X’.
core (co)The per-project operating guide — which tools, skills, and commands to reach for. Injected at session start, synced into every AI host's rules file.
tracker (tr)LIVE status of one entity — a deploy, draft, migration, or campaign. One tracker per entity (slug <entity>-status), updated by re-saving the same slug; renders as the session-start status board.
TOON (Thought Object Observation Notation) is memgit's storage format — line-oriented, human-readable, and diff-friendly. It is modestly leaner than equivalent markdown (~5–10% with a real tokenizer); the big token savings comes from BM25 top-k retrieval, not the format.
A memory in TOON format looks like:
Each line is a sigil-prefixed field: the header carries type, slug, timestamp, and priority; # lines carry tags; PROJ scopes the memory to a project; KEY:value lines carry the rule and its context; BODY holds the full multi-line detail (newlines escaped, so every field stays one line and diffs cleanly under git).
You can import existing memories: memgit import claude-code (auto-finds ~/.claude/projects/*/memory) or memgit import file memories.md
memgit ships a Model Context Protocol (MCP) stdio server with 6 tools:
resume_sessionWhere we left off — last checkpoints, work in flight, critical rules (~335 tokens)search_memoriesBM25 search — returns top-N relevant memories as TOONget_memoryFetch a specific memory by sluglist_memoriesList all memories with metadatasave_memoryUpsert a memory and auto-commitget_checkpoint_logRetrieve the last N commit messagesThe tool descriptions teach the model judgment — "does this request depend on state you don't have in context?" — so it calls resume_session when the user says "continue" or asks about pending work, and search_memories before answering anything that touches past work, injecting only the relevant few hundred tokens instead of your full memory file.
Everything above is free and MIT-licensed, and always will be — the CLI, the store, the MCP server and every command on this page run with no account. Pro adds one thing: hosted end-to-end encrypted sync, so one memory follows you across machines and AI tools. It is $12/month or $99/year, billed by Polar, and one key covers all your machines.
Your key arrives by email the moment the payment clears, and it is also on your Polar purchases page. Activate it once per machine:
That validates the key with Polar and writes it to ~/.memgit/license.json with 0600 permissions. The only bytes that leave your machine are the key itself and memgit's public organisation id — no memory content is ever sent, on this path or any other.
Activation is re-checked at most once every 24 hours, and a machine that has validated recently keeps working for 14 days offline. A flight, an outage at Polar or a dead network never locks you out of your own memories.
Sync ships as an extra, so the base install stays dependency-light:
Commit before you sync. memgit add writes a memory but does not checkpoint it, and sync ships checkpoints — so an uncommitted memory is not an error, it is simply not there yet. The MCP server commits for you on every save; on the command line it is a step. A team is just the unit a store belongs to, and it is yours alone until you invite someone. link creates the repo but not the team, so theteam create line above is required the first time. push and pull exist separately if you want them. Encryption happens on your machine before anything is uploaded: the server stores ciphertext and holds no key that can read it. Your passphrase is what unlocks your keys, and it is never transmitted — lose it and nobody, including us, can recover your memories.
If you activate a key while already logged in, memgit attaches it to your cloud account in the same step. If you logged in afterwards, just run memgit pro activate again.
MCP hosts and CI runners often have no writable home directory. Set the key in the environment instead — it is validated through the same cache and never written to disk:
There is no activation limit: install the key on as many of your own machines as you use. Cancel any time from your Polar purchases page. A lapsed plan never holds your data hostage — the local store is plain files you already have, every memory stays readable, and memgit cloud pull keeps working so you can take everything with you.
Pricing and checkout are on the pricing section; refunds are covered in the Refund Policy.
For ChatGPT, Gemini, or any HTTP-capable LLM:
/resumeWhere-we-left-off digest (checkpoints, staged work, critical rules)/memoriesList all memories/memories/:slugFetch one memory by slug/memories/searchBM25 search with query body/memoriesCreate or update a memory/logGet checkpoint history/statsToken usage statsFull OpenAPI 3.1 spec: openapi.json in the memgit GitHub repo.