GrayMatter

GrayMatter is the installable OpenClaw skill for durable memory, shared graph state, and live organizational schema awareness through api-0.

Core rule

This skill is intentionally thin. It defines when to use GrayMatter, what to write, and how to choose durable types. Transport resilience, retries, token refresh, fallback queues, and replay behavior belong to shared infrastructure and plugin/client runtime, not this skill.

Use GrayMatter as the primary durable memory system. Use local workspace files only as:

bootstrap context
fallback when api-0 is unavailable
a temporary scratchpad when durable writes are blocked

GrayMatter is not only a note store. It is the authenticated memory and object-graph layer that lets an OpenClaw instance inhabit the organization's live data model safely, within RBAC and the current account's permissions.

Startup behavior

On startup or first use in a workspace that depends on GrayMatter:

Ensure auth is available
Confirm install readiness
Register the OpenClaw instance as an Agent record for itself in api-0
Load the live OpenAPI from https://api-0.valkyrlabs.com/v1/api-docs
Treat that spec as the source of truth for the environment's available business objects and actions
Use GrayMatter and the broader schema as the primary operational context

Minimum activation flow:

scripts/gm-activate

Expanded manual flow:

scripts/gm-login
scripts/gm-install-check
scripts/gm-smoke
scripts/gm-register-agent
scripts/gm-openapi-sync

Auth should be treated as an OpenClaw-managed first-run step. The user should be prompted for api-0 username and password, and the resulting session should be stored securely in macOS/iCloud Keychain for reuse. The user should not need to manually fetch or paste a raw auth token.

What this skill gives the agent

1) Primary memory

Use these first:

/MemoryEntry
/MemoryEntry/query
/MemoryEntry/read
/MemoryEntry/write
/graymatter-retrieval-receipts
/GrayMatter

Use MemoryEntry.type intentionally:

decision
todo
context
artifact
preference

Use Retrieval Receipts when an agent is going to answer from memory. Receipt-backed retrieval exposes retrievalStatus, answerPolicy, recommendedAction, quality scores, provenance, coverage, and policy decisions.

When GrayMatter returns a Retrieval Receipt:

obey answerPolicy
do not answer confidently if the policy is DO_NOT_ANSWER_CONFIDENTLY, REQUIRE_RETRY, REQUIRE_CLARIFICATION, or DENY
if status is LOW_CONFIDENCE, STALE_CONTEXT, PARTIAL_COVERAGE, or CONFLICTING_CONTEXT, retry retrieval, ask a clarifying question, or state uncertainty
preserve receiptId and traceId in internal logs when available

2) Entire-schema awareness

Load the live OpenAPI spec and use it to understand the organization's environment. This skill assumes the agent should understand and work across the available schema, not just memory endpoints. The entire RBAC-visible schema is available to GrayMatter as the operational object graph for the current account.

Observed live schema domains from api-0 include, among many others:

Organization
Customer
Opportunity
Invoice
Product
Application
Workbook
Workflow
Task
Note
MediaObject
FileRecord
SalesActivity
SalesPipeline
Goal
StrategicPriority
KeyMetric
Agent
Space
SwarmOps
GrayMatter
MemoryEntry

This means a properly authenticated OpenClaw instance can understand the business as a live object graph, not as disconnected chat logs.

3) Shared graph coordination

Use SwarmOps and related graph endpoints for the agentic coordination portion of the object graph:

registering Codex/OpenClaw or other agents
agentic tracking
bot coordination
workflow ownership
operating context that spans agents

Use the broader RBAC-visible schema, not SwarmOps alone, for business object relationships such as customers, opportunities, invoices, files, goals, tasks, workflows, notes, and content records.

Scripts

Core transport:

scripts/graymatter_api.sh

Readiness and auth:

scripts/gm-login
scripts/gm-activate
scripts/gm-install-check
scripts/gm-smoke
scripts/gm-register-agent
scripts/gm-openapi-sync
scripts/gm-openapi-summary

Memory and graph helpers:

scripts/gm-write
scripts/gm-query
scripts/gm-retrieval-receipt
scripts/gm-graph
scripts/gm-entity

Local/server packaging:

scripts/gm-light-bootstrap
scripts/gm-light-up
scripts/gm-light-env
scripts/gm-light-json-smoke
scripts/package-local-server

MCP server:

