mixdog 0.7.1

package/src/memory/lib/memory-retrievers.mjs

@@ -0,0 +1,112 @@
+import { recallReadQuery } from './memory-recall-read-query.mjs'
+
+const VALID_CATEGORIES_SET = new Set([
+  'rule', 'constraint', 'decision', 'fact', 'goal', 'preference', 'task', 'issue',
+])
+const VALID_STATUS_SET = new Set(['pending', 'active', 'archived'])
+
+export async function retrieveEntries(db, filters = {}) {
+  const where = []
+  const params = []
+
+  // is_root filter (default: true)
+  const isRoot = filters.is_root === undefined ? true : Boolean(filters.is_root)
+  where.push(`is_root = $${params.length + 1}`)
+  params.push(isRoot ? 1 : 0)
+
+  if (filters.session_id != null) {
+    const sid = String(filters.session_id).trim()
+    if (sid) { where.push(`session_id = $${params.length + 1}`); params.push(sid) }
+  }
+
+  // projectScope filter: 'common' → project_id IS NULL only;
+  // specific slug → project_id IS NULL OR project_id = slug;
+  // 'all' or undefined → no filter (full pool).
+  if (filters.projectScope === 'common') {
+    where.push(`project_id IS NULL`)
+  } else if (typeof filters.projectScope === 'string' && filters.projectScope && filters.projectScope !== 'all') {
+    where.push(`(project_id IS NULL OR project_id = $${params.length + 1})`)
+    params.push(filters.projectScope)
+  }
+  // projectScope === 'all' or undefined → no filter
+
+  const tsFrom = Number(filters.ts_from)
+  if (Number.isFinite(tsFrom)) { where.push(`ts >= $${params.length + 1}`); params.push(tsFrom) }
+  const tsTo = Number(filters.ts_to)
+  if (Number.isFinite(tsTo)) { where.push(`ts <= $${params.length + 1}`); params.push(tsTo) }
+
+  if (filters.category != null) {
+    const cats = (Array.isArray(filters.category) ? filters.category : [filters.category])
+      .map(c => String(c).trim().toLowerCase())
+      .filter(c => VALID_CATEGORIES_SET.has(c))
+    if (cats.length > 0) {
+      const ph = cats.map((_, i) => `$${params.length + 1 + i}`).join(',')
+      where.push(`category IN (${ph})`)
+      params.push(...cats)
+    }
+  }
+
+  if (filters.status != null) {
+    const statusVal = String(filters.status).trim().toLowerCase()
+    if (VALID_STATUS_SET.has(statusVal)) {
+      where.push(`status = $${params.length + 1}`)
+      params.push(statusVal)
+    }
+  }
+
+  // R11 reviewer H2: exclude archived leakage in temporal augment paths.
+  if (Array.isArray(filters.excludeStatuses) && filters.excludeStatuses.length > 0) {
+    const exc = filters.excludeStatuses
+      .map(s => String(s).trim().toLowerCase())
+      .filter(s => VALID_STATUS_SET.has(s))
+    if (exc.length > 0) {
+      const ph = exc.map((_, i) => `$${params.length + 1 + i}`).join(',')
+      where.push(`(status IS NULL OR status NOT IN (${ph}))`)
+      params.push(...exc)
+    }
+  }
+
+  // R11 reviewer M3: orphan raw chunks (chunk_root IS NULL) for narrow-window
+  // raw merging — prevents classified-member chunks from duplicating their root.
+  if (filters.chunkRootNull === true) {
+    where.push(`chunk_root IS NULL`)
+  }
+
+  const limit = Math.max(1, Math.min(500, Number(filters.limit ?? 50)))
+  const offset = Math.max(0, Number(filters.offset ?? 0))
+  const sort = String(filters.sort ?? 'importance').trim().toLowerCase()
+  const orderBy = sort === 'date'
+    ? 'ts DESC, id DESC'
+    : 'score DESC NULLS LAST, ts DESC, id DESC'
+
+  params.push(limit, offset)
+  const sql = `SELECT id, ts, role, content, source_ref, session_id, source_turn,
+                      chunk_root, is_root, element, category, summary, project_id,
+                      status, score, last_seen_at
+               FROM entries
+               WHERE ${where.join(' AND ')}
+               ORDER BY ${orderBy}
+               LIMIT $${params.length - 1} OFFSET $${params.length}`
+
+  const rows = (await recallReadQuery(db, sql, params)).rows
+
+  if (filters.includeMembers && rows.length > 0) {
+    const rootIds = rows.map(r => r.id)
+    const memRes = (await recallReadQuery(
+      db,
+      `SELECT id, ts, role, content, session_id, source_turn, project_id, chunk_root
+       FROM entries WHERE chunk_root = ANY($1::bigint[]) AND is_root = 0
+       ORDER BY chunk_root, ts ASC, id ASC`,
+      [rootIds],
+    )).rows
+    const byRoot = new Map()
+    for (const m of memRes) {
+      const rid = Number(m.chunk_root)
+      if (!byRoot.has(rid)) byRoot.set(rid, [])
+      byRoot.get(rid).push({ id: m.id, ts: m.ts, role: m.role, content: m.content, session_id: m.session_id, source_turn: m.source_turn, project_id: m.project_id })
+    }
+    for (const r of rows) r.members = byRoot.get(Number(r.id)) || []
+  }
+
+  return rows
+}

