GrayMatter

В документе объясняется, как находить полный список данных, явно различать повторное использование и проверку записи, а также связывать подтверждения с решениями, артефактами и тестами — без выдуманных оценок экономии.

GrayMatter Lite — полноценный продукт с открытым исходным кодом для одного пользователя или одной рабочей области. Он работает локально или на инфраструктуре под вашим контролем и с первого запуска поддерживает весь основной рабочий цикл: вход в систему, создание долговременной памяти, поиск через MCP, импорт и экспорт переносимых KnowledgePacks, а также подключение локальных и размещённых профилей агентов.

Это не пробная версия с ограниченным сроком действия и не пустая демонстрация. В состав GrayMatter Lite входят каноническая YAML-спецификация ThorAPI в 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; в систему они не устанавливаются. Команда собирает автономный Lite с использованием общедоступных зависимостей Maven, создаёт один локальный профиль, запускает сервисы и проверяет подключение. Учётная запись размещённого сервиса и закрытый генератор ThorAPI не требуются.

Явная генерация схемы по-прежнему доступна через ./vaix generate.

После настройки запускаются:

панель управления и вход в систему: 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-auth и возможностью переключать локальные профили;
создание и чтение долговременных записей MemoryEntry, гибридный поиск и хранение данных в H2;
локальная индексация векторов с необязательными эмбеддингами через Ollama на loopback-интерфейсе, а также ограниченный контекст Bifrost, указатели на цитаты, повторная проверка источников и подтверждения поиска;
существующие панель управления Valkyr, рабочая область памяти, телеметрия и статус SWARM;
встроенный MCP-сервер с поддержкой stdio и HTTP для Codex, OpenClaw, Claude, хостов локальных моделей и других совместимых с MCP клиентов;
импорт подписанных KnowledgePack-файлов .gmkp и экспорт всей памяти в формате 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-auth для локальных учётных записей находятся в файле секретов с правами 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 приведены в разделе Локальные модели. При выполнении локальных Workflow используются две границы MCP: Valkyr SWARM отвечает за регистрацию и координацию подписанных Workflow, а 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.

При запуске он подписывается в соответствии с тем же автономным контрактом целостности, что и обычные KnowledgePacks, затем импортируется штатным импортёром, а содержащиеся в нём записи сохраняются в локальной базе 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 сохраняет предусмотренные для человека этапы подтверждения перед отправкой данных наружу, развёртыванием в production, слиянием изменений и контролируемым перезапуском сервисов. GrayMatter Lite не создаёт отдельную шину команд и не позволяет агенту подтверждать собственные действия.

Документация и сообщество

Используйте GitHub Issues для сообщений о воспроизводимых дефектах, а GitHub Discussions — для получения поддержки, обсуждения идей, KnowledgePacks и интеграций. О сообщениях об уязвимостях рассказывайте конфиденциально, как указано в SECURITY.md.

Платформа GrayMatter: интеллект для всего вашего бизнеса

Valkyr GrayMatter™ превращает приложения, документы, рабочие процессы, переписки и институциональные знания в постоянно обновляемый, доступный для поиска интеллектуальный слой.

Это больше, чем векторная база данных или память чата. GrayMatter объединяет долговременную память, поиск в реальном времени, структурированные бизнес-данные и анализ с учётом связей в единой защищённой системе, доступной агентам, людям, приложениям и API.

Система памяти, которая действительно учитывает контекст

GrayMatter сохраняет решения, предпочтения, задачи, результаты исследований, процедуры, переписки и операционные знания в виде структурированных записей с указанием источника, а не как исчезающую историю чата. Каждая запись может содержать источник, область действия, теги, связи, временные метки, сведения о владельце и происхождении данных. Благодаря этому система отличает личное предпочтение от политики компании, текущую задачу от исторического контекста, а исходный документ — от созданного ИИ резюме.

Система поддерживает агентную память для Codex, OpenClaw, SageChat, рабочих процессов и подключённых инструментов. Все авторизованные агенты получают общее представление о бизнесе, а информация не сводится к непрозрачному промпту, происхождение которого невозможно отследить.

Гибридный поиск: по ключевым словам, векторам, графу и структурированным данным

Поиск GrayMatter предназначен как для простых, так и для сложных запросов:

Точный поиск по именам, идентификаторам, тегам, командам, продуктам и записям
Полнотекстовый поиск по документам, заголовкам, полям и обработанным загруженным файлам
Семантический и векторный поиск по понятиям, намерениям и смыслу
Поиск с учётом связей между сущностями ThorAPI и связями графа знаний
Структурированная фильтрация по типу, дате, категории, тегам, тенанту, рабочему процессу, проекту и другим параметрам
Отчёты о результатах поиска с цитатами, подтверждениями, показателями качества и рекомендациями по подготовке ответа

Пользователь может искать информацию на общедоступном сайте, в рабочем пространстве с авторизацией или через SageChat — все они используют одну интеллектуальную основу. При этом каждому интерфейсу предоставляется только та информация, к которой у него есть доступ.

Векторный интеллект на базе PostgreSQL

GrayMatter использует PostgreSQL как надёжную операционную основу, а pgvector — как высокопроизводительный инструмент ускорения семантического поиска.

