Skip to content
GrayMatter

Quick start

GrayMatter is a single ~10 MB static binary. Install it, run init, restart your editor — done.

Install

Section titled “Install”
Terminal window
brew install angelnicolasc/tap/graymatter

Wire and verify

Section titled “Wire and verify”

  1. Wire every supported MCP client at once:

    Terminal window
    graymatter init

    This creates .graymatter/, writes the MCP config for each detected client, and adds a memory block to CLAUDE.md / AGENTS.md. Existing MCP entries from other servers and customized GrayMatter entries are preserved.

    To replace one GrayMatter entry, run graymatter init --only claudecode --replace-mcp with the client you selected. Invalid files fail before setup writes anything; a later partial apply returns nonzero and can be retried. --best-effort permits a known partial result when a script explicitly accepts one. init --json reports preparation, not live client readiness. On Windows, interactive init asks separately before updating user PATH; --no-path prevents the update.

    graymatter init --global still performs this setup for the current project. It additionally installs home-scoped agent instructions; it does not globalize project-scoped MCP configs. Those clients still need wiring in each repository. A user-scoped Claude MCP registration can be reused across repositories, and Codex’s MCP config is already home-scoped.

  2. Verify:

    Terminal window
    graymatter doctor

  3. Restart your editor. Seven memory tools are live: memory_search, memory_search_batch, memory_add, memory_alias, checkpoint_save, checkpoint_resume, and memory_reflect.

Already using Claude Code globally?

Section titled “Already using Claude Code globally?”

If Claude already has GrayMatter’s MCP server at user scope and can read your global memory instructions, you can prepare a new project’s local store without repeating client setup. The --store-only flag is available since v0.20.0:

Terminal window
graymatter init --store-only --quiet

If the user-scoped MCP registration is missing, add it once:

Terminal window
claude mcp add --scope user --transport stdio graymatter -- graymatter mcp serve

To require preparation before MCP can open a new project store, choose this opt-in registration instead for a new user-scoped entry:

Terminal window
claude mcp add --scope user --transport stdio graymatter -- graymatter mcp serve --no-create
cd /path/to/selected/project
graymatter init --store-only --quiet

Reconnect Claude’s MCP client after preparation. --no-create is not added to existing custom entries by init; change such an entry deliberately. The flag requires a regular gray.db or MEMORY.md, but it is not read-only and does not validate database health. An accepted server can still create gray.db. Hooks and MCP reject a symlink, directory, or other nonregular gray.db even without the flag. HTTP remains authenticated by default; --no-auth is only allowed on loopback. Remove --no-create from the registration before using an older binary, which rejects the unknown flag.

init --store-only creates .graymatter/MEMORY.md only if neither it nor a regular gray.db exists. It does not write MCP configs, agent instructions, hooks or PATH, and it does not verify the database or client routing. Global Claude hooks are optional (graymatter hooks install --scope global). MCP may create gray.db when it starts even if you have not run init. To launch from the selected Git checkout or worktree root, use the Claude Code launcher examples. Keep MCP and hooks pointed at that root, or set the same absolute --dir for all three commands when using a custom store location.

MCP stdio and hooks select a project root per invocation. With no --dir, they use its .graymatter directory. An explicit relative --dir resolves against the launching process’s working directory, which can differ from the project root. If a prior store exists at that other location, GrayMatter asks you to select the destination explicitly; it does not move facts. Read the project routing and migration guide before reusing one MCP registration across repositories or worktrees.

Optional: knowledge graph from day one

Section titled “Optional: knowledge graph from day one”
Terminal window
graymatter init --kg

Persists knowledge-graph activation so every future daemon builds the graph automatically. See Knowledge graph.

Next steps

Section titled “Next steps”
  • MCP clients — per-client config files and manual wiring
  • Agent guide — how agents should use the seven tools
  • Benchmarks — where the 90% number comes from