GrayMatter provides AI agents with persistent memory and significantly reduces token consumption, offering a stateful layer for typically stateless AI interactions. Targeting developers building AI agents, particularly those using MCP-compatible clients like Claude Code and Cursor, it promises up to a 90% reduction in token usage while maintaining or improving response quality through memory consolidation. Its core benefit is enabling more efficient, cost-effective, and context-aware AI agent operations without complex infrastructure.

How It Works

GrayMatter operates as a zero-dependency Go library and a single binary, designed for easy integration. It addresses the stateless nature of AI agents by storing conversation history and learned facts persistently on disk using a local bbolt KV store and a chromem-go vector index. The system employs a hybrid retrieval mechanism combining vector embeddings (with fallbacks to keyword-only search), recency, and relevance scoring (RRF fusion) to recall the most pertinent information for a given query. Memory is managed through explicit Remember calls, LLM-assisted extraction (RememberExtracted), agent self-editing via the memory_reflect MCP tool, and an asynchronous Consolidate process that summarizes, decays, and prunes memories over time. This approach ensures context quality improves and token usage decreases dramatically in longer sessions.

Quick Start & Requirements

• Primary install / run command: Recommended installation is via pre-compiled binaries available for Linux, macOS, and Windows. Alternatively, it can be installed using go install github.com/angelnicolasc/graymatter/cmd/graymatter@latest. The Go library can be added via go get github.com/angelnicolasc/graymatter.
• Non-default prerequisites: Basic functionality requires no external dependencies beyond the binary or Go installation. For embedding capabilities, Ollama (with nomic-embed-text) or API keys for OpenAI/Anthropic are supported. No Docker, databases, or cloud accounts are required for core operation.
• Setup: The project emphasizes a "drop it in" philosophy. For MCP clients, graymatter init automatically configures supported editors.
• Links: Official releases and source code are available on GitHub.

Highlighted Details

• Achieves ~90% token reduction in sessions of 100+ interactions, as demonstrated by local benchmarks.
• Seamlessly integrates with MCP-compatible clients (Claude Code, Cursor, Codex, OpenCode, Antigravity) via a simple init command or by running graymatter mcp serve.
• Offers a graymatter tui command for a live, 4-view terminal dashboard displaying memory statistics, agent activity, and token costs.
• Supports pluggable embedding models, defaulting to Ollama, with fallbacks to OpenAI, Anthropic, or a keyword-only mode.
• Provides a knowledge graph export feature compatible with Obsidian vaults.

Maintenance & Community

The project is maintained by angelnicolasc, with the latest release (v0.5.1) dated April 2026. No specific community channels (like Discord or Slack) or details on sponsorships/partnerships are mentioned in the README.

Licensing & Compatibility

The README states the project is "Free. Offline. No account required. Zero vendor lock-in." However, a specific open-source license (e.g., MIT, Apache) is not explicitly mentioned. This lack of explicit licensing may pose a consideration for commercial use or integration into proprietary systems, requiring further clarification.

Limitations & Caveats

WebSocket streaming for the REST API is listed as a future roadmap item, indicating it is not currently available. While GrayMatter is designed as a library and MCP server, it is explicitly not an agent runner, framework, or hosted service, meaning users must integrate it into their existing agent execution logic. The absence of a clearly stated license requires due diligence for commercial adoption.