SemanticIndexEntry остаётся переносимой канонической записью, а проекции pgvector, ограниченные рамками тенанта, обеспечивают быстрый поиск ближайших соседей. Платформа поддерживает настраиваемые провайдеры эмбеддингов, включая производственные эмбеддинги OpenAI и детерминированные локальные эмбеддинги для автономной работы и разработки. Она также отслеживает модель, провайдера, размерность векторов, состояние индекса, устаревшие записи, рекомендации по переиндексации и состояние деградации.

Это позволяет перейти от обычных реляционных данных к семантическому поиску производственного уровня, не создавая отдельный закрытый граф или изолированное векторное хранилище.

Полноценный граф знаний на основе ThorAPI

GrayMatter рассматривает знания не как набор документов, а как сеть связей.

Сущности ThorAPI и связи между ними, описанные в OpenAPI, можно индексировать после успешной записи данных. Это позволяет безопасно использовать семантические данные о рабочих процессах, приложениях, клиентах, задачах, файлах, процедурах, агентах, целях, заметках и многом другом. Записи GraphLink явно фиксируют важные отношения: поддерживает, блокирует, ссылается на, получено из, связано с и другие.

Это позволяет выполнять поиск с учётом связей, например:

«Что связано с этой проблемой клиента?»
«От какой интеграции зависит этот рабочий процесс?»
«Какие данные подтверждают это решение?»
«Какие документы, записи памяти и задачи объясняют этот результат?»

Система поддерживает ограниченный обход графа, цитирование источников и дальнейшую аналитику графа. При этом индекс и граф не могут обходить механизмы авторизации ThorAPI.

SageChat и обработка документов

SageChat превращает загруженные файлы и обработанные документы в доступные для поиска подтверждения, а не оставляет их в хранилище без дальнейшего использования.

Файлы обрабатываются в виде ограниченных по объёму семантических данных с подробными сведениями о происхождении: исходный файл, результат парсера, фрагменты, страницы или смещения, хеши источников, качество извлечения и связи с поддерживаемыми ими бизнес-объектами. Затем GrayMatter может предоставить эти данные в SageChat с цитатами и пояснениями, чтобы пользователи понимали не только ответ, но и его источник.

Плагины, навыки и MCP: интеллект повсюду

GrayMatter распространяется как устанавливаемая система плагинов и навыков для агентов в стиле Codex/OpenClaw. Она поддерживает безопасную аутентификацию с использованием хранилища секретов платформы, регистрацию агентов, работу со схемами, чтение и запись долговременной памяти, доступ к графу, отчёты о результатах поиска и проверку работоспособности.

Благодаря поддержке MCP GrayMatter доступен совместимым ИИ-клиентам через типизированные инструменты: запись в память, поиск и чтение памяти, извлечение данных с отчётом, просмотр графа, обнаружение схем и авторизованный доступ к сущностям.

Плагины и навыки обеспечивают каждому агенту доступ к одному и тому же долговременному организационному контексту, а MCP позволяет использовать его во внешних ИИ-средах и рабочих процессах.

Кредиты для реальных задач с ИИ

GrayMatter включает модель кредитов и прав доступа для расширенных операций с памятью и ИИ. Она обеспечивает устойчивое использование семантического поиска, эмбеддингов, переиндексации и расширенных интеллектуальных функций, сохраняя при этом прозрачный операционный контроль.

Платформа отделяет функции, безопасные для публичного использования, от частных операционных инструментов. Это предотвращает утечку коммерческой информации и данных об управлении учётными записями в публичные интерфейсы ИИ.

Безопасность заложена в основу

GrayMatter не использует поиск как способ обойти механизмы безопасности.

Сгенерированные механизмы RBAC и ACL в ThorAPI остаются источником истины для каждого результата, фрагмента, количества записей, элемента фасетной навигации, пути в графе, цитаты из файла и рекомендации. Контекст тенанта определяется на стороне сервера. Конфиденциальные поля, учётные данные, двоичные данные и защищённая информация аудита исключаются из индексации. Поиск, векторное извлечение, навигация по графу и инструменты агентов спроектированы так, чтобы запрещать доступ, если авторизация не подтверждена.

Результат

GrayMatter становится интеллектуальным слоем, который позволяет каждому продукту Valkyr, рабочему процессу, приложению, агенту и документу участвовать в формировании общей защищённой системы знаний с возможностью поиска:

Система памяти для агентов и команд
Граф знаний бизнеса
Гибридная поисковая система для сайтов и рабочих пространств
Слой векторного интеллекта на PostgreSQL
Механизм исследований и рассуждений для SageChat с цитатами источников
Переносимая платформа на основе ThorAPI для плагинов, навыков, инструментов MCP и автоматизации с помощью ИИ

GrayMatter — устанавливаемый навык OpenClaw и сервис MCP для:

основной долговременной памяти
общего состояния графа объектов
актуальных сведений о схеме организации через OpenAPI ValkyrAI api-0

С его помощью агент выходит за пределы локальных файлов и изолированного контекста чата. После аутентификации GrayMatter становится единственной основной долговременной памятью агента: она надёжно сохраняет данные, анализирует актуальную бизнес-схему и работает в среде данных организации с ограничениями RBAC.

Приложение для ChatGPT в режиме разработчика

