git-mem
A git-backed memory MCP server for AI agents — with a read-through cache and a godemode-style "code mode" tool.
git-mem lets an agent get and set memories that are stored as committed files
in a git repository. Because the backstore is git, you get versioned history and
real conflict detection / resolution for free — exactly what you want when
multiple agents (or multiple machines) share one memory store.
- Git is the source of truth. Every memory is one JSON file; every write is a
commit. History, blame, and merges are just git.
- Cache on the Get layer. A read-through LRU+TTL cache serves hot reads
without touching git.
- Code mode. Instead of one MCP round trip per operation, an agent can submit
a single Go program that batches many memory operations — fewer API calls,
fewer tokens. (This is the godemode architecture.)
- Tiny dependency surface. Only two dependencies, both load-bearing:
go-git (pure-Go git, no external binary)
and yaegi (the Go interpreter behind code
mode). Everything else — the MCP server, the cache, the store glue — is Go
standard library.
Benchmarks:
imran31415/git-mem is performative and comptetive with other memory solutions while retaining the easy to understand json/git format:
git-mem-bench
Video Overview:
https://github.com/user-attachments/assets/74b4987c-4619-4c7c-ab12-b5ff30415774
Install
go install github.com/imran31415/git-mem/cmd/git-mem@latest
Or build from source:
git clone https://github.com/imran31415/git-mem
cd git-mem
make build # produces ./bin/git-mem
git-mem speaks MCP over stdio. Point your MCP client at the binary:
{
"mcpServers": {
"git-mem": {
"command": "git-mem",
"args": ["-repo", "/home/you/.git-mem"]
}
}
}
The repo at -repo is created and git init'd automatically if it doesn't exist.
| Tool |
Purpose |
memGet |
Fetch one memory by key (cache-first). |
memSet |
Create/update a memory and commit it. Returns the commit revision. |
memDelete |
Delete a memory and commit the removal. |
memList |
List keys, optionally by prefix. |
memSearch |
Substring search over keys, values, and tags. |
memHistory |
Git commit history for a key. |
memSync |
Pull from the remote and three-way merge; return any conflicts to resolve. |
memPush |
Publish local memory commits to the remote. |
run |
Code mode — run one Go program that batches many of the above. |
Web control panel
git-mem ships a built-in web UI for humans: see the current state of every
memory, browse the git-backed audit trail, and run code-mode
("interpreter") programs from the browser. It's served from the same binary —
no separate process, no build step, no extra files (the whole frontend is
embedded). The web layer is pure Go standard library, keeping the dependency
surface as tiny as the rest of git-mem.
git-mem -repo ~/.git-mem -http :8080
# then open http://localhost:8080
Four views:
-
State — every memory, newest first: decoded value, tags, metadata,
revision, and per-key commit history. Create / edit / delete inline (each
write is a commit).

-
Interpreter — the code-mode editor. Write one Go program that batches many
gitmem.Call(...) operations and see its return value, stdout, and duration.
Snippets and a live list of available calls are one click away.

-
Audit Trail — the repo-wide commit timeline. Because git is the source of
truth, this is the durable record of every change across all keys.

-
Activity — a live trail of recent tool calls across every surface (MCP,
code mode, and the panel itself), with duration and success/error status.

