@100xprompt/chitta 0.1.0

package/src/embedded/sqlite-store.ts

@@ -0,0 +1,95 @@
+// Embedded store schema (bun:sqlite). A generic property-graph (nodes + edges)
+// plus a chunks table holding payloads and dense vectors. One file = the whole
+// knowledge base - no servers. This is what makes the single-binary path work.
+//
+// Vector search adapts: if an extension-capable SQLite is available it loads
+// sqlite-vec and maintains a `vec_chunks` ANN index (the zvec-style fast path,
+// in-process, same file); otherwise it transparently falls back to brute-force
+// cosine. Either way the public API and the VectorDBService interface are identical.
+//
+// This file is a thin FACADE: it owns the single bun:sqlite Database and delegates
+// to focused modules under ./store/ (schema/migrations, graph nodes+edges, chunks+
+// vec ANN, FTS5, salience). Pure structural refactor - identical SQL, identical
+// behavior. The public surface of SqliteStore is preserved exactly.
+
+import { Database } from "bun:sqlite"
+import { migrate, tryEnableExtensions, tryLoadVec } from "./store/schema"
+import * as graph from "./store/nodes-edges"
+import * as fts from "./store/fts"
+import { ChunkRepo } from "./store/chunks"
+import * as salience from "./store/salience"
+
+export type Json = Record<string, unknown>
+
+export class SqliteStore {
+  readonly db: Database
+  readonly vecEnabled: boolean
+  readonly ftsEnabled: boolean
+  private readonly chunks: ChunkRepo
+
+  constructor(path = ":memory:") {
+    tryEnableExtensions()
+    this.db = new Database(path)
+    this.db.exec("PRAGMA journal_mode = WAL;")
+    migrate(this.db)
+    this.vecEnabled = tryLoadVec(this.db)
+    this.ftsEnabled = fts.tryEnableFts(this.db)
+    this.chunks = new ChunkRepo(this.db, this.vecEnabled, this.ftsEnabled)
+  }
+
+  // ── Graph: nodes & edges ────────────────────────────────────────────────
+  addNode(id: string, coll: string, data: Json = {}): void {
+    graph.addNode(this.db, id, coll, data)
+  }
+
+  addEdge(src: string, dst: string, label: string, opts: { weight?: number; validAt?: number; recordId?: string; confidence?: number } = {}): void {
+    graph.addEdge(this.db, src, dst, label, opts)
+  }
+
+  clearRecordContributions(recordId: string): void {
+    graph.clearRecordContributions(this.db, recordId)
+  }
+
+  supersedeEdge(src: string, label: string, keepDst: string, atTime = Date.now()): number {
+    return graph.supersedeEdge(this.db, src, label, keepDst, atTime)
+  }
+
+  backfillEdgeProvenance(): number {
+    return graph.backfillEdgeProvenance(this.db)
+  }
+
+  // ── Salience / decay ────────────────────────────────────────────────────
+  recordSalience(recordIds: string[]): Map<string, { lastAccessedAt: number; accessCount: number; importance: number }> {
+    return salience.recordSalience(this.db, recordIds)
+  }
+
+  touchRecords(recordIds: string[]): void {
+    salience.touchRecords(this.db, recordIds)
+  }
+
+  // ── Chunks + vec0 ANN ───────────────────────────────────────────────────
+  addChunk(pointId: string, virtualRecordId: string, orgId: string, content: string, embedding: number[]): void {
+    this.chunks.addChunk(pointId, virtualRecordId, orgId, content, embedding)
+  }
+
+  knnSearch(queryVec: number[], k: number): Array<{ rowid: number; distance: number }> {
+    return this.chunks.knnSearch(queryVec, k)
+  }
+
+  resetVec(): void {
+    this.chunks.resetVec()
+  }
+
+  // ── FTS5 keyword index ──────────────────────────────────────────────────
+  ftsSearch(query: string, k: number): number[] {
+    return fts.ftsSearch(this.db, this.ftsEnabled, query, k)
+  }
+
+  resetFts(): void {
+    fts.resetFts(this.db, this.ftsEnabled)
+  }
+
+  close(): void {
+    this.db.close()
+  }
+}

