Архитектура RAG — self-hosted семантический поиск

Статус: работает с Phase 71 (2026-06-05). Заменяет мост Google NotebookLM, выпущенный в Phase 36.

TL;DR: вики + задачи + скиллы каждого проекта Arc эмбеддятся в пер-проектный векторный индекс, живущий внутри существующего SQLite SSOT. Запросы возвращают семантически релевантные пассажи по контенту проекта + общему глобальному пулу скиллов. Никакого внешнего retrieval-сервиса, никакой пер-пользовательской Google-сессии, никаких лимитов на источники.

1. Почему мы ушли с NotebookLM

Мост Phase 36 оборачивал Google NotebookLM как векторное хранилище через reverse-engineered cookie-аутентификацию. Это породило две проблемы, которые сам продукт исправить не может:

1. Лимит источников. NotebookLM Plus ограничен 100 источниками на ноутбук. К середине 2026 несколько проектов Arc давно превысили лимит; логика вытеснения превратилась в перманентный костыль (#324).
2. Привязка к личному аккаунту. Каждый новый проект создавал ноутбук внутри личного NotebookLM CEO. Масштабирование до N клиентов означало N ноутбуков в чьём-то одном сайдбаре — неуправляемый побочный эффект, который мост не мог развязать.

Phase 71 заменяет слой ретривала self-hosted пайплайном, который никогда не касается Google-аккаунта пользователя.

2. Карта компонентов

                Write path                          Read path
                ──────────                          ─────────
 wiki.ts handleWikiSave ────┐                 chat.ts executeAskNotebooklm ──┐
 cli-routes.ts handleCreate/                                                 │
   UpdateIssue ─────────────┤              shared/routes/rag-search.ts ──────┤
 skills.ts handleSave/      │                 GET /api/crm/projects/:name/   │
   Delete + global CRUD ────┤                 rag/search                     │
                            │                                                │
                            ▼                                                ▼
              shared/rag-hooks.ts                              shared/rag.ts search()
                syncIssue / syncWiki /                            │  embeds query →
                syncSkill (fire-and-forget)                       │  KNN over vec0 →
                            │                                     │  project + doc_type filter
                            ▼                                     │  → top-K passages
              shared/rag.ts upsert()                              │
                paragraph-aware chunker (~1800 chars)              │
                  → atomic transaction:                            │
                       embeddings ⨯ embeddings_vec                 │
                            │                                     │
                            ▼                                     │
              shared/embeddings.ts ◄────────────────────────────  │
                Cohere embed-multilingual-v3.0                    │
                (1024-dim float32, batch ≤96 inputs/call)         │
                            │                                     │
                            ▼                                     │
              SQLite (data/citadel.db)  ◄──────────────────────── ┘
                 ┌──────────────────────┐   ┌─────────────────────┐
                 │ embeddings           │   │ embeddings_vec      │
                 │ (project, doc_type,  │   │ (vec0 virtual,      │
                 │  doc_id, chunk_ix,   │   │  embedding FLOAT    │
                 │  text, created_at)   │ ──┤  [1024])            │
                 │ id ←→ rowid          │   │                     │
                 └──────────────────────┘   └─────────────────────┘

2.1 Модули в одной таблице

3. Выбор эмбеддингов — Cohere embed-multilingual-v3.0

Живой кросс-языковой смоук по prod-корпусу:

UK-запрос обошёл соответствующую EN-EN дистанцию — выравнивание мультиязычного подпространства реально, а не маркетинговое заявление.

4. Хранение — sqlite-vec внутри SSOT

Миграция 049_embeddings создаёт две таблицы:

CREATE TABLE embeddings (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  project     TEXT NOT NULL,
  doc_type    TEXT NOT NULL,         -- 'wiki' | 'issue' | 'skill' | 'transcript'
  doc_id      TEXT NOT NULL,         -- filename, issue id, skill name
  chunk_ix    INTEGER NOT NULL DEFAULT 0,
  text        TEXT NOT NULL,
  created_at  TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE VIRTUAL TABLE embeddings_vec USING vec0(
  embedding FLOAT[1024]
);
-- embeddings.id ←→ embeddings_vec.rowid

Разделение держит метаданные в обычном SQLite (джойнятся с таблицами wiki/issues/skills, простые LIST/DELETE), а виртуальная таблица vec0 хранит плотные векторы для ANN-поиска.

Размеры. 1024-dim float32 = 4096 байт на строку. 100K строк ≈ 400МБ. Нормально для текущего масштаба; пересмотреть при 1M+ строк.

Загрузка. sqlite-vec загружается как runtime-расширение в shared/db.ts initDb() до выполнения миграций. Миграция 049 проверяет vec_version() и чисто прерывается, если расширение не загрузилось.

5. Путь записи — хуки переэмбеддинга (Phase 71.5)

Каждая поверхность записи, мутирующая индексируемый контент, вызывает fire-and-forget хук, чтобы эмбеддинг оставался свежим без отдельной задачи синхронизации.

Правило: ошибки Cohere печатают одну строку и умирают. Они никогда не откатывают диск/SQL-запись, которая их вызвала. Устойчивые сбои сходятся обратно через ночной бэкфилл, а не через ретраи в горячем пути.

6. Путь чтения — search() + фасады по поверхностям

import { search } from "shared/rag";

const hits = await search("arc-v2", "How does the multi-tenancy gate work?", {
  k: 6,
  doc_types: ["wiki", "issue", "skill", "transcript"], // optional narrow
});
// hits: Array<{ doc_type, doc_id, chunk_ix, text, distance }> sorted by distance

Под капотом:

1. Эмбеддинг запроса с input_type="search_query" (другое подпространство, чем search_document).
2. KNN по embeddings_vec с перевыборкой k * 4.
3. Фильтр по проекту + опциональному doc_type на SQL JOIN.
4. Возврат top-K пассажей, отсортированных по возрастанию L2-дистанции.

Публичные фасады

• GET /api/crm/projects/:name/rag/search?q=...&k=...&include_global=true&doc_types=... — HTTP-точка входа. Питает arc kb search + инструмент ask_notebooklm в чате.
• chat.ts executeAskNotebooklm — выполняет поиск по проекту + глобально параллельно, мержит по дистанции, фолбэк на keyword-поиск при топ-хите d > 1.6 или нуле результатов.
• skills.ts handleGenerateSkill — использует RAG как ретривал house-style, затем вызывает Claude Sonnet для генерации.
• help.ts ragSemantic — чат Arc Help подаёт проектные + глобальные хиты как контекст модели.

7. Бэкфилл — scripts/phase-71-backfill-rag.ts

bun scripts/phase-71-backfill-rag.ts                       # all projects + global
bun scripts/phase-71-backfill-rag.ts --dry-run             # inventory only
bun scripts/phase-71-backfill-rag.ts --project arc-v2      # one project + global
bun scripts/phase-71-backfill-rag.ts --skip-global         # projects only
bun scripts/phase-71-backfill-rag.ts --doc-types wiki,issue
bun scripts/phase-71-backfill-rag.ts --force               # re-embed even if row exists
bun scripts/phase-71-backfill-rag.ts --limit 100           # cap docs per project
bun scripts/phase-71-backfill-rag.ts --throttle 700        # ms between Cohere calls (default 700; set 0 on Production keys)

Идемпотентность. Каждый кандидат проверяется на наличие (project, doc_type, doc_id) в embeddings и пропускается, если найден, кроме случая с --force. Повторные запуски не стоят ничего по квоте Cohere.

Production-прогон (2026-06-05). 814 кандидатов в 20 проектах + _global_ (37 wiki + 482 issue + 295 skill). Первый проход сжёг месячный лимит Trial в 1000 вызовов на глобальных скиллах. После апгрейда до Production-ключа оставшиеся 178 документов завершились за 57 с без ошибок. Всего записано чанков: ~3 150.

8. Границы безопасности

• API-ключ Cohere живёт в vault (COHERE_API_KEY), ротируется через Platform Settings → RAG / Semantic search. Живая кнопка Test выполняет 1-токенный embed-вызов для проверки доступности.
• Никакой утечки промптов в Cohere. Эмбеддинги — производные bag-of-words; восстановить из них исходный текст непрактично. Политика самой Cohere заявляет, что они не обучаются на API-трафике.
• Multi-tenancy. Имена проектов — ключи неймспейсов; canAccessProject охраняет /api/crm/projects/:name/* до запуска обработчика поиска. Глобальные скиллы живут в сентинельном неймспейсе _global_, с которым не может коллидировать ни одно имя пользовательского проекта (валидатор запрещает имена, начинающиеся с _).
• GDPR ст. 17. DELETE /api/auth/account каскадно вызывает rag.removeProject для каждого собственного проекта, чтобы эмбеддинги не пережили удаление.

9. Миграция с NotebookLM (одноразовая, 2026-06-05)

10. Эксплуатационные заметки

• Имя инструмента осталось ask_notebooklm. Определение инструмента Anthropic уходит вниз по потоку к Claude в диалоге Cloud PM. Переименование сломало бы in-flight циклы tool_use. Реализация теперь — чистый RAG; публичный контракт остался стабильным.
• Audio overview исчез. Автогенерируемые аудио-саммари NotebookLM не имеют эквивалента в self-hosted пайплайне. POST /api/crm/projects/:name/memory/fetch-artifact теперь возвращает 410 Gone. Если это понадобится снова — это отдельная фаза (вероятно, Whisper TTS-проход по вики проекта).
• Кнопка переиндексации всё ещё работает. POST /api/crm/projects/:name/memory/refresh теперь переэмбеддит MANIFEST.md + ROADMAP.md + ключевые файлы в локальное хранилище embeddings, а не загружает в NotebookLM. Для пользователя: та же кнопка, тот же результат («знания проекта обновлены»), другое хранилище.
• Никаких URL ноутбуков. GET /api/crm/projects/:name/notebooks возвращает { notebooks: [], retired: "phase-71.8" }, чтобы старые сборки фронтенда не падали с 404. Вкладка Neural Memory в CRM будет убрана в последующем косметическом проходе.

11. Ссылки

• shared/embeddings.ts, shared/rag.ts, shared/rag-hooks.ts, shared/routes/rag-search.ts
• shared/migrations/049_embeddings.ts, shared/migrations/050_drop_notebook_id.ts
• scripts/phase-71-backfill-rag.ts
• Задачи #321 (родительская) · #358–#367 (подфазы) · #322 / #324 (закрыты вместе)
• Журнал решений: docs/architecture/PHASE_71_RAG_MIGRATION.md