GrayMatter

GrayMatter

检索覆盖范围与贡献证据 说明如何发现完整列表、明确区分复用与写入验证，以及如何报告从回执到决策、再到产物和测试的完整链路，而不虚构节省情况。

GrayMatter Lite 是一款真正的开源记忆产品，面向个人或单个工作区。它可在本地运行，也可部署在你掌控的基础设施上，并从首次启动起就提供完整实用的产品闭环：登录、创建持久记忆、通过 MCP 检索、导入或导出可移植的 KnowledgePacks，以及连接本地或托管的 Agent 配置。

它不是限时试用版，也不是空壳演示版。Lite 的边界由本仓库中的规范 ThorAPI YAML（位于 openapi/bundles）、./vaix 构建器、Spring/H2 后端、嵌入式仪表板、MCP 服务、入门 KnowledgePack、Docker 定义、测试和公开文档共同构成。

选择托管或本地记忆

从设置页面开始。 GrayMatter Cloud 是推荐的默认选项：使用你的 valkyrlabs.com 账户和原生插件登录来连接托管记忆。租户和账户权限由托管服务强制执行。

本地 GrayMatter Lite 无需注册 valkyrlabs.com 账户。在 ValorIDE 中，点击欢迎屏幕上的 Connect Local GrayMatter Lite（或从命令面板执行该命令），然后在出现提示时选择此源文件夹。ValorIDE 会启动 Lite，并验证本地账户和 MCP 记忆工具。请另行选择 Ollama、LM Studio 或你自己的模型提供商。首次构建源代码时可能需要下载工具链和依赖项；安装后的本地记忆可离线使用。

对于其他客户端，请使用下方的源代码命令。托管工作流、电商和应用托管使用经过身份验证的 ValkyrAI 服务。

一条命令安装本地 Lite

在 macOS 或 Linux 上：

git clone https://github.com/ValkyrLabs/GrayMatter.git
cd GrayMatter
./vaix setup

./vaix setup 会尽可能使用机器上已有的 Java 17+、Maven 和 Node 20+。缺少的工具链会下载到 .vaix/runtime 下的私有目录；不会在系统范围内安装任何内容。此命令使用公开 Maven 依赖项构建独立的 Lite，创建一个本地配置、启动服务并验证连接。无需托管账户或私有 ThorAPI 生成器。仍可通过 ./vaix generate 显式生成架构。 Setup 会启动：

• 仪表板和登录页面：http://localhost:8787
• HTTP MCP：http://localhost:3333/mcp
• 持久化 H2 数据：.graymatter-lite/data

仅在需要时获取生成的本地凭据：

./vaix credentials
./vaix doctor

其他源代码命令：

./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

请参阅架构重新生成，了解权威文件、生成代码与手写代码的边界、扩展约定和故障处理规则。

Docker

Docker 路径从已提交的源代码构建；它不依赖闭源的预构建 GrayMatter 后端镜像：

export GRAYMATTER_ADMIN_PASSWORD='choose-a-strong-local-password'
docker compose -f deploy/docker-compose.lite.yml up --build

同一仪表板可通过端口 8787 访问，MCP 可通过端口 3333 访问。H2 数据保存在 graymatter-lite-data 卷中。

包含内容

• 一个本地用户／工作区，支持 Basic 身份验证登录和可切换的本地配置文件；
• 持久化 MemoryEntry 的创建、读取、混合搜索和 H2 持久化；
• 本地向量索引，可选择使用 loopback Ollama 嵌入，并提供有界 Bifrost 上下文、引用指针、来源复查和检索回执；
• 现有 Valkyr 仪表板、记忆工作台、遥测和 SWARM 状态；
• 随附的 stdio/HTTP MCP 服务，供 Codex、OpenClaw、Claude、本地模型主机及其他兼容 MCP 的客户端使用；
• 已签名的 .gmkp KnowledgePack 导入，以及完整记忆的 KnowledgePack 导出；
• 经审核的入门 KnowledgePack，包含 GrayMatter、Valkyr SWARM、ValkyrAI 和 ThorAPI 的设置／产品／支持知识，并以幂等方式插入本地 H2；
• 本地和托管的命名配置文件，以及显式只读的混合检索；
• 通过 ./vaix 进行源码构建，以及通过 Docker Compose 进行容器构建；
• AGPL-3.0 源码、公开文档、Issues/Discussions 支持渠道，以及私密安全问题报告途径。

为保持向后兼容，旧版环境和文件系统标识符仍保留 LIGHT。公开产品名称为 GrayMatter Lite。

配置文件与混合记忆

./vaix setup 会注册 graymatter-lite-local，而不会更改已激活的托管身份。配置文件在 profiles.json 中存储路由元数据；托管会话仍保存在平台凭据库中，本地 Basic 身份验证密码则存储在仓库外、权限模式为 0600 的机密文件中。

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"

混合读取会在各配置文件下独立执行，并保留配置文件和账户指纹来源信息。选定单个配置文件之前，所有写入操作都会安全失败。MCP 为记忆查询／读取／健康状态工具提供相同的只读联合检索；在选定单个配置文件之前，会修改数据的工具或不受支持的工具会返回只读恢复结果。更改持久化配置文件选择后，请重启 MCP 进程。

本地模型

GrayMatter 与模型无关。Ollama、LM Studio、llama.cpp 和其他本地模型主机可通过 MCP 连接，同时模型进程与 H2 记忆及授权边界保持分离。stdio 和 HTTP 示例请参阅本地模型。本地工作流执行使用两个 MCP 边界：Valkyr SWARM 负责注册和已签名的工作流协调；GrayMatter 负责记忆、上下文和持久化证据。仅运行模型的 LM Studio/Ollama 节点是 signed-workflow-only 推理工作节点，绝不会充当通用命令运行器。

导入、导出和入门知识

使用仪表板或 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

入门包源文件已提交至 templates/graymatter-light-bootstrap/local-server/src/main/resources/knowledgepacks/graymatter-lite-starter.json。 启动时，系统会使用与常规 KnowledgePack 相同的自包含完整性契约为其签名，通过生产导入器导入，并将其记录存储在本地 H2 数据库中。重复启动不会产生重复内容。

Valkyr SWARM

入门 KnowledgePack 介绍了受支持的 SWARM 流程。当此机器需要注册、发送心跳、接收经过身份验证的 ValkyrAI 主控端发出的精确目标控制命令，并返回持久化回执时，请安装这个配套开源产品：

git clone https://github.com/ValkyrLabs/ValkyrSWARM.git
codex plugin marketplace add "$PWD/ValkyrSWARM"
codex plugin add valkyr-swarm@valkyr-swarm

