git-mem

module
v0.0.0-...-19b05ac Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 15, 2026 License: MIT

README

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

Configure your agent

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.

Tools

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

    State view

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

    Interpreter view

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

    Audit Trail view

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

    Activity view

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:

  1. memSet commits locally; memPush publishes to the remote.

  2. 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.
  3. 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" } ] }
    
  4. 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

Directories

Path Synopsis
cmd
git-mem command
Command git-mem is an MCP server that stores agent memories in a git repository, with a read-through cache and a godemode-style code-mode tool.
Command git-mem is an MCP server that stores agent memories in a git repository, with a read-through cache and a godemode-style code-mode tool.
internal
version
Package version holds the build version, overridable via -ldflags.
Package version holds the build version, overridable via -ldflags.
pkg
cache
Package cache is a tiny, dependency-free, concurrency-safe LRU+TTL cache used to serve the Get layer without hitting git on every read.
Package cache is a tiny, dependency-free, concurrency-safe LRU+TTL cache used to serve the Get layer without hitting git on every read.
executor
Package executor runs godemode-style "code mode": the agent submits one Go program that drives the memory registry via the injected `gitmem` package, and the whole batch executes locally in a single round trip.
Package executor runs godemode-style "code mode": the agent submits one Go program that drives the memory registry via the injected `gitmem` package, and the whole batch executes locally in a single round trip.
mcp
Package mcp implements a minimal MCP server over the stdio transport (newline-delimited JSON-RPC 2.0), exposing the memory registry as native tools plus a single "run" code-mode tool.
Package mcp implements a minimal MCP server over the stdio transport (newline-delimited JSON-RPC 2.0), exposing the memory registry as native tools plus a single "run" code-mode tool.
memory
Package memory defines the on-disk envelope for a single agent memory.
Package memory defines the on-disk envelope for a single agent memory.
store
Package store defines the persistence contract for memories and provides the git-backed implementation plus a cache decorator.
Package store defines the persistence contract for memories and provides the git-backed implementation plus a cache decorator.
tools
Package tools is the godemode-style tool registry.
Package tools is the godemode-style tool registry.
web
Package web serves the git-mem control panel: a single-page UI plus a small JSON API over the same registry + code-mode executor that back the MCP server.
Package web serves the git-mem control panel: a single-page UI plus a small JSON API over the same registry + code-mode executor that back the MCP server.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL