graymatter

Three lines of code to give your AI agents persistent memory and cut token usage 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.

ctx := context.Background()
mem := graymatter.New(".graymatter")
mem.Remember(ctx, "agent", "user prefers bullet points, hates long intros")
facts, _ := mem.Recall(ctx, "agent", "how should I format this response?")
// ["user prefers bullet points, hates long intros"]

Hand it to your agent

GrayMatter is meant to be installed by the agent that will use it. Paste this to Claude Code, Cursor, Codex, OpenCode, Antigravity, or anything else with shell access:

Set up GrayMatter in this project: https://github.com/angelnicolasc/graymatter Follow the "Agent setup procedure" in its README, and tell me when I need to restart you.

Agent setup procedure

If you are an agent and a user asked you to set GrayMatter up, run these in order and report what each one printed.

1. Install the binary. With Go available:

go install github.com/angelnicolasc/graymatter/cmd/graymatter@latest

Otherwise take the archive for the user's platform from Install below and put graymatter on PATH.

2. Wire the project.

graymatter init            # this project
graymatter init --global   # and every other project on this machine

This writes MCP config for every supported client plus the memory block into CLAUDE.md / AGENTS.md. Entries from other MCP servers are merged, never overwritten, so it is safe in a repo that already has some.

3. Verify.

graymatter doctor

Every line must be ✓ or ·. If it warns, fix that before continuing; the hints are actionable.

4. Ask the user to restart you. This step is not optional. MCP servers are launched by the client when it starts, so the five memory tools do not exist in the session that just ran init. A correct install looks broken until the restart, and this is the single most common reason people think GrayMatter is not working.

5. After the restart, call memory_search once to confirm the tools are loaded, then follow AGENTS.md for when to use which.

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.

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.

Install

Binary (recommended):

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

# Linux (ARM64)
curl -sSL -o graymatter.tar.gz https://github.com/angelnicolasc/graymatter/releases/download/v0.9.0/graymatter_0.9.0_linux_arm64.tar.gz
tar -xzf graymatter.tar.gz
sudo mv graymatter /usr/local/bin/

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

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

Go install:

go install github.com/angelnicolasc/graymatter/cmd/graymatter@latest

Library:

go get github.com/angelnicolasc/graymatter

MCP clients (drop-in)

graymatter init

One command auto-wires GrayMatter into every supported client at once. Existing entries from other MCP servers are merged, not overwritten — safe to run in any repo.

init also drops a managed memory block into CLAUDE.md and AGENTS.md so the model is actually told to call the tools (skip with --skip-instructions). Your own content in those files is preserved; only the marked block is managed.

Client Config file auto-wired Scope

Claude Code .mcp.json project

Cursor .cursor/mcp.json project

Codex (OpenAI) ~/.codex/config.toml home

OpenCode opencode.jsonc project

Antigravity (Google) mcp_config.json project (opt-in: --with-antigravity)

Narrow down what gets wired:

graymatter init --only claudecode,cursor     # whitelist
graymatter init --skip-codex --skip-opencode # blacklist
graymatter init --with-antigravity           # include opt-in clients

Then restart your editor (or toggle the MCP server off/on in its settings). Five tools become available:

Tool What it does

memory_search Recall facts for a query

memory_add Store a new fact

checkpoint_save Snapshot current session

checkpoint_resume Restore last checkpoint

memory_reflect Add / update / forget / link memories (agent self-edit)

Agents using these tools should read docs/AGENTS.md — when to store vs. checkpoint, query patterns, anti-patterns, and the exact per-tool parameter names (heads-up: memory_reflect uses agent, the other four use agent_id).

Any other MCP-compatible client

GrayMatter speaks plain MCP. If your client isn't on the table above, point it at the binary:

graymatter mcp serve                        # stdio transport
graymatter mcp serve --http 127.0.0.1:8080  # HTTP transport (bearer token required)

The schema is identical to every other MCP server — command + args: ["mcp", "serve"]. No proprietary glue.

Global install (all projects)

If you'd rather not run graymatter init in every repo, drop the same JSON into the editor's global config — ~/.cursor/mcp.json for Cursor, ~/.claude/mcp.json for Claude Code:

{
  "mcpServers": {
    "graymatter": {
      "command": "graymatter",
      "args": ["mcp", "serve"]
    }
  }
}

graymatter must be on PATH. The init command handles this automatically on Windows via the User PATH registry; on macOS / Linux the recommended install path /usr/local/bin is already on PATH.

Troubleshooting — "MCP is connected but nothing gets stored"

Run the built-in diagnosis first:

graymatter doctor        # human-readable
graymatter doctor --json # scriptable

It checks the full chain: binary on PATH → data dir writable → store health and lock state → MCP wiring per client → agent instructions present.

The two most common failure modes it catches:

• No instructions. An MCP connection only makes tools available — nothing tells the model to call them. If CLAUDE.md / AGENTS.md don't mention the memor