package/src/embedded/sqlite-vec-service.ts

@@ -0,0 +1,122 @@
+// VectorDBService over bun:sqlite. Uses the sqlite-vec ANN index when the store
+// has it (fast path), else brute-force cosine - same results, same interface.
+// Honors the must/should filter the retrieval spine builds: a point passes if it
+// matches all `must` AND (no `should` OR matches a `should`). The `should` on
+// virtualRecordId is the ACL restriction to accessible records, applied AFTER the
+// ANN candidates come back (over-fetched) so recall holds under filtering.
+
+import type { VectorDBService, VectorPoint, VectorQueryResult } from "../provider"
+import type { SqliteStore } from "./sqlite-store"
+
+interface EmbeddedFilter {
+  must?: Record<string, unknown>
+  should?: Record<string, unknown>
+}
+
+function cosine(a: number[], b: number[]): number {
+  let dot = 0
+  let na = 0
+  let nb = 0
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) {
+    dot += a[i] * b[i]
+    na += a[i] * a[i]
+    nb += b[i] * b[i]
+  }
+  if (na === 0 || nb === 0) return 0
+  return dot / (Math.sqrt(na) * Math.sqrt(nb))
+}
+
+export class SqliteVecService implements VectorDBService {
+  constructor(private readonly store: SqliteStore) {}
+
+  async filterCollection(args: {
+    must?: Record<string, unknown>
+    should?: Record<string, unknown>
+  }): Promise<EmbeddedFilter> {
+    return { must: args.must, should: args.should }
+  }
+
+  async queryNearestPoints(args: {
+    collectionName: string
+    requests: unknown[]
+  }): Promise<VectorQueryResult[]> {
+    return args.requests.map((reqUnknown) => {
+      const req = reqUnknown as {
+        prefetch?: Array<{ query: unknown; using?: string }>
+        filter?: EmbeddedFilter
+        limit?: number
+      }
+      const dense = (req.prefetch?.find((p) => p.using === "dense")?.query ?? req.prefetch?.[0]?.query) as number[]
+      const filter = req.filter ?? {}
+      const limit = req.limit ?? 20
+      const mustOrg = filter.must?.["orgId"] as string | undefined
+      const allowedVids = filter.should?.["virtualRecordId"] as string[] | undefined
+      const allowed = allowedVids ? new Set(allowedVids) : undefined
+
+      // Try ANN; fall back to brute-force when the index can't serve (missing /
+      // not yet built / written by a non-vec store). Guarantees we never miss rows
+      // that exist in `chunks` just because the ANN index isn't populated.
+      let points = this.store.vecEnabled && dense ? this.annQuery(dense, mustOrg, allowed, limit) : []
+      if (points.length === 0) points = this.bruteForce(dense, mustOrg, allowed, limit)
+      return { points }
+    })
+  }
+
+  // Fast path: ANN candidates from vec0, over-fetched then ACL-filtered.
+  private annQuery(
+    dense: number[],
+    mustOrg: string | undefined,
+    allowed: Set<string> | undefined,
+    limit: number,
+  ): VectorPoint[] {
+    const knn = this.store.knnSearch(dense, Math.max(limit * 20, 50))
+    if (knn.length === 0) return []
+    const byRowid = new Map(knn.map((k) => [k.rowid, k.distance]))
+    const rows = this.store.db
+      .query(`SELECT rowid, point_id, virtual_record_id, org_id, content FROM chunks WHERE rowid IN (${knn.map(() => "?").join(",")})`)
+      .all(...knn.map((k) => k.rowid)) as Array<{
+      rowid: number
+      point_id: string
+      virtual_record_id: string
+      org_id: string
+      content: string
+    }>
+    const out: VectorPoint[] = []
+    for (const c of rows) {
+      if (mustOrg != null && c.org_id !== mustOrg) continue
+      if (allowed && !allowed.has(c.virtual_record_id)) continue
+      out.push({
+        id: c.point_id,
+        score: 1 - (byRowid.get(c.rowid) ?? 1), // cosine distance → similarity
+        payload: { page_content: c.content, metadata: { virtualRecordId: c.virtual_record_id, orgId: c.org_id } },
+      })
+    }
+    out.sort((a, b) => b.score - a.score)
+    return out.slice(0, limit)
+  }
+
+  // Fallback: scan + cosine in TS (portable, no extension needed).
+  private bruteForce(
+    dense: number[] | undefined,
+    mustOrg: string | undefined,
+    allowed: Set<string> | undefined,
+    limit: number,
+  ): VectorPoint[] {
+    const rows = this.store.db
+      .query("SELECT point_id, virtual_record_id, org_id, content, embedding FROM chunks")
+      .all() as Array<{ point_id: string; virtual_record_id: string; org_id: string; content: string; embedding: string }>
+    const scored: VectorPoint[] = []
+    for (const c of rows) {
+      if (mustOrg != null && c.org_id !== mustOrg) continue
+      if (allowed && !allowed.has(c.virtual_record_id)) continue
+      scored.push({
+        id: c.point_id,
+        score: dense ? cosine(dense, JSON.parse(c.embedding) as number[]) : 0,
+        payload: { page_content: c.content, metadata: { virtualRecordId: c.virtual_record_id, orgId: c.org_id } },
+      })
+    }
+    scored.sort((a, b) => b.score - a.score)
+    return scored.slice(0, limit)
+  }
+}