В качестве основы используется существующий Node MCP-адаптер из mcp-server/, работающий в защищённом режиме публичного приложения. api-0 остаётся единственным источником данных для памяти, ContextPage, процедур, подтверждений, RBAC, ACL и арендаторов.

Контракт публичного развёртывания:

Production URL MCP: https://api-0.valkyrlabs.com/graymatter/mcp
URL для обеспечения совместимости: https://api-0.valkyrlabs.com/mcp
Метаданные защищённого ресурса: https://api-0.valkyrlabs.com/.well-known/oauth-protected-resource
Целевой URL метаданных сервера авторизации: https://api-0.valkyrlabs.com/.well-known/oauth-authorization-server
URL MCP для разработки: http://localhost:3333/graymatter/mcp

Указанные выше production URL MCP и OAuth — это целевые адреса развёртывания. Они не означают, что обратный прокси и сервер авторизации OAuth уже доступны. Перед созданием или отправкой приложения ChatGPT проверьте их работоспособность.

Переменные окружения, необходимые для публичного приложения:

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 token текущего пользователя. Публичный режим проверяет издателя, аудиторию, срок действия, подпись RS256, обязательные идентификационные утверждения и области доступа инструментов. Затем он передаёт в api-0 только bearer token и никогда не пересылает идентификаторы арендатора или владельца, предоставленные вызывающей стороной. Метаданные OAuth, запросы JWKS и чтение тела запроса используют общий срок выполнения запроса и прекращаются по его истечении. HTTP-тела запросов и локальные сообщения stdio отклоняются до разбора JSON, если их размер превышает GRAYMATTER_MCP_MAX_REQUEST_BYTES (по умолчанию — 1 MiB, максимум — 16 MiB); проверки состояния и ошибки с ограниченным объёмом данных возвращают executionLimits без содержимого.

Чтобы подключить версию для разработчиков в ChatGPT:

Разверните конечную точку через HTTPS или откройте локальный сервер с помощью Secure MCP Tunnel либо другого HTTPS-туннеля.
В ChatGPT откройте Settings → Security and login и включите Developer mode.
Откройте Settings → Plugins и нажмите кнопку с плюсом.
Укажите GrayMatter, описание Persistent, secure memory and shared context for AI agents. и HTTPS URL /graymatter/mcp.
Завершите подключение через OAuth и убедитесь, что обнаружено ровно восемь инструментов.
Начните новый чат, добавьте GrayMatter через поле ввода и выполните примеры запросов из SUBMISSION_CHECKLIST.md.
После изменения метаданных инструментов повторно разверните приложение и нажмите Refresh в приложении, работающем в режиме разработчика.

Запустите автоматическую проверку контракта публичного приложения, используя две изолированные учётные записи рецензентов:

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. Также поддерживается запуск MCP под управлением плагина с помощью node mcp-server/index.js --stdio.
Плагин Codex: .codex-plugin/plugin.json представляет этот репозиторий как плагин graymatter, содержащий автономный навык и .mcp.json. Это позволяет Codex обнаруживать и инструкции, и сервер MCP.
Автономный навык OpenClaw: graymatter.skill включает SKILL.md и необходимые скрипты для установки и активации в OpenClaw, использования размещённого api-0 и запуска GrayMatter Light в локальном режиме.

Если sparse/root-установка из GitHub загружает только файлы из корня репозитория, запустите ./graymatter-bootstrap в macOS/Linux или .\\graymatter-bootstrap.ps1 в Windows. Обе команды восстанавливают scripts/ и mcp-server/ из архива graymatter.skill.

Быстрый старт

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 — один диалог WinForms с поддержкой Windows Credential Manager. На первом экране доступны варианты GrayMatter Cloud (api-0), Local GrayMatter Lite (localhost:8787), Local ValkyrAI (localhost:8080) и Other self-hosted server, а также редактируемое поле URL сервера и поле пароля со скрытым вводом. Если вход не удался, окно остаётся в том же сценарии: имя пользователя сохраняется, а пользователь получает понятное сообщение о том, что нужно исправить. Пароли ValkyrAI и Cloud передаются только выбранной конечной точке входа, не выводятся на экран и не сохраняются; полученная сессия помещается в системное хранилище учётных данных. HTTP разрешён только для локальных адресов loopback; для удалённых экземпляров требуется 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, чтобы выполнить полную начальную проверку работоспособности, регистрацию агента и синхронизацию схемы.

‏scripts/gm-activate — рекомендуемый способ первого запуска. Скрипт проверяет наличие обновлений, выполняет вход, при наличии сохраняет сессию в Keychain, проверяет установку, регистрирует агента и создаёт ограниченный по размеру артефакт предварительной проверки запуска после получения инвариантов, обнаружения доступных возможностей с аутентификацией и проверки актуальности OpenAPI.

Перед планированием задач, изменением кода, действиями, влияющими на production, или ответами, основанными на истории проекта, агенты должны сразу выполнить предварительную проверку инвариантов для текущего рабочего пространства и продукта:

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

Узлы MCP, которые не могут запускать команды в оболочке, должны вызывать graymatter_invariant_preflight. Полученные записи decision с тегами invariants, security, RBAC/ACL, generated-code, AspectJ, vaix/vai, testing или названиями продуктов являются обязательными операционными правилами. Отсутствие данных или ухудшение качества поиска не дают права игнорировать известные долгосрочные правила.

