Skip to main content

GrayMatter Quick Reference Card

Authentication​

All requests require JWT token in Authorization header:

Authorization: Bearer eyJhbGc...

For agents and operators using the GrayMatter plugin, prefer the managed login flow instead of manually pasting tokens:

scripts/gm-login
scripts/gm-install-check
scripts/gm-doctor --quick

gm-login stores reusable auth in the OS keychain when available. gm-doctor --quick verifies install health, auth, memory layer, business graph layer, OpenAPI cache, MCP contract, and deferred replay without running the credit-consuming smoke query.

From the ValkyrAI repository, run the bridge wrapper instead:

scripts/graymatter-doctor.sh --quick

Core Endpoints​

Credit charges are runtime-configured. Use this page for endpoint shape, and use the main site Pricing page for current credit pricing.

Memory CRUD​

OperationEndpointMethodCredit Charge
Create/v1/memory/entriesPOSTRuntime configured
Read/v1/memory/entries/{id}GETRuntime configured
Query/v1/memory/entries?query=XGETRuntime configured
Update/v1/memory/entries/{id}PATCHRuntime configured
Delete/v1/memory/entries/{id}DELETERuntime configured

Operations​

OperationEndpointMethodCredit Charge
Stats/v1/memory/statsGETRuntime configured
Runs/v1/memory/runsGETRuntime configured
Compact/v1/memory/compactPOSTRuntime configured
Reindex/v1/memory/reindexPOSTRuntime configured
Prune/v1/memory/prunePOSTRuntime configured
Expand/v1/memory/expandPOSTRuntime configured

TypeScript SDK Quick Start​

Installation​

npm install @valkyr-labs/api-client

Create Entry​

const memory = new MemoryEntryService({ token });

const entry = await memory.createEntry({
  type: "preference",
  title: "My Pattern",
  text: "Description here",
  tags: ["tag1", "tag2"],
  metadata: { key: "value" },
});

Query Entries​

const results = await memory.queryEntries({
  query: "search term",
  tags: ["tag1"],
  type: "preference",
  limit: 10,
});

results.items.forEach((item) => {
  console.log(item.title);
});

Get Single Entry​

const entry = await memory.getEntry("entry-id");

Update Entry​

const updated = await memory.updateEntry("entry-id", {
  text: "Updated text",
  metadata: { newField: "value" },
});

Delete Entry​

await memory.deleteEntry("entry-id");

Watch Stats​

const stats = await memory.getMemoryStats();
console.log(`Hit rate: ${stats.memory.hitRate}`);
console.log(`Utilization: ${stats.context.usedPct}`);

Run Operations​

// Compact
const compact = await memory.compact({ dryRun: false });
console.log(`Space recovered: ${compact.spaceRecoveredMb}MB`);

// Reindex
const reindex = await memory.reindex({ dryRun: false });
console.log(`Reindex complete`);

// Prune
const prune = await memory.prune({
  confidenceThreshold: 0.5,
  dryRun: false,
});
console.log(`Deleted: ${prune.entriesDeleted}`);

Python HTTP Quick Start​

Create Entry​

import os
import requests

base_url = os.environ.get("VALKYRAI_API_URL", "http://localhost:8080/v1")
headers = {"Authorization": f"Bearer {os.environ['JWT_TOKEN']}"}

entry = requests.post(
    f"{base_url}/memory/entries",
    headers=headers,
    json={
        "type": "instruction",
        "text": "Description here",
        "tags": ["tag1", "tag2"],
    },
).json()

Query Entries​

results = requests.get(
    f"{base_url}/memory/entries",
    headers=headers,
    params={"query": "search term", "tags": "tag1", "type": "instruction", "limit": 10},
).json()

for item in results:
    print(item.title)

Memory Operations​

# Compact
compact = requests.post(f"{base_url}/memory/compact", headers=headers, json={"dryRun": False}).json()
print(compact)

# Reindex
reindex = requests.post(f"{base_url}/memory/reindex", headers=headers, json={"dryRun": False}).json()
print(reindex)

# Prune
prune = requests.post(f"{base_url}/memory/prune", headers=headers, json={"dryRun": False}).json()
print(prune)

Query Syntax Examples​

# Simple keyword
GET /v1/memory/entries?query=payment