package/src/embedded/store/chunks.ts

@@ -0,0 +1,61 @@
+// Chunk persistence + vec0 ANN index + knnSearch. Pure structural extraction from
+// sqlite-store.ts - identical SQL, identical behavior.
+//
+// The vec0 ANN table is created lazily once we know the embedding dimension, so the
+// mutable `vecDim` state lives in a small repo object owned by the facade.
+
+import { Database } from "bun:sqlite"
+import { indexChunkFts } from "./fts"
+
+export class ChunkRepo {
+  private vecDim = 0
+
+  constructor(
+    private readonly db: Database,
+    private readonly vecEnabled: boolean,
+    private readonly ftsEnabled: boolean,
+  ) {}
+
+  // The vec0 ANN table is created lazily once we know the embedding dimension.
+  private ensureVec(dim: number): void {
+    if (!this.vecEnabled || this.vecDim) return
+    this.db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(embedding float[${dim}] distance_metric=cosine)`)
+    this.vecDim = dim
+  }
+
+  addChunk(pointId: string, virtualRecordId: string, orgId: string, content: string, embedding: number[]): void {
+    const res = this.db
+      .query("INSERT OR REPLACE INTO chunks (point_id, virtual_record_id, org_id, content, embedding) VALUES (?, ?, ?, ?, ?)")
+      .run(pointId, virtualRecordId, orgId, content, JSON.stringify(embedding))
+    const rowid = Number(res.lastInsertRowid)
+    if (this.vecEnabled) {
+      this.ensureVec(embedding.length)
+      this.db.query("DELETE FROM vec_chunks WHERE rowid = ?").run(rowid)
+      this.db.query("INSERT INTO vec_chunks(rowid, embedding) VALUES (?, ?)").run(rowid, JSON.stringify(embedding))
+    }
+    if (this.ftsEnabled) {
+      indexChunkFts(this.db, rowid, content)
+    }
+  }
+
+  /** ANN KNN over the vec0 index → [{rowid, distance}] (cosine distance). Returns
+   *  [] if the index isn't present/usable (e.g. data written by a non-vec store, a
+   *  query-only process, or a dim mismatch) - the caller then falls back to brute-force. */
+  knnSearch(queryVec: number[], k: number): Array<{ rowid: number; distance: number }> {
+    if (!this.vecEnabled) return []
+    try {
+      return this.db
+        .query("SELECT rowid, distance FROM vec_chunks WHERE embedding MATCH ? ORDER BY distance LIMIT ?")
+        .all(JSON.stringify(queryVec), k) as Array<{ rowid: number; distance: number }>
+    } catch {
+      return [] // vec_chunks missing or incompatible → brute-force handles it
+    }
+  }
+
+  /** Drop the ANN index (e.g. before reindexing with a different embedder/dim). */
+  resetVec(): void {
+    if (!this.vecEnabled) return
+    this.db.exec("DROP TABLE IF EXISTS vec_chunks")
+    this.vecDim = 0
+  }
+}

package/src/embedded/store/fts.ts

@@ -0,0 +1,50 @@
+// FTS5 build/search/reset. Pure structural extraction from sqlite-store.ts -
+// identical SQL, identical behavior.
+
+import { Database } from "bun:sqlite"
+
+// BM25 keyword index (SQLite FTS5, built-in - no extension needed). Complements the
+// dense vector index: FTS5 nails exact tokens dense embeddings miss (acronyms "SAP",
+// numbers "£230M", proper nouns). Backfills existing chunks on first open so hybrid
+// search works on prior data without a reindex.
+export function tryEnableFts(db: Database): boolean {
+  try {
+    db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(content)")
+    const ftsCount = (db.query("SELECT count(*) c FROM chunks_fts").get() as { c: number }).c
+    const chunkCount = (db.query("SELECT count(*) c FROM chunks").get() as { c: number }).c
+    if (ftsCount === 0 && chunkCount > 0)
+      db.exec("INSERT INTO chunks_fts(rowid, content) SELECT rowid, content FROM chunks")
+    return true
+  } catch {
+    return false // FTS5 unavailable → dense-only, hybrid degrades gracefully
+  }
+}
+
+// Upsert a chunk row into the FTS index (called as part of addChunk).
+export function indexChunkFts(db: Database, rowid: number, content: string): void {
+  db.query("DELETE FROM chunks_fts WHERE rowid = ?").run(rowid)
+  db.query("INSERT INTO chunks_fts(rowid, content) VALUES (?, ?)").run(rowid, content)
+}
+
+/** BM25 keyword search → chunk rowids in relevance order (best first). Each query
+ *  token is matched as a quoted literal OR-joined, so punctuation/special chars are
+ *  safe and ANY matching term contributes (high recall). [] if FTS is unavailable. */
+export function ftsSearch(db: Database, ftsEnabled: boolean, query: string, k: number): number[] {
+  if (!ftsEnabled) return []
+  const terms = (query.toLowerCase().match(/[\p{L}\p{N}£$€%.\-]+/gu) ?? []).filter((t) => t.replace(/[^a-z0-9]/g, "").length >= 2)
+  if (!terms.length) return []
+  const expr = terms.map((t) => `"${t.replace(/"/g, "")}"`).join(" OR ")
+  try {
+    return (
+      db.query("SELECT rowid FROM chunks_fts WHERE chunks_fts MATCH ? ORDER BY bm25(chunks_fts) LIMIT ?").all(expr, k) as Array<{ rowid: number }>
+    ).map((r) => r.rowid)
+  } catch {
+    return []
+  }
+}
+
+/** Drop + recreate the BM25 index (e.g. before a full reindex). */
+export function resetFts(db: Database, ftsEnabled: boolean): void {
+  if (!ftsEnabled) return
+  db.exec("DROP TABLE IF EXISTS chunks_fts; CREATE VIRTUAL TABLE chunks_fts USING fts5(content);")
+}

