Arra Memory Lab

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

Развертывание создает один Worker, автоматически подготавливает его базу данных D1 из wrangler.jsonc и запускает включенные миграции через скрипт развертывания. Workers AI предоставляет 768-мерные эмбеддинги @cf/google/embeddinggemma-300m.

Что это демонстрирует

• Уровни авторитетности: воспоминания являются авторитетными; фрагменты/эмбеддинги и наблюдения являются производными.

• Честный поиск: каждый поиск сообщает запрошенный режим, фактический режим, деградацию и происхождение ранжирования.

• Происхождение доказательств: наблюдения сохраняют идентификаторы исходных воспоминаний, ревизии и хэши.

• Безопасное изменение: забывание и перестроение выполняются сначала в режиме предварительного просмотра; подтверждение забывания привязано к точному снимку предварительного просмотра, а подтвержденная работа по перестроению ограничена.

• Минимизация данных: новейшие 100 трасс поиска содержат операционные метаданные, но никогда не содержат содержимое запросов или воспоминаний.

• Поиск, связанный с трассами: поиск возвращает traceId, когда сохранение трассы успешно; снимки ранжированных результатов сохраняют только идентификатор воспоминания, происхождение ранга/оценки, исходную ревизию и исходный хэш.

• Явное замещение: supersedesMemoryId разрешается один раз при записи в неизменяемый снимок идентификатора/ревизии/хэша. Он не выводит временной граф.

• Малый объем происхождения: project, sourcePath и createdBy являются структурированными полями; идентичность Oracle остается тегом oracle-<name>. retrospective и cheatsheet являются полноценными видами воспоминаний.

Хэш queryHash трассы является корреляционным дескриптором, а не анонимизацией — особенно для запросов с низкой энтропией, — поэтому доступ к трассам остается защищенным, даже если исходный запрос и содержимое воспоминаний опущены.

Related MCP server: Ghostkeep

Идентичность релиза

package.json является единственным источником истины для календарного версионирования лаборатории в Бангкоке: YY.M.D-alpha.HMM, где HMM = час × 100 + минута в Asia/Bangkok. Сборка внедряет только эту строку в публичный клиент; /api/info, MCP initialize, инструмент lab_info и нижний колонтитул интерфейса сообщают одно и то же значение.

npm run version:next   # preview the next available Bangkok minute
npm run version:bump   # update package.json + package-lock.json, no commit/tag
npm run version:check  # fail if format or lock metadata drift

Команда bump отклоняет повторное использование в ту же минуту, откат часов, неизвестные флаги и любой CalVer, не новее существующих тегов arra-memory-lab-v*.

Это намеренно не является производственной схемой идентичности или аренды. Частный веб-API использует один секрет владельца в качестве bearer-токена. Удаленный канал MCP использует OAuth 2.1, S256 PKCE, динамическую регистрацию клиентов (DCR), истекающие токены доступа и токены обновления, чтобы Claude.ai и другие веб-MCP-клиенты могли подключаться без хранения парольной фразы владельца. Арендаторы, очереди, ANN-индексы и автономная консолидация остаются отложенными.

Поток данных и граница конфиденциальности

• Создание воспоминания пытается выполнить эмбеддинг по мере возможности после успешной записи источника в D1.

• Семантический/гибридный поиск отправляет текст запроса в Workers AI.

• Подтвержденное перестроение отправляет выбранные фрагменты заголовка/содержимого воспоминания в Workers AI и записывает производные векторы в D1.

• Поиск по ключевым словам и предварительные просмотры перестроения не вызывают Workers AI.

• D1 хранит авторитетный текст плюс производный текст/векторы фрагментов; трассы поиска и ссылки на результаты хранят только хэши, идентификаторы, ранги, оценки и операционные метаданные.

Используйте синтетические или нечувствительные данные, если политика вашей учетной записи Cloudflare и модель угроз явно не разрешают такую обработку. В локальной разработке привязка Workers AI по-прежнему обращается к удаленному сервису и может привести к расходам.

Развертывание

1. Нажмите Deploy to Cloudflare выше и авторизуйте развертывание репозитория.