mcp-server/ exposes memory_write, memory_read, memory_query, memory_retrieve_with_receipt, retrieval_receipt_get, retrieval_receipt_query, graph_get, entity_list, entity_get, entity_create, and schema_summary
set VALKYR_API_BASE to hosted api-0 for Cloud mode or to the running GrayMatter Light base URL for local ThorAPI mode

Design boundary:

these scripts are ergonomic wrappers for operators and agents
they must not duplicate retry/auth refresh/fallback/replay logic that already exists in shared infrastructure
if resilience behavior changes, update shared client/plugin contracts first, then keep this skill aligned

Account signup and credits

For a new GrayMatter account, use:

Signup: https://api-0.valkyrlabs.com/v1/auth/signup
Credits and recharge: https://api-0.valkyrlabs.com/v1/credits

Commercial model:

fresh signups should receive 500 starter credits automatically
GrayMatter query and some higher-order operations consume credits
after the starter balance is exhausted, account recharge is required for full GrayMatter functionality

Immediate install and use

Fresh machine or fresh OpenClaw skill install:

scripts/gm-activate

scripts/gm-activate is the one-shot OpenClaw bootstrap script. It can either:

prompt the interactive user for username/password through the normal login flow, or
use credentials already present in environment variables

Then it:

stores the session securely in Keychain
runs install validation
runs the smoke test
registers the OpenClaw server as an Agent
syncs the live OpenAPI
prints a schema summary

Expanded manual flow if needed:

scripts/gm-login
scripts/gm-install-check
scripts/gm-smoke
scripts/gm-register-agent
scripts/gm-openapi-sync
scripts/gm-openapi-summary

scripts/gm-login is the intended OpenClaw login UX: prompt once for username/password, store securely in Keychain, and let the rest of the skill use that session automatically.

scripts/gm-register-agent should run immediately after auth succeeds so the OpenClaw server creates or refreshes an Agent record for itself in api-0 before normal operation.

After that, GrayMatter is ready to use as primary durable memory and schema context.

Basic examples

# query durable memory
scripts/gm-query "graymatter launch" 10

# retrieve memory with an auditable receipt before answering
scripts/gm-retrieval-receipt create "graymatter launch status" 8 DEFAULT

# write durable context
scripts/gm-write context "GrayMatter is primary memory for this OpenClaw instance"

# write durable decision with tags
scripts/gm-write decision "Use GrayMatter as primary memory and file memory as backup" openclaw "graymatter,bootstrap,memory"

# one-shot activation for OpenClaw install or skill bootstrap
scripts/gm-activate

# register this OpenClaw instance as an agent in api-0
scripts/gm-register-agent

# inspect graph state
scripts/gm-graph GET

# fetch live OpenAPI and store a local cache for startup/reference
scripts/gm-openapi-sync

# summarize the live schema in a human-usable way
scripts/gm-openapi-summary

# list organizations visible to the current account
scripts/gm-entity Organization

# fetch a specific customer by id
scripts/gm-entity Customer 123

# create a note directly if the account is allowed
scripts/gm-entity Note POST '{"title":"Launch note","content":"GrayMatter launch in progress"}'

Auth

graymatter_api.sh uses:

VALKYR_API_BASE, defaulting to https://api-0.valkyrlabs.com/v1
VALKYR_KEYCHAIN_SERVICE, defaulting to VALKYR_AUTH
macOS/iCloud Keychain lookup for VALKYR_AUTH
VALKYR_AUTH_TOKEN if already present as an override/debug path
VALKYR_JWT_SESSION as a compatible env fallback

Preferred auth behavior is OpenClaw-first:

check Keychain for VALKYR_AUTH first
if present, reuse it automatically
otherwise prompt for username/password
exchange for a VALKYR_AUTH token
store it in Keychain

If activation can write/read by id and register the agent but semantic memory query is blocked by missing credits, treat that as a degraded startup state rather than total activation failure. Preserve auth, register the agent, sync the schema, and surface that query/list capability is limited until credits are available.

Do not hardcode secrets into the skill. Do not print tokens. Do not require manual token handling as the normal setup path.

OpenAPI and schema loading

The live OpenAPI endpoint is:

https://api-0.valkyrlabs.com/v1/api-docs

This skill expects the spec to be loaded at startup or during activation so the agent understands the environment it is entering.

Use the spec to:

discover available entities
inspect CRUD capabilities
understand domain boundaries
adapt behavior to the current tenant/business
operate as a business-native agent rather than a generic chatbot