The UI is compact and responsive — it works on a phone as well as a desktop.
-http is mutually exclusive with the default MCP-over-stdio transport (stdout
there is the JSON-RPC channel). The JSON API behind the UI lives under /api/
(/api/state, /api/audit, /api/activity, /api/history, /api/run,
/api/tool, /api/tools).
Keys
Keys are dotted and map to a directory tree under the repo's memories/
subdirectory:
user.preferences.editor -> memories/user/preferences/editor.json
Code mode
The run tool interprets a Go program that imports the injected gitmem
package. gitmem.Call(name, args) invokes any tool above; gitmem.Return(v)
sets the structured result.
package main
import "gitmem"
func main() {
// Batch: read a profile, derive a value, write it back — one round trip.
p, err := gitmem.Call("memGet", map[string]interface{}{"key": "user.profile"})
if err != nil {
gitmem.Return(map[string]interface{}{"error": err.Error()})
return
}
gitmem.Call("memSet", map[string]interface{}{
"key": "user.derived.greeting",
"value": "hello!",
})
gitmem.Return(p)
}
Code mode is sandboxed: imports like os, os/exec, syscall, net, and
unsafe are rejected before interpretation, and every run has a timeout.
Multi-agent sync & conflict resolution
Point several agents at the same git remote and git-mem becomes a shared memory
with real conflict detection — the whole reason the backstore is git.
# Each agent clones/seeds the shared repo on first run:
git-mem -repo ~/.git-mem -remote-url git@github.com:you/agent-memory.git
The loop is set → push → sync → resolve → push:
-
memSet commits locally; memPush publishes to the remote.
-
memSync fetches and three-way merges. Because each memory is its own file:
- edits to different keys merge automatically (no conflict);
- a fast-forward just adopts the remote;
- edits to the same key on both sides are a true conflict.
-
On conflict, git-mem keeps your local value, records a merge commit (so the
merge base advances and resolution converges), and returns the conflict with
all three values:
{ "conflicts": [
{ "key": "doc.title", "base": null,
"local": "B-version", "remote": "A-version" } ] }
-
The agent picks a resolution, memSets it, and memPushes. Other agents
memSync and converge — no value is ever lost (the remote side is preserved
in git history via the merge commit's second parent).
If memPush reports a non-fast-forward, someone else pushed first: memSync
then memPush again.
Auth for real remotes: set GIT_MEM_TOKEN (and optionally GIT_MEM_USER,
default git) for HTTPS; SSH remotes use your agent automatically. Local and
file:// remotes need nothing.
Architecture
agent ──MCP/stdio──▶ pkg/mcp (JSON-RPC 2.0) human ──HTTP──▶ pkg/web (UI + JSON API)
│ │
└──────────────┬───────────────────────────┘
┌──────────────┴──────────────┐
native tools run (code mode)
│ │
▼ ▼
pkg/tools.Registry ◀── pkg/executor (yaegi)
│
▼
pkg/store.CachedStore ──▶ pkg/cache (LRU+TTL)
│
▼
pkg/store.GitStore ──────▶ go-git repository (source of truth)
The native MCP tools, code mode, and the web UI all drive the same registry,
so cache and store logic is written exactly once. Because every call funnels
through Registry.Call, the web panel can observe one unified activity trail
across all three surfaces.
Flags
-repo path to the git memory repo (default ~/.git-mem; created if absent)
-subdir subdirectory for memory files (default "memories")
-remote git remote name for sync/push (default "origin" when -remote-url is set)
-remote-url clone/seed the memory repo from this URL if -repo doesn't exist yet
-author-name commit author name (default "git-mem")
-author-email commit author email (default "git-mem@localhost")
-cache-size max Get-cache entries, 0 = unbounded (default 1024)
-cache-ttl Get-cache TTL, 0 = no expiry (default 5m)
-exec-timeout code-mode execution timeout (default 30s)
-async-writes write-back commits: faster Set/Delete, deferred commit durability (default off)
-flush-interval how often async write-back flushes pending commits (default 50ms)
-http serve the web control panel on this address (e.g. :8080) instead of MCP-over-stdio
-version print version and exit
Development
All workflows are driven by the Makefile — run make (or make help) for the
full list:
make build # build ./bin/git-mem (version stamped from git)
make test # full suite: unit + integration + binary e2e
make test-short # fast suite (skips the binary build)
make test-race # race detector
make cover # coverage.out + coverage.html
make bench # benchmarks
make check # CI gate: tidy-check + vet + test
make deps # print direct deps (should stay at two)
Tests
- Unit tests cover each package in isolation: the LRU+TTL cache, the git
store, the in-memory store, the tool registry, the memory tools, the code-mode
validator, and the interpreter.
- Integration tests (
pkg/mcp) drive the real server stack — MCP →
registry → cached git store → executor — over in-process pipes, asserting on
actual JSON-RPC responses.
- Binary end-to-end tests (
test/) build the binary and talk to it as a
subprocess over stdio, including a test that proves a memory written by code
mode in one process is readable by a second process from the same git repo.
Benchmarks
make bench
Two illustrative benchmarks:
-
Get layer — cache vs git. The read-through cache is dramatically faster
than reading from git on every call:
BenchmarkGet_GitRead-4 ~323000 ns/op
BenchmarkGet_CacheHit-4 ~469 ns/op # ~690x faster
-
Code mode vs native dispatch. Locally, interpreting a program costs more
CPU than direct calls — code mode's real win is collapsing N API round
trips into one, which a local benchmark can't show. The benchmark measures
exactly that local trade-off (and the comment in the test says so).
-
Writes (BenchmarkSet). Each memSet is a real git commit. The naive
go-git path (worktree.Add + worktree.Commit) rescans the whole worktree
and rebuilds the entire tree on every commit — O(repo size). git-mem instead
keeps an in-memory tree model and writes the commit incrementally: only the
tree objects along the changed file's path are rebuilt, reusing cached sibling
subtree hashes. For realistic (namespaced) keys, writes are effectively
constant time regardless of store size:
store size go-git worktree.Add incremental tree (current)
namespaced keys flat keys (worst case)
1 memory ~1.9 ms ~1.2 ms ~0.9 ms
1000 memories ~60.6 ms ~1.2 ms ~3.7 ms
2000 memories — ~1.3 ms ~7.3 ms
"Namespaced" means keys spread across a directory tree (user.*,
project.foo.*, …) — the normal case. "Flat" means thousands of keys jammed
into one directory; git must re-hash that one large tree, which is inherent to
git's data model. Spread keys across namespaces for best write performance.
-
Reads are fully in-memory. git-mem keeps an in-memory index of every
memory (loaded once at startup, kept current on each write), so memGet,
memList, and memSearch never touch disk:
BenchmarkGet ~0.3 µs/op (index lookup; was ~16µs reading the file)
BenchmarkList ~12 µs/op (500 keys)
BenchmarkSearch ~150 µs/op (500 entries; was ~10ms reading every file)
BenchmarkSet ~1.3 ms/op (real git commit: ~6 object writes)
BenchmarkDelete ~1.1 ms/op (real git commit)
memSearch is a substring scan over the index (keys, values, tags) and takes
an optional limit. The index trades memory for speed — it holds all values in
RAM, like the in-memory stores it competes with; git remains the durable
backstore.
In the default (synchronous) mode, memSet/memDelete are bounded by writing
the git objects a real commit needs (blob + the trees along the path + the
commit) — go-git doesn't fsync them, so it's syscall + zlib, not disk-sync.
That's the floor for durable, immediately-committed writes (~1–1.5ms).
Async write-back mode (-async-writes)
For workloads that want sub-millisecond writes, -async-writes makes
memSet/memDelete update the working-tree file and the in-memory tree, compute
the real commit hash, and return — while a background goroutine flushes the
git objects + ref move to disk (every -flush-interval, default 50ms).
sync (default) async
memSet ~1.4 ms ~0.25 ms
memDelete ~1.2 ms ~0.11 ms
Guarantees and trade-offs:
- Reads stay consistent.
memGet/memList reflect a write the instant it
returns (served from the working file / in-memory tree), flushed or not.
- Writes never diverge. They're still serialized, so commits form a linear
chain — async only defers when the chain hits disk, never what it is.
- Data is durable immediately; the commit lags. The value is written to the
working-tree file synchronously. If the process is killed before the
background flush, the commit is replayed from the working tree on next
startup (
recover uncommitted writes).
memSync/memPush/memHistory flush first, so remote and history
operations always see a complete, on-disk state.
- Errors become asynchronous (a flush failure surfaces on the next operation,
not from the
memSet that caused it).
Use sync mode (the default) when "every write is an immediately-committed,
pushable revision" matters most; use async when write latency does.
Comparison with other MCP memory servers
Independent benchmarks vs engram and @modelcontextprotocol/server-memory are at
imran31415/git-mem-bench.
Key results (50 ops, 100-item dataset):
| Operation |
git-mem async |
engram |
mcp-server-memory |
| WRITE |
0.39 ms ★ |
32.73 ms |
1.72 ms |
| READ |
0.09 ms ★ |
38.55 ms † |
1.10 ms |
| SEARCH |
2.38 ms |
36.58 ms |
1.74 ms ★ |
| DELETE |
0.20 ms ★ |
0.23 ms |
3.43 ms |
| LIST |
0.17 ms ★ |
3.48 ms |
1.52 ms |
★ = fastest · † engram has no direct key lookup; READ runs a full-text search.
git-mem wins on READ/WRITE/DELETE/LIST via its in-memory value index and incremental
git commits. mcp-server-memory wins on SEARCH (flat JSONL scan). The benchmark repo
also covers 12 multi-agent scenarios (concurrent contention, session recovery, large
payloads, etc.).
Status
Implemented and tested end-to-end (unit + integration + binary e2e): the MCP
server, all memory tools, the git backstore, the read-through cache, code mode,
and remote sync — fetch + file-level three-way merge with conflict detection,
plus push. The two-agent conflict→resolve→converge loop is verified against a
shared remote.
Possible next steps: an interpreter pool for lower code-mode latency, and a
value-level (sub-document) merge for keys whose JSON objects changed in
non-overlapping fields.
License
MIT