SWARM 保留了出站发送、生产部署、合并和受监督服务重启的标准人工审批关卡。GrayMatter Lite 不会另行创建命令总线，也不允许 Agent 自行批准。

文档与社区

• GrayMatter Lite 指南
• 本地模型兼容性
• KnowledgePacks
• MCP 服务
• 架构
• 贡献指南
• 社区支持
• 安全策略

对于可复现的缺陷，请使用 GitHub Issues；对于支持、想法、KnowledgePacks 和集成，请使用 GitHub Discussions。请按照 SECURITY.md 中的说明私下报告漏洞。

---

GrayMatter Platform：为整个企业打造的 AI 大脑

Valkyr GrayMatter™ 将您的应用、文档、工作流、对话和机构知识转化为一个动态、可搜索的智能层。

它不只是一个向量数据库，也不只是聊天记忆。GrayMatter 将持久记忆、实时搜索、结构化业务数据和关系感知推理整合到一个安全系统中，供 Agent、人、应用和 API 协同使用。

真正能够记住上下文的记忆系统

GrayMatter 将持久的决策、偏好、任务、研究、流程、对话和运营知识存储为结构化且可溯源的记录，而非一次性的聊天历史。每条记忆都可以包含来源、范围、标签、关系、时间戳、所有权和溯源信息，因此系统能够区分个人偏好与公司政策、当前任务与历史上下文，以及源文档与 AI 生成的摘要。

它支持 Codex、OpenClaw、SageChat、工作流和已连接工具之间的 Agent 式记忆，让每个获授权的 Agent 都能共享对业务的理解，而不会将一切压扁成无法追溯的提示词。

混合搜索：关键词、向量、图谱和结构化数据

GrayMatter 搜索旨在解答简单和复杂的问题：

• 精确搜索名称、ID、标签、命令、产品和记录
• 在文档、标题、字段和解析后的上传文件中进行全文搜索
• 通过语义／向量搜索查找概念、意图和含义
• 跨 ThorAPI 实体和知识图谱链接进行关系感知搜索
• 按类型、日期、类别、标签、租户、工作流、项目等进行结构化筛选
• 提供包含引用、证据、质量信号和答案策略指引的检索凭据

这意味着用户可以通过同一智能基础搜索公开网站、已认证的工作区或 SageChat，同时每个界面只能获取其获准查看的信息。

基于 PostgreSQL 的原生向量智能

GrayMatter 使用 PostgreSQL 作为持久化运营基础，并使用 pgvector 作为高性能语义搜索加速器。

SemanticIndexEntry 仍是可移植的规范记录，而按租户划分的 pgvector 投影则支持快速的近邻检索。平台支持可配置的嵌入服务提供商，包括生产环境使用的 OpenAI 嵌入，以及适用于离线／开发环境的确定性本地回退嵌入。平台还会跟踪模型、提供商、维度、索引健康状况、过期行、重新索引指引和降级状态。

这让团队能够切实地从普通关系型数据迈向生产级语义召回，而无需采用单独的专有图谱或向量孤岛。

基于 ThorAPI 构建的真实知识图谱

GrayMatter 深知，知识不是一堆文档，而是一个网络。

成功写入后，ThorAPI 实体及其由 OpenAPI 定义的关系可以编入索引，从而在工作流、应用、客户、任务、文件、流程、Agent、目标、笔记等方面生成安全的语义证据。GraphLink 记录会明确呈现重要关系：支持、阻止、引用、派生自、关联，以及更多关系。

这使得感知关系的检索成为可能，例如：

• “与这个客户问题相关的内容有哪些？”
• “哪个工作流依赖此集成？”
• “有哪些证据支持这一决策？”
• “哪些文档、记忆和任务能够解释这一结果？”

系统旨在支持有界图遍历、引用和未来的图分析，同时确保索引或图不会绕过 ThorAPI 授权。

SageChat 与文档智能

SageChat 可以将上传的文件和解析后的文档转化为可搜索的证据，而不是让它们闲置在存储中。

文件会被处理为有界且来源信息丰富的语义材料：源文件、解析器输出、分块、页面或偏移量、源哈希、提取质量，以及与其所支持业务对象的关系。随后，GrayMatter 可以在 SageChat 中通过引用和可解释性呈现这些证据，帮助用户不仅了解答案，还能了解答案的来源。

插件、技能与 MCP：让智能无处不在

GrayMatter 以可安装的插件和技能系统形式提供，适用于 Codex/OpenClaw 风格的 Agent。它支持由平台保险库提供支持的安全身份验证、Agent 注册、架构感知、持久记忆的读取与写入、图访问、检索回执和运行状况检查。

其 MCP 功能可通过记忆写入、记忆查询、记忆读取、带回执的检索、图检查、架构发现和授权实体访问等类型化工具，让兼容的 AI 客户端使用 GrayMatter。

插件和技能让每个 Agent 都能获得相同的持久组织上下文；MCP 则让外部 AI 环境和工作流能够使用这些上下文。

专为真实 AI 运营设计的额度

GrayMatter 提供额度和权益模型，用于更高级的记忆和 AI 操作。这支持语义检索、嵌入、重新编入索引和高级智能功能的可持续使用，同时保留清晰的运营控制。

该平台区分公开安全的体验与私有运营工具，避免商业或账户管理详情泄露到公开 AI 界面中。

安全始于设计

GrayMatter 不会将搜索当作绕过安全措施的捷径。

生成的 ThorAPI RBAC 和 ACL 仍是每条结果、片段、计数、分面、图路径、文件引用和推荐内容的事实来源。租户上下文在服务端解析。敏感字段、凭据、二进制数据和受保护的审计信息不会被编入索引。搜索、向量检索、图导航和 Agent 工具均采用封闭式故障设计，以应对授权状态不确定的情况。

最终成果

GrayMatter 正在成为智能层，让每款 Valkyr 产品、工作流、应用、Agent 和文档都能参与共享、安全且可搜索的大脑：

• 面向 Agent 和团队的记忆系统
• 面向业务的知识图谱
• 面向网站和工作区的混合搜索引擎
• 基于 PostgreSQL 的向量智能层
• 为 SageChat 提供带引用来源的研究与推理引擎
• 可移植、原生支持 ThorAPI 的平台，用于插件、技能、MCP 工具和 AI 自动化

GrayMatter 是一项可安装的 OpenClaw 技能和 MCP 服务，提供：

