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

Статус: працює з Phase 71 (2026-06-05). Замінює міст Google NotebookLM, який з'явився у Phase 36.

TL;DR: wiki + issues + skills кожного проєкту Arc вбудовуються (embeddings) у векторний індекс per-project, що живе всередині існуючого SQLite SSOT. Запити повертають семантично релевантні фрагменти з контенту проєкту + спільного глобального пулу skills. Жодного зовнішнього retrieval-сервісу, жодної Google-сесії на користувача, жодних лімітів на джерела.

1. Чому ми пішли з NotebookLM

Міст із Phase 36 обгортав Google NotebookLM як векторне сховище через reverse-engineered cookie auth. Це породило дві проблеми, які базовий продукт виправити не може:

1. Ліміт джерел. NotebookLM Plus обмежений 100 джерелами на notebook. До середини 2026 кілька проєктів Arc вилетіли за ліміт; логіка витіснення перетворилася на перманентну милицю (#324).
2. Прив'язка до особистого акаунта. Кожен новий проєкт створював notebook усередині особистого NotebookLM CEO. Масштабування до N клієнтів означало N notebooks у сайдбарі однієї людини — некерований побічний ефект, який міст не міг розв'язати.

Phase 71 замінює retrieval-шар на 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. Вибір embedding-моделі — Cohere embed-multilingual-v3.0

Live крос-мовний smoke на 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 рядків ≈ 400MB. На поточному масштабі ок; переглянути при 1M+ рядків.

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

5. Write path — хуки re-embed (Phase 71.5)

Кожна поверхня запису, що змінює індексований контент, запускає fire-and-forget хук, тож embedding залишається свіжим без окремої sync-задачі.

Правило: помилки Cohere друкують один рядок і вмирають. Вони ніколи не відкочують disk/SQL-запис, що їх спричинив. Сталі збої сходяться через нічний backfill, а не через retry у hot path.

6. Read path — 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 з overfetch 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-пошуку, коли top hit d > 1.6 або нуль результатів.
• skills.ts handleGenerateSkill — використовує RAG для retrieval house-style, потім викликає Claude Sonnet для генерації.
• help.ts ragSemantic — чат Arc Help подає проєктні + глобальні збіги як контекст моделі.

7. Backfill — 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 викликів на глобальних skills. Після переходу на Production-ключ решта 178 документів завершилася за 57 с без жодної помилки. Усього записано чанків: ~3 150.

8. Межі безпеки

• API-ключ Cohere живе у vault (COHERE_API_KEY), ротується через Platform Settings → RAG / Semantic search. Жива кнопка Test виконує 1-токенний embed-виклик для перевірки доступності.
• Жодного витоку промптів у Cohere. Embeddings — це похідні bag-of-words; відновити з них вихідний текст практично неможливо. Власна політика Cohere каже, що вони не тренуються на API-трафіку.
• Multi-tenancy. Імена проєктів — це ключі неймспейсів; canAccessProject охороняє /api/crm/projects/:name/* до запуску пошукового хендлера. Глобальні skills живуть у sentinel-неймспейсі _global_, з яким не може колізувати жодне ім'я проєкту користувача (валідатор забороняє імена, що починаються з _).
• GDPR Art. 17. DELETE /api/auth/account каскадно викликає rag.removeProject для кожного власного проєкту, тож embeddings не переживають видалення.

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

10. Операційні нотатки

• Ім'я інструмента залишилось ask_notebooklm. Tool definition 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 прохід по wiki проєкту).
• Кнопка Re-index досі працює. POST /api/crm/projects/:name/memory/refresh тепер повторно вбудовує MANIFEST.md + ROADMAP.md + ключові файли у локальне сховище embeddings, а не завантажує у NotebookLM. Для користувача: та сама кнопка, той самий результат ("project knowledge is now fresh"), інше сховище.
• Жодних notebook URLs. GET /api/crm/projects/:name/notebooks повертає { notebooks: [], retired: "phase-71.8" }, щоб старі білди frontend не падали з 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
• Issues #321 (батьківська) · #358–#367 (підфази) · #322 / #324 (закриті разом)
• Лог рішень: docs/architecture/PHASE_71_RAG_MIGRATION.md