GrayMatter

June 27, 2026 · View on GitHub

GrayMatter is an installable OpenClaw skill and MCP service for:

primary durable memory
shared object-graph state
live organizational schema awareness through the ValkyrAI api-0 OpenAPI

It lets an agent move beyond local files and isolated chat context. Once authenticated, GrayMatter is the agent's exclusive primary durable memory: it persists durable memory, inspects the live business schema, and operates inside the organization's RBAC-scoped data environment.

Release surfaces

GrayMatter ships as three related but independently usable surfaces:

MCP service: mcp-server/ runs as an HTTP/SSE service for Claude.ai, Claude Code, Cursor, ChatGPT Apps SDK, and any MCP-compatible host, and also supports node mcp-server/index.js --stdio for plugin-managed MCP launch.
Codex plugin: .codex-plugin/plugin.json exposes this repo as the graymatter plugin with the standalone skill plus .mcp.json, so Codex can discover both the instructions and the MCP server.
Standalone OpenClaw skill: graymatter.skill packages SKILL.md and the required scripts for OpenClaw install, activation, hosted api-0 use, and GrayMatter Light local mode.

If a GitHub sparse/root install only brings down root files, run ./graymatter-bootstrap from the installed GrayMatter directory. It restores scripts/ and mcp-server/ from the bundled graymatter.skill archive so end-user installs do not depend on a full repo clone.

Quick start

git clone https://github.com/ValkyrLabs/GrayMatter.git
cd GrayMatter
brew install jq
scripts/gm-activate

scripts/gm-activate is the preferred first-run path. It checks for updates, signs in, stores the session in Keychain when available, validates the install, registers the agent, syncs the OpenAPI schema, and runs the readiness checks needed for normal use.

Before task planning, code edits, production-affecting actions, or answers based on project history, agents must immediately run the invariant preflight for the current workspace/product:

scripts/gm-invariant-preflight ValkyrAI signup acl thorapi aspectj

MCP hosts that cannot shell out should call graymatter_invariant_preflight. Returned decision records tagged as invariants, security, RBAC/ACL, generated-code, AspectJ, vaix/vai, testing, or product names are binding operational rules. Missing or degraded retrieval is never permission to ignore known durable rules.

The required preflight is broader than a keyword search. It must look up invariants, rules, instructions, prior session context, personalization, business truth, personal truth, and organizational truth before the agent begins work. New user-provided corrections, procedures, preferences, and invariants must be written to GrayMatter during the session and read back by ID to confirm persistence.

For ValkyrAI, ValorIDE, GrayMatter Light, and ThorAPI-generated application work, agents should prefer repo launchers over direct build shortcuts: ./vaix build, ./vaix test, ./vaix run, and repo-documented ./vai flows preserve ThorAPI generation, AspectJ weaving, heap defaults, local H2/runtime flags, and end-user operational behavior. Signup, ACL/RBAC, and generated API fixes should normally be proven with ./vaix run on localhost:8080 plus the frontend on localhost:5174 before using production only as a comparison point.

For Valkyr-native agent routing, treat GrayMatter as shared memory and schema context for ValkyrAI, ValorIDE, ThorAPI, TrustFabric, GridHeim, and SWARM coordination work. Load durable invariants first, then route implementation through the owning generated-code, security, workflow, or MCP surface.

P0 RBAC/ACL security invariant: generated ThorAPI ACL behavior is the authorization source of truth. No custom controller, delegate, service, frontend filter, status check, type check, role shortcut, catalog rule, or "public-ish" heuristic may bypass, weaken, replace, or shadow generated ACL behavior. Users may see owned records and records shared by explicit ACL grants only; public access requires explicit anonymousUser READ. Solve ACL scale with indexed owner/ACL query selection plus final generated ACL guards, never by scanning private rows or adding object-specific bypasses.

