Skip to main content

GrayMatter Memory + Credits

This is the production operator view for memory quality and economic control.

Routes​

  • /graymatter-memory (authenticated)
  • /credits/:accountId? (authenticated)
  • /buy-credits

GrayMatter Memory Dashboard​

The dashboard combines polling + websocket updates to track:

  • context pressure (usedPct, wastePct)
  • memory hit quality (hitRate, hotEntries)
  • cost signals (burnRate, retrieval/write/assembly costs)
  • actionable recommendations (compact, reindex, prune, expand)

Primary API surface:

  • GET /v1/memory/stats
  • GET /v1/memory/runs?limit=N
  • POST /v1/memory/compact
  • POST /v1/memory/reindex
  • POST /v1/memory/prune
  • POST /v1/memory/expand

Live overlay events include memory/context/cost channels and alert pushes.

Project Object Graph​

GrayMatter memory operations still write memory primitives such as MemoryEntry, GrayMatter, and SemanticIndexEntry. SwarmOps remains coordination-only.

The RBAC-visible object graph is broader. Project and ProjectObjectLink are now first-class graph objects, so GrayMatter, Valor, ValorIDE, and external agents can reason over:

  • strategy-backed project state
  • goals and tasks
  • generated applications
  • deployments and MCP publications
  • memory evidence attached to project decisions

The LCARS dashboard exposes this through Business > Projects. Workflow Studio exposes deterministic project updates through the Project ExecModule.

Credits Ledger Model​

Credits are ledger-based and prepaid.

Balance model:

  • Balance = Sum(PaymentTransaction.credits) - Sum(UsageTransaction.credits)

Core invariants:

  • no negative credit values
  • idempotency key support to prevent duplicate charges/credits
  • derived balance from ledger entries (not mutable counter state)

Key endpoints used by the UI:

  • GET /v1/credits/{accountId}/balance
  • POST /v1/credits/{accountId}/usage
  • POST /v1/credits/{accountId}/payment
  • POST /api/llm/pass/{accountId} (pass-through usage lane)

Operating Playbook​

  1. Watch memory hit rate and waste in /graymatter-memory.
  2. Execute one recommendation action at a time.
  3. Validate credits balance before high-volume workflow runs.
  4. Use idempotency keys for payment/usage writes when integrating external clients.

Result: better memory quality, cleaner context windows, and fewer billing surprises.