package/src/embedded/store/nodes-edges.ts

@@ -0,0 +1,112 @@
+// Graph vertex/edge CRUD + provenance + supersession. Pure structural extraction
+// from sqlite-store.ts - identical SQL, identical behavior.
+
+import { Database } from "bun:sqlite"
+import type { Json } from "../sqlite-store"
+
+export function addNode(db: Database, id: string, coll: string, data: Json = {}): void {
+  db.query("INSERT OR REPLACE INTO nodes (id, coll, data) VALUES (?, ?, ?)").run(id, coll, JSON.stringify(data))
+}
+
+// Merge-on-upsert (LightRAG): one row per (src,dst,label). Re-asserting an edge
+// ACCUMULATES weight, refreshes its validity (revives a previously superseded
+// edge), and unions provenance - the graph gets denser per write, never duplicated.
+export function addEdge(
+  db: Database,
+  src: string,
+  dst: string,
+  label: string,
+  opts: { weight?: number; validAt?: number; recordId?: string; confidence?: number } = {},
+): void {
+  const now = Date.now()
+  db
+    .query(
+      `INSERT INTO edges (src, dst, label, weight, created_at, valid_at, invalid_at, expired_at, provenance, confidence)
+       VALUES (?, ?, ?, ?, ?, ?, NULL, NULL, '[]', ?)
+       ON CONFLICT(src, dst, label) DO UPDATE SET
+         weight = weight + excluded.weight,
+         expired_at = NULL,
+         invalid_at = NULL,
+         valid_at = COALESCE(edges.valid_at, excluded.valid_at),
+         confidence = MAX(edges.confidence, excluded.confidence)`,
+    )
+    .run(src, dst, label, opts.weight ?? 1, now, opts.validAt ?? null, opts.confidence ?? 1)
+  if (opts.recordId) addProvenance(db, src, dst, label, opts.recordId)
+}
+
+// Union a source record id into an edge's provenance list (which records asserted it).
+function addProvenance(db: Database, src: string, dst: string, label: string, recordId: string): void {
+  const row = db.query("SELECT provenance FROM edges WHERE src = ? AND dst = ? AND label = ?").get(src, dst, label) as
+    | { provenance: string }
+    | undefined
+  if (!row) return
+  const set = new Set<string>(JSON.parse(row.provenance) as string[])
+  if (set.has(recordId)) return
+  set.add(recordId)
+  db.query("UPDATE edges SET provenance = ? WHERE src = ? AND dst = ? AND label = ?").run(JSON.stringify([...set]), src, dst, label)
+}
+
+// Source-keyed replace-on-reingest (Graphify build_merge): before re-ingesting a
+// record, drop everything IT contributed so facts removed from the source get
+// garbage-collected (an entity-id-keyed upsert alone would orphan them forever).
+// Removes the record's `mentions` edges, and strips the record from every concept
+// edge's provenance - deleting the edge if no other record still asserts it, else
+// lowering its weight to the surviving source count.
+export function clearRecordContributions(db: Database, recordId: string): void {
+  db.query("DELETE FROM edges WHERE src = ? AND label = 'mentions'").run(recordId)
+  const rows = db
+    .query("SELECT src, dst, label, provenance FROM edges WHERE provenance LIKE ?")
+    .all(`%${JSON.stringify(recordId).slice(1, -1)}%`) as Array<{ src: string; dst: string; label: string; provenance: string }>
+  for (const r of rows) {
+    const prov = (JSON.parse(r.provenance) as string[]).filter((p) => p !== recordId)
+    if (prov.length === (JSON.parse(r.provenance) as string[]).length) continue // not actually this record
+    if (prov.length === 0) {
+      db.query("DELETE FROM edges WHERE src = ? AND dst = ? AND label = ?").run(r.src, r.dst, r.label)
+    } else {
+      db
+        .query("UPDATE edges SET provenance = ?, weight = ? WHERE src = ? AND dst = ? AND label = ?")
+        .run(JSON.stringify(prov), prov.length, r.src, r.dst, r.label)
+    }
+  }
+}
+
+// Non-destructive supersession (Graphiti): close the validity interval on every
+// LIVE edge from `src` with this `label` whose target ISN'T `keepDst`. Used for a
+// FUNCTIONAL relation (single-valued: lives_in, works_at) when a newer fact arrives.
+// The old edge stays in the table with invalid_at/expired_at set - history intact.
+export function supersedeEdge(db: Database, src: string, label: string, keepDst: string, atTime = Date.now()): number {
+  const res = db
+    .query(
+      `UPDATE edges SET invalid_at = ?, expired_at = ?
+       WHERE src = ? AND label = ? AND dst != ? AND expired_at IS NULL`,
+    )
+    .run(atTime, Date.now(), src, label, keepDst)
+  return Number(res.changes)
+}
+
+// Backfill provenance for LEGACY concept edges that predate provenance tracking
+// (migrated/older data has provenance '[]'). With per-edge ACL now fail-closed, an
+// un-provenanced edge would be hidden from everyone - so attribute each to the
+// records that mention BOTH of its endpoints (where the relationship was extracted),
+// restoring it to the correct permission scope. Returns the number repaired.
+export function backfillEdgeProvenance(db: Database): number {
+  const edges = db
+    .query(
+      `SELECT src, dst, label FROM edges
+       WHERE provenance = '[]' AND label NOT IN ('mentions','permissions','belongsTo','inheritPermissions')`,
+    )
+    .all() as Array<{ src: string; dst: string; label: string }>
+  const recordsMentioningBoth = db.query(
+    `SELECT m1.src AS r FROM edges m1 JOIN edges m2 ON m1.src = m2.src
+     WHERE m1.label = 'mentions' AND m2.label = 'mentions' AND m1.dst = ? AND m2.dst = ?`,
+  )
+  let repaired = 0
+  for (const e of edges) {
+    const recs = [...new Set((recordsMentioningBoth.all(e.src, e.dst) as Array<{ r: string }>).map((x) => x.r))]
+    if (recs.length) {
+      db.query("UPDATE edges SET provenance = ? WHERE src = ? AND dst = ? AND label = ?").run(JSON.stringify(recs), e.src, e.dst, e.label)
+      repaired++
+    }
+  }
+  return repaired
+}