• 主要持久记忆
• 共享对象图状态
• 通过 ValkyrAI api-0 OpenAPI 实现的实时组织架构感知

它让 Agent 超越本地文件和孤立的聊天上下文。完成身份验证后，GrayMatter 将成为 Agent 独占的主要持久记忆：它会持久保存记忆、检查实时业务架构，并在组织的 RBAC 范围内数据环境中运行。

ChatGPT 开发者模式应用

提交入口是 mcp-server/ 中现有的 Node MCP 适配器，以加固的公共应用模式运行。它将 api-0 保持为记忆、ContextPage、流程、回执、RBAC、ACL 和租户的事实来源。

公共部署契约：

• 生产环境 MCP URL：https://api-0.valkyrlabs.com/graymatter/mcp
• 兼容 URL：https://api-0.valkyrlabs.com/mcp
• 受保护资源元数据：https://api-0.valkyrlabs.com/.well-known/oauth-protected-resource
• 授权服务器元数据目标：https://api-0.valkyrlabs.com/.well-known/oauth-authorization-server
• 开发环境 MCP URL：http://localhost:3333/graymatter/mcp

上述生产环境 MCP 和 OAuth URL 是部署目标，并不表示反向代理和 OAuth 授权服务器已投入运行。创建或提交 ChatGPT 应用前，请先验证这些 URL。

公共应用所需环境：

export PORT=3333
export GRAYMATTER_MCP_MODE=hosted-multi-tenant
export GRAYMATTER_PUBLIC_APP=true
export GRAYMATTER_PUBLIC_RESOURCE=https://api-0.valkyrlabs.com
export GRAYMATTER_PUBLIC_MCP_PATH=/graymatter/mcp
export GRAYMATTER_OAUTH_ISSUER=https://api-0.valkyrlabs.com
export GRAYMATTER_OAUTH_JWKS_URI=https://api-0.valkyrlabs.com/oauth2/jwks
export GRAYMATTER_ALLOWED_ORIGINS=https://chatgpt.com,https://platform.openai.com
export VALKYR_API_BASE=https://api-0.valkyrlabs.com/v1
node mcp-server/index.js

请勿在公共多租户服务上配置 VALKYR_AUTH_TOKEN、VALKYR_JWT_SESSION、GRAYMATTER_TENANT_ID 或 X-Valkyr-Token。每个请求都必须携带当前用户的 OAuth Bearer 令牌。公共模式会验证签发者、受众、有效期、RS256 签名、必要的身份声明和工具作用域；随后仅将 Bearer 令牌转发给 api-0，不会转发调用方的租户或所有者标识符。OAuth 元数据、JWKS 获取和请求正文读取都受请求共享执行时限约束，并会在时限到期时停止。HTTP 请求正文和本地 stdio 消息在 JSON 解析前，若超过 GRAYMATTER_MCP_MAX_REQUEST_BYTES（默认为 1 MiB，上限为 16 MiB），就会失败；健康检查和受限错误会返回不含内容的 executionLimits。

在 ChatGPT 中连接开发者版本：

1. 通过 HTTPS 部署端点，或使用 Secure MCP Tunnel 等 HTTPS 隧道公开本地服务器。
2. 在 ChatGPT 中打开“设置”→“安全和登录”，并启用“开发者模式”。
3. 打开“设置”→“插件”，然后选择加号按钮。
4. 输入 GrayMatter、描述 Persistent, secure memory and shared context for AI agents.，以及 HTTPS /graymatter/mcp URL。
5. 完成 OAuth 关联，并确认发现的工具恰好有八个。
6. 开始新聊天，从消息编辑器中添加 GrayMatter，并运行 SUBMISSION_CHECKLIST.md 中的代表性提示词。
7. 工具元数据发生变化后，重新部署并在开发者模式应用中使用“刷新”。

使用两个隔离的审核者账户运行自动化公共应用契约：

GRAYMATTER_MCP_URL=https://api-0.valkyrlabs.com/graymatter/mcp \
GRAYMATTER_TENANT_A_TOKEN='redacted' \
GRAYMATTER_TENANT_B_TOKEN='redacted' \
GRAYMATTER_TEST_RECEIPT_ID='authorized-receipt-id' \
scripts/smoke-test-public-mcp.sh

发布形式

GrayMatter 提供三种相关但可独立使用的形式：

• MCP 服务：mcp-server/ 作为 HTTP/SSE 服务运行，适用于 Claude.ai、Claude Code、Cursor、ChatGPT Apps SDK 和任何兼容 MCP 的宿主，也支持 node mcp-server/index.js --stdio，以便由插件管理 MCP 启动。
• Codex 插件：.codex-plugin/plugin.json 将此仓库作为 graymatter 插件公开，其中包含独立技能和 .mcp.json，让 Codex 能发现说明和 MCP 服务。
• 独立 OpenClaw 技能：graymatter.skill 打包了 SKILL.md 和所需脚本，用于安装 OpenClaw、激活、使用托管的 api-0，以及使用 GrayMatter Light 本地模式。

如果 GitHub 稀疏检出或根目录安装只下载了根目录文件，请在 macOS/Linux 上运行 ./graymatter-bootstrap，或在 Windows 上运行 .\\graymatter-bootstrap.ps1。两者都会从随附的 graymatter.skill 归档中恢复 scripts/ 和 mcp-server/。

快速开始

macOS/Linux：

git clone https://github.com/ValkyrLabs/GrayMatter.git
cd GrayMatter
./install.sh

Windows PowerShell：

git clone https://github.com/ValkyrLabs/GrayMatter.git
Set-Location GrayMatter
.\\install.ps1

如果 Codex CLI 可用，安装程序会自动将此检出目录连接到 Codex、安装插件，并打开一个原生 GrayMatter 登录窗口。macOS 使用单个 AppKit 对话框；Windows 使用一个由 Windows Credential Manager 支持的 WinForms 对话框。首屏提供 GrayMatter Cloud (api-0)、Local GrayMatter Lite (localhost:8787)、Local ValkyrAI (localhost:8080) 和 Other self-hosted server 选项，并提供可编辑的服务 URL 和密码遮罩字段。登录被拒后，会返回相同流程，保留用户名并显示清晰的更正提示。ValkyrAI/Cloud 密码只会发送到所选登录端点，不会被打印或保存；返回的会话会存储在平台凭据库中。本地 HTTP 仅允许用于环回地址；远程实例必须使用 HTTPS。GrayMatter Lite 使用现有的本地账户身份验证，并将本地凭据保存在权限为 mode-0600 的私有配置文件中。

