GrayMatter: a single Go binary that gives MCP agents persistent memory

The problem GrayMatter targets: stateless agents and a Go-shaped gap

The README opens with a blunt claim: every AI agent is stateless by default, and each run re-injects the full conversation history. That history grows linearly, so the second prompt in a session already carries the cost of the first. GrayMatter's framing is that this is a money problem as much as a memory problem. The project positions itself against Mem0, Zep and Supermemory, which it describes as Python or TypeScript only and requiring a running server. Whether that characterisation is still accurate for those projects is not something this repository can settle. What matters is the gap GrayMatter claims to fill: an embeddable, zero-dependency memory layer written in Go. The intended user is someone running an MCP-compatible agent on a laptop or a single machine, who wants facts to survive between sessions without standing up Postgres, Redis or Docker. The README lists Claude Code, Cursor, Codex, OpenCode and Antigravity as supported clients, and notes the same code is usable as a plain Go library for people who do not use MCP at all.

How storage and recall actually work: facts, weights, and a 30-day half-life

The mechanism described in the README is a fact store with a decay function rather than a transcript store. Facts are written to disk, and the README states memory cost is reported in KB on disk, covering text plus embeddings, explicitly not tokens. Recall is described as retrieval by meaning rather than keyword, and the default injection size is top-8 relevant facts. Each fact carries a weight, and the TUI defines health as the percentage of facts above a relevance threshold of weight greater than 0.5. Decay is deterministic with a 30-day half-life: facts fade when nothing touches them. Deletion is not offered as a primitive. The README says tombstones are used, never deletes, which means the store grows in one direction unless you manage the underlying files yourself. The recall path exposes its reasoning through recall --explain, which returns per-signal ranks, a fused score and provenance. That is the most useful design decision in the project, because a fused ranking with no explanation is very hard to debug when the wrong fact surfaces.

The knowledge graph is built from co-mention, not from a schema you write

Running graymatter daemon run --kg turns on graph construction. According to the README, each consolidation cycle extracts typed entities (person, organization, project) and links entities that appear together. There is no manual tagging and no configuration step. Every edge stores the fact IDs that produced it, which the README calls receipts. That provenance link is what makes the graph auditable: you can trace an edge back to the facts that created it rather than trusting an opaque similarity score. Export targets are concrete. graymatter kg render --out graph.html produces a self-contained page with inline force-directed SVG and no external assets, so it renders offline. The same command with --out graph.dot emits Graphviz for your own layout. Obsidian export turns entities into notes and connections into wikilinks. The honest caveat is that co-mention linking is a heuristic. Two entities that happen to appear in the same session will be joined whether or not the relationship is meaningful, and the README does not describe a confidence threshold or a pruning rule for weak edges.

Getting it running: hooks, context sync, and the commands that matter

The install path described is a single binary, roughly 10 MB and static, with no Docker, no Redis and no config files. The README gives graymatter hooks install as the step that wires automatic recall into Claude Code, injecting routine recall every turn while leaving MCP available for writes and focused searches. A second integration is context-sync, which projects top facts into CLAUDE.md or AGENTS.md inside a token budget. That is the piece to watch, because it writes into files your agent already reads, and the budget is the only thing standing between you and a bloated instruction file. For inspection, graymatter tui opens a terminal dashboard that auto-refreshes every 5 seconds, with keys 1 through 4 to switch tabs, r to force refresh and q to quit. graymatter doctor --graph reports hubs by degree, articulation points, orphans and a declared connectivity ratio, printed or as JSON. graymatter doctor --graph --html combines analytics with the graph render. The README also includes scripts/kg-timelapse.sh, which turns a deterministic corpus into frames and then a GIF, with a container variant at scripts/Dockerfile.kg-timelapse.

Where the design bites: decay, tombstones, and the shape of the claims

The 30-day half-life is a real constraint, not a footnote. A fact that nothing recalls for two months will have decayed to roughly a quarter of its original weight, and the health metric is defined as the share of facts above 0.5. If your agent touches a topic once a quarter, that topic is drifting toward the tombstone side of the store by design. The README presents this as self-curation, and for a personal coding assistant it probably is. For an audit trail or a compliance record, a decaying weight is the wrong model and GrayMatter is the wrong tool. The second thing to weigh is provenance of the headline numbers. The roughly 90% token reduction is measured against full-history injection, which is the most favourable possible baseline. The claim that facts planted 96 sessions back return 83% of the time is a project-authored figure with no method described in the README. Neither number should be treated as an independent result. The third is operational: the whole design assumes a binary running on the same machine as the agent, which rules out sandboxed or ephemeral agent environments unless you mount the store.

Compared with a hosted memory service, the trade is control for operations

Mem0, Zep and Supermemory are the alternatives the README names, and the stated difference is architectural. Those projects run as servers, typically with Python or TypeScript runtimes, and GrayMatter runs as a local MCP server backed by files on disk. The practical consequences run in both directions. You get offline operation, no account, no API key for storage, and no vendor holding your facts. You also get no server-side multi-tenant model, no managed backups, and no team-shared memory unless you build the sync yourself. A hosted service can be queried from a CI runner or a cloud function without installing anything. GrayMatter cannot, because the agent needs the binary and the store on the same filesystem. There is also a library-level comparison worth noting for Go teams: GrayMatter doubles as an importable Go package, so if you are writing an agent in Go you can call it directly instead of going through MCP. That is a meaningfully different integration path from the server-based options, and it is the one that fits the project's stated thesis about the Go ecosystem.

Licence, maintenance and what the release cadence tells you

GrayMatter is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. That is the permissive end of the spectrum and imposes no copyleft obligation on your own code. This is not legal advice; check the LICENSE file in the repository before you ship. On maintenance, the repository is not archived, the default branch is main, and the most recent push recorded is 2026-09-07. The release history shows v0.19.1 on 2026-09-07, v0.19.0 on 2026-09-07 and v0.18.0 on 2026-08-28, so two releases landed in a single day and three within roughly ten days. A version number still below 1.0 combined with that cadence suggests active development with a still-moving interface. The README advertises CI coverage of core 90% and CLI 81%, and a CI badge is present. Treat the sub-1.0 version as the operative fact: pin a version rather than tracking main, and read the release notes before upgrading, because a memory store that changes its on-disk format between minor versions is a migration you want to schedule rather than discover.

Editorial conclusion

Adopt GrayMatter if you run Claude Code or another MCP client locally and want memory to live in a file on your own disk rather than in a hosted service. Do not adopt it if you need a shared memory layer across a team, or if your agent runs in a container where a CLI binary cannot be installed. Before committing, run graymatter doctor --audit against your existing CLAUDE.md or AGENTS.md to see how many tokens it currently spends, then run graymatter recall --explain on a few queries to confirm the ranking signals behave the way you expect on your own data.

Official sources

1. angelnicolasc/graymatter on GitHub
2. License: MIT
3. Project website
4. README
5. Releases