GrayMatter

GrayMatter

Retrieval coverage and contribution evidence explains complete-list discovery, explicit reuse versus write verification, and receipt-to-decision-to-artifact-to-test reporting without invented savings.

GrayMatter Lite is a real open-source memory product for one person or one workspace. It runs locally or on infrastructure you control and includes the same useful product loop from the first launch: sign in, create durable memory, retrieve it through MCP, import or export portable KnowledgePacks, and connect local or hosted agent profiles.

It is not a time-limited trial and it is not a hollow demo. The Lite boundary is the canonical ThorAPI YAML under openapi/bundles, ./vaix builder, Spring/H2 backend, embedded dashboard, MCP server, starter KnowledgePack, Docker definition, tests, and public documentation in this repository.

Choose hosted or local memory

Start with the setup page. GrayMatter Cloud is the recommended default: use your valkyrlabs.com account and the native plugin sign-in to connect hosted memory. Tenant and account permissions are enforced by the hosted service.

Local GrayMatter Lite needs no valkyrlabs.com signup. In ValorIDE, click Connect Local GrayMatter Lite on the welcome screen (or use that command from the command palette), then select this source folder if asked. ValorIDE starts Lite and verifies the local account and MCP memory tools. Choose Ollama, LM Studio or your own model provider separately. The first source build may need toolchain and dependency downloads; installed local memory works offline.

For other clients, use the source commands below. Hosted workflows, ecommerce and application hosting use their authenticated ValkyrAI services.

Install local Lite in one command

On macOS or Linux:

git clone https://github.com/ValkyrLabs/GrayMatter.git

cd GrayMatter ./vaix setup

./vaix setup uses Java 17+, Maven, and Node 20+ already on the machine when possible. Missing toolchains are downloaded privately under .vaix/runtime; nothing is installed system-wide. The command builds standalone Lite using public Maven dependencies, creates one local profile, starts the services, and verifies the connection. A hosted account or private ThorAPI generator is not required. Explicit schema generation remains available through ./vaix generate. Setup starts:

• dashboard and sign-in: http://localhost:8787
• HTTP MCP: http://localhost:3333/mcp
• durable H2 data: .graymatter-lite/data

Retrieve the generated local credentials only when you need them:

./vaix credentials

./vaix doctor

Other source commands:

./vaix generate     # compose canonical YAML and generate Spring + TypeScript

./vaix generate --extension ./application-domain.yaml ./vaix regenerate # generate, clean-build, and run the acceptance suite ./vaix build # build the Spring/H2 backend ./vaix test # backend, bootstrap, docs, release parity, and MCP contracts ./vaix run # foreground backend ./vaix up # background backend + HTTP MCP ./vaix stop

See Schema regeneration for the authoritative files, generated/handwritten boundary, extension contract, and failure rules.

Docker

The Docker path builds from the committed source; it does not depend on a closed prebuilt GrayMatter backend image:

export GRAYMATTER_ADMIN_PASSWORD='choose-a-strong-local-password'

docker compose -f deploy/docker-compose.lite.yml up --build

The same dashboard is available on port 8787 and MCP on 3333. H2 data is kept in the graymatter-lite-data volume.

What is included

• one local user/workspace with Basic-auth sign-in and a switchable local profile;
• durable MemoryEntry creation, read, hybrid search, and H2 persistence;
• local vector indexing with optional loopback Ollama embeddings, plus bounded Bifrost context, citation pointers, source rechecks, and retrieval receipts;
• the existing Valkyr dashboard, memory workbench, telemetry, and SWARM status;
• the bundled stdio/HTTP MCP server for Codex, OpenClaw, Claude, local-model hosts, and other MCP-compatible clients;
• signed .gmkp KnowledgePack import plus whole-memory KnowledgePack export;
• a vetted starter KnowledgePack with GrayMatter, Valkyr SWARM, ValkyrAI, and ThorAPI setup/product/support knowledge, inserted idempotently into local H2;
• local and hosted named profiles plus explicit read-only blended retrieval;
• source builds through ./vaix and container builds through Docker Compose;
• AGPL-3.0 source, public docs, Issues/Discussions support, and a private security-reporting path.

The legacy environment and filesystem identifiers retain LIGHT for backward compatibility. The public product name is GrayMatter Lite.

Profiles and blended memory

./vaix setup registers graymatter-lite-local without changing an already active hosted identity. Profiles store routing metadata in profiles.json; hosted sessions remain in the platform credential vault and local Basic-auth passwords live in a mode-0600 secret file outside the repository.

scripts/gm-profile add-local graymatter-lite-local \

--api-base http://localhost:8787/v1 --password-stdin scripts/gm-profile add cloud --from-current scripts/gm-profile use graymatter-lite-local scripts/gm-profile blend graymatter-lite-local cloud scripts/gm-query "release rules"

Blended reads execute independently under each profile and preserve profile and account-fingerprint provenance. Every write fails closed until a single profile is selected. MCP exposes the same read-only federation for memory query/read/health tools; mutating or unsupported tools return a read-only recovery result until one profile is selected. Restart the MCP process after changing the persistent profile selection.

