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.

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.