回访用户可立即登录。新用户选择 Create Free Account，在浏览器中完成专用的 GrayMatter Cloud 注册页面，然后返回仍打开的连接窗口，使用创建的用户名登录。Recover Account 会打开专用的用户名/密码恢复页面。对于本地或自托管实例，请先选择连接，再输入凭据。GrayMatter Lite 账户通过 ./vaix setup 创建；ValkyrAI 账户由该实例的注册流程或管理员提供。Open Instance 会打开所选服务，而不是 Cloud 注册页面。Cloud 账户并非必需。所选服务会保存为账户配置文件，以便下次启动插件时使用；其凭据与托管账户的凭据相互独立。正常登录流程不会使用浏览器重定向、剪贴板令牌或手动处理 JWT：原生窗口会将凭据发送到所选 ValkyrAI 服务，并从响应正文、标头或安全 Cookie 中获取会话。

登录身份示例：

Username: your-username

顺利完成的流程刻意只包含四个可见阶段：downloading plugin、performing signup/login、authenticating 和 GrayMatter plugin ready。流程不需要 jq 或手动处理 JWT。高级 OpenClaw 操作者之后可以运行 scripts/gm-activate，执行完整的冒烟测试、Agent 注册和架构同步引导流程。

scripts/gm-activate 是推荐的首次运行方式。它会检查更新、登录、在可用时将会话存储到 Keychain、验证安装、注册 Agent，并在获取不变量、经过身份验证的能力发现以及实时 OpenAPI 新鲜度检查后，写入一份有界的启动预检产物。

在规划任务、编辑代码、执行影响生产环境的操作，或根据项目历史作答之前，Agent 必须立即针对当前工作区/产品运行不变量预检：

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

无法执行 Shell 命令的 MCP 宿主应调用 graymatter_invariant_preflight。返回的、标记为 invariants、security、RBAC/ACL、generated-code、AspectJ、vaix/vai、testing 或 product names 的 decision 记录均为具有约束力的操作规则。检索缺失或降级，绝不意味着可以忽略已知的持久规则。

所需的预检范围比关键词搜索更广。Agent 开始工作前，必须查找 invariants、rules、instructions、prior session context、personalization、business truth、personal truth 和 organizational truth。会话期间，必须将用户提供的新更正、流程、偏好和 invariants 写入 GrayMatter，并按 ID 读回以确认已持久化。

对于 ValkyrAI、ValorIDE、GrayMatter Light 和 ThorAPI 生成的应用相关工作，Agent 应优先使用仓库启动器，而不是直接使用构建捷径：./vaix build、./vaix test、./vaix run 以及仓库文档记录的 ./vai 流程，能够保留 ThorAPI 代码生成、AspectJ 编织、堆内存默认值、本地 H2/运行时标志和面向终端用户的操作行为。Signup、ACL/RBAC 和生成 API 的修复，通常应先通过 localhost:8080 上的 ./vaix run 以及 localhost:5174 上的前端验证，再将生产环境仅用作对照。

对于 Valkyr 原生的 Agent 路由，应将 GrayMatter 视为 ValkyrAI、ValorIDE、ThorAPI、TrustFabric、GridHeim 和 SWARM 协调工作的共享记忆与架构上下文。首先加载持久 invariants，然后通过负责该工作的生成代码、安全、工作流或 MCP 接口来推进实现。

P0 RBAC/ACL 安全 invariant：生成的 ThorAPI ACL 行为是授权的真实依据。任何自定义控制器、委托、服务、前端过滤器、状态检查、类型检查、角色捷径、目录规则或“近似公开”的启发式规则，都不得绕过、弱化、取代或掩盖生成的 ACL 行为。用户只能查看自己拥有的记录，以及通过明确 ACL 授权共享的记录；公开访问必须明确授予 anonymousUser 的 READ 权限。要解决 ACL 的扩展性问题，应使用带索引的所有者/ACL 查询选择，再执行最终的生成 ACL 守卫；绝不能扫描私有行或添加针对特定对象的绕过规则。

P0 Valkyr Way UX/auth invariant：产品 UX 必须集成到共享应用外壳和集中式 auth/session 原语中。不得创建绕过 LCARS 导航、路由守卫、共享访问控制状态、RTK Query 缓存失效机制或生成的 RBAC/ACL 契约的一次性屏幕、独立管理功能、自行管理的 auth 检查、浏览器缓存捷径或拼凑的小型应用。管理和财务工具应放在相应的 LCARS 仪表板/侧边栏界面中；用户管理应通过一个 Users & Roles 界面提供卡片/列表模式，而不是分别实现 /userList 和仪表板版本。如果 auth 行为发生变化，应更新集中的 auth/access-control 模块和测试，而不是在各个组件中零散添加检查。

GrayMatter 的用途

GrayMatter 是面向业务原生 Agent 系统的记忆与上下文层。

它旨在让 OpenClaw 实例能够：

• 读取和写入 GrayMatter 与 MemoryEntry 记录
• 通过明确的 Retrieval Receipts 检索记忆，了解置信度、新鲜度、来源、策略和后续操作信号
• 将租户/账户所公开的整个 RBAC 可见架构用作对象图
• 通过 SwarmOps 协调 Agent
• 适应实际业务环境，例如客户、发票、产品、备注、文件、工作流、任务、类似 CMS 的内容、策略对象和销售记录
• 仅将基于文件的记忆用作引导或回退方案

核心理念如下：

GrayMatter 不只是记忆存储。 它是经过身份验证的对象关系型记忆图和架构感知层，让 Agent 能够安全、有效地融入组织并为其服务。

主记忆模型

边界规则： 此技能应保持轻量，只需说明使用意图、持久类型选择和操作体验。 重试行为、身份验证／会话刷新、备用队列处理和重放执行属于共享的 GrayMatter 基础设施契约。 应让此代码库与这些契约保持一致，而不是重新实现它们。

只要能通过技能、插件、MCP 服务、应用连接器或提示词命令使用 GrayMatter，就应将其作为唯一的主要持久记忆系统。 Agent 不应维护相互竞争的持久记忆存储来保存用户、项目、业务、组织或长期 Agent 状态。

本地文件仅可用于：

• 首次启动时提供引导上下文
• 托管的 api-0 不可用或身份验证确实受阻时，作为临时备用方案
• 写入路径受阻时，作为临时的可重放备份

本地备用方案属于降级模式下的重放，不是事实来源记忆。连接恢复且授权租户上下文恢复后，首次成功的身份验证请求会自动将 API 延迟操作和 gm-write 备用记录都重放到 api-0。只有持久写入成功后才会移除本地副本；scripts/gm-replay-deferred 仍可用于操作员显式重试。

