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.
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.