Skip to main content

GrayMatter: The Memory System for AI Agents

GrayMatter architecture

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

Inside the Valhalla suite, GrayMatter works with Valhalla api-0, the ValkyrAI workflow engine, ValorIDE, Valor, Sheetster Grid, Gridheim Runes, and SWARM-capable agents such as CODEX, OpenClaw, Claude adapters, and other registered workers. Valhalla api-0 supplies the suite backend, generated APIs, RBAC, billing, and admin/control surfaces. ValkyrAI supplies workflow execution and orchestration. GrayMatter supplies memory and RBAC-scoped object graph awareness. Gridheim Runes supply no-persistence calculated fields on generated objects. SwarmOps supplies live agent registration and coordination, not memory storage.

For the system view, use the Valhalla Suite poster: it is a print-ready 36 x 24 in relationship map showing the work surfaces, api-0 control plane, ThorAPI generation spine, generated objects, GrayMatter memory layer, SwarmOps coordination layer, and RBAC-visible object graph.

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 (context, decision, artifact, configuration, preference, todo)"Always use idempotency keys for payment mutations"
PropertiesStructured data, 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 (runtime-configured credit charge, saves 10-20% space)
  • REINDEX: Rebuild semantic indexes (runtime-configured credit charge, improves hit rate 5-10%)
  • PRUNE: Remove stale, low-confidence entries (runtime-configured credit charge, frees up space)
  • EXPAND: Increase capacity when demand sustained (runtime-configured credit charge)

💰 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. Current rates live on the main site Pricing page.

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
  • Control API (/v1/graymatter/control): Valhalla suite, memory, semantic, object-graph, SwarmOps, and client endpoint contract
  • 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 durable memory and a common RBAC-visible object graph. Agent 1 researches a market and writes durable findings. Agent 2 reads those findings and traverses permitted business objects. Agent 3 builds go-to-market strategy. Chain of work is coherent and fast.

For real-time coordination, use the GrayMatter SWARM Protocol as the canonical event contract. WebSocket/STOMP is the live bus; SwarmOps is registration and coordination state; GrayMatter memory remains MemoryEntry/GrayMatter/semantic index state.

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​