Требуемая предварительная проверка шире обычного поиска по ключевым словам. До начала работы агент должен найти инварианты, правила, инструкции, контекст предыдущих сессий, персонализацию, бизнес-факты, личные факты и организационные факты. Новые исправления, процедуры, предпочтения и инварианты, предоставленные пользователем, необходимо записывать в GrayMatter во время сессии, а затем считывать по ID, чтобы подтвердить их сохранение.

При работе над приложениями, созданными с помощью ValkyrAI, ValorIDE, GrayMatter Light и ThorAPI, агентам следует предпочитать средства запуска из репозитория прямым сокращённым командам сборки: ./vaix build, ./vaix test, ./vaix run и документированные в репозитории сценарии ./vai сохраняют генерацию ThorAPI, weaving AspectJ, настройки heap, флаги локальной среды H2/runtime и поведение продукта для конечных пользователей. Исправления регистрации, ACL/RBAC и сгенерированных API обычно следует проверять с помощью ./vaix run на localhost:8080 и фронтенда на localhost:5174, используя production только для сравнения.

При маршрутизации агентов в экосистеме Valkyr следует считать GrayMatter общей памятью и контекстом схем для задач по ValkyrAI, ValorIDE, ThorAPI, TrustFabric, GridHeim и координации SWARM. Сначала загружайте долгосрочные инварианты, затем направляйте реализацию в соответствующий модуль генерации кода, безопасности, рабочих процессов или MCP.

Инвариант безопасности P0 для RBAC/ACL: источником истины для авторизации служит поведение ACL, генерируемое ThorAPI. Никакие пользовательские контроллеры, делегаты, сервисы, фильтры фронтенда, проверки статуса или типов, упрощённые проверки ролей, правила каталога и эвристики вроде «почти публичный» не должны обходить, ослаблять, подменять или затенять сгенерированное поведение ACL. Пользователям доступны только принадлежащие им записи и записи, которыми с ними поделились посредством явных разрешений ACL; для публичного доступа требуется явное разрешение READ для anonymousUser. Масштабирование ACL следует решать за счёт выбора запросов по индексированным владельцам и ACL с последующими сгенерированными проверками ACL, а не сканирования закрытых строк или добавления обходных правил для отдельных объектов.

Инвариант UX/auth P0 для Valkyr Way: пользовательский интерфейс продукта должен быть встроен в общую оболочку приложения и использовать централизованные механизмы auth/session. Не создавайте отдельные экраны, автономные средства администрирования, собственные проверки аутентификации, обходы через кеш браузера или самодельные мини-приложения, которые обходят навигацию LCARS, защиту маршрутов, общее состояние управления доступом, инвалидацию кеша RTK Query или контракты сгенерированного RBAC/ACL. Инструменты администрирования и финансов должны находиться в соответствующих разделах панели управления или боковой панели LCARS; управление пользователями должно быть доступно на единой странице Users & Roles с режимами карточек и списка, а не в отдельных реализациях /userList и панели управления. При изменении поведения аутентификации обновляйте централизованные модули auth/access-control и тесты, а не распределяйте отдельные проверки по компонентам.

Для чего нужен GrayMatter

GrayMatter — это слой памяти и контекста для агентных систем, ориентированных на бизнес.

Он разработан так, чтобы экземпляр OpenClaw мог:

читать и записывать записи GrayMatter и MemoryEntry
извлекать память с помощью явных Retrieval Receipts, содержащих сведения об уверенности, актуальности, происхождении, политике и следующих действиях
использовать всю схему, доступную через RBAC для арендатора или учётной записи, в качестве графа объектов
координировать агентов с помощью SwarmOps
адаптироваться к реальной бизнес-среде: например, к клиентам, счетам, продуктам, заметкам, файлам, рабочим процессам, задачам, контенту в стиле CMS, стратегическим объектам и данным о продажах
использовать файловую память только для начальной настройки или в качестве резервного варианта

Основная идея такова:

GrayMatter — это не просто хранилище памяти. Это аутентифицированный объектно-реляционный граф памяти и слой понимания схемы, который позволяет агенту безопасно и эффективно работать внутри организации.

Модель основной памяти

Правило границ ответственности:

Эта skill должна оставаться компактной. Её задача — объяснять назначение функций, выбор устойчивых типов данных и удобные для операторов способы работы.

Повторные попытки, обновление auth/session, постановка в очередь при сбоях и повторное выполнение операций относятся к общим контрактам инфраструктуры GrayMatter.

Поддерживайте этот репозиторий в соответствии с этими контрактами, не реализуя их повторно.

Когда GrayMatter доступен через skill, плагин, сервер MCP, коннектор приложения или команду prompt, он должен быть единственной основной системой долговременного хранения памяти.

Агентам не следует поддерживать параллельные долговременные хранилища пользовательских, проектных, бизнес- или организационных данных, а также долгосрочного состояния агента.

Используйте локальные файлы только как:

начальный контекст при первом запуске
временный резервный вариант, если размещённый api-0 недоступен или аутентификация действительно заблокирована
временную резервную копию с возможностью повторного воспроизведения, если запись заблокирована

Локальный резервный режим предназначен для повторного воспроизведения операций при сбое, а не для хранения данных — источника истины. Первый

