Arra Memory Lab

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

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

Что здесь демонстрируется

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

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

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

• Безопасные изменения: forget и rebuild сначала выполняются в режиме dry-run; подтверждение forget привязано к точному снапшоту предпросмотра, а подтверждённый объём работы rebuild ограничен.

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

Поле queryHash в журнале — это корреляционный идентификатор, а не анонимизация, особенно для низкоэнтропийных запросов; поэтому доступ к журналам остаётся защищённым, даже несмотря на то, что исходный запрос и содержимое памяти из них исключены.

Это намеренно не продакшен-решение для идентификации или мультитенантности. Здесь используется один bearer-токен, без него доступ закрывается (fail closed), а OAuth/DCR, тенанты, очереди, ANN-индексы и автономная консолидация вынесены за рамки лаборатории.

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

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

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

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

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

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

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

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

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

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

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

API и /mcp требуют заголовок Authorization: Bearer $LAB_ACCESS_TOKEN. Публичным является только GET /api/info, и он раскрывает архитектуру и возможности, а не содержимое корпуса. Если LAB_ACCESS_TOKEN отсутствует, защищённый доступ закрывается.

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

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

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

Для установки, сборки и развёртывания требуется Node.js, для тестовых и проверочных скриптов — Bun, а для Workers AI — учётная запись Cloudflare. 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":"decision","tags":["architecture"]}'

# 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","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

Лаборатория предоставляет MCP-сервер без сохранения состояния по протоколу Streamable HTTP на /mcp со следующими инструментами:

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

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

Проверка MCP-эндпоинта через curl

curl -X POST "$LAB_URL/mcp" \
  -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Конфигурация MCP-клиента

Для клиентов, поддерживающих серверы Streamable HTTP:

{
  "mcpServers": {
    "arra-memory-lab": {
      "type": "http",
      "url": "https://arra-memory-lab.<account>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${LAB_ACCESS_TOKEN}"
      }
    }
  }
}

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

Контракты при сбоях

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

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

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

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

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

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

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

Зафиксированную границу v1 см. в CONTRACT.md, а для описание UI-системы — в DESIGN.md.

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

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

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

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

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

• Drizzle ORM с Cloudflare D1