package/src/memory/lib/memory-score.mjs

@@ -0,0 +1,71 @@
+// Per-category grade (base score ceiling) and decay rate.
+//
+// grade = baseline ceiling for the category (durability of knowledge type).
+// decay = how fast score drops with age. 0 means immune to age-decay
+//         (rules never decay), higher means faster drop.
+//
+// Pairing: rules/constraints have high grade + low/zero decay (long-term),
+// issues/tasks have low grade + high decay (transient by nature).
+//
+// score = grade * 1 / (1 + ageDays*rate/30)^0.3
+//
+// At ageDays=0: score = grade.
+// As ageDays → ∞: score → 0.
+// rate=0 disables decay entirely → score stays at grade forever.
+export const CATEGORY_GRADE = {
+  rule:       2.0,
+  constraint: 1.9,
+  decision:   1.8,
+  fact:       1.6,
+  goal:       1.5,
+  preference: 1.4,
+  task:       1.1,
+  issue:      1.0,
+}
+
+export const CATEGORY_DECAY = {
+  rule:       0.0,
+  constraint: 0.06,
+  decision:   0.15,
+  fact:       0.25,
+  goal:       0.30,
+  preference: 0.35,
+  task:       0.45,
+  issue:      0.50,
+}
+
+// Smooth exponential freshness factor — used by hybrid retrieval ranking
+// (separate from computeEntryScore, which is the persisted column score).
+// Returns value in [0.50, 1.60].
+//   ageH=0 → 1.60, ageH=6 → ~1.39, ageH=24 → ~1.08, ageH=72 → ~0.85,
+//   ageH=168 → ~0.68, ageH=720 → ~0.50.
+export function freshnessFactor(ts, nowMs = Date.now()) {
+  const ts_ = Number(ts ?? 0)
+  if (!Number.isFinite(ts_) || ts_ <= 0) return 0.85
+  const ageH = Math.max(0, (nowMs - ts_) / 3_600_000)
+  const raw = 0.50 + 1.10 * Math.exp(-ageH / 55)
+  return Math.max(0.50, Math.min(1.60, raw))
+}
+
+/**
+ * Persisted entry score = grade * decay-curve(ageDays, category-specific rate).
+ *
+ * Returns null on unknown category or non-finite timestamps.
+ * rate=0 (rule) yields score = grade with no time component.
+ *
+ * @param {string} category
+ * @param {number|string} lastSeenAt — ms timestamp
+ * @param {number} nowMs
+ * @returns {number|null}
+ */
+export function computeEntryScore(category, lastSeenAt, nowMs) {
+  const grade = CATEGORY_GRADE[String(category ?? '').toLowerCase()]
+  const rate  = CATEGORY_DECAY[String(category ?? '').toLowerCase()]
+  if (grade == null || rate == null) return null
+  if (!Number.isFinite(Number(nowMs))) return null
+  const anchor = Number.isFinite(Number(lastSeenAt)) ? Number(lastSeenAt) : Number(nowMs)
+  const ageDays = Math.max(0, (Number(nowMs) - anchor) / 86_400_000)
+  const adjustedAge = ageDays * rate
+  const decay = 1 / Math.pow(1 + adjustedAge / 30, 0.3)
+  return Math.min(grade, grade * decay)
+}

