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# initializes repo + imports existing CLAUDE.md
$memgit setup claude-code# wires MCP server + auto-commit hook
$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 or Chocolatey in the meantime.

Chocolatey

Package submitted and pending Chocolatey moderation (1–3 days). Will be installable as:

$choco install memgit

#Commands

memgit init

Initialize a memgit repository in the current directory. Automatically scans for and imports existing AI memory files.

$memgit init
$memgit init --import=claude-code# import from CLAUDE.md only
$memgit init --bare# no auto-import

memgit add

Stage a memory for the next commit. Accepts a file path or a TOON-formatted string.

$memgit add memory.toon
$memgit add --slug auth-pattern --body "JWT in Authorization header, never in cookie"

memgit commit

Create a checkpoint with all staged memories. This is called automatically by the IDE hooks.

$memgit commit -m "Added React hooks rules"
$memgit commit --auto# auto-generates message from changes

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 commits
$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 --slug auth-pattern# diff for one memory

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" --format=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 stats --format=json

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 thread merge main# merge thread into main

memgit setup

Register memgit with an installed AI tool. Writes the MCP server config, adds the Stop hook, and creates the initial commit.

$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 memgit-mcp in ~/.claude/settings.json and installs a Stop hook that auto-commits on session end.

Cursor

memgit writes the top-8 relevant memories into your .cursorrules file before each session.

$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

Writes relevant memories into .windsurfrules at session start.

Gemini CLI

$memgit setup gemini-cli

Populates GEMINI.md and tools.json with the top-8 memories.

Copilot / HTTP API

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

$memgit serve --port 8765

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 five types:

feedback

Rules and preferences about how the AI should behave — avoid X, prefer Y approach.

user

Facts about you — your role, expertise level, and preferences.

project

Project context — decisions, deadlines, architecture choices.

reference

Pointers to external systems — Linear projects, Grafana dashboards, API endpoints.

other

Catch-all for miscellaneous context.

#TOON Format

TOON (Token-Optimised Object Notation) is memgit's storage format — 40% more token-efficient than JSON, human-readable, and diff-friendly.

A memory in TOON format looks like:

--- slug: auth-pattern type: feedback priority: high --- JWT in Authorization header, never in cookie. Use PKCE for all OAuth flows. Minimum 12 chars for passwords, bcrypt rounds=12.

Compared to JSON, TOON avoids quote-heavy key-value pairs and uses YAML-style frontmatter for metadata. The body is plain text — no escaping needed.

You can import existing markdown files: memgit import --format=markdown 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 --port 8765
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 →