graymatter

AI agents forget everything between sessions. GrayMatter gives them persistent memory, a self-building knowledge graph, and cuts context tokens by 90%. One binary. Drop it in. Run it. No Docker, no databases, no config files, no cloud accounts, no bullshit. General-purpose MCP server. Zero vendor lock-in. Works with Claude Code, Cursor, Codex, OpenCode, Antigravity — and any MCP-compatible client. Also a plain Go library if you don't use MCP. Free. Offline. No account required.

Why

Every AI agent is stateless by default. Each run re-injects the full conversation history — and that history grows linearly. Two prompts in and you've already burned half of your daily quota.

That's not just a memory problem. That's a money and performance problem.

Mem0, Zep, Supermemory solve this — but they're Python/TypeScript-only and require a running server. The Go ecosystem has no production-ready, embeddable, zero-dependency memory layer for agents.

That gap is GrayMatter.

Knowledge Graph

Your agent doesn't just remember facts — it builds a map of how they connect.

Run the daemon with --kg and every consolidation cycle extracts typed entities (person, organization, project) and links the ones that appear together. No manual tagging. No configuration. The graph builds itself from ordinary use.

graymatter daemon run --kg    # that's it — the graph builds itself

The graph as one self-contained page — inline force-directed SVG, zero external assets, works offline. Hover any edge to see the fact IDs that produced it:

graymatter kg render --out graph.html
graymatter kg render --out graph.dot    # Graphviz, for your own layout
graymatter doctor --graph --html        # analytics + this render in one go

Watch it build, one frame per session:

scripts/kg-timelapse.sh    # deterministic corpus -> frames -> GIF
                           # or anywhere: scripts/Dockerfile.kg-timelapse

Observability

You can't improve what you can't see.

graymatter tui opens a live terminal dashboard with everything your agent memory is doing — no extra setup required.

What you get at a glance:

• Facts — total stored, distributed across agents
• Memory cost — KB on disk (text + embeddings), not tokens
• Recalls — cumulative access count across all sessions
• Health — percentage of facts above relevance threshold (weight > 0.5)
• Token cost (30d) — real spend breakdown by model, with cache hit rate
• Agent activity — facts vs recalls per agent, side by side
• Weight distribution — how consolidated your memory is over time
• Activity timeline — facts created per day, last 30 days

The dashboard auto-refreshes every 5 seconds. Press 1–4 to switch tabs, r to force refresh, q to quit.

graymatter doctor --graph extends visibility to the knowledge graph itself: hubs by degree, articulation points, orphans, and a declared connectivity ratio — printed or emitted as JSON.

What GrayMatter gives you

Quick start

Install and see it working in under a minute — no API keys, no Ollama:

go install github.com/angelnicolasc/graymatter/cmd/graymatter@latest
graymatter demo              # a working store with 3 agents, then the TUI opens
graymatter init              # wire YOUR project: MCP config + memory block
graymatter init --hooks      # Claude Code: memory injected every turn
graymatter doctor            # verify everything

graymatter init --global still performs that normal setup in the current directory. It additionally installs the managed memory instructions in Claude Code and OpenCode's home-scoped instruction files. It does not globalize project-scoped MCP configs: each repository must be wired separately with graymatter init or manual client configuration. Codex is the exception in the table below because its MCP config is already home-scoped.

graymatter demo seeds a scratch store, runs consolidation, and opens the TUI — then graymatter kg render --out kg-graph.html shows the graph it built. Restart your editor. Seven memory tools are live.

# Homebrew (macOS / Linux)
brew install angelnicolasc/tap/graymatter

# Scoop (Windows)
scoop bucket add angelnicolasc https://github.com/angelnicolasc/scoop-bucket
scoop install graymatter

# Linux (x86_64)
curl -sSL https://github.com/angelnicolasc/graymatter/releases/download/v0.19.1/graymatter_0.19.1_linux_amd64.tar.gz | tar -xz && sudo mv graymatter /usr/local/bin/

# macOS (Apple Silicon)
curl -sSL https://github.com/angelnicolasc/graymatter/releases/download/v0.19.1/graymatter_0.19.1_darwin_arm64.tar.gz | tar -xz && sudo mv graymatter /usr/local/bin/

# Windows (PowerShell)
iwr https://github.com/angelnicolasc/graymatter/releases/download/v0.19.1/graymatter_0.19.1_windows_amd64.zip -OutFile graymatter.zip
Expand-Archive graymatter.zip -DestinationPath .

graymatter init auto-wires every supported client at once. Existing entries from other MCP servers are merged, never overwritten.

Also works out of the box: Pi (reads .mcp.json natively), Zed, Cline, and any MCP-compatible client — point them at graymatter mcp serve. Per-client verified configs for 25 clients, including the ones that need a different shape (VS Code's servers key, Codex TOML, Zed's context_servers), live in docs/integrations.md. See docs/AGENTS.md for tool parameters and query patterns.

Token efficiency

Numbers produced by go run ./benchmarks/token_count — real Recall calls, keyword embedder, no LLM required:

Does it return the right facts?

Tokens are only half the question. A second benchmark checks whether the returned facts actually answer the query, against a real sliding window:

At equal fact count, relevance-selected facts cost slightly more tokens than a window's newest-first picks. With MinRelevance, GrayMatter drops below the window's cost while keeping full recall of old facts. Method and per-query detail in benchmarks/RESULTS.md.

Every figure on this page is machine-checked against a live run in CI.

Memory lifecycle

Recall(agent, task)          ← hybrid: vector + keyword + recency → top-8 facts
    ↓
Inject into system prompt    ← your 3 lines of code
    ↓
Agent runs
    ↓
Remember(agent, observation) ← store key facts during/after run
    ↓
Consolidate() [async]        ← summarise + decay + prune + extract entities

Consolidation is the only "smart" step. Everything else is deterministic.

Hooks (Claude Code, opt-in)

graymatter hooks install writes the hook block into .claude/settings.json