package/src/embedded/store/salience.ts

@@ -0,0 +1,37 @@
+// Memory salience / decay ops. Pure structural extraction from sqlite-store.ts -
+// identical SQL, identical behavior.
+
+import { Database } from "bun:sqlite"
+import { ph } from "./schema"
+
+// Memory salience (Generative-Agents / ACT-R): per-record access recency, frequency,
+// and importance - used to gently re-weight retrieval so fresh/important/often-used
+// memories surface over stale ones. NEVER deletes; only dampens retrieval strength.
+export function recordSalience(
+  db: Database,
+  recordIds: string[],
+): Map<string, { lastAccessedAt: number; accessCount: number; importance: number }> {
+  const out = new Map<string, { lastAccessedAt: number; accessCount: number; importance: number }>()
+  if (recordIds.length === 0) return out
+  const rows = db
+    .query(
+      `SELECT id,
+              COALESCE(json_extract(data,'$.lastAccessedAt'), json_extract(data,'$.createdAt'), 0) la,
+              COALESCE(json_extract(data,'$.accessCount'), 0) ac,
+              COALESCE(json_extract(data,'$.importance'), 1) imp
+       FROM nodes WHERE coll = 'records' AND id IN (${ph(recordIds.length)})`,
+    )
+    .all(...recordIds) as Array<{ id: string; la: number; ac: number; imp: number }>
+  for (const r of rows) out.set(r.id, { lastAccessedAt: r.la, accessCount: r.ac, importance: r.imp })
+  return out
+}
+
+/** Mark records as just-accessed (bump recency + frequency) - called on retrieval. */
+export function touchRecords(db: Database, recordIds: string[]): void {
+  const now = Date.now()
+  const stmt = db.query(
+    `UPDATE nodes SET data = json_set(json_set(data,'$.lastAccessedAt', ?), '$.accessCount',
+      COALESCE(json_extract(data,'$.accessCount'),0) + 1) WHERE id = ? AND coll = 'records'`,
+  )
+  for (const id of recordIds) stmt.run(now, id)
+}

