GrayMatter v0.20.0
Persistent memory for AI agents. Local storage, CLI and MCP server.
Quick install
go install github.com/angelnicolasc/graymatter/cmd/graymatter@v0.20.0Prebuilt binaries for Linux, macOS and Windows are in the assets below,
with checksums.txt (sha256). Per-platform download commands are in the
README.
Added
-
Memory workbench with six terminal views. Memory, Recall, Activity, Graph, Usage and Status share a command palette, responsive list/inspector layouts, explicit focus, dark/light/terminal themes and optional mouse navigation. Recall inspection leaves access counts, learned aliases and recall hooks unchanged. Exact-ID curation rejects stale selections; revision commits the replacement and source retirement together. Read-only sessions block mutations at the store boundary and do not start a daemon.
-
Usage observations with explicit provenance. Subscription windows, API billing, request events and session context have separate representations. Configured subscription and administrative billing sources can be refreshed explicitly; snapshot and statusline imports support other clients. Unknown values remain unknown, failed sources retain stale data, and currencies or overlapping estimates are never summed. Harness requests record disjoint token categories; dated user-supplied price books can produce labeled estimates. See Usage setup.
-
Offline workbench demo. The demo uses one isolated keyword-only store, deterministic graph extraction and clearly labeled synthetic Usage observations, regardless of inherited model-provider environment settings.
-
Opt-in confidence writes and retrieval (Refs #126). MCP add and reflect add/update accept validated
confidence; search and batch acceptmin_confidenceand finiteconfidence_weightin[0, 0.5]. CLI remember/revise and recall expose equivalent flags, including shared/all/batch scopes. Go methods add narrow optional capabilities without changingAdvancedStoreorVectorStore. Text and metadata commit on the exact fact; new RPC methods negotiate versioned capabilities and reject unsupported requests with an update/restart error. -
Reconstructible confidence ranking receipts. Filtering precedes IDF, signal ranks, recency, relevance floor, deduplication and top-k. Preference multiplies base RRF by
1 + weight * c(+1verified,0inferred/legacy,-1unverified/unknown). Explain keepsranks.fused_scoreas the base score and adds final score, factor and policy; text and JSON show effective retrieval options even for empty results. Explicit filters suppress graph labels without confidence receipts. The v3 compact index stores effective confidence and rebuilds from canonical facts; read-only old indexes fall back to scan. Native vectors intersect eligible IDs before truncation; custom filtered backends must prove completeness through an optional capability. -
Normal
graymatter initpreserves customized GrayMatter MCP entries. The seven auto-wired clients now retain existing custom commands, arguments, environments, remote endpoints and disabled entries by default.--only CLIENT --replace-mcpdeliberately replaces only selected GrayMatter nodes. Config edits preserve other nodes and require valid, editable documents; unsafe leaves and unsupported metadata fail without truncation. On Windows, any edit to an existing setup file, including instructions, requires permission to read its audit SACL; otherwise preflight rejects it. Edit the file manually or omit the blocked action (for example,--skip-instructions). Explicit--dirpersists an absolute destination in newly installed MCP and hook commands; omitted--dirremains dynamic. -
Init reports a versioned setup result with
--json. The command validates every requested action before applying any, reports per-action status andruntime_verified:false, and exits nonzero on incomplete setup by default.--best-effortpermits exit 0 for a known partial apply with a successful required action; validation, total failure, output errors and uncertain effects still fail. Successful earlier files remain in place for retry. Interactive Windows setup now asks separately for PATH with No as the default, and--no-pathprevents the update. -
graymatter init --store-onlyprepares a project's memory directory without client setup (#81). It creates.graymatter/MEMORY.mdonly when neither a regular marker norgray.dbis present; an existing database remains untouched. The repeatable operation does not write MCP configs, instructions or hooks, changePATH, or open the runtime.--dirselects the store,--quietsuppresses success text, and--jsonreportscreatedoralready_preparedwith the selected path and marker. Versioned Bash and PowerShell launchers inexamples/claude-global/prepare the Git checkout or worktree root before starting Claude Code. The command does not verify database health or client routing, and a user-scoped MCP server can still creategray.dbwhen it starts. -
graymatter mcp serve --no-createrequires a prepared store before MCP startup (#81). This opt-in flag admits an existing regulargray.db, or a regularMEMORY.mdwhen the database is absent; it does not make the runtime read-only or certify database health. An unprepared stdio or HTTP server exits with an actionable error before creating a token, starting a daemon, or serving tools. Prepare withinit --store-only, then reconnect. Existing MCP registrations are not silently changed. Before downgrading to a binary without this flag, remove it from opted-in registrations; an unknown flag fails visibly. -
graymatter doctorshows prompt-packet policies configured in project and global settings. The read-only checks identify explicit choices, inherited defaults, and invalid configurations, and show how to enable experimental lexical selection. -
Optional lexical selection puts more useful memory in the initial prompt context.
graymatter hooks install --packet-policy lexicalselects up to three whole facts from 32 candidates within 832 UTF-8 payload bytes per namespace. It runs locally in Go without an additional model or download;nativeremains the default and is available as an explicit return path. In an exploratory keyword-only pilot of 24 paired tasks, follow-up memory searches fell from 43 to 23, with similar functional results in that sample. The updated hook benchmark measured warm process medians of 51.1 ms native and 56.3 ms lexical at 10,000 facts on the local test machine, with 12 samples per policy. These results are scoped measurements, not general quality or latency guarantees. See lexical hook selection. -
checkpoint_resumecan report a missing checkpoint as a successful, machine-readable result. A new optionalon_missingparameter ("error"— the default — or"empty") lets callers ask for{"found": false, "agent_id"}withisErrorunset instead of the historical not-found tool error, so a session-start check can tell "nothing saved yet" from a broken store without parsing prose. The output schema declares both result shapes underoneOf; storage and daemon failures stay prose-only errors in both modes. See ADR-015.
Changed
-
Omitted confidence on revised or summarized text is conservative. The replacement uses the minimum of inferred and the effective confidence of its validated live sources. LLM-extracted facts are unverified; original-text fallback keeps legacy storage. Pin, decay, access and retirement use narrow current-state mutations that preserve unrelated labels. Revision writes and later retirements remain separate phases; errors report a known committed replacement rather than claiming full workflow atomicity. No pin is inherited.
-
MCP stdio and Claude hooks now choose one project root and store per invocation.
CLAUDE_PROJECT_DIRtakes priority, followed by the hook payloadcwdfor hooks, then the process working directory. An omitted--diruses<project root>/.graymatter; an explicit relative--dirstill uses the process working directory. For example, a hook launched in/work/repo/subdirwithCLAUDE_PROJECT_DIR=/work/reponow uses store/work/repo/.graymatterand namespacerepo, where the prior process-directory path could use/work/repo/subdir/.graymatterandsubdir. A different legacy store containing data causes an explicit routing conflict; no facts are moved. Select the intended store with an absolute--dir, and inspect old namespace IDs before any manual migration. HTTP keeps its service-root routing, authentication policy, and explicitagent_idrequirement. See project routing and migration. -
Hooks and MCP now reject a nonregular
gray.dbbefore opening a store. A symbolic link, reparse point, directory, device, or inspection error blocks both eager and guarded startup, even beside a regularMEMORY.md; an absent DB remains allowed for default eager startup. Valid aliases of the data directory itself remain supported. This leaf check does not detect hardlinks to a regular DB or protect against filesystem replacement after inspection. HTTP still uses bearer authentication by default, with--no-authlimited to loopback.
Fixed
-
Release checks now reject mismatched versions before publishing. Preflight validates release metadata and the CLI's pinned core dependency, and the standalone install smoke checks both the binary version and linked library against the tag without local replacements. CI jobs that test source checkouts apply the local core replacement before Go commands, including scheduled fuzz, mutation, coverage and release snapshot checks.
-
Standard
graymatter doctorno longer writes or removes a fixed-name probe. Setup diagnostics opengray.dbread-only with a private inert vector backend, never run the executable found on PATH, and report incomplete store or graph observations instead of presenting them as empty. The additive JSON fieldsstatus,diagnostic_mode,readiness, anddata_dir_writabilitydistinguish observed checks from client readiness. Existingokand check fields remain. A missing data directory still exits successfully with a warning; filesystem and database failures are surfaced. The special doctor modes keep their separate runtime or output-file contracts. -
The CLI now requires
golang.org/x/text v0.39.0, which fixes GO-2026-5970. This dependency update applies independently of the selected hook policy; lexical selection also rejects malformed UTF-8 before normalization. The module graph advancesgolang.org/x/syncto v0.21.0 without raising the CLI's minimum Go version.
Notes
-
Confidence preference remains disabled by default. The new options are available in v0.20.0 and absent from v0.19.1. This release keeps product and low-level weight zero, preserves old RPC/REST ranking and leaves #126 open. A positive product default requires explicit notice in a published minor release and promotion in a later minor release after frozen calibration and validation gates. This release does not announce a positive default. Explicit zero remains the legacy ranking opt-out and never disables a requested filter.
-
Lexical hook selection remains experimental while conflict coverage and everyday use are evaluated for a future default change. It can omit a supporting fact or one side of a disagreement, and recalling the larger pool updates access metadata even for candidates omitted from the packet. Existing explicit policy choices are preserved.
-
Advance notice: a future
checkpoint_resumedefault ofon_missing: "empty"is conditional on real-client validation. v0.20.0 keeps"error"as the default. A change in v0.21.0 may proceed only after a successful OpenChamber/OpenCode smoke and publication of this prior-minor notice and the matching notice indocs/api-stability.md. If the client rejects the union schema, apply and validate the documented fallback before publishing v0.20.0, keep the default as"error", and defer the default change. Callers that require absence to remain an error should passon_missing: "error"explicitly; that value remains accepted throughout v0.x.