# Multiple tags (AND)
GET /v1/memory/entries?query=payment&tags=stripe&tags=pattern

# Full-text search
GET /v1/memory/entries?query=exponential%20backoff

# Type filter
GET /v1/memory/entries?query=retry&type=preference

# Sorting
GET /v1/memory/entries?query=payment&sort=updatedAt&order=DESC

# Pagination
GET /v1/memory/entries?query=payment&limit=20&offset=40

Error Codes & Fixes​

CodeErrorFix
400Bad RequestCheck query parameters
401UnauthorizedVerify JWT token is valid
402Payment RequiredPurchase credits at /buy-credits
403ForbiddenCheck ACL permissions
404Not FoundVerify entry ID is correct
429Too Many RequestsRetry with backoff (2^n * 100ms)
500Server ErrorContact support

CLI Recovery Commands​

SituationCommand
Fresh install or first authscripts/gm-activate
Need a complete readiness reportscripts/gm-doctor --quick
Need the same report from ValkyrAIscripts/graymatter-doctor.sh --quick
Need live write/query proofscripts/gm-doctor
Token missing or expiredscripts/gm-login && scripts/gm-install-check
Plugin feels stalescripts/gm-self-update maybe
OpenAPI/schema looks stalescripts/gm-openapi-sync && scripts/gm-openapi-summary
Writes were deferred during an outagescripts/gm-replay-deferred
Query fails with 402Recharge credits, then rerun scripts/gm-doctor

Rate Limits​

ResourceLimit
Reads/min1,000
Writes/min100
Compact/hour5
Reindex/hour3
Prune/hour5

Memory Types​

TypePurposeExample
contextReusable operational or domain context"SAP has 28% market share"
decisionChosen direction and rationale"Use hosted embeddings for production retrieval"
artifactOutputs, results"Generated pitch deck JSON"
configurationDurable system or agent configuration notes"ValorIDE uses api-0 as its default ValkyrAI host"
preferenceUser/agent preferences"Always use exponential backoff"
todoFollow-up work that should survive sessions"Reindex after importing customer history"

Entry Structure​

{
  "id": "uuid",
  "type": "context|decision|artifact|configuration|preference|todo",
  "title": "Human-readable title",
  "text": "Full content",
  "tags": ["tag1", "tag2"],
  "metadata": {
    "key1": "value1",
    "confidence": 0.95,
    "source": "origin"
  },
  "principalId": "owner-uuid",
  "createdAt": "2026-04-03T15:22:00Z",
  "updatedAt": "2026-04-03T15:22:00Z",
  "createdBy": "user@example.com"
}

Monitoring Commands​

# Check stats every hour
watch -n 3600 'curl -H "Authorization: Bearer $TOKEN" https://api-0.valkyrlabs.com/v1/memory/stats | jq'

# Monitor burst rate
curl https://api-0.valkyrlabs.com/v1/memory/stats | jq '.cost.burnRate'

# List recent operations
curl https://api-0.valkyrlabs.com/v1/memory/runs?limit=10 | jq '.runs[] | {action, success, creditsCharged}'

# Check credit balance
curl https://api-0.valkyrlabs.com/v1/credits/{accountId}/balance | jq '.balance'

Common Patterns​

Pre-Task Context Reading​

const context = await memory.queryEntries({
  query: taskGoal,
  tags: ["instruction"],
  limit: 5,
});

// Use context in execution

Post-Task Learning Capture​

await memory.createEntry({
  type: "decision",
  title: `Success: ${taskName}`,
  text: resultSummary,
  tags: ["learned", taskType],
  metadata: { success: true, duration: ms },
});

Conditional Branching​

const rules = await memory.queryEntries({
  query: decisionPoint,
  type: "PREFERENCE",
  limit: 1,
});

const decision = interpretRule(rules.items[0]);

Multi-Agent Coordination​

// Agent 1: Write findings
await memory.createEntry({
  text: findings,
  tags: ["shared", "research"],
});

// Agent 2: Read & extend
const prior = await memory.queryEntries({
  tags: ["shared", "research"],
});

const extended = extend(prior, newAnalysis);

Dashboard URLs​

  • Memory Dashboard: /graymatter-memory
  • Credits: /credits/{accountId}
  • Buy Credits: /buy-credits

Support & Docs​