успешный аутентифицированный запрос после восстановления подключения и авторизованного контекста арендатора автоматически повторно передаёт в api-0 как отложенные API-операции, так и резервные записи gm-write. Локальные копии удаляются только после

успешной записи данных в постоянное хранилище; для явной повторной попытки оператором по-прежнему доступен scripts/gm-replay-deferred.

Целевые типы долговременной памяти

Основные цели:

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

Типичные значения MemoryEntry.type:

decision
todo
context
artifact
preference

Retrieval Receipts

Чтобы обосновывать ответы, агенту следует использовать поиск с Retrieval Receipts, а не выполнять обычный поиск по памяти, если он намерен отвечать на основе сохранённых данных.

Retrieval Receipts превращают обращение к памяти в транзакцию, которую можно проверить:

retrievalStatus сообщает агенту, был ли результат поиска убедительным, пустым, устаревшим, противоречивым или недостаточно достоверным
answerPolicy указывает, может ли агент ответить, должен ли он оговорить ограничения, повторить поиск, запросить уточнение или отказаться от ответа
recommendedAction подсказывает следующий шаг до генерации ответа
quality, coverage, provenance и policy объясняют, на чём основана оценка результата
receiptId и traceId позволяют связать ответ с обращением к памяти в последующих журналах и при аудите

Правило для агента:

Если получен Retrieval Receipt, перед ответом проверьте answerPolicy. Не отвечайте уверенно, если значение этого поля — DO_NOT_ANSWER_CONFIDENTLY, REQUIRE_RETRY, REQUIRE_CLARIFICATION или DENY.

Работа со всей схемой

При запуске GrayMatter должен загружать актуальную OpenAPI-спецификацию ValkyrAI:

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

Так агент получает актуальную информацию о среде, в которой работает.

Это позволяет ему проверять, какие сущности и операции действительно доступны в текущем развёртывании, вместо того чтобы полагаться на устаревшие предположения.

Почему это важно

Большинство компаний — это не просто «память и чат».

В них есть структурированные операционные данные.

В текущей актуальной схеме, например, представлены:

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 настолько эффективен: агент может глубоко учитывать контекст компании и при этом не выходить за пределы предоставленных ему разрешений.

SwarmOps по-прежнему важен, но как часть графа объектов, отвечающая за координацию агентов: регистрацию, отслеживание и состояние протокола swarm для Codex/OpenClaw и других агентов. Для работы с бизнес-связями следует напрямую использовать более широкую схему, доступную в рамках RBAC.

Модель безопасности

GrayMatter обладает широкими возможностями, поскольку доступ к нему аутентифицирован и ограничен рамками арендатора.

При правильном использовании система также безопасна по своей архитектуре, поскольку:

доступ ограничен RBAC текущей учётной записи
разрешения пользователя и организации определяют, что агент может просматривать и изменять
об ошибках разрешений можно сообщать понятным образом
навык не должен предполагать, что ему доступно всё, только потому, что схема существует

Правило:

доступность схемы не означает разрешения использовать всё, что в ней описано

Содержимое репозитория