package/src/memory/lib/memory-text-utils.mjs

@@ -0,0 +1,58 @@
+import {
+  cleanMemoryText,
+} from './memory-extraction.mjs'
+
+const MEMORY_TOKEN_STOPWORDS = new Set([
+  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'but', 'by', 'did', 'do', 'does', 'for', 'from',
+  'how', 'i', 'if', 'in', 'is', 'it', 'me', 'my', 'of', 'on', 'or', 'our', 'so', 'that', 'the',
+  'their', 'them', 'they', 'this', 'to', 'was', 'we', 'were', 'what', 'when', 'who', 'why', 'you',
+  'your', 'unless', 'with',
+  'user', 'assistant', 'requested', 'request', 'asked', 'ask', 'stated', 'state', 'reported', 'report',
+  'mentioned', 'mention', 'clarified', 'clarify', 'explicitly', 'currently',
+  '사용자', '유저', '요청', '질문', '답변', '언급', '말씀', '설명', '보고', '무슨', '뭐야', '했지', 'user', 'asks', 'asked', 'request', 'requested', 'question', 'answer', 'reply', 'said', 'mentioned', 'explained', 'reported', 'what', 'huh',
+])
+
+export function normalizeMemoryToken(token) {
+  let normalized = String(token ?? '').trim().toLowerCase()
+  if (!normalized) return ''
+
+  // Korean suffix stripping: basic particles + compound endings
+  if (/[\uAC00-\uD7AF]/.test(normalized) && normalized.length > 2) {
+    const stripped = normalized
+      .replace(/(했었지|했더라|됐었나|됐던가|했는지|였는지|인건가|하려면|에서는|이라서|였더라|에서도|이었지|으로도|거였지|한건지|이었나)$/u, '')
+      .replace(/(했던|했지|됐던|됐지|하게|되던|이라|에서|으로|하는|없는|있는|었던|하자|않게|할때|인지|인데|인건|이고|보다|처럼|까지|부터|마다|밖에|없이)$/u, '')
+      .replace(/(은|는|이|가|을|를|랑|과|와|도|에|의|로|만|며|나|고|서|자|요)$/u, '')
+    if (stripped.length >= 2) normalized = stripped
+  }
+
+  if (/^[a-z][a-z0-9_-]+$/i.test(normalized)) {
+    if (normalized.length > 5 && normalized.endsWith('ing')) normalized = normalized.slice(0, -3)
+    else if (normalized.length > 4 && normalized.endsWith('ed')) normalized = normalized.slice(0, -2)
+    else if (normalized.length > 4 && normalized.endsWith('es')) normalized = normalized.slice(0, -2)
+    else if (normalized.length > 3 && normalized.endsWith('s')) normalized = normalized.slice(0, -1)
+  }
+
+  return normalized
+}
+
+export function tokenizeMemoryText(text) {
+  return cleanMemoryText(text)
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}_]+/u)
+    .map(token => normalizeMemoryToken(token))
+    .filter(token => token.length >= 2)
+    .filter(token => !MEMORY_TOKEN_STOPWORDS.has(token))
+    .slice(0, 24)
+}
+
+export function buildFtsQuery(text) {
+  const tokens = tokenizeMemoryText(text)
+  if (tokens.length === 0) return ''
+  // Include 2-char Korean tokens (they carry meaning unlike 2-char English)
+  const ftsTokens = [...new Set(tokens)].filter(t => t.length >= 3 || (t.length === 2 && /[\uAC00-\uD7AF]/.test(t)))
+  if (ftsTokens.length === 0) return ''
+  // websearch_to_tsquery handles tokenization + OR/AND/quoting itself; pass plain tokens space-joined.
+  return ftsTokens.map(t => t.replace(/["']/g, '')).filter(t => t.length > 0).join(' ')
+}
+
+

package/src/memory/lib/memory.mjs

@@ -0,0 +1,412 @@
+// Native-PG-backed memory store. Schema, helpers, and lifecycle.
+
+import { ensurePgInstance, closePgInstance, withSchemaBootstrapLock } from './pg/adapter.mjs'
+import { mkdirSync } from 'fs'
+import { resolve } from 'path'
+import { cleanMemoryText } from './memory-extraction.mjs'
+
+const dbs = new Map()
+const opening = new Map()
+
+export { cleanMemoryText }
+
+export const VALID_CATEGORY = new Set([
+  'rule', 'constraint', 'decision', 'fact', 'goal', 'preference', 'task', 'issue',
+])
+
+export async function init(db, dims) {
+  const dimCount = Number(dims)
+  if (!Number.isInteger(dimCount) || dimCount <= 0) {
+    throw new Error(`init: dims must be a positive integer, got ${dims}`)
+  }
+
+  // Extensions are created once by pg-adapter.bootstrapInstance; skip here.
+
+  // Status as a real ENUM type — DB-level enforcement, B-tree friendly.
+  // PG has no CREATE TYPE IF NOT EXISTS; guard via pg_type lookup so a partial
+  // bootstrap (crash after CREATE TYPE but before boot.schema_bootstrap_complete)
+  // can re-run init() on the next boot without colliding on the existing type.
+  await db.exec(`
+    DO $$
+    BEGIN
+      IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'entry_status') THEN
+        CREATE TYPE entry_status AS ENUM ('pending', 'active', 'archived');
+      END IF;
+    END
+    $$
+  `)
+
+  // Per-category score parameters (lookup table for the score function).
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS category_score_params (
+      category TEXT PRIMARY KEY,
+      grade    REAL NOT NULL,
+      decay    REAL NOT NULL
+    )
+  `)
+  await db.query(`
+    INSERT INTO category_score_params(category, grade, decay) VALUES
+      ('rule', 2.0, 0.0),
+      ('constraint', 1.9, 0.06),
+      ('decision', 1.8, 0.15),
+      ('fact', 1.6, 0.25),
+      ('goal', 1.5, 0.30),
+      ('preference', 1.4, 0.35),
+      ('task', 1.1, 0.45),
+      ('issue', 1.0, 0.50)
+    ON CONFLICT (category) DO NOTHING
+  `)
+
+  // SQL function mirrors src/memory/lib/memory-score.mjs computeEntryScore.
+  // STABLE (not IMMUTABLE) because the function reads category_score_params.
+  // IMMUTABLE would let the planner cache results across rows where params
+  // could legitimately differ if the table is updated.
+  await db.exec(`
+    CREATE OR REPLACE FUNCTION compute_entry_score(
+      category_p TEXT,
+      last_seen_at_p BIGINT,
+      now_ms_p BIGINT
+    ) RETURNS REAL LANGUAGE sql STABLE AS $$
+      SELECT CASE
+        WHEN p.grade IS NULL OR last_seen_at_p IS NULL OR now_ms_p IS NULL THEN NULL::REAL
+        WHEN p.decay = 0 THEN p.grade
+        ELSE LEAST(
+          p.grade,
+          p.grade / POWER(
+            1 + (GREATEST(0, (now_ms_p - last_seen_at_p)) / 86400000.0) * p.decay / 30,
+            0.3
+          )
+        )::REAL
+      END
+      FROM category_score_params p
+      WHERE p.category = category_p
+    $$
+  `)
+
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS entries (
+      id            BIGSERIAL PRIMARY KEY,
+      ts            BIGINT NOT NULL,
+      role          TEXT NOT NULL,
+      content       TEXT NOT NULL,
+      source_ref    TEXT NOT NULL UNIQUE,
+      session_id    TEXT,
+      project_id    TEXT,
+      source_turn   INTEGER,
+      chunk_root    BIGINT REFERENCES entries(id) ON DELETE SET NULL,
+      is_root       SMALLINT NOT NULL DEFAULT 0,
+      element       TEXT,
+      category      TEXT,
+      summary       TEXT,
+      core_summary  TEXT,
+      status        entry_status,
+      score         REAL,
+      last_seen_at  BIGINT,
+      reviewed_at   BIGINT,
+      promoted_at   BIGINT,
+      error_count   INTEGER NOT NULL DEFAULT 0,
+      embedding     halfvec(${dimCount}),
+      summary_hash  TEXT,
+      search_tsv    tsvector GENERATED ALWAYS AS (
+        setweight(to_tsvector('simple',  coalesce(element, '')), 'A') ||
+        setweight(to_tsvector('simple',  coalesce(summary, '')), 'B') ||
+        setweight(to_tsvector('simple',  coalesce(content, '')), 'C') ||
+        setweight(to_tsvector('english', coalesce(element, '')), 'A') ||
+        setweight(to_tsvector('english', coalesce(summary, '')), 'B') ||
+        setweight(to_tsvector('english', coalesce(content, '')), 'C')
+      ) STORED
+    )
+  `)
+
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_chunk_root  ON entries(chunk_root) WHERE chunk_root IS NOT NULL`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_ts_desc     ON entries(ts DESC)`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_session_ts  ON entries(session_id, ts DESC) WHERE session_id IS NOT NULL`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_root_status_score ON entries(status, score DESC) WHERE is_root = 1`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_root_category     ON entries(category, status)   WHERE is_root = 1`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_pending     ON entries(ts DESC, id DESC) WHERE chunk_root IS NULL AND session_id IS NOT NULL`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_roots_active        ON entries(status, last_seen_at ASC, score DESC) WHERE is_root = 1 AND status = 'active'`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_project     ON entries(project_id) WHERE project_id IS NOT NULL`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_reviewed_at ON entries(reviewed_at ASC) WHERE is_root = 1`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_phase_sweep ON entries(status, is_root, error_count, reviewed_at, id)`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_promoted_at ON entries(promoted_at) WHERE promoted_at IS NOT NULL`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_tsv         ON entries USING GIN (search_tsv)`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_content_trgm ON entries USING GIN (content gin_trgm_ops) WHERE is_root = 1`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_element_trgm ON entries USING GIN (element gin_trgm_ops) WHERE is_root = 1 AND element IS NOT NULL`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_entries_embedding_hnsw ON entries USING hnsw (embedding halfvec_cosine_ops) WHERE is_root = 1 AND embedding IS NOT NULL`)
+
+  // BEFORE INSERT/UPDATE trigger keeps score in sync with category + last_seen_at
+  // automatically; cycle code no longer needs to UPDATE entries SET score = ...
+  await db.exec(`
+    CREATE OR REPLACE FUNCTION trg_entry_score_recalc() RETURNS trigger LANGUAGE plpgsql AS $$
+    BEGIN
+      IF NEW.is_root = 1 AND NEW.category IS NOT NULL THEN
+        -- NOW()-to-ms conversion is intentional schema-level work; the
+        -- "no EXTRACT(EPOCH …)" rule applies to ms-stored BIGINT timestamp
+        -- COLUMNS, not to the trigger reading the current wall clock.
+        NEW.score := compute_entry_score(
+          NEW.category,
+          COALESCE(NEW.last_seen_at, NEW.ts),
+          (EXTRACT(EPOCH FROM NOW()) * 1000)::BIGINT
+        );
+      END IF;
+      RETURN NEW;
+    END;
+    $$
+  `)
+  await db.exec(`DROP TRIGGER IF EXISTS trg_entries_score ON entries`)
+  await db.exec(`
+    CREATE TRIGGER trg_entries_score
+    BEFORE INSERT OR UPDATE OF category, last_seen_at, promoted_at, is_root ON entries
+    FOR EACH ROW
+    EXECUTE FUNCTION trg_entry_score_recalc()
+  `)
+
+  await db.exec(`
+    CREATE OR REPLACE FUNCTION trg_entry_embedding_invalidate() RETURNS trigger LANGUAGE plpgsql AS $$
+    BEGIN
+      IF NEW.is_root = 1 AND (
+        NEW.content IS DISTINCT FROM OLD.content OR
+        NEW.summary IS DISTINCT FROM OLD.summary OR
+        NEW.element IS DISTINCT FROM OLD.element
+      ) THEN
+        NEW.embedding := NULL;
+        NEW.summary_hash := NULL;
+      END IF;
+      RETURN NEW;
+    END;
+    $$
+  `)
+  await db.exec(`DROP TRIGGER IF EXISTS trg_entries_embedding_invalidate ON entries`)
+  await db.exec(`
+    CREATE TRIGGER trg_entries_embedding_invalidate
+    BEFORE UPDATE OF content, summary, element ON entries
+    FOR EACH ROW EXECUTE FUNCTION trg_entry_embedding_invalidate()
+  `)
+
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS core_entries (
+      id          BIGSERIAL PRIMARY KEY,
+      element     TEXT NOT NULL,
+      summary     TEXT NOT NULL,
+      category    TEXT NOT NULL,
+      project_id  TEXT,
+      embedding   halfvec(${dimCount}),
+      created_at  BIGINT NOT NULL,
+      updated_at  BIGINT NOT NULL
+    )
+  `)
+  await db.exec(`CREATE INDEX IF NOT EXISTS core_entries_project_idx ON core_entries(project_id)`)
+  await db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS core_entries_unique_proj_elem ON core_entries (project_id, element) NULLS NOT DISTINCT`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS core_entries_embedding_hnsw ON core_entries USING hnsw (embedding halfvec_cosine_ops) WHERE embedding IS NOT NULL`)
+
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS meta (
+      key    TEXT PRIMARY KEY,
+      value  JSONB NOT NULL
+    )
+  `)
+
+  // Operational view — used by /health and dashboards. One round-trip,
+  // covers the metrics that previously needed 6+ COUNT queries.
+  await db.exec(`
+    CREATE OR REPLACE VIEW v_cycle_state AS
+    SELECT
+      COUNT(*) FILTER (WHERE is_root = 1) AS roots,
+      COUNT(*) FILTER (WHERE is_root = 1 AND status = 'pending')  AS pending,
+      COUNT(*) FILTER (WHERE is_root = 1 AND status = 'active')   AS active,
+      COUNT(*) FILTER (WHERE is_root = 1 AND status = 'archived') AS archived,
+      COUNT(*) FILTER (WHERE chunk_root IS NULL)                  AS unclassified,
+      COUNT(*) AS total
+    FROM entries
+  `)
+
+  // Hot active set — recall hot path uses the materialized copy. Refresh hook
+  // is owned by cycle2 (after promotion/archival). Created WITH NO DATA so
+  // bootstrap is fast; first refresh happens on the first cycle2 run.
+  await db.exec(`
+    CREATE MATERIALIZED VIEW IF NOT EXISTS mv_hot_active AS
+    SELECT id, element, summary, category, status, score, last_seen_at, promoted_at,
+           project_id, embedding, search_tsv
+    FROM entries
+    WHERE is_root = 1 AND status = 'active' AND embedding IS NOT NULL
+    WITH NO DATA
+  `)
+  await db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS mv_hot_active_id ON mv_hot_active(id)`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS mv_hot_active_hnsw ON mv_hot_active USING hnsw (embedding halfvec_cosine_ops)`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS mv_hot_active_tsv  ON mv_hot_active USING GIN (search_tsv)`)
+  await db.exec(`CREATE INDEX IF NOT EXISTS mv_hot_active_score ON mv_hot_active(score DESC)`)
+
+  await db.query(
+    `INSERT INTO meta(key, value) VALUES ($1, $2::jsonb)
+     ON CONFLICT(key) DO UPDATE SET value = EXCLUDED.value`,
+    ['embedding.current_dims', JSON.stringify(dimCount)],
+  )
+  await db.query(
+    `INSERT INTO meta(key, value) VALUES ($1, $2::jsonb)
+     ON CONFLICT(key) DO UPDATE SET value = EXCLUDED.value`,
+    ['boot.schema_bootstrap_complete', JSON.stringify('1')],
+  )
+}
+
+// Validate that the halfvec column dimension stored in the DB matches
+// dimCount from the current model config. Call after schema is confirmed
+// complete and before any embedding operations.
+export async function validateEmbeddingDims(db, dimCount) {
+  const r = await db.query(`
+    SELECT atttypmod
+    FROM pg_attribute a
+    JOIN pg_class c ON c.oid = a.attrelid
+    WHERE c.relname = 'entries'
+      AND a.attname = 'embedding'
+      AND a.attnum > 0
+      AND NOT a.attisdropped
+  `)
+  const row = r.rows[0]
+  if (!row) return // column absent — pre-schema DB; bootstrapSchema will handle
+  // pgvector halfvec stores dimension as atttypmod directly (unlike varchar which uses dims+4).
+  const colDims = row.atttypmod
+  if (colDims !== dimCount) {
+    throw new Error(
+      `Embedding dimension mismatch: DB column halfvec(${colDims}) vs model config ${dimCount} dims. ` +
+      `Reconfigure the embedding model or rebuild the memory store before booting.`
+    )
+  }
+}
+
+export async function ensureCurrentSchemaExtensions(db, dims) {
+  // core_entries gained an embedding column for cross-table semantic dedup
+  // between user-curated rows and cycle2-promoted entries. ALTER + index are
+  // idempotent and define the current runtime schema.
+  if (Number.isInteger(dims) && dims > 0) {
+    await db.exec(`ALTER TABLE core_entries ADD COLUMN IF NOT EXISTS embedding halfvec(${dims})`)
+    await db.exec(`CREATE INDEX IF NOT EXISTS core_entries_embedding_hnsw ON core_entries USING hnsw (embedding halfvec_cosine_ops) WHERE embedding IS NOT NULL`)
+  }
+  await db.exec(`ALTER TABLE entries ADD COLUMN IF NOT EXISTS core_summary text`)
+
+
+
+  // Dedupe core_entries before creating the unique index — keeps the row with
+  // the most recent updated_at (id breaks ties), drops the rest.
+  const dedupe = await db.query(`
+    WITH ranked AS (
+      SELECT id,
+             row_number() OVER (
+               PARTITION BY project_id, element
+               ORDER BY updated_at DESC NULLS LAST, id DESC
+             ) AS rn
+      FROM core_entries
+    ), deleted AS (
+      DELETE FROM core_entries c
+      USING ranked r
+      WHERE c.id = r.id AND r.rn > 1
+      RETURNING c.id
+    )
+    SELECT count(*)::int AS n FROM deleted
+  `)
+  const deduped = Number(dedupe.rows?.[0]?.n ?? 0)
+  if (deduped > 0) {
+    process.stderr.write(`[memory] ensureCurrentSchemaExtensions: removed ${deduped} duplicate core_entries before unique index creation\n`)
+  }
+  try {
+    await db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS core_entries_unique_proj_elem ON core_entries (project_id, element) NULLS NOT DISTINCT`)
+  } catch (err) {
+    process.stderr.write(`[memory] ensureCurrentSchemaExtensions: core_entries_unique_proj_elem creation failed — duplicate rows must be deduplicated before this index can be created: ${err?.message || err}\n`)
+    throw err
+  }
+}
+
+export async function openDatabase(dataDir, dims) {
+  const key = resolve(dataDir)
+
+  // Fast path — already resolved.
+  if (dbs.get(key)) return dbs.get(key)
+
+  // Dedupe concurrent callers — return the in-flight Promise if one exists.
+  if (opening.has(key)) return opening.get(key)
+
+  const promise = (async () => {
+    mkdirSync(key, { recursive: true })
+
+    const { db, pool } = await ensurePgInstance(dataDir, { schema: 'memory' })
+
+    if (!(await isBootstrapComplete(db))) {
+      // Serialize the schema/CREATE TYPE bootstrap across concurrent first-boot
+      // processes with a cluster-global advisory lock. Re-check completion once
+      // the lock is held (double-checked locking) so a worker that lost the
+      // race skips the redundant DDL instead of re-running init().
+      await withSchemaBootstrapLock(pool, async () => {
+        if (!(await isBootstrapComplete(db))) {
+          await init(db, dims)
+        }
+      })
+    }
+    await ensureCurrentSchemaExtensions(db, Number(dims))
+    await validateEmbeddingDims(db, Number(dims))
+
+    dbs.set(key, db)
+    return db
+  })()
+
+  opening.set(key, promise)
+  try {
+    return await promise
+  } finally {
+    opening.delete(key)
+  }
+}
+
+export function getDatabase(dataDir) {
+  if (!dataDir) return null
+  const key = resolve(dataDir)
+  return dbs.get(key) ?? null
+}
+
+export async function closeDatabase(dataDir) {
+  const key = resolve(dataDir)
+  const db = dbs.get(key)
+  if (!db) return
+  try { await db.close() } catch {}
+  dbs.delete(key)
+  // Evict pg-adapter's instance cache too: db.close() ends the pool, but the
+  // adapter still holds `instances.get(key)` pointing at the ended pool. A
+  // same-process reopen would then return the dead handle. closePgInstance
+  // drops the cache entry (and re-ends the pool, which is a safe no-op on
+  // an already-ended pool) so the next ensurePgInstance rebuilds fresh.
+  try { await closePgInstance(dataDir, { schema: 'memory' }) } catch {}
+}
+
+export async function isBootstrapComplete(db) {
+  try {
+    const r = await db.query(`SELECT 1 FROM meta WHERE key = 'boot.schema_bootstrap_complete'`)
+    return r.rows.length > 0
+  } catch {
+    return false
+  }
+}
+
+// Returns the raw JSON-encoded string stored in meta.value. Callers JSON.parse
+// it themselves; preserves API parity with the prior TEXT column.
+export async function getMetaValue(db, key, fallback = null) {
+  try {
+    const r = await db.query(`SELECT value::text AS v FROM meta WHERE key = $1`, [key])
+    if (r.rows.length === 0) return fallback
+    return r.rows[0].v ?? fallback
+  } catch {
+    return fallback
+  }
+}
+
+// Caller passes a JSON-encoded string (e.g. JSON.stringify(obj) or a quoted
+// scalar like '"v1"'). Stored verbatim into the JSONB column.
+export async function setMetaValue(db, key, value) {
+  await db.query(
+    `INSERT INTO meta(key, value) VALUES ($1, $2::jsonb)
+     ON CONFLICT(key) DO UPDATE SET value = EXCLUDED.value`,
+    [key, value == null ? 'null' : String(value)],
+  )
+}
+
+export function embeddingToSql(arr) {
+  if (!arr || !Array.isArray(arr)) return null
+  return `[${arr.map((n) => Number(n).toFixed(6)).join(',')}]`
+}