持久记忆目标

主要目标：

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

典型的 MemoryEntry.type 值：

• decision
• todo
• context
• artifact
• preference

检索回执

为了确保答案有据可依，当 Agent 打算依据记忆作答时，优先使用有回执支持的检索，而不是直接搜索原始记忆。

检索回执会将记忆查找转变为可审计的事务：

• retrievalStatus 告知 Agent 查找结果是可靠、为空、过时、存在冲突还是置信度较低
• answerPolicy 告知 Agent 是否可以作答、必须添加限定说明、必须重试、必须澄清或必须拒绝
• recommendedAction 告知生成答案前的下一步操作
• quality、coverage、provenance 和 policy 说明原因
• receiptId 和 traceId 可让下游日志和审计将答案与记忆查找关联起来

Agent 规则： 如果存在检索回执，作答前应检查 answerPolicy。当其值为 DO_NOT_ANSWER_CONFIDENTLY、REQUIRE_RETRY、REQUIRE_CLARIFICATION 或 DENY 时，不要给出确定的答案。

全模式能力

GrayMatter 应在启动时加载实时的 ValkyrAI OpenAPI：

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

这让 Agent 能够实时了解其运行环境。

也就是说，Agent 可以检查当前部署中实际存在的实体和操作，而不是依赖过时的假设。

重要原因

大多数企业不只是“记忆加聊天”。 它们还拥有结构化的运营数据。

当前实时模式中观察到的示例包括：

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

当前实时端点公开了广泛的业务领域接口，包含 100 多个标签和数百个路径。具体可用的子集仍由用户的凭据、组织设置和 RBAC 决定。

GrayMatter 的强大之处正在于此：Agent 能够在业务中深入了解上下文，同时不会越权超出已授予的权限。

SwarmOps 仍然重要，但它只是对象图中用于 Agent 协同的部分：为 Codex/OpenClaw 和同级 Agent 提供注册、跟踪和 swarm 协议状态。业务关系应直接使用更广泛的 RBAC 可见模式。

安全模型

GrayMatter 功能强大，因为访问经过身份验证，并限定在租户范围内。 正确使用时，它在设计上也是安全的，因为：

• 访问权限受当前账户的 RBAC 限制
• 用户和组织的权限决定 Agent 可以查看和更改哪些内容
• 权限失败可以清晰地呈现
• 不能仅仅因为架构存在，就假设技能拥有普遍访问权限

规则：

• 架构可见不等于有权使用所有内容

仓库内容