SKILL.md — инструкции OpenClaw AgentSkill
graymatter.skill — упакованный дистрибутив AgentSkill
scripts/graymatter_api.sh — транспорт для аутентифицированной работы с production API
scripts/gm-login — вспомогательный скрипт для входа
scripts/gm-activate — однократная начальная настройка: аутентификация, установка, регистрация агента и синхронизация схемы
scripts/gm-activation-fastlane — проверка готовности при первом запуске, однократная активация, телеметрия без секретов и безопасный для проверяющих запуск демонстрации
scripts/gm-mcp-launcher — проверка подписанного выпуска с ограничениями, аутентификация, условное обновление схемы, контроль повторного воспроизведения и корректная передача управления MCP через stdio
scripts/gm-schema-cache-lib — вспомогательные функции для идентификации кэша OpenAPI с учётом области действия, метаданных, актуальности и блокировок
scripts/gm-self-update — подготовка подписанного стабильного выпуска, атомарное переключение версий, состояние и блокировки с ключами, откат
scripts/gm-install-check — проверка зависимостей и готовности аутентификации
scripts/gm-doctor — полный отчёт о готовности самообновления, аутентификации, памяти, схемы, MCP, повторного воспроизведения и smoke-тестов
scripts/gm-smoke — production smoke-тест для проверки записи и запросов
scripts/gm-invariant-preflight — загрузка обязательных долговременных инвариантов перед планированием агента, изменениями или действиями, влияющими на production
scripts/gm-query — запросы к MemoryEntry
scripts/gm-read — чтение одного MemoryEntry по ID
scripts/gm-retrieval-receipt — создание, получение и просмотр Retrieval Receipts через 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 — матрица готовности для установки, чтения, поиска, записи, MCP, схемы и безопасных ответов в агентах на основе OpenClaw и Codex
scripts/gm-client — универсальная REST-обёртка для GET/POST/PUT/PATCH/DELETE-запросов к путям GrayMatter API
scripts/gm-entity — универсальный вспомогательный инструмент для просмотра списка, чтения и записи произвольных сущностей схемы
scripts/gm-record — вспомогательный инструмент для работы с записями стратегических приоритетов и KPI
scripts/gm-register-agent — регистрация или обновление сервера OpenClaw как Agent в api-0
scripts/gm-mcp-contract — создание переносимой схемы контракта MCP-инструментов для работы с памятью, используемой адаптерами агентов и IDE
scripts/gm-light-bootstrap — копирование и формирование локального пакета приложения GrayMatter и каркаса исходного кода сервера из шаблонов, совместимых с bash
scripts/gm-light-up — генерация и запуск локального экземпляра GrayMatter Light на базе ThorAPI
scripts/gm-light-env — вывод переменных окружения, направляющих скрипты навыка к работающему экземпляру Light
scripts/gm-light-smoke — проверка локального сценария Light: запись и запрос решения, а также проверка состояния памяти
scripts/gm-light-json-smoke — smoke-тест резервного сценария с JSON-файлом для проверки структуры данных Light без ThorAPI
scripts/package-local-server — упаковка отдельного архива GrayMatter Local Server для загрузки
scripts/package-graymatter — детерминированная проверка и упаковка
mcp-server/ — отдельный сервер HTTP/SSE и Apps SDK /mcp для инструментов GrayMatter: работа с памятью, проверка инвариантов перед выполнением, Retrieval Receipts, граф, сущности, схема и обзор
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 — основной контракт реализации управляемой агентной памяти, адаптивного поиска, временного графа, 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/* — рекомендации по выпускам и работе нескольких агентов, включая правила параллельного выполнения
references/mcp/memory-tool-contract.v1.json — стабильный переносимый контракт версии 1 для операций с памятью и графом
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 процесс должен выглядеть так:

GrayMatter открывает системное окно подключения macOS или Windows; пользователь выбирает Cloud, localhost или собственный сервер
Пароль вводится в защищённое системное поле, где символы скрыты
OpenClaw обменивает эти учетные данные на сессию
Сессии ValkyrAI/Cloud сохраняются в хранилище учетных данных; локальные учетные записи GrayMatter Lite — в отдельном файле учетных данных профиля
OpenClaw создает или обновляет собственную запись Agent в api-0
При последующих запусках GrayMatter автоматически получает сессию из системного хранилища учетных данных

Таким образом, для пользователя работа с GrayMatter должна сводиться к тому, чтобы:

один раз войти в систему
безопасно сохранить учетные данные
пользоваться сервисом, пока не потребуется обновить сессию

Временные сбои сети или сервера не должны приводить к удалению сохраненной сессии или повторному запросу пароля, создающему ложное впечатление, что авторизация потеряна. Только явный ответ 401 или 403 означает, что авторизацию при запуске нужно считать недействительной. В Windows слишком большие сессии сохраняются в Credential Manager в виде защищенных фрагментов, которые система объединяет прозрачно для пользователя. Благодаря этому длинные JWT не превышают ограничение размера отдельной записи.

Ручная работа с токенами предназначена для отладки и служит запасным вариантом, а не основным пользовательским сценарием.

Установка из репозитория

После клонирования репозитория запустите ./install.sh в macOS/Linux или .\install.ps1 в Windows PowerShell. Если Codex установлен, эти команды добавят marketplace репозитория и автоматически установят 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 входит в обязательную последовательность запуска. Подключаясь к api-0, сервер OpenClaw должен создать или обновить собственную запись 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-сервер обнаруживают истекшие сессии и при необходимости снова открывают защищенное окно авторизации; они никогда не сохраняют пароль для повторного использования в hosted-среде. При ошибке ревизии схемы или маршрута выполняется одна ограниченная попытка синхронизировать схему из сети и повторить запрос; во время сбоя кэшированная схема используется только для поиска данных. Операции записи, безопасные для повторного выполнения, которые заблокированы из-за кредитов, проблем с транспортом или временно недоступного контекста tenant, ставятся в локальную очередь. После восстановления разрешенного контекста tenant они автоматически повторяются при первом успешном авторизованном запросе. Для этого предусмотрены ограничение числа операций и блокировка процесса. scripts/gm-replay-deferred остается доступным для явного повтора отложенных операций.

После этого установка должна быть сразу готова к работе.

Если авторизация прошла успешно, но запрос к памяти временно ограничен из-за кредитов, scripts/gm-activate продолжает работу в ограниченном режиме: учетные данные сохраняются, агент регистрируется, OpenAPI синхронизируется, а скрипт сообщает, что запросы к памяти будут ограничены до появления доступных кредитов.

Для проверки приложения или первого запуска пользователем используйте ускоренный сценарий активации:

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

--check-only проверяет готовность установки, состояние среды выполнения и переносимый контракт инструментов MCP для работы с памятью. Эта опция не выполняет активацию и не записывает демонстрационные данные. --reviewer-demo запускает обычный процесс активации, а затем выполняет ограниченную демонстрацию: записывает и запрашивает пример MemoryEntry, читает граф, выводит сводку схемы и безопасный список сущностей MemoryEntry. Скрипт выводит в stderr события, не содержащие секретных данных, например activation_started, auth_completed, schema_synced, first_memory_written, first_query_succeeded, credit_warning_shown и activation_completed. Если задана переменная окружения GRAYMATTER_ACTIVATION_EVENT_LOG, события также добавляются в указанный в ней файл.

Настройка с сырым bearer-токеном предназначена для отладки и опытных пользователей. Стандартный сценарий первого запуска: войти в систему, безопасно сохранить учетные данные, проверить инструменты, записать и запросить демонстрационную запись в памяти, а затем перейти к дальнейшим действиям с учетом стартовых кредитов.

Чтобы получить отчет после установки одной командой, запустите:

scripts/gm-doctor

gm-doctor проверяет готовность самообновления, зависимости установки, состояние авторизации и keychain, состояние рабочих слоев памяти и графа объектов, синхронизацию OpenAPI, доступность контракта MCP, готовность к повтору отложенных операций и выполнение тестового сценария записи и запроса. Запустите scripts/gm-doctor --quick, если нужен такой же отчет без расходования кредитов на тестовый запрос.

Установка упакованного skill

Импортируйте или поместите graymatter.skill в каталог skills целевого экземпляра OpenClaw
Убедитесь, что распакованная папка находится по пути graymatter/
Запустите:

scripts/gm-activate

Если все проверки пройдены, skill готов к установке и использованию.

Критерии готовности новой установки

Установка GrayMatter считается готовой к запуску только в том случае, если новый пользователь может:

установить репозиторий или упакованный skill
успешно пройти авторизацию
пройти проверку установки
записать и запросить MemoryEntry
создать Retrieval Receipt для запроса к памяти и проверить answerPolicy
проверить состояние графа
зарегистрировать экземпляр OpenClaw как Agent в api-0
получить актуальную спецификацию OpenAPI и просмотреть ее сводку
просмотреть как минимум одно актуальное семейство сущностей из бизнес-схемы

Если хотя бы один из этих пунктов не выполняется, skill нельзя считать полностью готовым.

Интеграция GrayMatter в процесс начальной настройки 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

Получение данных с сохранением Retrieval Receipt:

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

Области видимости памяти

Используйте sourceChannel в качестве ключа области видимости для памяти, связанной с чатом, рабочим пространством или автоматизацией. gm-write может определить этот ключ по явно заданным полям области видимости или по локальному пути, а затем записывает в MemoryEntry.text компактный заголовок [graymatter-scope]. Благодаря этому иерархию можно проверить даже при недоступности тегов.

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. Для папок проектов Codex внутри Documents/Codex// значение sourceChannel будет codex:workspace:/. Если хост может предоставить более точные идентификаторы, чем путь к файлу, используйте --chat-key, --session-key, --workspace-key или --automation-id.

Запись с тегами и автоматическим резервным режимом

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

Если на backend не удаётся сохранить теги, скрипт повторяет запись без них, вместо того чтобы прерывать операцию.

Если вызов API всё равно завершается ошибкой, gm-write добавляет попытку записи в memory/graymatter-fallback.json, если доступен scripts/gm-fallback-append.

Активация одной командой

scripts/gm-activate

Это рекомендуемая точка входа для установки и первоначальной настройки OpenClaw.

Регистрация агента

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
поиск VALKYR_AUTH в macOS Keychain, Windows Credential Manager или Linux Secret Service
VALKYR_AUTH_TOKEN в качестве расширенного переопределения для отладки, а не обычного способа активации
VALKYR_JWT_SESSION в качестве совместимого резервного значения для переменных среды, используемого последующими инструментами

Рекомендуемый процесс авторизации:

сначала проверить наличие VALKYR_AUTH в хранилище учётных данных платформы
если значение найдено, использовать его автоматически
в противном случае один раз запросить имя пользователя и пароль
обменять их на токен VALKYR_AUTH
сохранить только этот токен и имя пользователя в защищённом хранилище учётных данных платформы для последующих запусков

Пароли для Hosted/ValkyrAI никогда не сохраняются; локальные профили GrayMatter Lite используют закрытые файлы учётных данных. При первом запуске плагина на macOS и Windows автоматически открывается системное окно входа, в том числе если у MCP-хоста нет интерактивного терминала. Для регистрации и восстановления учётной записи используются специальные страницы сайта, после чего пользователь возвращается в ещё открытое системное окно подключения. При обычном сохранении сеанса не используются перенаправление из браузера или токен из буфера обмена.

Не храните секреты в репозитории или skill.

Не выводите токены.

Не делайте ручное управление токенами обычным способом работы для пользователей.

Резервный режим с локальным хранилищем

Если 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

Поведение CLI при INSUFFICIENT_FUNDS:

выводит ссылки для покупки кредитов и регистрации в stderr
пытается показать всплывающее окно в macOS (osascript) и Windows (powershell.exe)
если инструменты для показа всплывающего окна недоступны, в качестве крайней меры открывает URL для покупки кредитов

Необязательные переопределения для пользовательских развёртываний:

VALKYR_BUY_CREDITS_URL
VALKYR_HUMAN_SIGNUP_URL
VALKYR_HUMAN_RECOVERY_URL

Если у нового аккаунта баланс равен 0.00, активация всё равно может пройти, и операции чтения и записи будут доступны. Запросы останутся недоступны до начисления кредитов.

Вход выполнен, но сессия не найдена

В некоторых развёртываниях api-0 возвращает данные авторизации в заголовках или cookies, а не в теле JSON-ответа.

Решение:

используйте актуальную версию scripts/gm-login
теперь скрипт использует VALKYR_AUTH как основной механизм авторизации
последующие вызовы API передают полученный токен как bearer-токен, VALKYR_AUTH и данные авторизации в cookies

Не удаётся загрузить OpenAPI

Проверьте:

доступ к исходящей сети
доступность api-0
не блокирует ли среда конечную точку документации

Если загрузить актуальную документацию не удаётся, временно используйте последнюю кэшированную копию, но учитывайте, что она может быть устаревшей.

Не удаётся определить причину сбоя

Выполните:

scripts/gm-doctor --verbose

Команда doctor выполняет все проверки до конца и сообщает о точной причине каждой ошибки или предупреждения, не останавливаясь при первой неисправной зависимости. Перед изменением авторизации, кредитов, конфигурации MCP или локальных файлов плагина рекомендуется сначала запустить именно её.

Сборка пакета

Генерация GrayMatter Lite и обратная совместимость

До этого этапа разработки дистрибутива режим Light был полезен, но недостаточно строго соответствовал api-0, чтобы служить его прямой заменой:

в локальной документации и пакетах использовались пути без префикса, например /MemoryEntry и /SwarmOps/graph
написанная вручную OpenAPI-спецификация для Light могла расходиться с целевой моделью GrayMatter
для работы упакованного сервера требовалась установленная в системе среда выполнения Java, если только оператор не предоставлял её самостоятельно
не было единой команды, которая проверяла бы локальную запись, запросы, состояние сервера и готовность к работе с MCP

После этого этапа режим Light соответствует структуре api-0:

VALKYR_API_BASE=http://localhost:/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

Пересоберите упакованный skill командой:

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, контрактом ThorAPI FEBE OpenAPI, пользовательскими компонентами панели управления, рабочей среды, продвижения и swarm, а также ссылками на встроенные компоненты rbac-core и data-workbooks
source/ со сгенерированным локальным сервером Spring Boot
bin/graymatter-local-server — скрипт запуска
lib/graymatter-local-server.jar, если во время сборки доступен Maven
runtime/, если во время сборки доступен jlink, чтобы в обычном сценарии пользователям не приходилось устанавливать Java вручную

Встроенная панель управления использует оформление Valkyr Labs, скрывает локальную панель входа после успешной авторизации, показывает ссылки для активации и пополнения через облачный мост valkyrlabs.com и отображает состояние локального графа swarm-ops через пути /v1, соответствующие производственной структуре.

Пакет материалов для публикации в awesome-codex-plugins

В GrayMatter входит готовый пакет материалов для отправки в awesome-codex-plugins.

Блок markdown для публикации: docs/awesome-codex-plugins.md
Исходные метаданные: .codex-plugin/plugin.json

Быстро скопировать материалы можно командой:

cat docs/awesome-codex-plugins.md

Затем создайте PR в hashgraph-online/awesome-codex-plugins и вставьте сгенерированный блок в README.md, соблюдая правила оформления материалов для этого репозитория.

Цели запуска

Цель запуска проста:

GrayMatter устанавливается как skill для OpenClaw без лишних сложностей
OpenClaw запускается с приоритетом на работу с памятью GrayMatter
при запуске агент загружает актуальную схему OpenAPI
агент понимает как долговременную память, так и более широкий граф объектов организации
файловая память остаётся резервной, а не основной

Именно такую версию GrayMatter стоит выпускать.

GrayMatter

Выберите размещённую или локальную память

Установите локальный Lite одной командой

Docker

Что входит в состав

Профили и объединённая память

Локальные модели

Импорт, экспорт и стартовые знания

Valkyr SWARM

Документация и сообщество

Платформа GrayMatter: интеллект для всего вашего бизнеса

Система памяти, которая действительно учитывает контекст

Гибридный поиск: по ключевым словам, векторам, графу и структурированным данным

Векторный интеллект на базе PostgreSQL

Полноценный граф знаний на основе ThorAPI

SageChat и обработка документов

Плагины, навыки и MCP: интеллект повсюду

Кредиты для реальных задач с ИИ

Безопасность заложена в основу

Результат

Приложение для ChatGPT в режиме разработчика

Варианты поставки

Быстрый старт

Для чего нужен GrayMatter

Модель основной памяти

Целевые типы долговременной памяти

Retrieval Receipts

Работа со всей схемой

Почему это важно

Модель безопасности

Содержимое репозитория

Установка

Регистрация учётной записи и кредиты

Первая авторизация: рекомендуемый сценарий OpenClaw

Установка из репозитория

Установка упакованного skill

Критерии готовности новой установки

Интеграция GrayMatter в процесс начальной настройки OpenClaw

Примеры использования

Долговременная память

Области видимости памяти

Запись с тегами и автоматическим резервным режимом

Активация одной командой

Регистрация агента

Состояние графа

Синхронизация актуальной схемы

Доступ к произвольным сущностям схемы

Авторизация

Рекомендации по работе в OpenClaw

Резервный режим с локальным хранилищем

Устранение неполадок

VALKYR_AUTH_TOKEN is required

jq: command not found

Не удаётся выполнить запись с тегами

Ошибка кредитов или оплаты при выполнении запроса

Вход выполнен, но сессия не найдена

Не удаётся загрузить OpenAPI

Не удаётся определить причину сбоя

Сборка пакета

Генерация GrayMatter Lite и обратная совместимость

Пакет материалов для публикации в awesome-codex-plugins

Цели запуска

`VALKYR_AUTH_TOKEN is required`

`jq: command not found`