Local cache path used by helper scripts:

tmp/api-docs.json
tmp/api-docs.summary.md

Treat the live API docs as authoritative, but remember that actual access is still constrained by auth and RBAC.

Entire-schema operating guidance

When helping in a GrayMatter-native environment:

Query GrayMatter for durable context first
Inspect the relevant business entities from the live schema second
Use file memory only as fallback or bootstrap
Keep durable memory concise and reusable
Prefer authenticated API state over stale local assumptions

Examples:

for sales work, inspect Customer, Opportunity, SalesActivity, SalesPipeline
for operations, inspect Task, Workflow, WorkflowExecution, Application
for content or CMS-like work, inspect Note, MediaObject, FileRecord, Space
for strategy, inspect Goal, StrategicPriority, KeyMetric
for agent coordination, inspect Agent, SwarmOps, GrayMatter, MemoryEntry

Write rules

Keep writes deterministic and bounded
Prefer one clear durable record over many noisy records
Do not dump giant blobs into MemoryEntry.text
Use the right object for the job, not only MemoryEntry
Respect permission failures and surface them clearly
If a known backend bug blocks a write path, fall back cleanly

Tag guidance

When tag persistence is healthy, prefer normalized tags such as:

graymatter
memory
launch
patchbot
salesbot
scribebot

Current caution:

some deployments may still have a MemoryEntry.tags persistence mismatch
scripts/gm-write should retry without tags when the backend rejects tagged writes

Scoped memory hierarchy

Use MemoryEntry.sourceChannel as the primary retrieval scope key. It is the field that gm-query maps to the query source filter, so it should carry the most specific stable context identifier available.

Recommended scope keys:

codex:automation:<automation-id>
codex:workspace:<workspace-key>
codex:chat:<chat-id>
codex:session:<session-id>

When memory is backed by a file path, preserve the folder hierarchy as structured metadata in the MemoryEntry.text header and mirror the strongest scope into sourceChannel. For example, $HOME/.codex/automations/mcp-and-skill-hunter/memory.md should become sourceChannel=codex:automation:mcp-and-skill-hunter with an audit header containing scope, runtime, automationId, artifactPath, and sourceChannel.

The helpers support this convention directly:

scripts/gm-write context "handoff state" --scope-path "$HOME/.codex/automations/mcp-and-skill-hunter/memory.md"
scripts/gm-query "handoff" 5 context --scope-path "$HOME/.codex/automations/mcp-and-skill-hunter/memory.md"

Tags are secondary hints only. Do not depend on tags for scoped retrieval until backend tag persistence is known healthy.

Failure handling

If api-0 is unavailable or a known schema/runtime bug blocks the exact write:

write the smallest safe fallback locally
say GrayMatter was intended but unavailable
preserve a replayable payload for later sync

If login authenticates successfully but no token appears in the response body, use the latest scripts/gm-login, which now treats VALKYR_AUTH as the primary contract and checks body, headers, and cookies accordingly.

Do not pretend durable memory succeeded when it did not.

Known operational note:

/MemoryEntry/query may require credits even when write/read paths succeed
new signups should receive an automatic 500-credit grant so GrayMatter query works immediately during activation
after starter credits are exhausted, recharge is required for full GrayMatter functionality
signup: https://api-0.valkyrlabs.com/v1/auth/signup
credits and recharge: https://api-0.valkyrlabs.com/v1/credits
buy credits: https://valkyrlabs.com/buy-credits
human signup form: https://valkyrlabs.com/funnel/white-paper
scripts/graymatter_api.sh prints both links on INSUFFICIENT_FUNDS and attempts a popup prompt on macOS/Windows
optional overrides: VALKYR_BUY_CREDITS_URL, VALKYR_HUMAN_SIGNUP_URL

Local fallback

Use local files only as backup, typically:

memory/YYYY-MM-DD.md
MEMORY.md
memory/graymatter-fallback.json

GrayMatter remains the primary system of record whenever available.

Installability standard

For this skill to count as installable and immediately usable, a fresh user should be able to:

install the skill
authenticate with scripts/gm-login or env vars
run scripts/gm-install-check
run scripts/gm-smoke
run scripts/gm-register-agent
run scripts/gm-openapi-sync
immediately query memory, write memory, inspect graph state, and inspect live business objects

If any of those fail, the install is not complete.