P0 Valkyr Way UX/auth invariant: product UX must be integrated into the shared application shell and centralized auth/session primitives. Do not create one-off screens, standalone admin affordances, self-managed auth checks, browser-cache shortcuts, or cobbled mini-apps that bypass LCARS navigation, route guards, shared access-control state, RTK Query cache invalidation, or generated RBAC/ACL contracts. Admin and finance tools belong inside the appropriate LCARS dashboard/sidebar surfaces; user management has one Users & Roles surface with card/list modes rather than separate /userList and dashboard implementations. If authentication behavior changes, update the centralized auth/access-control modules and tests instead of scattering per-component checks.

What GrayMatter is for

GrayMatter is the memory and context layer for business-native agent systems.

It is designed so an OpenClaw instance can:

read and write GrayMatter and MemoryEntry records
retrieve memory through explicit Retrieval Receipts that expose confidence, freshness, provenance, policy, and next-action signals
use the entire RBAC-visible schema exposed by the tenant/account as its object graph
coordinate agents through SwarmOps
adapt to the actual business environment, for example customers, invoices, products, notes, files, workflows, tasks, CMS-like content, strategy objects, and sales records
use file-based memory only as bootstrap or fallback

This is the core idea:

GrayMatter is not just memory storage. It is the authenticated object-relational memory graph and schema-awareness layer that lets the agent inhabit the organization safely and usefully.

Primary-memory model

Boundary rule: This skill stays thin. It should teach usage intent, durable type selection, and operator ergonomics. Retry behavior, auth/session refresh, fallback queueing, and replay execution belong to shared GrayMatter infrastructure contracts. Keep this repository aligned with those contracts rather than re-implementing them.

GrayMatter should be the exclusive primary durable memory system whenever it is available through the skill, plugin, MCP server, app connector, or prompt command. Agents should not maintain a competing durable memory store for user, project, business, organizational, or long-lived agent state.

Use local files only as:

bootstrap context on first startup
temporary fallback when hosted api-0 is unavailable or authentication is genuinely blocked
temporary replayable backup when a write path is blocked

Local fallback is degraded-mode replay, not source-of-truth memory. Once auth or connectivity returns, agents must replay local records into api-0, confirm durable sync, and remove synchronized local copies.

Durable memory targets

Primary targets:

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

Typical MemoryEntry.type values:

decision
todo
context
artifact
preference

Retrieval Receipts

For answer grounding, prefer receipt-backed retrieval over raw memory search when the agent intends to answer from memory.

Retrieval Receipts turn a memory lookup into an auditable transaction:

retrievalStatus tells the agent whether the lookup was strong, empty, stale, conflicted, or low confidence
answerPolicy tells the agent whether it may answer, must caveat, must retry, must clarify, or must deny
recommendedAction tells the next move before generation
quality, coverage, provenance, and policy explain why
receiptId and traceId let downstream logs and audits connect the answer to the memory lookup

Agent rule: When a Retrieval Receipt is present, inspect answerPolicy before answering. Do not answer confidently when it is DO_NOT_ANSWER_CONFIDENTLY, REQUIRE_RETRY, REQUIRE_CLARIFICATION, or DENY.

Entire-schema capability

GrayMatter should load the live ValkyrAI OpenAPI at startup:

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

This gives the agent live knowledge of the environment it is operating in.

That means the agent can inspect what entities and operations actually exist for the current deployment, instead of relying on stale assumptions.

Why this matters

Most businesses are not just “memory plus chat.” They have structured operational data.

Examples observed in the current live schema include:

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

The current live endpoint exposes a large domain surface, including 100+ tags and hundreds of paths. The exact usable subset is still governed by the human's credentials, organization setup, and RBAC.

This is what makes GrayMatter powerful: the agent can become deeply context-aware inside the business without overreaching beyond granted permissions.

SwarmOps remains important, but as the agentic coordination slice of the object graph: registration, tracking, and swarm protocol state for Codex/OpenClaw and peer agents. Business relationships should use the broader RBAC-visible schema directly.

Safety model

