GrayMatter is an installable and immediately usable OpenClaw skill for:
- primary durable memory
- shared object-graph state
- live organizational schema awareness through the ValkyrAI
api-0OpenAPI
GrayMatter lets an OpenClaw instance move beyond file memory and isolated chat context. When properly authenticated, the agent can persist durable memory, inspect the live business schema, and operate inside the organization's RBAC-scoped data environment.
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 supportsnode mcp-server/index.js --stdiofor plugin-managed MCP launch. - Codex plugin:
.codex-plugin/plugin.jsonexposes this repo as thegraymatterplugin with the standalone skill plus.mcp.json, so Codex can discover both the instructions and the MCP server. - Standalone OpenClaw skill:
graymatter.skillpackagesSKILL.mdand the required scripts for OpenClaw install, activation, hosted api-0 use, and GrayMatter Light local mode.
GrayMatter is the memory and context layer for business-native agent systems.
It is designed so an OpenClaw instance can:
- read and write
GrayMatterandMemoryEntryrecords - coordinate through graph state using
SwarmOps - understand the entire available schema exposed by the tenant/account
- 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.
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 primary durable memory system.
Use local files only as:
- bootstrap context on first startup
- fallback when
api-0is unavailable - temporary replayable backup when a write path is blocked
Primary targets:
/MemoryEntry/MemoryEntry/query/MemoryEntry/read/MemoryEntry/write/GrayMatter/SwarmOps/graph
Typical MemoryEntry.type values:
decisiontodocontextartifactpreference
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.
Most businesses are not just “memory plus chat.” They have structured operational data.
Examples observed in the current live schema include:
OrganizationCustomerOpportunityInvoiceProductApplicationWorkbookWorkflowTaskNoteMediaObjectFileRecordSalesActivitySalesPipelineGoalStrategicPriorityKeyMetricAgentSpaceGrayMatterMemoryEntrySwarmOps
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.
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
SKILL.md— OpenClaw AgentSkill instructionsgraymatter.skill— packaged distributable AgentSkillscripts/graymatter_api.sh— authenticated production API transportscripts/gm-login— login helperscripts/gm-activate— one-shot auth + install + agent registration + schema sync bootstrapscripts/gm-install-check— dependency and auth readiness checkscripts/gm-smoke— production smoke test for write/query validationscripts/gm-query— queryMemoryEntryscripts/gm-write— writeMemoryEntry, with tagged-write fallback behaviorscripts/gm-fallback-append— append failed writes to local replay queue atmemory/graymatter-fallback.jsonscripts/gm-graph— inspect Swarm graph endpointsscripts/gm-openapi-sync— fetch and cache the live OpenAPI spec locallyscripts/gm-openapi-summary— summarize live schema domains and endpointsscripts/gm-status— quick health/status surface for auth source, fallback queue, and OpenAPI cachescripts/gm-client— generic REST wrapper for GET/POST/PUT/PATCH/DELETE against GrayMatter API pathsscripts/gm-entity— generic helper for listing, reading, and writing arbitrary schema entitiesscripts/gm-register-agent— register or refresh the OpenClaw server as an Agent in api-0scripts/gm-mcp-contract— emit the portable MCP memory-tool contract schema used by agent/IDE adaptersscripts/gm-light-bootstrap— generate the local GrayMatter app bundle and server source scaffoldscripts/gm-light-up— generate and start the local ThorAPI-backed GrayMatter Light instancescripts/gm-light-env— print the environment exports that point skill scripts at the running Light instancescripts/gm-light-json-smoke— JSON-file fallback smoke test for Light payload shape without ThorAPIscripts/package-local-server— package the standalone downloadable GrayMatter Local Server archivescripts/package_graymatter.py— deterministic validation and packagingmcp-server/— standalone HTTP/SSE and Apps SDK/mcpserver for GrayMatter memory, graph, entity, schema, and overview toolsdocs/architecture.md— architecture and operating modeldocs/openai-app-directory-submission.md— Apps SDK submission checklist and copydocs/privacy-policy.md— GrayMatter-specific public privacy policy sourcedocs/reviewer-test-credentials.md— review demo-account setup and secure credential handoff runbookdocs/prd-context-compaction-reset.md— PRD for bounded chat compaction and reset flowsdocs/thorapi-integration.md— ThorAPI relationship and bundle directiondocs/graymatter-light.md— local/offline notesopenai-app/submission-manifest.json— non-secret app metadata for OpenAI dashboard submissionexamples/*— example payloads and Light-mode starter assetsreferences/*— release and multi-agent guidance, including concurrency conventionsreferences/mcp/memory-tool-contract.v1.json— stable v1 portable tool contract for memory and graph operationsclawhub.json— publishing metadata
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
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-0username - 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.
git clone https://github.com/ValkyrLabs/GrayMatter.git
cd GrayMatter
brew install jq
scripts/gm-activatescripts/gm-activate is the intended one-shot bootstrap for OpenClaw installs. It can use:
- interactive username/password prompts, or
- credentials already present in environment variables
Supported env inputs:
GRAYMATTER_USERNAMEorVALKYR_USERNAMEGRAYMATTER_PASSWORDorVALKYR_PASSWORD- optional
VALKYR_AUTH_TOKEN - optional
VALKYR_KEYCHAIN_SERVICEif 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.
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.
- Import or place
graymatter.skillin the target OpenClaw skills directory - Confirm the extracted folder resolves to
graymatter/ - Run:
scripts/gm-activateIf those pass, the skill is installable and usable.
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 - 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.
The workspace BOOTSTRAP.md should be rewritten so OpenClaw:
- 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 is now part of the GrayMatter launch plan.
scripts/gm-write decision "GrayMatter is primary memory for this instance"
scripts/gm-query "GrayMatter" 10Use 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.
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.
scripts/gm-activateThis is the preferred OpenClaw install/bootstrap entrypoint.
scripts/gm-register-agentThis should run when an OpenClaw server first connects to api-0 so the system has an explicit Agent record for that instance.
scripts/gm-graph GETscripts/gm-openapi-sync
scripts/gm-openapi-summary
scripts/gm-status# 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"}'GrayMatter uses:
VALKYR_API_BASE, defaulthttps://api-0.valkyrlabs.com/v1- macOS/iCloud Keychain lookup for
VALKYR_AUTH VALKYR_AUTH_TOKENas the primary env override/debug pathVALKYR_JWT_SESSIONas a compatible env fallback for downstream tooling
Preferred auth flow:
- check Keychain for
VALKYR_AUTHfirst - if present, reuse it automatically
- otherwise prompt for username and password once
- exchange for a
VALKYR_AUTHtoken - 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.
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.
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.mdMEMORY.mdmemory/graymatter-fallback.json
No env token is set and no matching macOS Keychain secret was found.
Fix:
- run
scripts/gm-loginand complete username/password sign-in, or - export
VALKYR_AUTH_TOKEN, or - ensure Keychain secret
VALKYR_AUTHexists
Install jq.
On macOS:
brew install jqSome deployments still have a MemoryEntry.tags persistence mismatch.
Fix:
- use
scripts/gm-write - let it retry automatically without tags
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: 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
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_URLVALKYR_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_AUTHas the primary auth contract - downstream API calls send the recovered token back as bearer auth,
VALKYR_AUTH, and cookie auth
Check:
- outbound network access
api-0availability- 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.
Rebuild the packaged skill with:
python3 scripts/package_graymatter.pyRun 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 MCP backing paths for memory_write, memory_read, memory_query, graph_get, entity tools, and schema_summary. The env file sets VALKYR_API_BASE=http://localhost:8080 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.
Build the standalone downloadable local server with:
scripts/package-local-serverThat 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-inrbac-core/data-workbookscomponent referencessource/with the generated Spring Boot local serverbin/graymatter-local-serverlauncherlib/graymatter-local-server.jarwhen Maven is available during packaging
The embedded dashboard includes Valkyr Labs branding, hides the local login panel after successful login, exposes Promote / Synchronize for the valkyrlabs.com mothership bridge, and reports the local graymatter-swarm-v0.1 light-node status.
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.mdThen open a PR against hashgraph-online/awesome-codex-plugins and paste the generated block into README.md using that repository's contribution format.
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.