Local models

GrayMatter is model-neutral. Ollama, LM Studio, llama.cpp, and other local-model hosts connect through MCP while the model process remains separate from the H2 memory and authorization boundary. See Local models for stdio and HTTP examples. Local Workflow execution uses two MCP boundaries: Valkyr SWARM owns registration and signed Workflow coordination; GrayMatter owns memory, context, and durable evidence. Model-only LM Studio/Ollama nodes are signed-workflow-only inference workers, never general command runners.

Imports, exports, and starter knowledge

Use the dashboard or API:

curl -u "admin:$GRAYMATTER_ADMIN_PASSWORD" \

-o graymatter-lite-memory.gmkp \ http://localhost:8787/v1/knowledge-packs/export

scripts/gm-knowledge-pack-import ./graymatter-lite-memory.gmkp

The starter pack source is committed at templates/graymatter-light-bootstrap/local-server/src/main/resources/knowledgepacks/graymatter-lite-starter.json. Startup signs it with the same self-contained integrity contract used by normal KnowledgePacks, imports it through the production importer, and stores its records in the local H2 database. Repeated starts are idempotent.

Valkyr SWARM

The starter KnowledgePack explains the supported SWARM path. Install the peer open-source product when this machine should register, heartbeat, receive exact-target control commands from an authenticated ValkyrAI mothership, and return durable receipts:

git clone https://github.com/ValkyrLabs/ValkyrSWARM.git

codex plugin marketplace add "$PWD/ValkyrSWARM" codex plugin add valkyr-swarm@valkyr-swarm

SWARM preserves the canonical human approval gates for outbound sends, production deploys, merges, and supervised service restarts. GrayMatter Lite does not invent a second command bus or allow an agent to approve itself.

Documentation and community

• GrayMatter Lite guide
• Local model compatibility
• KnowledgePacks
• MCP server
• Architecture
• Contributing
• Community support
• Security policy

Use GitHub Issues for reproducible defects and GitHub Discussions for support, ideas, KnowledgePacks, and integrations. Report vulnerabilities privately as described in SECURITY.md.

---

GrayMatter Platform: the AI brain for your entire business

Valkyr GrayMatter™ turns your applications, documents, workflows, conversations, and institutional knowledge into a living, searchable intelligence layer.

It is more than a vector database and more than chat memory. GrayMatter combines durable memory, real-time search, structured business data, and relationship-aware reasoning into one secure system that agents, people, apps, and APIs can use together.

A memory system that actually remembers context

GrayMatter stores durable decisions, preferences, tasks, research, procedures, conversations, and operational knowledge as structured, attributable records—not disposable chat history. Every memory can carry source, scope, tags, relationships, timestamps, ownership, and provenance, so the system can distinguish a personal preference from a company policy, a current task from historical context, or a source document from an AI-generated summary.

It supports agentic memory across Codex, OpenClaw, SageChat, workflows, and connected tools, giving every authorized agent a shared understanding of the business without flattening everything into an untraceable prompt.

Hybrid search: keyword, vector, graph, and structured data

GrayMatter search is designed to answer both simple and difficult questions:

• Exact search for names, IDs, tags, commands, products, and records
• Full-text search across documents, titles, fields, and parsed uploads
• Semantic/vector search for concepts, intent, and meaning
• Relationship-aware search across ThorAPI entities and knowledge-graph links
• Structured filtering by type, date, category, tags, tenant, workflow, project, and more
• Retrieval receipts with citations, evidence, quality signals, and answer-policy guidance

That means a user can search the public website, an authenticated workspace, or SageChat through the same intelligence foundation—while each surface receives only the information it is permitted to see.

PostgreSQL-native vector intelligence

GrayMatter uses PostgreSQL as the durable operational foundation and pgvector as a high-performance semantic-search accelerator.

SemanticIndexEntry remains the portable canonical record, while tenant-scoped pgvector projections provide fast nearest-neighbor retrieval. The platform supports configurable embedding providers, including production OpenAI embeddings and deterministic local fallback embeddings for offline/development environments. It also tracks model, provider, dimensions, index health, stale rows, reindex guidance, and degradation state.

This gives teams a practical path from ordinary relational data to production-grade semantic recall without adopting a separate proprietary graph or vector silo.

A real knowledge graph, built from ThorAPI

GrayMatter understands that knowledge is not a pile of documents—it is a network.

ThorAPI entities and their OpenAPI-defined relationships can be indexed after successful writes, producing safe semantic evidence across workflows, applications, customers, tasks, files, procedures, agents, goals, notes, and more. GraphLink records make important relationships explicit: supports, blocks, references, derives from, relates to, and beyond.

This enables relationship-aware retrieval such as:

• “What is related to this customer issue?”
• “Which workflow depends on this integration?”
• “What evidence supports this decision?”
• “Which documents, memories, and tasks explain this result?”

The system is designed for bounded graph traversal, citations, and future graph analytics without allowing the index or graph to