2. Форма развертывания Cloudflare запрашивает LAB_ACCESS_TOKEN. Укажите длинное случайное значение (например, сгенерированное с помощью openssl rand -hex 32); Cloudflare хранит его как секретную привязку. Это же значение разблокирует API браузера и одобряет новых OAuth-клиентов, но OAuth-клиенты никогда его не получают.

3. Разверните. Скрипт развертывания репозитория автоматически применяет миграции D1 перед сборкой и публикацией Worker.

4. Откройте URL Worker. Введите тот же токен один раз; браузер хранит его только в sessionStorage, поэтому закрытие сеанса браузера очищает его.

Если форма развертывания или автоматический шаг миграции требует ручного восстановления, используйте эквивалентный запасной вариант через CLI:

printf '%s' 'replace-with-a-long-random-token' | npx wrangler secret put LAB_ACCESS_TOKEN
npx wrangler d1 migrations apply DB --remote

Для проверенного релиза не редактируйте идентификаторы-заглушки в wrangler.jsonc. Помощник релиза сначала собирает и тестирует, разрешает ровно одну базу данных D1 с именем arra-memory-lab и одно пространство имен KV с именем arra-memory-lab-oauth, записывает их идентификаторы только во временный конфиг с режимом 0600, применяет миграции, а затем развертывает ту же неизменяемую сборку:

npm run deploy:dry-run
npm run deploy