package/src/embedded/store/schema.ts

@@ -0,0 +1,109 @@
+// Schema DDL + migrations + sqlite-vec load detection for the embedded store.
+// Pure structural extraction from sqlite-store.ts - identical SQL, identical behavior.
+
+import { Database } from "bun:sqlite"
+import fs from "node:fs"
+import * as sqliteVec from "sqlite-vec"
+
+// setCustomSQLite must be called once, before any Database is opened. We point bun
+// at an extension-capable SQLite (Homebrew / system) so sqlite-vec can load.
+let triedCustomSqlite = false
+export function tryEnableExtensions(): void {
+  if (triedCustomSqlite) return
+  triedCustomSqlite = true
+  const candidates = [
+    "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib",
+    "/usr/local/opt/sqlite/lib/libsqlite3.dylib",
+    "/usr/lib/x86_64-linux-gnu/libsqlite3.so",
+    "/usr/lib/aarch64-linux-gnu/libsqlite3.so",
+  ]
+  const lib = candidates.find((p) => fs.existsSync(p))
+  if (!lib) return
+  try {
+    ;(Database as unknown as { setCustomSQLite(p: string): void }).setCustomSQLite(lib)
+  } catch {
+    /* already opened a DB, or unsupported - fall back to brute-force */
+  }
+}
+
+export function tryLoadVec(db: Database): boolean {
+  try {
+    sqliteVec.load(db)
+    return true
+  } catch {
+    return false // no extension support → brute-force path
+  }
+}
+
+export function migrate(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS nodes (
+      id TEXT PRIMARY KEY,
+      coll TEXT NOT NULL,
+      data TEXT NOT NULL DEFAULT '{}'
+    );
+    CREATE INDEX IF NOT EXISTS idx_nodes_coll ON nodes(coll);
+    CREATE TABLE IF NOT EXISTS chunks (
+      point_id TEXT PRIMARY KEY,
+      virtual_record_id TEXT,
+      org_id TEXT,
+      content TEXT,
+      embedding TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_chunks_org ON chunks(org_id);
+  `)
+  migrateEdges(db)
+  // Confidence tier (Graphify EXTRACTED=1.0 / INFERRED≈0.8 / AMBIGUOUS≈0.5) - how
+  // sure we are the relationship is real. Added idempotently so existing DBs upgrade.
+  const ecols = (db.query("PRAGMA table_info(edges)").all() as Array<{ name: string }>).map((c) => c.name)
+  if (!ecols.includes("confidence")) db.exec("ALTER TABLE edges ADD COLUMN confidence REAL NOT NULL DEFAULT 1")
+}
+
+// The edges table is a property-graph relation store shared by ACL (permissions/
+// belongsTo), structure (mentions), and the concept graph (relates_to / typed verbs).
+// It is bi-temporal + merge-on-upsert: one row per (src,dst,label), with `weight`
+// accumulating across mentions (frequency≈confidence, LightRAG), `created_at` the
+// ingest time, and (valid_at, invalid_at, expired_at) the Graphiti validity axes -
+// a "live" edge has expired_at IS NULL. Contradictions INVALIDATE (close the
+// interval); they never delete, so history is never lost.
+export function migrateEdges(db: Database): void {
+  const cols = db.query("PRAGMA table_info(edges)").all() as Array<{ name: string }>
+  const hasEdges = cols.length > 0
+  const hasWeight = cols.some((c) => c.name === "weight")
+  if (hasEdges && hasWeight) return // already current
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS edges_new (
+      src TEXT NOT NULL,
+      dst TEXT NOT NULL,
+      label TEXT NOT NULL,
+      weight REAL NOT NULL DEFAULT 1,
+      created_at INTEGER NOT NULL DEFAULT 0,
+      valid_at INTEGER,
+      invalid_at INTEGER,
+      expired_at INTEGER,
+      provenance TEXT NOT NULL DEFAULT '[]',
+      PRIMARY KEY (src, dst, label)
+    );
+  `)
+  if (hasEdges) {
+    // Fold any duplicate (src,dst,label) rows from the old schema into one,
+    // carrying the duplicate COUNT forward as the starting weight.
+    db.exec(`
+      INSERT INTO edges_new (src, dst, label, weight, created_at)
+      SELECT src, dst, label, COUNT(*), 0 FROM edges GROUP BY src, dst, label;
+      DROP TABLE edges;
+    `)
+  }
+  db.exec(`
+    ALTER TABLE edges_new RENAME TO edges;
+    CREATE INDEX IF NOT EXISTS idx_edges_src ON edges(src, label);
+    CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst, label);
+    CREATE INDEX IF NOT EXISTS idx_edges_live ON edges(label, expired_at);
+  `)
+}
+
+// Small shared placeholder helper for IN (...) clauses.
+export function ph(n: number): string {
+  return Array.from({ length: n }, () => "?").join(",")
+}