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:

0. If scripts/gm-activate is missing but graymatter-bootstrap exists, run ./graymatter-bootstrap to restore runtime files from graymatter.skill
1. Ensure auth is available
2. Confirm install readiness
3. Register the OpenClaw instance as an Agent record for itself in api-0
4. Load the live OpenAPI from https://api-0.valkyrlabs.com/v1/api-docs
5. Treat that spec as the source of truth for the environment's available business objects and actions
6. Use GrayMatter and the broader schema as the primary operational context

Minimum activation flow:

test -x scripts/gm-activate || ./graymatter-bootstrap
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
• /SwarmOps/graph

Use MemoryEntry.type intentionally:

• decision
• todo
• context
• artifact
• preference

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.

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 when relationships matter:

• bot coordination
• entity relationships
• workflow ownership
• operating context that spans objects and agents

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-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, 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: \x3Chttps://api-0.valkyrlabs.com/v1/auth/signup>
• Credits and recharge: \x3Chttps://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

# 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:

1. Query GrayMatter for durable context first
2. Inspect the relevant business entities from the live schema second
3. Use file memory only as fallback or bootstrap
4. Keep durable memory concise and reusable
5. 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

1. Keep writes deterministic and bounded
2. Prefer one clear durable record over many noisy records
3. Do not dump giant blobs into MemoryEntry.text
4. Use the right object for the job, not only MemoryEntry
5. Respect permission failures and surface them clearly
6. 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:\x3Cautomation-id>
• codex:workspace:\x3Cworkspace-key>
• codex:chat:\x3Cchat-id>
• codex:session:\x3Csession-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: \x3Chttps://api-0.valkyrlabs.com/v1/auth/signup>
• credits and recharge: \x3Chttps://api-0.valkyrlabs.com/v1/credits>
• buy credits: \x3Chttps://valkyrlabs.com/buy-credits>
• human signup form: \x3Chttps://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:

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

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