Частные маршруты /api/* требуют Authorization: Bearer $LAB_ACCESS_TOKEN. /mcp принимает только токены доступа, выданные OAuth-провайдером лаборатории; сам секрет владельца там отклоняется. OAuth-обнаружение, DCR, обмен токенами и интерфейс одобрения находятся в /.well-known/*, /oauth/* и /authorize. Только GET /api/info является публичным содержимым приложения. Если LAB_ACCESS_TOKEN отсутствует, частный доступ к API и одобрение OAuth завершаются с отказом.

Ответ согласия намеренно опускает CSP form-action: встроенные OAuth-браузеры, используемые реальными MCP-хостами, блокировали отправку даже с точным списком разрешенных источников. Цель формы — фиксированный относительный /authorize; base-uri 'none' предотвращает переписывание базовой цели, каждое поле, полученное из DCR, экранируется в HTML, а путь POST повторно анализирует состояние PKCE/областей/клиента перед тем, как OAuth-провайдер проверит и завершит перенаправление. Это измеренная граница совместимости, а не общая рекомендация по CSP.

Почему D1 для развертывания в один клик?

D1 используется потому, что поток развертывания Cloudflare может автоматически подготовить и привязать его, что делает эту лабораторию действительно близкой к одному клику. Компромисс — намеренная привязка к провайдеру: эта версия не демонстрирует переносимый уровень базы данных или развертывание Turso/libSQL. Это приемлемо для узкоспециализированной лаборатории Cloudflare, а не общая рекомендация для производства.

Локальная разработка

Требуется Node.js для установки/сборки/развертывания, Bun для тестов/скриптов проверки и учетная запись Cloudflare для Workers AI. Wrangler предупреждает, потому что привязка AI остается удаленной, даже когда Worker и D1 работают локально.

cd labs/arra-memory-lab
npm install
cp .env.example .dev.vars
# Set LAB_ACCESS_TOKEN in .dev.vars
npx wrangler d1 migrations apply DB --local
npm run dev

Проверки качества:

npm run typecheck
npm test
npm run build
# or all three:
npm run check

Хук postbuild удаляет файлы .env* и .dev.vars* из dist/. Это защита в глубину для локальных артефактов; манифест развертывания Wrangler не загружает эти файлы разработки.

Примеры HTTP

export LAB_URL='https://arra-memory-lab.<account>.workers.dev'
export LAB_ACCESS_TOKEN='your-long-random-token'
export AUTH="Authorization: Bearer $LAB_ACCESS_TOKEN"

# Public capability disclosure
curl "$LAB_URL/api/info"

# Create an authoritative memory (indexing is best effort)
curl -X POST "$LAB_URL/api/memories" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"title":"Prefer explicit authority","content":"Memories are sources; embeddings are projections.","kind":"retrospective","tags":["architecture"],"project":"github.com/soul-brews-studio/claude-ai-mcp-poc","sourcePath":"ψ/memory/retrospectives/example.md","createdBy":"rrr","oracleName":"neo","supersedesMemoryId":"OPTIONAL_EXISTING_MEMORY_ID"}'

# Hybrid recall exposes requested/effective modes and rank provenance
curl -X POST "$LAB_URL/api/search" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"query":"Which data is authoritative?","mode":"hybrid","project":"github.com/soul-brews-studio/claude-ai-mcp-poc","limit":8}'

# Preview a forget and retain the returned expected* fields
curl -X POST "$LAB_URL/api/memories/MEMORY_ID/forget" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":false}'

# Confirm only that exact preview. A changed source/impact returns 409 stale_preview.
curl -X POST "$LAB_URL/api/memories/MEMORY_ID/forget" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":true,"expectedRevision":1,"expectedHash":"COPY_FROM_PREVIEW","expectedChunks":0,"expectedObservationCount":0}'

# Preview a bounded rebuild; confirmed work is capped at 10 memories / 256 chunks
curl -X POST "$LAB_URL/api/index/rebuild" -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"confirm":false}'

MCP

Лаборатория предоставляет stateless Streamable HTTP MCP на /mcp. Токен с обеими заявленными областями получает следующие инструменты:

lab_info, remember, recall, observe, forget, rebuild_index, memory_stats, trace_list, trace_get.

lab_info всегда присутствует для действительного токена. memory:read управляет recall, memory_stats, trace_list и trace_get; memory:write управляет remember, observe, forget и rebuild_index. Проверки областей используют развернутую область токена доступа для каждого stateless-запроса, включая понижение области при использовании токена обновления.

Реализация закрепляет @modelcontextprotocol/server@2.0.0 и использует обертку createMcpHandler от Cloudflare Agents. «SDK v2» и «версия протокола» — это отдельные оси: конечная точка обслуживает современные запросы 2026-07-28 и сохраняет поток initialize эпохи 2025 года как stateless-совместимый канал. Ни один канал не создает Mcp-Session-Id; каждый запрос получает новый экземпляр сервера. См. docs/mcp-v2-stateless.md для матрицы доказательств.

Подключение или перезагрузка MCP-клиента

npm run mcp:connect -- codex "$LAB_URL/mcp" arra-memory-lab
# or Claude Code:
npm run mcp:connect -- claude "$LAB_URL/mcp" arra-memory-lab

Помощник регистрирует URL и запускает OAuth-вход клиента. Повторный запуск обновляет путь регистрации/входа. Для Claude.ai откройте Settings → Connectors → Add custom connector, введите только https://…/mcp, нажмите Connect и введите парольную фразу лаборатории на странице одобрения.

Bearer против OAuth

См. docs/provenance-oauth-report.md для измеренного решения и очищенных доказательств.

Контракты отказа

• Авторитетные записи воспоминаний переживают сбои эмбеддинга.

• Гибридный поиск деградирует только при сбоях провайдера эмбеддинга и сообщает причину.

• Явный семантический поиск завершается ошибкой, если семантический вывод недоступен.

• Ошибки базы данных/векторов не помечаются как запасной вариант ИИ.

• Сбои записи трассы никогда не изменяют успешный поиск и не маскируют его исходную ошибку.

• Завершенная трасса, ссылки на ранжированные результаты и очистка по сроку хранения выполняются в одном пакете D1; сохранение трассы остается отказоустойчивым относительно поиска.

• Забывание воспоминания не стирает исторические снимки результатов трасс или замещений; очистка трассы каскадно удаляет ее ранжированные ссылки.

• Перестроение повторно проверяет исходную ревизию/хэш перед заменой производных фрагментов.

• Подтверждение забывания требует ревизию, хэш, количество фрагментов и количество наблюдений, возвращенные его предварительным просмотром; устаревшее подтверждение завершается ошибкой HTTP 409 / stale_preview.

См. CONTRACT.md для текущей границы выполнения и DESIGN.md для системы интерфейса.

Основные ссылки на платформу

• Кнопки развертывания Cloudflare и автоматическое выделение ресурсов

• Конфигурация привязки Cloudflare D1

• Привязки Cloudflare Workers AI

• OAuth-провайдер Cloudflare для удаленного MCP

• Аутентификация удаленного MCP-коннектора Anthropic

• Контракт модели EmbeddingGemma 300M

• Drizzle ORM с Cloudflare D1