Home/Docs

Documentation

Everything you need to use memgit — installation, commands, IDE integrations, and the TOON format spec.

GitHub →Releases →

#Quick Start

Get memgit running in under 30 seconds:

$pip install memgit# or npm, brew — see Installation below
$memgit init# auto-picks the store location
$memgit setup claude-code# registers the MCP server (or: memgit setup all)
$memgit search "your query"# AI reads 640 tokens, not 12,840

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.

#Installation

pip (Python 3.11+)

The primary distribution — works on macOS, Linux, and Windows.

$pip install memgit
$pip install --upgrade memgit# upgrade to latest

npm — MCP server (Node.js 16+)

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:

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

Package on npm: npmjs.com/package/memgit-mcp

Homebrew (macOS / Linux)

Uses a custom tap hosted at github.com/code4161/homebrew-tap:

$brew tap code4161/tap
$brew install memgit

VS Code Extension

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.

$code --install-extension code416-memgit.memgit# CLI install

winget (Windows)

winget support is planned for a future release (requires a standalone Windows executable). Use pip in the meantime.

Chocolatey

Not yet published to the Chocolatey community feed — use pip on Windows for now. Once it lands it will be installable as:

$choco install memgit

#Commands

memgit init

Initialize a memgit store. With no argument it auto-picks the best location (Claude Code, Cursor, or Windsurf store paths, else ~/.memgit-store). Import existing memories afterwards with memgit import claude-code.

$memgit init# auto-picks the store location
$memgit init ~/my-store# explicit directory
$memgit import claude-code# one-time import of existing Claude Code memories

memgit add

Add or update a mnemonic: a kebab-case slug plus the fact itself, with optional type, why/when context, tags, and priority.

$memgit add auth-pattern "JWT in Authorization header, never in cookie" -t cn
$memgit add api-lesson "Rate limit hits at 60 req/min" -t lx -w "cost us an outage" -W "any client calling the API" -p 3

memgit commit

Create a checkpoint of the current memory state. memgit sync can also pull from Claude Code memory files and auto-checkpoint in one step.

$memgit commit -m "Added React hooks rules"
$memgit commit# message optional

memgit log

Show the checkpoint history. Each entry shows a short SHA, message, timestamp, and memory delta.

$memgit log
$memgit log -n 20# show last 20 checkpoints
$memgit log --oneline# compact view

memgit diff

Show what changed between two checkpoints. Uses git-compatible short SHA refs.

$memgit diff HEAD~1 HEAD# last two commits
$memgit diff c3a891f b7f3e2a# specific commits
$memgit diff --full# show rule text for changed memories

memgit search

BM25 relevance search across all memories. Returns ranked results with token count estimate.

$memgit search "authentication pattern"
$memgit search "auth" --top 5# return top 5 results
$memgit search "auth" --json# machine-readable output

memgit rollback

Revert to a previous checkpoint. Creates a new commit for traceability — history is never lost.

$memgit rollback HEAD~2
$memgit rollback a1d9f3c# rollback to specific SHA
$memgit rollback HEAD~1 --dry-run# preview changes before applying

memgit stats

Show token usage comparison between loading all memories vs. memgit's BM25 top-N approach.

$memgit stats

memgit thread

Manage memory threads. Threads let you maintain separate memory contexts (e.g. per project or per client).

$memgit thread list
$memgit thread create frontend
$memgit thread switch frontend

memgit setup

Register memgit with an installed AI tool by writing the MCP server entry into that tool's config.

$memgit setup claude-code
$memgit setup cursor
$memgit setup windsurf
$memgit setup all# auto-detect and register every tool

#IDE Setup

Claude Code

memgit integrates via the MCP (Model Context Protocol) stdio server. Run:

$memgit setup claude-code

This registers the memgit MCP server in ~/.claude/settings.json — Claude Code then searches and saves memories through the 5 MCP tools.

Cursor

Registers the memgit MCP server in ~/.cursor/mcp.json:

$memgit setup cursor

VS Code

Install the VS Code extension and configure the path to your memgit repository:

$code --install-extension code416-memgit.memgit

Then add to settings.json:

{ "memgit.repoPath": "~/.memgit", "memgit.autoCommit": true }

Windsurf

$memgit setup windsurf

Registers the memgit MCP server in ~/.windsurf/mcp.json.

Gemini

$memgit serve --http

Use Gemini function calling against the HTTP server with the tool definitions in llm-tool-definitions.json from the memgit repo.

ChatGPT / HTTP API

Any LLM that supports HTTP function calling can use the memgit HTTP server (port 7474 by default):

$memgit serve --http

The OpenAPI spec is at openapi.json in the memgit repo root. Use it to configure ChatGPT Custom Actions or any OpenAPI-compatible client.

#Memory Types

memgit organizes memories into six 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’.

#TOON Format

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:

TOON1|fb|auth-pattern|2026-07-01T10:00Z|!3 #auth #security RULE:JWT in Authorization header, never in cookie WHY:Cookie-stored tokens were CSRF-prone in a past incident WHEN:Any authentication or OAuth flow (use PKCE)

Each line is a sigil-prefixed field: the header carries type, slug, timestamp, and priority; # lines carry tags; KEY:value lines carry the rule and its context. No quoting or escaping needed — every field diffs cleanly under git.

You can import existing memories: memgit import claude-code ~/.claude/projects/ or memgit import file memories.md

#MCP Integration

memgit ships a Model Context Protocol (MCP) stdio server with 5 tools:

search_memoriesBM25 search — returns top-N relevant memories as TOON
get_memoryFetch a specific memory by slug
list_memoriesList all memories with metadata
save_memoryUpsert a memory and auto-commit
get_checkpoint_logRetrieve the last N commit messages

The MCP config written by memgit setup tells Claude Code to call search_memories at context-load time, injecting only the relevant 640 tokens instead of your full memory file.

#HTTP API

For ChatGPT, Gemini, or any HTTP-capable LLM:

$memgit serve --http --port 8765# --port only applies with --http
GET/memoriesList all memories
GET/memories/:slugFetch one memory by slug
POST/memories/searchBM25 search with query body
POST/memoriesCreate or update a memory
GET/logGet checkpoint history
GET/statsToken usage stats

Full OpenAPI 3.1 spec: openapi.json in the memgit GitHub repo.

← HomeReleases →