Skip to main content

GrayMatter: The Memory System for AI Agents

GrayMatter architecture

GrayMatter is the durable, relational memory substrate that transforms AI agents from stateless models into intelligent, context-aware systems that learn, adapt, and improve over time.

The Problem​

Traditional AI agents suffer from three critical limitations:

  1. Transient context: Information lives in prompt windows and evaporates between sessions
  2. Opacity: Memory is a black box—you can't see, measure, or improve retrieval quality
  3. Waste: Agents repeat contextual work, hallucinate over forgotten preferences, and accumulate low-signal data

The Solution​

GrayMatter flips the script: Memory is not a side effect of prompts; it's a first-class system.

  • Durable: Memories are stored in PostgreSQL, not prompt windows
  • Queryable: Rich REST APIs for creating, reading, updating, and searching memories
  • Measurable: Dashboard metrics show hit rate, utilization, cost, and recommendations
  • Operationally managed: Compact, reindex, prune, expand—like a relational database
  • Secure: Encryption, ACLs, audit trails for sensitive data
  • Cost-controlled: Prepaid credits for every operation (read, write, compute)

The 4D Memory Matrix​

GrayMatter organizes memory along four orthogonal dimensions:

DimensionDescriptionExample
ObjectsTyped, durable memory atoms (FACT, PREFERENCE, INSTRUCTION, INSIGHT, ARTIFACT)"Always use idempotency keys for payment mutations"
PropertiesStructured data, formulas, derived fields, confidence scoresTitle, text, tags, metadata, embeddings
RelationshipsGraph links: references, contradicts, suggests, causality"This newer instruction supersedes that older one"
TimeTemporal snapshots, diffs, replay for root-cause analysis"What was true when?", "what changed while I was offline?"

Core Capabilities​

📊 Measure: Context Quality​

Watch real-time metrics on the /graymatter-memory dashboard:

  • Hit Rate: % of queries returning relevant results (target: >90%)
  • Context Utilization: % of stored memory actively used (target: 60-80%)
  • Waste: % of memory matching queries but not used (target: <20%)
  • Burn Rate: Credits spent per session (optimize for lowest cost)

🎯 Act: Operational Decisions​

Execute high-ROI memory operations:

  • COMPACT: Consolidate and deduplicate entries (cost: 10 credits, saves 10-20% space)
  • REINDEX: Rebuild semantic indexes (cost: 15 credits, improves hit rate 5-10%)
  • PRUNE: Remove stale, low-confidence entries (cost: 5 credits, frees up space)
  • EXPAND: Increase capacity when demand sustained (cost: 2 credits per increment)

💰 Control: Cost Economics​

Ledger-based prepaid credits:

OperationCostPurpose
Read entryRuntime configuredQuery and retrieve memory
Write entryRuntime configuredCreate or update memory
CompactRuntime configuredOptimize storage and preserve an auditable action record
ReindexRuntime configuredRefresh semantic index metadata
PruneRuntime configuredRemove stale, duplicate, or low-signal entries
ExpandRuntime configuredRecord capacity-expansion intent and checkpoint context

Set automatic top-ups at thresholds. Monitor burn rate for cost anomalies.

Where It Lives in Product​

  • /graymatter-memory (authenticated): Operational dashboard, stats, memory operations
  • /credits/{accountId} (authenticated): Credit balance, usage history, payment methods
  • /buy-credits (unauthenticated): Purchase prepaid credit packages
  • /graymatter/activate (unauthenticated): Dedicated GrayMatter signup/activation funnel with attribution context
  • /graymatter/credits (unauthenticated): Dedicated GrayMatter recharge entrypoint that routes to buy-credits with activation context
  • REST API (/v1/memory/*): Memory runtime operations and compatibility aliases
  • Generated ThorAPI TypeScript clients (src/thorapi): Source-of-truth entity CRUD and model contracts
  • Server & Controls Guide (read the implementation guide): Exact server-side flow, frontend controls, agent usage, tips, gotchas, and FAQ
  • SWARM Protocol (v0.1 spec, JSON schema): Durable coordination contract for Codex, OpenClaw, Valor, Valklaw, ValorIDE, Claude, ValkyrAI native agents, workflows, CRM, CMS, deployments, and audit events. Agents register in the Agent Directory before they broadcast SwarmOps presence.
  • Integrations: ValkyrAI workflows, ValorIDE agents, external systems

Common Use Cases​

1. Support Agents with Contextual Intelligence​

Store issue patterns, solutions, customer preferences. Agents retrieve relevant context before responding. Hit rate improves 30-40%, resolution time drops 50%.

2. Business Analysts Auto-Generating Pitch Decks​

Store market intelligence, company profiles, winning pitch patterns. Agents assemble data-driven decks in 30 min vs. 4 hours of manual work.

3. Agents Continuously Learning​

Store execution logs, successful patterns, failure modes. Each run improves the next: success rate increases 20%+ over 12 weeks.

4. Multi-Agent Coordination​

Agents share a common memory namespace. Agent 1 researches a market, writes findings. Agent 2 reads findings, runs competitive analysis. Agent 3 builds go-to-market strategy. Chain of thought is coherent and fast.

For real-time coordination, use the GrayMatter SWARM Protocol as the canonical event contract. WebSocket/STOMP is the live bus; GrayMatter is the durable replay and audit layer.

5. Compliance & Audit Trail​

Store decisions with full reasoning, signatures, principal IDs. Regulators can inspect the why behind every agent decision. Immutable, timestamped, non-repudiation.

Documentation​