Architecture RAG — recherche sémantique auto-hébergée

Statut : En production depuis la Phase 71 (2026-06-05). Remplace le bridge Google NotebookLM livré en Phase 36.

TL;DR : le wiki + les tickets + les skills de chaque projet Arc sont indexés dans un index vectoriel par projet qui vit à l'intérieur du SSOT SQLite existant. Les requêtes renvoient des passages sémantiquement pertinents à travers le contenu du projet + un pool global de skills partagé. Aucun service de récupération externe, aucune session Google par utilisateur, aucune limite de sources.

1. Pourquoi nous avons quitté NotebookLM

Le bridge de la Phase 36 enrobait Google NotebookLM en magasin de vecteurs via une auth par cookies rétro-ingéniérée. Cela produisait deux problèmes que le produit sous-jacent ne peut pas corriger :

1. Plafond de sources. NotebookLM Plus plafonne à 100 sources par notebook. Mi-2026, plusieurs projets Arc avaient largement dépassé ce plafond ; la logique d'éviction est devenue un pansement permanent (#324).
2. Couplage au compte personnel. Chaque nouveau projet créait un notebook dans le NotebookLM personnel du CEO. Passer à N clients signifiait N notebooks dans la barre latérale d'une seule personne — un effet de bord non géré que le bridge ne pouvait pas découpler.

La Phase 71 remplace la couche de récupération par un pipeline auto-hébergé que le compte Google de l'utilisateur ne touche jamais.

2. Carte des composants

                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 Les modules en un coup d'œil

3. Choix d'embedding — Cohere embed-multilingual-v3.0

Test croisé multilingue en direct contre le corpus de prod :

La requête UK a battu la distance EN-EN correspondante — l'alignement du sous-espace multilingue est réel, pas un argument marketing.

4. Stockage — sqlite-vec à l'intérieur du SSOT

La migration 049_embeddings crée deux tables :

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

Cette séparation garde les métadonnées dans du SQLite classique (jointables avec les tables wiki/issues/skills, LIST/DELETE faciles) tandis que la table virtuelle vec0 contient les vecteurs denses pour la recherche ANN.

Dimensionnement. float32 1024 dimensions = 4096 octets / ligne. 100K lignes ≈ 400 Mo. Suffisant à l'échelle actuelle ; à réexaminer au-delà de 1M de lignes.

Chargement. sqlite-vec est chargé comme extension runtime dans shared/db.ts initDb() avant l'exécution des migrations. La migration 049 vérifie vec_version() et s'interrompt proprement si l'extension n'a pas chargé.

5. Chemin d'écriture — hooks de ré-indexation (Phase 71.5)

Chaque surface d'écriture qui modifie du contenu indexable déclenche un hook fire-and-forget afin que l'embedding reste à jour sans job de synchronisation séparé.

Règle : les erreurs Cohere affichent une ligne et meurent. Elles n'annulent jamais l'écriture disque/SQL qui les a déclenchées. Les échecs persistants reconvergent via le backfill nocturne, pas via des retries dans le chemin chaud.

6. Chemin de lecture — search() + façades par surface

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

Sous le capot :

1. Embedding de la requête avec input_type="search_query" (sous-espace différent de search_document).
2. KNN sur embeddings_vec avec un surfetch de k * 4.
3. Filtrage par projet + doc_type optionnel au niveau du JOIN SQL.
4. Retour des top-K passages triés par distance L2 croissante.

Façades publiques

• GET /api/crm/projects/:name/rag/search?q=...&k=...&include_global=true&doc_types=... — point d'entrée HTTP. Alimente arc kb search + l'outil ask_notebooklm en chat.
• chat.ts executeAskNotebooklm — exécute la recherche projet + globale en parallèle, fusionne par distance, bascule sur la recherche par mots-clés quand le meilleur résultat a d > 1.6 ou en l'absence de résultats.
• skills.ts handleGenerateSkill — utilise le RAG comme récupération du style maison, puis appelle Claude Sonnet pour la génération.
• help.ts ragSemantic — le chat Arc Help expose les résultats projet + globaux comme contexte du modèle.

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)

Idempotence. Chaque candidat est vérifié pour la présence de (project, doc_type, doc_id) dans embeddings et sauté s'il est trouvé, sauf si --force est passé. Les ré-exécutions coûtent zéro quota Cohere.

Exécution de production (2026-06-05). 814 candidats à travers 20 projets + _global_ (37 wiki + 482 tickets + 295 skills). Le premier passage a épuisé le plafond mensuel Trial de 1000 appels sur les skills globaux. Après passage à une clé Production, les 178 documents restants ont été traités en 57 s sans aucune erreur. Total de chunks écrits : ~3 150.

8. Frontières de sécurité

• La clé API Cohere vit dans le vault (COHERE_API_KEY), tourne via Platform Settings → RAG / Semantic search. Un bouton Test en direct effectue un appel d'embedding de 1 token pour confirmer la joignabilité.
• Aucune fuite de prompts vers Cohere. Les embeddings sont des dérivés de type bag-of-words ; les inverser vers le texte source est impraticable. La politique de Cohere indique qu'ils n'entraînent pas leurs modèles sur le trafic API.
• Multi-tenancy. Les noms de projets sont des clés de namespace ; canAccessProject garde /api/crm/projects/:name/* avant l'exécution du handler de recherche. Les skills globaux vivent dans un namespace sentinelle _global_ avec lequel aucun nom de projet utilisateur ne peut entrer en collision (le validateur interdit les noms commençant par _).
• RGPD Art. 17. DELETE /api/auth/account cascade rag.removeProject pour chaque projet possédé afin que les embeddings ne survivent pas à la suppression.

9. Migration depuis NotebookLM (unique, 2026-06-05)

10. Notes d'exploitation

• Le nom d'outil reste ask_notebooklm. La définition d'outil Anthropic est transmise en aval à Claude dans la conversation Cloud PM. La renommer casserait les boucles tool_use en vol. L'implémentation est désormais du pur RAG ; le contrat public est resté stable.
• L'audio overview a disparu. Les résumés audio auto-générés de NotebookLM n'ont pas d'équivalent dans le pipeline auto-hébergé. POST /api/crm/projects/:name/memory/fetch-artifact renvoie désormais 410 Gone. Si tu en as besoin, c'est une phase séparée (probablement une passe Whisper TTS sur le wiki du projet).
• Le bouton de ré-indexation fonctionne toujours. POST /api/crm/projects/:name/memory/refresh ré-indexe désormais MANIFEST.md + ROADMAP.md + les fichiers clés dans le store local embeddings au lieu de les uploader vers NotebookLM. Comportement côté utilisateur : même bouton, même résultat (« la connaissance du projet est maintenant fraîche »), stockage différent.
• Plus d'URL de notebooks. GET /api/crm/projects/:name/notebooks renvoie { notebooks: [], retired: "phase-71.8" } pour éviter les 404 sur les anciens builds frontend. L'onglet Neural Memory du CRM sera retiré dans une passe cosmétique ultérieure.

11. Références

• 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
• Tickets #321 (parent) · #358–#367 (sous-phases) · #322 / #324 (clos dans la foulée)
• Journal de décisions : docs/architecture/PHASE_71_RAG_MIGRATION.md