GrayMatter is powerful because access is authenticated and tenant-scoped. It is also safe by design when used correctly because:

access is bounded by the current account's RBAC
the user and organization permissions determine what the agent can see and change
permission failures can be surfaced cleanly
the skill should never assume universal access just because the schema exists

Rule:

schema visibility does not equal permission to use everything

Repository contents

SKILL.md — OpenClaw AgentSkill instructions
graymatter.skill — packaged distributable AgentSkill
scripts/graymatter_api.sh — authenticated production API transport
scripts/gm-login — login helper
scripts/gm-activate — one-shot auth + install + agent registration + schema sync bootstrap
scripts/gm-activation-fastlane — first-run readiness, one-shot activation, non-secret telemetry, and reviewer-safe demo runner
scripts/gm-self-update — repo/plugin self-update check for startup, weekly refresh, and auth/connectivity recovery
scripts/gm-install-check — dependency and auth readiness check
scripts/gm-doctor — full readiness report for self-update, auth, memory, schema, MCP, replay, and smoke status
scripts/gm-smoke — production smoke test for write/query validation
scripts/gm-invariant-preflight — load binding durable invariants before agent planning, edits, or production-impacting actions
scripts/gm-query — query MemoryEntry
scripts/gm-read — read one MemoryEntry by ID
scripts/gm-retrieval-receipt — create, fetch, and list retrieval receipts through ThorAPI
scripts/gm-write — write MemoryEntry, with tagged-write fallback behavior
scripts/gm-fallback-append — append failed writes to local replay queue at memory/graymatter-fallback.json
scripts/gm-replay-deferred — replay operations that were locally deferred during credit/connectivity/auth outages
scripts/gm-graph — inspect Swarm graph endpoints
scripts/gm-openapi-sync — fetch and cache the live OpenAPI spec locally
scripts/gm-openapi-summary — summarize live schema domains and endpoints
scripts/gm-status — quick health/status surface for auth source, fallback queue, and OpenAPI cache
scripts/gm-agent-smoke-matrix — install/read-search/write/MCP/schema/safe-response readiness matrix for OpenClaw and Codex-style agents
scripts/gm-client — generic REST wrapper for GET/POST/PUT/PATCH/DELETE against GrayMatter API paths
scripts/gm-entity — generic helper for listing, reading, and writing arbitrary schema entities
scripts/gm-record — convenience helper for strategic-priority and KPI records
scripts/gm-register-agent — register or refresh the OpenClaw server as an Agent in api-0
scripts/gm-mcp-contract — emit the portable MCP memory-tool contract schema used by agent/IDE adapters
scripts/gm-light-bootstrap — copy and render the local GrayMatter app bundle and server source scaffold from bash-friendly templates
scripts/gm-light-up — generate and start the local ThorAPI-backed GrayMatter Light instance
scripts/gm-light-env — print the environment exports that point skill scripts at the running Light instance
scripts/gm-light-smoke — prove the local Light loop by writing/querying a decision and checking memory health
scripts/gm-light-json-smoke — JSON-file fallback smoke test for Light payload shape without ThorAPI
scripts/package-local-server — package the standalone downloadable GrayMatter Local Server archive
scripts/package-graymatter — deterministic validation and packaging
mcp-server/ — standalone HTTP/SSE and Apps SDK /mcp server for GrayMatter memory, invariant preflight, retrieval receipt, graph, entity, schema, and overview tools
docs/architecture.md — architecture and operating model
docs/openai-app-directory-submission.md — Apps SDK submission checklist and copy
docs/privacy-policy.md — GrayMatter-specific public privacy policy source
docs/reviewer-test-credentials.md — review demo-account setup and secure credential handoff runbook
docs/prd-context-compaction-reset.md — PRD for bounded chat compaction and reset flows
docs/thorapi-integration.md — ThorAPI relationship and bundle direction
docs/graymatter-light.md — local/offline notes
docs/server-capabilities.md — live api-0 memory, retrieval, graph, schema, auth, credit, and MCP capability map
openai-app/submission-manifest.json — non-secret app metadata for OpenAI dashboard submission
examples/* — example payloads and Light-mode starter assets
references/* — release and multi-agent guidance, including concurrency conventions
references/mcp/memory-tool-contract.v1.json — stable v1 portable tool contract for memory and graph operations
clawhub.json — publishing metadata

Install details

For a new GrayMatter account, use:

Signup and activation: https://valkyrlabs.com/graymatter/activate?source=graymatter&intent=signup&operation=memory_query
Credits and recharge: https://valkyrlabs.com/graymatter/credits?source=graymatter&intent=recharge&operation=memory_query

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

First-run auth, the intended OpenClaw flow

The user should not have to manually acquire or paste a raw auth token.

The intended first-run OpenClaw auth step is:

OpenClaw prompts the user for their api-0 username
OpenClaw prompts for their password
OpenClaw exchanges those credentials for a session
OpenClaw stores the resulting session securely in macOS/iCloud Keychain
OpenClaw creates or refreshes an Agent record for itself in api-0
Subsequent GrayMatter use reads from Keychain automatically

That means GrayMatter should feel like:

sign in once
store securely
use forever after until refresh is needed

Manual token handling is a fallback/debug path, not the primary user experience.

Repo-based install

git clone https://github.com/ValkyrLabs/GrayMatter.git
cd GrayMatter
brew install jq
scripts/gm-activate

scripts/gm-activate is the intended one-shot bootstrap for OpenClaw installs. It first runs scripts/gm-self-update force by default so activation and recovery do not skip the source-of-truth update check just because the weekly startup interval has not elapsed, then authenticates and validates the install. Set GRAYMATTER_ACTIVATE_SELF_UPDATE_MODE=maybe only when an operator intentionally wants interval-gated startup behavior. It can use:

interactive username/password prompts, or
credentials already present in environment variables

Supported env inputs:

GRAYMATTER_USERNAME or VALKYR_USERNAME
GRAYMATTER_PASSWORD or VALKYR_PASSWORD
optional VALKYR_AUTH_TOKEN
optional VALKYR_KEYCHAIN_SERVICE if a non-default macOS Keychain service name is required
optional OPENCLAW_INSTANCE_ID
optional OPENCLAW_AGENT_NAME
optional OPENCLAW_AGENT_ROLE

scripts/gm-login should be treated as the standard OpenClaw login step. It prompts for username/password and stores the session in macOS/iCloud Keychain by default.

scripts/gm-register-agent is part of the expected startup handshake. When an OpenClaw server connects to api-0, it should create or refresh an Agent record for itself before proceeding with normal work.

scripts/gm-self-update is the normal plugin/repo update path. Agents should run it on startup and when auth or transport looks suspicious. It updates clean git checkouts with a fast-forward pull and updates packaged installs from https://github.com/ValkyrLabs/GrayMatter.git when the weekly interval is due or force is requested; activation uses force unless overridden. Dirty git checkouts are never overwritten.

scripts/graymatter_api.sh and the MCP server perform autonomous auth refresh when the stored token expires or api-0 returns a refreshable auth failure. Replay-safe write operations blocked by credits or transport can be deferred and retried with scripts/gm-replay-deferred.

At that point the install should be immediately usable.

If auth succeeds but memory query is temporarily credit-gated, scripts/gm-activate now continues in a degraded mode: auth is stored, the agent is registered, the OpenAPI is synced, and the script reports that memory query capability is limited until credits are available.

For the app-review or customer first-run path, use the activation fastlane:

scripts/gm-activation-fastlane --check-only
scripts/gm-activation-fastlane --reviewer-demo

--check-only verifies install readiness, runtime status, and the portable MCP memory-tool contract without activating or writing demo data. --reviewer-demo runs the normal activation path, then performs a bounded sample MemoryEntry write/query, graph read, schema summary, and safe MemoryEntry entity list. The script emits non-secret events such as activation_started, auth_completed, schema_synced, first_memory_written, first_query_succeeded, credit_warning_shown, and activation_completed to stderr, and also appends them to GRAYMATTER_ACTIVATION_EVENT_LOG when that env var is set.

Raw bearer-token setup remains a debug/advanced path. The default first-run story is sign in, store securely, validate tools, write/query a demo memory, then continue with starter-credit-aware next actions.

For a one-command post-install report, run:

scripts/gm-doctor

gm-doctor checks self-update readiness, install dependencies, auth/keychain state, live memory and object-graph layer status, OpenAPI sync, MCP contract availability, deferred replay readiness, and the live write/query smoke path. Use scripts/gm-doctor --quick when you want the same report without consuming credits on the smoke query.

Packaged-skill install

Import or place graymatter.skill in the target OpenClaw skills directory
Confirm the extracted folder resolves to graymatter/
Run:

scripts/gm-activate

If those pass, the skill is installable and usable.

Fresh-install acceptance standard

GrayMatter counts as launch-ready only if a fresh user can:

install the repo or packaged skill
authenticate successfully
pass install validation
write and query a MemoryEntry
create a Retrieval Receipt for a memory query and inspect answerPolicy
inspect graph state
register the OpenClaw instance as an Agent in api-0
fetch and summarize the live OpenAPI
inspect at least one live entity family from the business schema

If those do not work, the skill is not truly ready.

Bootstrap integration for OpenClaw

OpenClaw workspace bootstrap guidance should treat GrayMatter as the default durable context layer:

uses GrayMatter as its primary durable memory
loads the live OpenAPI at startup
understands the organization schema as the operating environment
uses local file memory only as backup

That startup model keeps local files useful for recovery while making GrayMatter the normal source of reusable memory and live schema context.

Typical usage

Durable memory

scripts/gm-write decision "GrayMatter is primary memory for this instance"
scripts/gm-query "GrayMatter" 10
scripts/gm-read f7c29154-216f-4934-ac02-2d5e8b242180 --brief

Receipt-backed retrieval:

scripts/gm-retrieval-receipt create "GrayMatter launch status" 8 DEFAULT
scripts/gm-retrieval-receipt list --status LOW_CONFIDENCE --limit 20

Scoped memory

Use sourceChannel as the retrieval scope key for chat-, workspace-, and automation-specific memory. gm-write can derive that key from explicit scope fields or from a local path, then writes a compact [graymatter-scope] header into MemoryEntry.text so the hierarchy remains auditable even when tags are unavailable.

scripts/gm-write context "Research complete; publish blocked" \
  --scope-path "$HOME/.codex/automations/mcp-and-skill-hunter/memory.md"

scripts/gm-query "publish blocked" 5 context \
  --scope-path "$HOME/.codex/automations/mcp-and-skill-hunter/memory.md"

For that path, GrayMatter derives sourceChannel=codex:automation:mcp-and-skill-hunter. For Codex project folders under Documents/Codex/<date>/<slug>, it derives sourceChannel=codex:workspace:<date>/<slug>. Use --chat-key, --session-key, --workspace-key, or --automation-id when a host can provide stronger identifiers than a file path.

Tagged write with automatic fallback

scripts/gm-write context "launch handoff" discord "launch,graymatter"

If tag persistence is broken on the backend, the script retries without tags instead of failing the whole write.

If the API call still fails, gm-write appends the attempted write to memory/graymatter-fallback.json when scripts/gm-fallback-append is present.

One-shot activation

scripts/gm-activate

This is the preferred OpenClaw install/bootstrap entrypoint.

Agent self-registration

scripts/gm-register-agent

This should run when an OpenClaw server first connects to api-0 so the system has an explicit Agent record for that instance.

Graph state

scripts/gm-graph GET

Live schema sync

scripts/gm-openapi-sync
scripts/gm-openapi-summary
scripts/gm-status
scripts/gm-doctor --quick

Arbitrary schema entity access

# list visible organizations
scripts/gm-entity Organization

# fetch one customer
scripts/gm-entity Customer 123

# create a note if authorized
scripts/gm-entity Note POST '{"title":"Launch","content":"GrayMatter launch work"}'

Auth

GrayMatter uses:

VALKYR_API_BASE, default https://api-0.valkyrlabs.com/v1
macOS/iCloud Keychain lookup for VALKYR_AUTH
VALKYR_AUTH_TOKEN as an advanced debug override, not the normal activation path
VALKYR_JWT_SESSION as a compatible env fallback for downstream tooling

Preferred auth flow:

check Keychain for VALKYR_AUTH first
if present, reuse it automatically
otherwise prompt for username and password once
exchange for a VALKYR_AUTH token
store that token securely in Keychain for future runs

Do not hardcode secrets into the repo or skill. Do not print tokens. Do not make manual token handling the normal user workflow.

OpenClaw operating guidance

In a GrayMatter-native workspace, the agent should:

query GrayMatter for durable context first
inspect relevant live business entities second
fall back to local files only if GrayMatter is unavailable or incomplete
keep durable writes concise and reusable
treat the live schema as the organization's environment model

This is how the agent becomes the right operator for a business, not just a chatbot with a diary.

Local fallback behavior

If api-0 is unavailable or a write path is temporarily broken:

write the smallest safe local backup
keep it replayable
retry later when GrayMatter is healthy again

Typical fallback files:

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

Troubleshooting

`VALKYR_AUTH_TOKEN is required`

No env token is set and no matching macOS Keychain secret was found.

Fix:

run scripts/gm-login and complete username/password sign-in, or
export VALKYR_AUTH_TOKEN, or
ensure Keychain secret VALKYR_AUTH exists

`jq: command not found`

Install jq.

On macOS:

brew install jq

Tagged write fails

Some deployments still have a MemoryEntry.tags persistence mismatch.

Fix:

use scripts/gm-write
let it retry automatically without tags

Query fails with a credits or billing error

If writes and reads succeed but /MemoryEntry/query fails with a credit error, that is usually an account billing configuration issue rather than a GrayMatter auth failure.

Observed requirement:

query currently consumes credits
a fresh signup should auto-provision 500 credits so GrayMatter query works immediately
after starter credits are exhausted, the user must recharge credits to continue full GrayMatter functionality

Useful links:

signup and activation: https://valkyrlabs.com/graymatter/activate?source=graymatter&intent=signup&operation=memory_query
credits and recharge: https://valkyrlabs.com/graymatter/credits?source=graymatter&intent=recharge&operation=memory_query

CLI behavior on INSUFFICIENT_FUNDS:

prints both buy and signup links in stderr
attempts a popup prompt on macOS (osascript) and Windows (powershell.exe)
opens the buy-credits URL as a last-resort fallback when popup tooling is unavailable

Optional overrides for custom deployments:

VALKYR_BUY_CREDITS_URL
VALKYR_HUMAN_SIGNUP_URL

If a new account has 0.00 balance, activation may still succeed for write/read operations while query fails until credits are provisioned.

Some api-0 deployments return auth in headers or cookies rather than in the JSON response body.

Fix:

use the latest scripts/gm-login
it now treats VALKYR_AUTH as the primary auth contract
downstream API calls send the recovered token back as bearer auth, VALKYR_AUTH, and cookie auth

OpenAPI fetch fails

Check:

outbound network access
api-0 availability
whether the environment blocks the docs endpoint

If the live docs cannot be fetched, use the last cached copy temporarily, but treat it as stale.

Unsure what is broken

Run:

scripts/gm-doctor --verbose

The doctor command continues through all checks and reports the exact required failure or warning instead of stopping at the first broken dependency. That is the preferred first diagnostic before changing auth, credits, MCP config, or local plugin files.

Packaging

GrayMatter Light before/after

Before this distribution sprint, Light mode was useful but not strict enough as a drop-in api-0 substitute:

local docs and bundles used unprefixed paths such as /MemoryEntry and /SwarmOps/graph
the hand-written Light OpenAPI could drift from the real ValkyrAI api.hbs.yaml / api-0 shape
the packaged server expected a system Java runtime unless the operator provided one
there was no single command proving local write, query, health, and MCP readiness

After this sprint, Light mode is api-0-shaped:

VALKYR_API_BASE=http://localhost:<port>/v1
Light implements the MemoryEntry-first production path subset: /v1/MemoryEntry/write, /v1/MemoryEntry/query, /v1/MemoryEntry/read, /v1/MemoryEntry/{id}, /v1/memory/status, /v1/graymatter/stats, /v1/graymatter/activation/bridge, /v1/swarm-ops/graph, and /v1/api-docs
the Light OpenAPI is generated from the real authenticated api-0/ValkyrAI OpenAPI snapshot and carries the production component schemas
the packaged local server uses H2 under the user-local app directory and supports bundled-runtime archives
scripts/gm-light-smoke proves the local write/query/health loop and prints MCP-ready instructions

Rebuild the packaged skill with:

scripts/package-graymatter

Run an actual local ThorAPI-backed Light instance with:

scripts/gm-light-up
source .graymatter-light/.graymatter-light-env
scripts/gm-write context "GrayMatter Light is running" local-light
scripts/gm-query "GrayMatter Light"

gm-light-up generates the api.hbs.yaml template at .graymatter-light/api.hbs.yaml, rendered api.yaml at .graymatter-light/api.yaml, the Docker Compose file, and the Light control panel, then starts the ThorAPI image with THORAPI_TEMPLATE=/app/api.hbs.yaml and THORAPI_SPEC=/app/api.yaml. The default image is ghcr.io/valkyrlabs/thorapi:latest; use --image or THORAPI_IMAGE when running a private, pinned, or locally built ThorAPI image. The rendered spec explicitly includes the production-shaped MCP backing paths for memory_put, memory_get, memory_query, memory_health, graph access, and schema summary. The env file sets VALKYR_API_BASE=http://localhost:8080/v1 and GRAYMATTER_LIGHT_MODE=true, so the normal GrayMatter skill scripts and the standalone MCP server can connect to the running local instance without requiring hosted api-0 auth.

Run the full local loop smoke test with:

scripts/gm-light-smoke

Build the standalone downloadable local server with:

scripts/package-local-server

That creates dist/graymatter-local-server-latest.tar.gz. The archive contains:

application-bundle/ with the ValkyrAI app-factory template, ThorAPI FEBE OpenAPI contract, custom dashboard/workbench/promotion/swarm components, and built-in rbac-core / data-workbooks component references
source/ with the generated Spring Boot local server
bin/graymatter-local-server launcher
lib/graymatter-local-server.jar when Maven is available during packaging
runtime/ when jlink is available during packaging, so users do not manually install Java in the happy path

The embedded dashboard includes Valkyr Labs branding, hides the local login panel after successful login, exposes activation/recharge links for the valkyrlabs.com Cloud bridge, and reports local swarm-ops graph status through the production-shaped /v1 paths.

awesome-codex-plugins listing kit

GrayMatter ships a ready-to-submit listing packet for awesome-codex-plugins.

Listing markdown block: docs/awesome-codex-plugins.md
Source metadata: .codex-plugin/plugin.json

Quick copy flow:

cat docs/awesome-codex-plugins.md

Then open a PR against hashgraph-online/awesome-codex-plugins and paste the generated block into README.md using that repository's contribution format.

Launch position

The launch target is simple:

GrayMatter installs cleanly as an OpenClaw skill
OpenClaw boots into GrayMatter-first memory behavior
the agent loads the live OpenAPI schema at startup
the agent understands both durable memory and the broader organization object graph
file memory remains backup, not the center of gravity

That is the version of GrayMatter worth shipping.