• SKILL.md — OpenClaw AgentSkill 说明
• graymatter.skill — 打包后的可分发 AgentSkill
• scripts/graymatter_api.sh — 经过身份验证的生产 API 传输
• scripts/gm-login — 登录辅助工具
• scripts/gm-activate — 一次性身份验证 + 安装 + Agent 注册 + 架构同步引导
• scripts/gm-activation-fastlane — 首次运行就绪检查、一次性激活、非机密遥测和适合审核者的演示运行器
• scripts/gm-mcp-launcher — 有界签名版本检查、身份验证、条件架构刷新、重放门控，以及干净的 MCP 标准输入/输出交接
• scripts/gm-schema-cache-lib — 范围限定的 OpenAPI 缓存标识、元数据、新鲜度和锁辅助工具
• scripts/gm-self-update — 稳定版签名发布暂存、原子版本切换、键控状态/锁和回滚
• scripts/gm-install-check — 依赖项和身份验证就绪检查
• scripts/gm-doctor — 涵盖自更新、身份验证、记忆、架构、MCP、重放和冒烟测试状态的完整就绪报告
• scripts/gm-smoke — 用于写入/查询验证的生产冒烟测试
• scripts/gm-invariant-preflight — 在 Agent 规划、编辑或执行会影响生产的操作之前，加载绑定的持久不变量
• scripts/gm-query — 查询 MemoryEntry
• scripts/gm-read — 按 ID 读取一条 MemoryEntry
• scripts/gm-retrieval-receipt — 通过 ThorAPI 创建、获取和列出检索收据
• scripts/gm-write — 写入 MemoryEntry，并提供带标签写入的回退行为
• scripts/gm-fallback-append — 将失败的写入追加到本地重放队列 memory/graymatter-fallback.json
• scripts/gm-replay-deferred — 重放因额度/连接/身份验证中断而在本地延期的操作
• scripts/gm-graph — 检查 Swarm 图端点
• scripts/gm-openapi-sync — 有条件地获取、验证并在本地原子缓存实时 OpenAPI 规范
• scripts/gm-openapi-summary — 汇总实时架构的领域和端点
• scripts/gm-status — 快速健康/状态界面，显示身份验证来源、回退队列和 OpenAPI 缓存
• scripts/gm-agent-smoke-matrix — 面向 OpenClaw 和 Codex 风格 Agent 的安装/读取-搜索/写入/MCP/架构/安全响应就绪矩阵
• scripts/gm-client — 用于针对 GrayMatter API 路径执行 GET/POST/PUT/PATCH/DELETE 的通用 REST 封装器
• scripts/gm-entity — 用于列出、读取和写入任意架构实体的通用辅助工具
• scripts/gm-record — 用于战略优先级和 KPI 记录的便捷辅助工具
• scripts/gm-register-agent — 将 OpenClaw 服务注册为 api-0 中的 Agent，或刷新其注册信息
• scripts/gm-mcp-contract — 输出供 Agent/IDE 适配器使用的可移植 MCP 记忆工具契约架构
• scripts/gm-light-bootstrap — 使用适用于 bash 的模板复制并渲染本地 GrayMatter 应用包和服务源代码脚手架
• scripts/gm-light-up — 生成并启动由 ThorAPI 支持的本地 GrayMatter Light 实例
• scripts/gm-light-env — 打印将技能脚本指向运行中 Light 实例的环境变量导出语句
• scripts/gm-light-smoke — 通过写入/查询一条决策并检查记忆健康状态，验证本地 Light 流程
• scripts/gm-light-json-smoke — 不依赖 ThorAPI，使用 JSON 文件回退方式对 Light 载荷结构进行冒烟测试
• scripts/package-local-server — 打包独立可下载的 GrayMatter Local Server 存档
• scripts/package-graymatter — 确定性验证和打包
• mcp-server/ — GrayMatter 记忆、不变量预检、检索收据、图、实体、架构和概览工具的独立 HTTP/SSE 与 Apps SDK /mcp 服务
• docs/architecture.md — 架构和运行模型
• docs/openai-app-directory-submission.md — Apps SDK 提交清单和文案
• docs/privacy-policy.md — GrayMatter 专用的公开隐私政策源文件
• docs/reviewer-test-credentials.md — 审核演示账户设置和安全凭证交接操作手册
• docs/prd-context-compaction-reset.md — 有界聊天压缩和重置流程的 PRD
• docs/prd-graymatter-omegarag.md — 受治理的 Agentic 记忆、自适应检索、时序图、SWARM 和 SkillOptics 产品的规范实现契约
• docs/thorapi-integration.md — ThorAPI 关系和产品包方向
• docs/graymatter-light.md — 本地/离线说明
• docs/server-capabilities.md — 实时 api-0 记忆、检索、图、架构、身份验证、额度和 MCP 能力图
• openai-app/submission-manifest.json — 用于提交至 OpenAI 控制面板的非机密应用元数据
• examples/* — 示例载荷和 Light 模式入门资源
• references/* — 发布和多 Agent 指南，包括并发约定
• references/mcp/memory-tool-contract.v1.json — 适用于记忆和图操作的稳定 v1 可移植工具契约
• clawhub.json — 发布元数据

安装详情

账户注册和积分

新建 GrayMatter 账户时，请使用：

• 注册：https://valkyrlabs.com/graymatter/cloud/signup?source=graymatter&intent=signup
• 积分和充值：https://valkyrlabs.com/graymatter/credits?source=graymatter&intent=recharge&operation=memory_query

商业模式：

• 免费层账户在注册时开始的每个月度周期内，可获得 500 个赠送积分
• GrayMatter 查询和某些高阶操作会消耗积分
• 赠送积分用完后，用户可以等待下次月度分配；不保证积分结转或累积
• ChatGPT 仅使用免费层功能，不提供购买、充值或升级操作或链接
• Codex、OpenClaw、Claude 和其他非 ChatGPT 客户端可能会提供积分包，或支持现有的 Valkyr Solo、Team 或 Enterprise 订阅
• 仅有积分并不能授权使用托管实例或执行工作流；必须拥有有效的付费 Valkyr 订阅，并通过服务器端权限检查

首次运行身份验证：OpenClaw 的预期流程

用户不应该需要手动获取或粘贴原始身份验证令牌。

OpenClaw 预期的首次运行身份验证步骤如下：

1. GrayMatter 打开原生 macOS 或 Windows 连接对话框；选择 Cloud、localhost 或自托管服务器
2. 在原生遮蔽字段中收集密码
3. OpenClaw 使用这些凭据换取会话
4. ValkyrAI/Cloud 会话存储在凭据库中；GrayMatter Lite 本地账户使用其私有配置文件凭据文件
5. OpenClaw 在 api-0 中为自身创建或刷新 Agent 记录
6. 后续使用 GrayMatter 时，会自动从平台凭据库读取会话

这意味着 GrayMatter 应该带来这样的体验：

• 登录一次
• 安全存储
• 此后一直使用，直至需要刷新

临时网络或服务器故障不会导致已存储的会话被丢弃，也不会重新弹出误导性的密码提示。只有明确的 401 或 403 才会使启动身份验证失效。Windows 会将过长的会话存储为透明的受保护 Credential Manager 分块，因此较长的 JWT 不会超出平台的单条目大小限制。

手动处理令牌是备用/调试途径，而非主要用户体验。

基于仓库的安装

克隆仓库后，在 macOS/Linux 上使用 ./install.sh，或在 Windows PowerShell 中使用 .\install.ps1。如果已安装 Codex，这些命令会添加仓库市场并自动安装 graymatter@graymatter；否则会准备独立运行时和身份验证界面。

scripts/gm-activate 是 OpenClaw 安装的预期一键引导程序。默认情况下，它会先运行 scripts/gm-self-update force，确保激活和恢复流程不会因为每周启动间隔尚未到期而跳过针对权威源的更新检查，然后再进行身份验证并验证安装。只有当操作者明确希望启动行为受间隔控制时，才设置 GRAYMATTER_ACTIVATE_SELF_UPDATE_MODE=maybe。它可以使用：

• 交互式用户名/密码提示，或
• 环境变量中已有的凭据

支持的环境变量输入：

• GRAYMATTER_USERNAME 或 VALKYR_USERNAME
• GRAYMATTER_PASSWORD 或 VALKYR_PASSWORD
• 可选的 VALKYR_AUTH_TOKEN
• 如果需要使用非默认的平台凭据库服务名称，可选的 VALKYR_KEYCHAIN_SERVICE
• 可选的 OPENCLAW_INSTANCE_ID
• 可选的 OPENCLAW_AGENT_NAME
• 可选的 OPENCLAW_AGENT_ROLE

scripts/gm-login 是 macOS/Linux 上的标准登录步骤；Windows 使用 scripts/gm-activate.ps1。插件管理的启动会在所有平台上使用 node scripts/gm-mcp-launcher.mjs --stdio，并在需要时自动打开原生对话框。

scripts/gm-register-agent 是预期启动握手流程的一部分。OpenClaw 服务连接到 api-0 时，应先为自身创建或刷新 Agent 记录，然后再开始正常工作。 node scripts/gm-mcp-launcher.mjs --stdio 是常规的跨平台 MCP 入口点。需要时，它会打开原生登录流程；随后，在受支持的 Unix 安装环境上启动 MCP 服务前，会继续执行有界的签名更新、架构刷新和重放检查。scripts/gm-self-update 只接受带内容寻址、经过签名验证的制品的已签名稳定版清单；它会将文件暂存到版本化安装根目录，原子切换状态，保留回滚能力，并且绝不会重写正在运行的 Codex 插件缓存目录。Valkyr Labs 的发布密钥随附于 release/graymatter-release-public.pem；可通过 GRAYMATTER_RELEASE_PUBLIC_KEY_FILE 或 GRAYMATTER_RELEASE_PUBLIC_KEY 显式覆盖该密钥，用于受控测试或密钥迁移。验证失败会被记录并显示出来。

scripts/graymatter_api.sh 和 MCP 服务会检测过期会话，并在需要时重新打开安全登录流程；它们绝不会保留可重复使用的托管密码。遇到架构版本或路由失败时，会执行一次有界的在线架构重新同步并重试；服务中断期间，缓存架构仅用于发现。因额度、传输问题或租户上下文暂时无法解析而受阻的可安全重放写入，会在本地排队；授权租户上下文恢复后，首次成功的已验证请求会在进程锁保护下自动重放，且重放次数有上限。scripts/gm-replay-deferred 仍是显式重试入口。

此时，安装应当可以立即使用。

如果身份验证成功，但内存查询暂时受额度限制，scripts/gm-activate 现在会以降级模式继续：保存身份验证信息，注册 Agent，同步 OpenAPI，并报告在额度可用之前内存查询能力受限。

对于应用审核或客户首次运行流程，请使用激活快速通道：

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

--check-only 会验证安装就绪状态、运行时状态和便携式 MCP 内存工具契约，但不会激活或写入演示数据。--reviewer-demo 会运行常规激活流程，然后执行有界的 MemoryEntry 示例写入/查询、图谱读取、架构摘要以及安全的 MemoryEntry 实体列表查询。脚本会将 activation_started、auth_completed、schema_synced、first_memory_written、first_query_succeeded、credit_warning_shown 和 activation_completed 等非敏感事件输出到 stderr；如果设置了该环境变量，还会将这些事件追加到 GRAYMATTER_ACTIVATION_EVENT_LOG。

原始承载令牌设置仍是调试/高级流程。默认的首次运行流程是登录、安全存储、验证工具、写入/查询演示内存，然后继续执行适配入门额度的后续操作。

如需生成一份安装后的一键报告，请运行：

scripts/gm-doctor

gm-doctor 会检查自更新就绪状态、安装依赖、身份验证/钥匙串状态、实时内存和对象图谱层状态、OpenAPI 同步、MCP 契约可用性、延迟重放就绪状态，以及实时写入/查询冒烟测试路径。如果希望生成相同报告，但不在冒烟查询中消耗额度，请使用 scripts/gm-doctor --quick。

打包技能安装

1. 将 graymatter.skill 导入或放入目标 OpenClaw 技能目录
2. 确认解压后的文件夹路径为 graymatter/
3. 运行：

scripts/gm-activate

如果这些步骤都通过，说明该技能可以安装并使用。

全新安装验收标准

只有当新用户能够完成以下操作时，GrayMatter 才算达到发布就绪状态：

1. 安装代码库或打包技能
2. 成功完成身份验证
3. 通过安装验证
4. 写入并查询 MemoryEntry
5. 为内存查询创建 Retrieval Receipt，并检查 answerPolicy
6. 检查图谱状态
7. 在 api-0 中将 OpenClaw 实例注册为 Agent
8. 获取并概述实时 OpenAPI
9. 检查业务架构中的至少一个实时实体类别

如果这些操作无法完成，该技能就还没有真正准备就绪。

OpenClaw 引导集成

OpenClaw 工作区引导指南应将 GrayMatter 视为默认的持久化上下文层：

• 将 GrayMatter 用作主要的持久化记忆
• 在启动时加载实时 OpenAPI
• 将组织架构理解为运行环境
• 仅将本地文件记忆用作备份

这种启动模式既能让本地文件在恢复时发挥作用，也能让 GrayMatter 成为可复用记忆和实时架构上下文的常规来源。

典型用法

持久化记忆

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

基于回执的检索：

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

限定范围的记忆

使用 sourceChannel 作为检索范围键，区分聊天、工作区和自动化专属记忆。gm-write 可以根据明确的范围字段或本地路径推导该键，然后将精简的 [graymatter-scope] 标头写入 MemoryEntry.text，以便即使无法使用标签，层级仍可审计。

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"

对于该路径，GrayMatter 会推导出 sourceChannel=codex:automation:mcp-and-skill-hunter。对于 Documents/Codex/<date>/<slug> 下的 Codex 项目文件夹，它会推导出 sourceChannel=codex:workspace:<date>/<slug>。如果宿主能提供比文件路径更可靠的标识符，请使用 --chat-key、--session-key、--workspace-key 或 --automation-id。

带标签的写入与自动回退

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

如果后端的标签持久化功能异常，脚本会在不带标签的情况下重试，而不是让整个写入失败。

如果 API 调用仍然失败，且存在 scripts/gm-fallback-append，gm-write 会将尝试写入的内容追加到 memory/graymatter-fallback.json。

一次性激活

scripts/gm-activate

这是首选的 OpenClaw 安装／引导入口。

Agent 自行注册

scripts/gm-register-agent

当 OpenClaw 服务首次连接 api-0 时应运行此操作，以便系统为该实例创建明确的 Agent 记录。

图状态

scripts/gm-graph GET

实时架构同步

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

任意架构实体访问

# 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 使用：

• VALKYR_API_BASE，默认值为 https://api-0.valkyrlabs.com/v1
• 通过 macOS Keychain、Windows Credential Manager 或 Linux Secret Service 查找 VALKYR_AUTH
• VALKYR_AUTH_TOKEN 作为高级调试覆盖项，而非常规激活路径
• VALKYR_JWT_SESSION 作为下游工具兼容的环境变量回退项

首选身份验证流程：

• 首先在平台凭据保险库中查找 VALKYR_AUTH
• 如果存在，则自动重用
• 否则，提示用户输入一次用户名和密码
• 交换获取 VALKYR_AUTH 令牌
• 仅将该令牌和用户名安全地存储在平台凭据保险库中，以供后续运行使用

托管版／ValkyrAI 密码绝不会被持久化；GrayMatter Lite 本地配置文件使用私有凭据文件。在 macOS 和 Windows 上，即使 MCP 宿主没有交互式终端，插件首次启动时也会自动打开原生登录对话框。注册和账户恢复通过专用网站页面完成，之后用户返回仍保持打开的原生连接窗口。常规会话捕获绝不依赖浏览器重定向或剪贴板令牌。

不要将机密硬编码到代码库或技能中。 不要打印令牌。 不要将手动处理令牌作为用户的常规操作流程。

OpenClaw 操作指南

在 GrayMatter 原生工作区中，Agent 应：

1. 首先查询 GrayMatter，获取持久化上下文
2. 然后检查相关的实时业务实体
3. 仅在 GrayMatter 不可用或信息不完整时回退到本地文件
4. 保持持久化写入精简且可复用
5. 将实时架构视为组织的环境模型

这样，Agent 才能成为合适的业务操作者，而不只是一个有日记的聊天机器人。

本地回退行为

如果 api-0 不可用，或写入路径暂时异常：

• 写入最小且安全的本地备份
• 确保该备份可重放
• 等 GrayMatter 恢复正常后再重试

典型的回退文件：

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

故障排除

VALKYR_AUTH_TOKEN is required

未设置环境令牌，也未找到匹配的平台凭据库会话。

修复方法：

• 运行 scripts/gm-login 并完成用户名/密码登录，或
• 导出 VALKYR_AUTH_TOKEN，或
• 确保平台凭据库中存在 VALKYR_AUTH 条目

jq: command not found

安装 jq。

在 macOS 上：

brew install jq

带标签的写入失败

某些部署仍存在 MemoryEntry.tags 持久化不匹配的问题。

修复方法：

• 使用 scripts/gm-write
• 让它自动重试，并在重试时不带标签

查询因额度或账单错误而失败

如果写入和读取成功，但 /MemoryEntry/query 因额度错误而失败，通常是账户账单配置问题，而不是 GrayMatter 身份验证失败。

已观察到的要求：

• 查询目前会消耗额度
• 免费套餐账户每月周期可获得 500 个包含额度，注册时的首个周期也包括在内
• 如果当前额度已用尽，请遵守服务器的额度限制；不要告知 ChatGPT 用户购买、充值或升级
• 非 ChatGPT 客户端可以为较高用量提供现有的 Valkyr 订阅或额度包

实用链接：

• 注册：https://valkyrlabs.com/graymatter/cloud/signup?source=graymatter&intent=signup
• 额度与充值：https://valkyrlabs.com/graymatter/credits?source=graymatter&intent=recharge&operation=memory_query

INSUFFICIENT_FUNDS 时的 CLI 行为：

• 在 stderr 中同时打印购买和注册链接
• 尝试在 macOS（osascript）和 Windows（powershell.exe）上弹出提示
• 如果弹窗工具不可用，则打开购买额度 URL，作为最后的备用方案

自定义部署的可选覆盖项：

• VALKYR_BUY_CREDITS_URL
• VALKYR_HUMAN_SIGNUP_URL
• VALKYR_HUMAN_RECOVERY_URL

如果新账户余额为 0.00，写入/读取操作仍可能成功激活，但查询会在额度发放前失败。

登录成功，但未找到会话

某些 api-0 部署会通过标头或 Cookie 返回身份验证信息，而非放在 JSON 响应正文中。

修复方法：

• 使用最新版 scripts/gm-login
• 它现在将 VALKYR_AUTH 视为主要身份验证约定
• 下游 API 调用会将恢复出的令牌作为 bearer 身份验证、VALKYR_AUTH 和 Cookie 身份验证发送回去

获取 OpenAPI 失败

请检查：

• 出站网络访问
• api-0 是否可用
• 环境是否阻止访问文档端点

如果无法获取在线文档，可暂时使用上次缓存的副本，但请将其视为过时内容。

不确定出了什么问题

运行：

scripts/gm-doctor --verbose

doctor 命令会继续执行所有检查，并报告确切的必要故障或警告，而不是在遇到第一个损坏的依赖项时停止。在更改身份验证、额度、MCP 配置或本地插件文件之前，建议优先运行此命令进行诊断。

打包

GrayMatter Lite 生成与旧版兼容性

在本轮分发冲刺之前，Light 模式虽然实用，但还不够严格，无法作为 api-0 的即插即用替代方案：

• 本地文档和软件包使用未加前缀的路径，例如 /MemoryEntry 和 /SwarmOps/graph
• 手写的 Light OpenAPI 可能会偏离预期的 GrayMatter 领域
• 软件包中的服务需要系统 Java 运行时，除非操作者自行提供
• 没有一条命令可以同时验证本地写入、查询、健康状态和 MCP 就绪情况

本轮冲刺之后，Light 模式采用 api-0 形态：

• VALKYR_API_BASE=http://localhost:<port>/v1
• Light 实现了以 MemoryEntry 为先的生产路径子集：/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 和 /v1/api-docs
• Lite OpenAPI 由 openapi/bundles/*.yaml 和可选的应用扩展组成，经 ThorAPI 增强后，输出为确定性 YAML 和派生 JSON
• 打包后的本地服务在用户本地应用目录下使用 H2，并支持捆绑运行时的归档文件
• scripts/gm-light-smoke 可验证本地写入/查询/健康状态流程，并输出 MCP 就绪说明

使用以下命令重新构建打包后的技能：

scripts/package-graymatter

使用以下命令运行规范的生成版 Lite 实例：

./vaix setup
./vaix doctor

旧版兼容启动器仍可供现有安装使用：

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 会将打包的兼容性快照复制到 .graymatter-light，并启动 ThorAPI 容器。该快照不是编写入口；架构变更应在 openapi/bundles 中完成，并通过 ./vaix 重新生成。 兼容性环境仍会设置 VALKYR_API_BASE=http://localhost:8080/v1 和 GRAYMATTER_LIGHT_MODE=true，因此现有脚本和 MCP 客户端可以继续使用。

使用以下命令运行完整的本地流程冒烟测试：

scripts/gm-light-smoke

使用以下命令构建可独立运行、可下载的本地服务：

scripts/package-local-server

这会创建 dist/graymatter-local-server-latest.tar.gz。该归档文件包含：

• application-bundle/，其中包含 ValkyrAI app-factory 模板、ThorAPI FEBE OpenAPI 契约、自定义 dashboard/workbench/promotion/swarm 组件，以及内置的 rbac-core / data-workbooks 组件引用
• source/，其中包含生成的 Spring Boot 本地服务
• bin/graymatter-local-server 启动器
• 如果打包期间 Maven 可用，则包含 lib/graymatter-local-server.jar
• 如果打包期间 jlink 可用，则包含 runtime/，这样用户在正常使用流程中无需手动安装 Java

内嵌的 dashboard 带有 Valkyr Labs 品牌标识；登录成功后会隐藏本地登录面板；提供用于 valkyrlabs.com Cloud 桥接的激活/充值链接；并通过符合生产形态的 /v1 路径报告本地 swarm-ops 图状态。

awesome-codex-plugins 提交资料包

GrayMatter 提供了一套可直接提交至 awesome-codex-plugins 的资料包。

• 列表 Markdown 区块：docs/awesome-codex-plugins.md
• 源元数据：.codex-plugin/plugin.json

快速复制流程：

cat docs/awesome-codex-plugins.md

然后向 hashgraph-online/awesome-codex-plugins 提交 PR，并按照该仓库的贡献格式，将生成的区块粘贴到 README.md 中。

发布定位

发布目标很简单：

• GrayMatter 能够作为 OpenClaw 技能顺利安装
• OpenClaw 启动后优先采用 GrayMatter 记忆行为
• Agent 在启动时加载实时 OpenAPI 架构
• Agent 能理解持久记忆以及更广泛的组织对象图
• 文件记忆仍作为备份，而非核心

这才是值得发布的 GrayMatter 版本。