github angelnicolasc/graymatter v0.20.0
GrayMatter v0.20.0

latest releases: v0.20.1, cmd/graymatter/v0.20.1
one month ago

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.0

Prebuilt 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 accept min_confidence and finite confidence_weight in [0, 0.5]. CLI remember/revise and recall expose equivalent flags, including shared/all/batch scopes. Go methods add narrow optional capabilities without changing AdvancedStore or VectorStore. 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 (+1 verified, 0 inferred/legacy, -1 unverified/unknown). Explain keeps ranks.fused_score as 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 init preserves 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-mcp deliberately 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 --dir persists an absolute destination in newly installed MCP and hook commands; omitted --dir remains dynamic.

  • Init reports a versioned setup result with --json. The command validates every requested action before applying any, reports per-action status and runtime_verified:false, and exits nonzero on incomplete setup by default. --best-effort permits 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-path prevents the update.

  • graymatter init --store-only prepares a project's memory directory without client setup (#81). It creates .graymatter/MEMORY.md only when neither a regular marker nor gray.db is present; an existing database remains untouched. The repeatable operation does not write MCP configs, instructions or hooks, change PATH, or open the runtime. --dir selects the store, --quiet suppresses success text, and --json reports created or already_prepared with the selected path and marker. Versioned Bash and PowerShell launchers in examples/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 create gray.db when it starts.

  • graymatter mcp serve --no-create requires a prepared store before MCP startup (#81). This opt-in flag admits an existing regular gray.db, or a regular MEMORY.md when 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 with init --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 doctor shows 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 lexical selects 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; native remains 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_resume can report a missing checkpoint as a successful, machine-readable result. A new optional on_missing parameter ("error" — the default — or "empty") lets callers ask for {"found": false, "agent_id"} with isError unset 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 under oneOf; 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_DIR takes priority, followed by the hook payload cwd for hooks, then the process working directory. An omitted --dir uses <project root>/.graymatter; an explicit relative --dir still uses the process working directory. For example, a hook launched in /work/repo/subdir with CLAUDE_PROJECT_DIR=/work/repo now uses store /work/repo/.graymatter and namespace repo, where the prior process-directory path could use /work/repo/subdir/.graymatter and subdir. 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 explicit agent_id requirement. See project routing and migration.

  • Hooks and MCP now reject a nonregular gray.db before opening a store. A symbolic link, reparse point, directory, device, or inspection error blocks both eager and guarded startup, even beside a regular MEMORY.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-auth limited 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 doctor no longer writes or removes a fixed-name probe. Setup diagnostics open gray.db read-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 fields status, diagnostic_mode, readiness, and data_dir_writability distinguish observed checks from client readiness. Existing ok and 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 advances golang.org/x/sync to 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_resume default of on_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 in docs/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 pass on_missing: "error" explicitly; that value remains accepted throughout v0.x.


Don't miss a new graymatter release

NewReleases is sending notifications on new releases.