GrayMatter MCP
Agent memory in one Go binary: facts outlive sessions, are found by meaning and by keyword, and unused ones fade over time
- 488 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Hooks in `.claude/settings.json` insert stored facts into the agent's prompt every turn
- The agent writes memory itself, so `.graymatter/gray.db` can end up holding code fragments, paths and stray secrets
- `go install ...@latest` pulls the newest version from GitHub with no pinning
Install
- Works in
Manual install
go install github.com/angelnicolasc/graymatter/cmd/graymatter@latestRequires Go. Installs the latest binary.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Hooks in `.claude/settings.json` insert stored facts into the agent's prompt every turn
- The agent writes memory itself, so `.graymatter/gray.db` can end up holding code fragments, paths and stray secrets
- `go install ...@latest` pulls the newest version from GitHub with no pinning
This is third-party code. Review the repository files before installing.
What it does
GrayMatter stores the facts an agent wrote about a project and returns the most relevant ones in new sessions. A static Go binary of about 10 MB runs the MCP server with `graymatter mcp serve`. Data lives in the file `.graymatter/gray.db`, and no Docker, Redis or cloud account is needed. MCP has seven tools: `memory_search`, `memory_search_batch`, `memory_add`, `memory_alias`, `checkpoint_save`, `checkpoint_resume` and `memory_reflect`, through which the agent adds, updates, forgets, pins and links facts itself. Search blends vector, keyword and recency signals and returns up to eight facts instead of the whole conversation history. Ollama, OpenAI or Voyage AI compute the vectors when available, and otherwise search runs on keywords. A fact has a 30-day half-life: its weight drops when nothing touches it, while pinned facts do not fade. The `recall --explain` command shows why each fact made it into the result. For Claude Code, `graymatter hooks install` writes the `SessionStart`, `UserPromptSubmit`, `PreCompact` and `SessionEnd` hooks. Memory is injected every turn and survives `/compact`, and the phrase `remember: text` in a prompt saves a fact at once. The `--kg` flag on the daemon builds a knowledge graph of people, organizations and projects, `graymatter kg render` draws it as one HTML file, and `graymatter tui` opens a memory workbench with six views.
Who it is for. Developers who run long projects in Claude Code, Cursor, Codex or OpenCode and are tired of explaining the same conventions to an agent every time.
Good fit when
- The agent forgets project conventions in every new session and you repeat them at the start of each chat
- A long history eats the quota: by the developer's own measurement, at 100 sessions an eight-fact result saves about 90% of tokens against the full history
- A fact changed and the agent must stop returning the old value: `graymatter revise` stores the correction
- Rules must reach every agent of a project at once: `remember shared: text` puts the fact in a shared space that each agent reads
- You want to review and edit the accumulated facts by hand in the `graymatter tui` window
Not a fit when
- You need analysis of source code, calls and dependencies: GrayMatter never reads your sources, and facts appear only after an explicit write
- Markdown files must be the primary format, as in Obsidian: `graymatter export --format obsidian` exports to it, but the working store remains the `gray.db` file
- You need shared team memory on a server: the REST server listens only on `127.0.0.1` and is protected by a token
Example request
Remember that migrations in this project are written in plain SQL only, and recall our earlier agreements on directory structureMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
OPENAI_API_KEYsecret- Enables semantic search through OpenAI when Ollama is unavailable.
VOYAGE_API_KEYsecret- Enables semantic search through Voyage AI.
Limitations
- Without Ollama, OpenAI or Voyage AI only keyword search with recency works, and semantic search is unavailable.
- Automatic hooks are described for Claude Code only; other clients connect memory through MCP and the agent writes facts itself.
- Facts fade: after 30 days without access the weight halves, so pin important ones with `graymatter pin`.
- Confidence labels (`--confidence`) arrived in version 0.20.0 and are absent from older binaries.
How to disable. Remove the `graymatter` entry from the client's MCP configuration (`claude mcp remove graymatter` for Claude Code) and the hooks block from `.claude/settings.json`. Memory lives in the project's `.graymatter/` directory: delete it if the facts are no longer needed.
FAQ
How do I connect GrayMatter to Claude Code?
Run `graymatter init` in the project folder and the wizard writes the server into `.mcp.json`. For a user-scoped registration use `claude mcp add --scope user --transport stdio graymatter -- graymatter mcp serve`. `graymatter init --hooks` turns on automatic memory through hooks. Restart the client afterwards.
Do I need an API key or Ollama?
No, storage and keyword search work with no keys and no network. Semantic search turns on when Ollama is available or `OPENAI_API_KEY` or `VOYAGE_API_KEY` is set.
How do I correct a fact the agent remembered wrongly?
`graymatter revise "agent" "old text" "new text"` stores the correction, and search stops returning the old value. To drop a fact with no replacement use `graymatter forget`. Retired facts stay in the store with a tombstone mark.
How is GrayMatter different from context compression?
A compressor shrinks payloads already moving to the model. GrayMatter never sees your traffic: the agent writes short outcomes and later recalls a few relevant ones. The two approaches can be stacked.
Does GrayMatter have a window for browsing memory?
Yes, `graymatter tui` opens a workbench with six views: memory, recall, activity, graph, usage and status. The `--read-only` flag blocks any changes.
Discussion
No questions or reviews yet.
Related
MCP serversA long-term memory MCP server for AI agents: facts fade along a forgetting curve and related records are compressed into a summary
One local binary that gives Claude Code, Codex and Cursor shared memory across sessions, with a knowledge graph on disk and no API keys
Long-term agent memory in local Markdown files with a link graph, semantic search and MCP access
Agent memory as a graph of linked facts: decisions and errors outlive the session, with no vector database or paid API calls
Persistent agent memory in a folder of linked markdown notes, so Claude Code remembers a project across sessions
A long-term memory MCP server for agents: one Rust binary that runs offline and never calls a language model
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| GrayMatter (this card) | no | not required | 488 | |
| agentmemory | yes | not required | 30,160 | hooks record the course of every session automatically, while GrayMatter keeps the facts the agent wrote itself |
| Mem0 | no | 68,456 | a memory layer with plugins, a CLI and an SDK, whereas GrayMatter installs as one Go binary | |
| Basic Memory | no | not required | 4,495 | keeps memory in Markdown files with a link graph, whereas GrayMatter holds facts in one `gray.db` file and weakens old ones |
README in short
The page explains why agents forget a project and gives token measurements on a test set. Next come the knowledge graph, the `graymatter tui` workbench, a quick start, a table of client wiring, the memory lifecycle and the command list. The end has an example of using it as a Go library, sections on embeddings and security, and a comparison with code graphs and context compressors.