@gotcos/glasses-server 6.44.10 → 6.44.13

package/CHANGELOG.md

@@ -1,3 +1,71 @@
+## 6.44.13
+
+Prune or accept a captured memory, and guardrails that prune nonsense for you.
+
+- Miles 2026-09-07, looking at a captured decision that read "AAAA...":
+  "we need the ability to either prune or accept the memory", and "an
+  automated review ... another person could set their own guardrails that
+  automatically just prune out stuff like this."
+- `POST /api/context/memory/:id/review` `{ decision: accept | prune, note? }`
+  stamps a captured memory as reviewed or deletes it; either way a review
+  ledger row (`accepted`, `pruned`) the learning timeline shows. Both are new
+  event types.
+- `GET` and `PUT /api/context/memory-guardrails`: the user's own rules
+  (minimum words, distinct characters, a repeat-ratio ceiling, banned
+  patterns, and an optional model pass: on or off, the tier, at most N per
+  run). The same rules refuse nonsense at capture time in the bridge's COS.
+- `POST /api/context/memory-guardrails/run` `{ days?, apply?, llm? }` scans
+  the captured memories, judges them (rules first; the model pass against
+  the COS philosophy principles only on what survives, only when enabled),
+  and returns every verdict with its reasons. Nothing is deleted without
+  `apply`; a record a person accepted is never flagged.
+- Includes 6.44.12, never published.
+
+## 6.44.12
+
+The Knowledge down-select, and a fail-closed embedding gate.
+
+- Miles 2026-09-07: the local embeddings are the free path for people who
+  run COS without an OpenAI key, and the setup's job is to help each person
+  down-select. The `embedding` block now carries `preference.local_only`
+  (the one question the user answers: may text leave this Mac?),
+  `recommended` (which provider to mark and the one-sentence reason: a key
+  plus the cloud allowed recommends OpenAI large; stay local recommends
+  Local premium when Ollama is running on the Mac, else Local light), and
+  `ready`/`fix` for the chosen provider. Every provider row carries
+  `present` (the key, Ollama, or the engine is there) and `fix` (the
+  sentence that makes it ready) beside `ready`.
+- `POST /api/context/graph/setup/embedding` accepts `local_only` (boolean),
+  alone or with `provider`; alone it moves the Recommended mark and changes
+  no choice. One of `provider` or `local_only` is required.
+- Every indexing kickoff (`POST /api/context/graph/ingest`, `/setup/sample`)
+  answers 409 `embedding_not_ready` `{ provider, fix, message }` when the
+  chosen embedding cannot embed on this Mac right now (no key, Ollama not
+  running or the model not pulled, fastembed absent), instead of spawning an
+  indexer that dies in its log. A status block without `ready` counts as
+  not ready.
+- The ingest kickoff's bridge budget is 20 s, not 5: the readiness gate probes
+  Ollama before it spawns, and the spawn still returns at once.
+
+## 6.44.11
+
+Choose how Knowledge indexes: the embedding and the extraction tier.
+
+- The setup checklist carries an `embedding` block (the chosen provider,
+  model and dimensions; whether the graph is locked to it; every provider's
+  readiness on this Mac; a fetch receipt) and an `extraction` block (the
+  tier and the three choices).
+- `POST /api/context/graph/setup/embedding` `{ provider, model?, fetch? }`
+  chooses OpenAI large (the historical default), OpenAI small, a local premium
+  model through Ollama, or a local light model through fastembed/ONNX, and can
+  start the local model's fetch. One choice serves LightRAG and every Qdrant
+  collection. A graph built with another embedding answers 409
+  `embedding_locked`, and every indexing kickoff answers `embedding_mismatch`
+  rather than opening a dimension-bound store with the wrong vectors.
+- `POST /api/context/graph/setup/extraction` `{ tier }` chooses Fast (Haiku),
+  Balanced (Sonnet) or Deep (Opus) for entity extraction; it takes effect on
+  the next run.
+
 ## 6.44.10
 
 Ingest progress for COS Control.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.44.10",
+  "version": "6.44.13",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {

package/server/lib/cos-context-browser.ts

@@ -470,7 +470,8 @@ export function normalizeGraphBlock(value: unknown): GraphBlock | null {
 // ── Recent learning payloads (GET /context/learning, /context/learning/:id) ──
 
 export const LEARNING_EVENT_ID_PATTERN = /^evt_[a-f0-9]{16}$/
-export const LEARNING_EVENT_TYPES = new Set(['captured', 'proposed', 'promotable', 'saved', 'retrieved', 'used', 'checked', 'dismissed', 'reverted', 'reopened', 'consolidated', 'previewed'])
+export const LEARNING_EVENT_TYPES = new Set(['captured', 'proposed', 'promotable', 'saved', 'retrieved', 'used', 'checked', 'dismissed', 'reverted', 'reopened', 'consolidated', 'previewed', 'accepted', 'pruned'])
+export const REVIEW_DECISIONS = new Set(['dismissed', 'reopened', 'accepted', 'pruned'])
 const LEARNING_LIST_LIMIT = 50
 /** The strict To review set is small (121 today); one page shows it whole. */
 export const LEARNING_REVIEW_LIMIT = 200
@@ -783,7 +784,7 @@ export function normalizeReviewDecision(value: unknown): Record<string, unknown>
   if (!row) return null
   const decision = stringOrAbsent(row.decision, 16)
   const lessonId = stringOrAbsent(row.lesson_id, 200)
-  if (!lessonId || (decision !== 'dismissed' && decision !== 'reopened')) return null
+  if (!lessonId || !decision || !REVIEW_DECISIONS.has(decision)) return null
   return {
     lesson_id: lessonId,
     decision,
@@ -853,6 +854,67 @@ function chosenPathOrAbsent(value: unknown, max = 1000): string | undefined {
 export const KNOWLEDGE_ASK_MAX_CHARS = 400
 
 export interface KnowledgeSetupCheck { id: string; ok: boolean; detail: string }
+
+export const EMBEDDING_PROVIDERS = ['openai-large', 'openai-small', 'ollama', 'onnx'] as const
+export const EXTRACTION_TIERS = ['haiku', 'sonnet', 'opus'] as const
+
+/** `embedding` block of the setup status (6.44.11): the choice, the lock, every provider's readiness. */
+export function normalizeEmbeddingBlock(value: unknown): Record<string, unknown> | null {
+  const e = asRecord(value)
+  if (!e) return null
+  const manifest = asRecord(e.manifest)
+  const fetch = asRecord(e.fetch)
+  const providers = (Array.isArray(e.providers) ? e.providers : []).flatMap((row) => {
+    const r = asRecord(row); const id = r ? stringOrAbsent(r.id, 24) : undefined
+    if (!id) return []
+    return [{
+      id, label: stringOrAbsent(r!.label, 40) ?? id, model: stringOrAbsent(r!.model, 120) ?? '', dimensions: integerOrAbsent(r!.dimensions) ?? null,
+      kind: r!.kind === 'local' ? 'local' : 'cloud', cost: stringOrAbsent(r!.cost, 200) ?? '', needs: stringOrAbsent(r!.needs, 200) ?? '',
+      ready: r!.ready === true, present: r!.present === true, detail: stringOrAbsent(r!.detail, 200) ?? '',
+      fix: stringOrAbsent(r!.fix, 300) ?? null, selected: r!.selected === true,
+    }]
+  })
+  // 6.44.12: the down-select. `preference.local_only` is the one question the
+  // user answers (may text leave this Mac?), `recommended` the mark it moves,
+  // `ready`/`fix` whether the chosen provider can embed right now and what
+  // would make it so. Absent on an older bridge: null, never a guess.
+  const preference = asRecord(e.preference)
+  const recommended = asRecord(e.recommended)
+  const recommendedId = recommended ? stringOrAbsent(recommended.id, 24) : undefined
+  return {
+    ready: e.ready === true,
+    fix: stringOrAbsent(e.fix, 300) ?? null,
+    preference: { local_only: preference && typeof preference.local_only === 'boolean' ? preference.local_only : null },
+    recommended: recommendedId ? {
+      id: recommendedId, label: stringOrAbsent(recommended!.label, 40) ?? recommendedId, reason: stringOrAbsent(recommended!.reason, 300) ?? '',
+      local_only: typeof recommended!.local_only === 'boolean' ? recommended!.local_only : null,
+      key_present: recommended!.key_present === true, ollama_present: recommended!.ollama_present === true,
+    } : null,
+    provider: stringOrAbsent(e.provider, 24) ?? null,
+    label: stringOrAbsent(e.label, 40) ?? null,
+    model: stringOrAbsent(e.model, 120) ?? null,
+    dimensions: integerOrAbsent(e.dimensions) ?? null,
+    kind: e.kind === 'local' ? 'local' : 'cloud',
+    cost: stringOrAbsent(e.cost, 200) ?? null,
+    chosen_at: isoOrAbsent(e.chosen_at) ?? null,
+    locked: e.locked === true,
+    mismatch: e.mismatch === true,
+    manifest: manifest ? { provider: stringOrAbsent(manifest.provider, 24) ?? null, model: stringOrAbsent(manifest.model, 120) ?? null, dimensions: integerOrAbsent(manifest.dimensions) ?? null, adopted: manifest.adopted === true } : null,
+    providers,
+    fetch: fetch ? { provider: stringOrAbsent(fetch.provider, 24) ?? null, model: stringOrAbsent(fetch.model, 120) ?? null, state: stringOrAbsent(fetch.state, 16) ?? 'unknown', pid: integerOrAbsent(fetch.pid) ?? null, started_at: isoOrAbsent(fetch.started_at) ?? null, ended_at: isoOrAbsent(fetch.ended_at) ?? null, error: stringOrAbsent(fetch.error, 300) ?? null } : null,
+  }
+}
+
+/** `extraction` block: the tier and the three choices. */
+export function normalizeExtractionBlock(value: unknown): Record<string, unknown> | null {
+  const x = asRecord(value)
+  if (!x) return null
+  const tiers = (Array.isArray(x.tiers) ? x.tiers : []).flatMap((row) => {
+    const r = asRecord(row); const id = r ? stringOrAbsent(r.id, 16) : undefined
+    return id ? [{ id, label: stringOrAbsent(r!.label, 40) ?? id, detail: stringOrAbsent(r!.detail, 200) ?? '', selected: r!.selected === true }] : []
+  })
+  return { tier: stringOrAbsent(x.tier, 16) ?? null, label: stringOrAbsent(x.label, 40) ?? null, detail: stringOrAbsent(x.detail, 200) ?? null, tiers }
+}
 export interface KnowledgeSetupSource { path: string; enabled: boolean; exists: boolean; files: number | null; added_at: string | null }
 
 /** `graph-setup-status`: the checklist behind the Knowledge setup path. */
@@ -892,6 +954,8 @@ export function normalizeKnowledgeSetup(value: unknown): Record<string, unknown>
       indexed: integerOrAbsent(sample.indexed) ?? 0,
     },
     lock: normalizeIngestKickoff({ lock: s.lock }).lock,
+    embedding: normalizeEmbeddingBlock(s.embedding),
+    extraction: normalizeExtractionBlock(s.extraction),
     ask_ready: s.ask_ready === true,
     protocol: integerOrAbsent(s.protocol) ?? null,
   }
@@ -955,6 +1019,47 @@ export function normalizeIngestProgress(value: unknown): Record<string, unknown>
   }
 }
 
+export const GUARDRAIL_LLM_TIERS = ['haiku', 'sonnet', 'opus'] as const
+
+/** The user's memory guardrails (6.44.13), every field bounded. */
+export function normalizeGuardrails(value: unknown): Record<string, unknown> | null {
+  const g = asRecord(value)
+  if (!g) return null
+  const llm = asRecord(g.llm_review) ?? {}
+  return {
+    min_words: integerOrAbsent(g.min_words) ?? 6,
+    min_distinct_chars: integerOrAbsent(g.min_distinct_chars) ?? 8,
+    max_repeat_ratio: typeof g.max_repeat_ratio === 'number' && Number.isFinite(g.max_repeat_ratio) ? g.max_repeat_ratio : 0.5,
+    banned_patterns: (Array.isArray(g.banned_patterns) ? g.banned_patterns : []).filter((p): p is string => typeof p === 'string').slice(0, 50).map(p => p.slice(0, 200)),
+    llm_review: {
+      enabled: llm.enabled === true,
+      model: (GUARDRAIL_LLM_TIERS as readonly string[]).includes(String(llm.model)) ? String(llm.model) : 'haiku',
+      max_per_run: integerOrAbsent(llm.max_per_run) ?? 20,
+    },
+    updated_at: isoOrAbsent(g.updated_at) ?? null,
+    by: stringOrAbsent(g.by, 32) ?? null,
+  }
+}
+
+/** One guardrails run: the receipt and the verdicts with their reasons. */
+export function normalizeGuardrailsRun(value: unknown): Record<string, unknown> {
+  const s = asRecord(value) ?? {}
+  const r = asRecord(s.run) ?? {}
+  const verdicts = (Array.isArray(s.verdicts) ? s.verdicts : []).flatMap((row) => {
+    const v = asRecord(row); const id = v ? stringOrAbsent(v.id, 200) : undefined
+    if (!id) return []
+    const verdict = v!.verdict === 'prune' || v!.verdict === 'keep' || v!.verdict === 'review' ? v!.verdict : 'review'
+    return [{ id, type: stringOrAbsent(v!.type, 32) ?? '', created_at: isoOrAbsent(v!.created_at) ?? null, excerpt: typeof v!.excerpt === 'string' ? v!.excerpt.slice(0, 200) : '', verdict,
+      reasons: (Array.isArray(v!.reasons) ? v!.reasons : []).filter((x): x is string => typeof x === 'string').slice(0, 8).map(x => x.slice(0, 300)), by: stringOrAbsent(v!.by, 16) ?? 'rules', applied: v!.applied === true }]
+  }).slice(0, 500)
+  return {
+    run: { id: stringOrAbsent(r.id, 64) ?? null, started_at: isoOrAbsent(r.started_at) ?? null, ended_at: isoOrAbsent(r.ended_at) ?? null, days: integerOrAbsent(r.days) ?? null,
+      scanned: integerOrAbsent(r.scanned) ?? 0, flagged: integerOrAbsent(r.flagged) ?? 0, review: integerOrAbsent(r.review) ?? 0, kept: integerOrAbsent(r.kept) ?? 0,
+      llm_reviewed: integerOrAbsent(r.llm_reviewed) ?? 0, llm_enabled: r.llm_enabled === true, applied: r.applied === true, pruned: integerOrAbsent(r.pruned) ?? 0 },
+    verdicts,
+  }
+}
+
 export function normalizeContextBrowserStatus(value: unknown): ContextBrowserStatus {
   const source = value && typeof value === 'object' && !Array.isArray(value)
     ? value as Record<string, unknown> : {}

package/server/lib/python-bridge.ts

@@ -65,6 +65,11 @@ export const LEARNING_COMMANDS = [
   'graph-ask',
   'graph-schedule',
   'graph-ingest-progress',
+  'graph-setup-embedding',
+  'graph-setup-extraction',
+  'memory-review',
+  'memory-guardrails',
+  'memory-guardrails-run',
 ] as const
 
 // The optional Python bridge is available only when the user points us at a real
@@ -246,6 +251,11 @@ function standaloneNoop(args: string[]): unknown {
     case 'graph-ask':
     case 'graph-schedule':
     case 'graph-ingest-progress':
+    case 'graph-setup-embedding':
+    case 'graph-setup-extraction':
+    case 'memory-review':
+    case 'memory-guardrails':
+    case 'memory-guardrails-run':
       return { error: 'cos_pipeline_not_configured' }
     case 'task-rows':
     case 'task-capture':

package/server/routes/memory.ts

@@ -30,6 +30,12 @@ import { normalizeReviewDecision, LEARNING_REVIEW_LIMIT,
   normalizeSampleKickoff,
   normalizeGraphAnswer,
   normalizeIngestProgress,
+  normalizeEmbeddingBlock,
+  normalizeExtractionBlock,
+  normalizeGuardrails,
+  normalizeGuardrailsRun,
+  EMBEDDING_PROVIDERS,
+  EXTRACTION_TIERS,
   KNOWLEDGE_SETUP_SAMPLE_MAX,
   KNOWLEDGE_ASK_MAX_CHARS,
   normalizeLearningEventDetail,
@@ -197,6 +203,92 @@ memoryRouter.post('/context/learning/:id/review', async (req, res) => {
   }
 })
 
+// ── Memory review and guardrails (6.44.13) ──────────────────────────
+//
+// Accept stamps a captured memory as reviewed; prune deletes it. Both are
+// review-ledger rows the timeline shows. The guardrails are the user's own
+// rules; a run scans, judges (rules, then an optional bounded model pass),
+// and prunes only with apply.
+
+memoryRouter.post('/context/memory/:id/review', async (req, res) => {
+  noStore(res)
+  const memoryId = String(req.params.id)
+  const decision = typeof req.body?.decision === 'string' ? req.body.decision : ''
+  if (!memoryId || memoryId.length > 200 || CONTROL_CHARACTER.test(memoryId)) { res.status(400).json({ error: 'invalid_memory_id' }); return }
+  if (decision !== 'accept' && decision !== 'prune') { res.status(400).json({ error: 'invalid_decision', message: 'decision must be accept or prune' }); return }
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  try {
+    const note = typeof req.body?.note === 'string' ? req.body.note.slice(0, 400) : ''
+    const answer = await callPython(['memory-review', `--id=${memoryId}`, `--decision=${decision}`, ...(note ? [`--note=${note}`] : [])], 20_000)
+    const code = bridgeErrorCode(answer)
+    if (code) { sendSetupError(res, code, answer); return }
+    const a = answer as { decision?: unknown; deleted?: unknown }
+    const row = normalizeReviewDecision({ decision: a.decision })
+    if (!row) { res.status(503).json({ error: 'memory_review_unavailable' }); return }
+    res.json({ decision: row, deleted: a.deleted === true })
+  } catch (error) {
+    console.warn('[context] memory review bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'memory_unavailable' })
+  }
+})
+
+memoryRouter.get('/context/memory-guardrails', async (_req, res) => {
+  noStore(res)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  try {
+    const answer = await callPython(['memory-guardrails'], 15_000)
+    const code = bridgeErrorCode(answer)
+    if (code) { sendSetupError(res, code, answer); return }
+    const a = answer as { guardrails?: unknown; philosophy_rubric_lines?: unknown }
+    res.json({ guardrails: normalizeGuardrails(a.guardrails), philosophy_rubric_lines: Number.isInteger(a.philosophy_rubric_lines) ? a.philosophy_rubric_lines : 0 })
+  } catch (error) {
+    console.warn('[context] guardrails bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'memory_unavailable' })
+  }
+})
+
+memoryRouter.put('/context/memory-guardrails', async (req, res) => {
+  noStore(res)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  const body = req.body
+  if (!body || typeof body !== 'object' || Array.isArray(body)) { res.status(400).json({ error: 'invalid_guardrails', message: 'the body must be a JSON object' }); return }
+  const text = JSON.stringify(body)
+  if (text.length > 16_000) { res.status(400).json({ error: 'invalid_guardrails', message: 'the guardrails patch is too large' }); return }
+  try {
+    const answer = await callPython(['memory-guardrails', '--stdin'], 15_000, text)
+    const code = bridgeErrorCode(answer)
+    if (code) { sendSetupError(res, code, answer); return }
+    const a = answer as { guardrails?: unknown; philosophy_rubric_lines?: unknown }
+    res.json({ guardrails: normalizeGuardrails(a.guardrails), philosophy_rubric_lines: Number.isInteger(a.philosophy_rubric_lines) ? a.philosophy_rubric_lines : 0 })
+  } catch (error) {
+    console.warn('[context] guardrails bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'memory_unavailable' })
+  }
+})
+
+/** `{ days?, apply?, llm? }` → scan the captured memories; prune the flagged ones only with apply. Bounded: 30 days, one model pass of max_per_run. */
+memoryRouter.post('/context/memory-guardrails/run', async (req, res) => {
+  noStore(res)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  const body = (req.body ?? {}) as { days?: unknown; apply?: unknown; llm?: unknown }
+  const days = body.days === undefined || body.days === null ? 30 : Number(body.days)
+  if (!Number.isInteger(days) || days < 1 || days > 3650) { res.status(400).json({ error: 'invalid_days', message: 'days must be an integer from 1 to 3650' }); return }
+  if (body.apply !== undefined && typeof body.apply !== 'boolean') { res.status(400).json({ error: 'invalid_apply', message: 'apply must be true or false' }); return }
+  if (body.llm !== undefined && body.llm !== null && typeof body.llm !== 'boolean') { res.status(400).json({ error: 'invalid_llm', message: 'llm must be true or false' }); return }
+  const argv = ['memory-guardrails-run', `--days=${days}`]
+  if (body.apply === true) argv.push('--apply')
+  if (typeof body.llm === 'boolean') argv.push(`--llm=${body.llm}`)
+  try {
+    const answer = await callPython(argv, body.llm === false ? 60_000 : 400_000)
+    const code = bridgeErrorCode(answer)
+    if (code) { sendSetupError(res, code, answer); return }
+    res.json(normalizeGuardrailsRun(answer))
+  } catch (error) {
+    console.warn('[context] guardrails run bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'memory_unavailable' })
+  }
+})
+
 memoryRouter.get('/context/learning/:id', async (req, res) => {
   noStore(res)
   if (!LEARNING_EVENT_ID_PATTERN.test(req.params.id)) { res.status(400).json({ error: 'invalid_event_id' }); return }
@@ -331,14 +423,16 @@ memoryRouter.post('/context/graph/ingest', async (req, res) => {
     return
   }
   try {
-    const data = await callPython(['graph-ingest-start', `--limit=${limit}`, '--reason=control'], 5_000)
+    // 20 s, not 5: the kickoff gates on the embedding's readiness, which probes Ollama
+    // (2 s bound) before it spawns. The spawn itself still returns at once (QA 2026-09-07).
+    const data = await callPython(['graph-ingest-start', `--limit=${limit}`, '--reason=control'], 20_000)
     const code = bridgeErrorCode(data)
     if (code === 'not_owner') {
       const detail = data as { message?: unknown; owner_host?: unknown }
       res.status(409).json({ error: code, message: typeof detail.message === 'string' ? detail.message : undefined, owner_host: typeof detail.owner_host === 'string' ? detail.owner_host : null })
       return
     }
-    if (code) { res.status(code.startsWith('invalid_') ? 400 : 503).json({ error: code }); return }
+    if (code) { sendSetupError(res, code, data); return }
     res.status(202).json(normalizeIngestKickoff(data))
   } catch (error) {
     console.warn('[context] ingest bridge failure:', (error as Error).message)
@@ -372,6 +466,14 @@ memoryRouter.get('/context/graph/ingest/progress', async (_req, res) => {
 function sendSetupError(res: import('express').Response, code: string, data: unknown): void {
   const detail = asDetail(data)
   if (code === 'not_owner') { res.status(409).json({ error: code, message: detail.message, owner_host: detail.owner_host ?? null }); return }
+  if (code === 'embedding_locked' || code === 'embedding_mismatch') { res.status(409).json({ error: code, message: detail.message }); return }
+  if (code === 'embedding_not_ready') {
+    // 6.44.12: the chosen embedding cannot embed on this Mac right now. The
+    // bridge refused before spawning; pass its fix through so the page can show it.
+    const d = (typeof data === 'object' && data !== null ? data : {}) as { provider?: unknown; fix?: unknown }
+    res.status(409).json({ error: code, message: detail.message, provider: typeof d.provider === 'string' ? d.provider : null, fix: typeof d.fix === 'string' ? d.fix : null })
+    return
+  }
   if (code.endsWith('_not_found')) { res.status(404).json({ error: code, message: detail.message }); return }
   if (code.startsWith('invalid_')) { res.status(400).json({ error: code, message: detail.message }); return }
   res.status(503).json({ error: code })
@@ -468,6 +570,63 @@ memoryRouter.post('/context/graph/ask', async (req, res) => {
   }
 })
 
+/**
+ * `{ provider?, model?, fetch?, local_only? }` → the embedding for every knowledge store (6.44.11). 409 when the graph was built with another.
+ * 6.44.12: `local_only` (boolean) records the one question the down-select asks, may text leave this Mac; alone it moves the
+ * Recommended mark and changes no choice. One of `provider` or `local_only` is required.
+ */
+memoryRouter.post('/context/graph/setup/embedding', async (req, res) => {
+  noStore(res)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  const body = (req.body ?? {}) as { provider?: unknown; model?: unknown; fetch?: unknown; local_only?: unknown }
+  const provider = typeof body.provider === 'string' ? body.provider : ''
+  const hasPreference = body.local_only !== undefined && body.local_only !== null
+  if (hasPreference && typeof body.local_only !== 'boolean') { res.status(400).json({ error: 'invalid_local_only', message: 'local_only must be true or false' }); return }
+  if (!provider && !hasPreference) { res.status(400).json({ error: 'invalid_provider', message: `provider must be one of ${EMBEDDING_PROVIDERS.join(', ')}, or local_only must be given` }); return }
+  if (provider && !(EMBEDDING_PROVIDERS as readonly string[]).includes(provider)) { res.status(400).json({ error: 'invalid_provider', message: `provider must be one of ${EMBEDDING_PROVIDERS.join(', ')}` }); return }
+  const model = typeof body.model === 'string' ? body.model.trim() : ''
+  if (model.length > 120 || !/^[A-Za-z0-9._:/-]*$/.test(model)) { res.status(400).json({ error: 'invalid_model', message: 'model names are letters, digits, dots, colons, slashes and dashes' }); return }
+  const argv = ['graph-setup-embedding']
+  if (provider) argv.push(`--provider=${provider}`)
+  if (hasPreference) argv.push(`--local-only=${body.local_only === true ? 'true' : 'false'}`)
+  if (model) argv.push(`--model=${model}`)
+  if (body.fetch === true) argv.push('--fetch')
+  try {
+    const data = await callPython(argv, 90_000)
+    const code = bridgeErrorCode(data)
+    if (code) { sendSetupError(res, code, data); return }
+    const d = data as { embedding?: unknown; fetch?: unknown }
+    res.json({ embedding: normalizeEmbeddingBlock(d.embedding), fetch: asRecord(d.fetch) ? { started: (d.fetch as { started?: unknown }).started === true, already_running: (d.fetch as { already_running?: unknown }).already_running === true, pid: integerOrNull((d.fetch as { pid?: unknown }).pid) } : null })
+  } catch (error) {
+    console.warn('[context] embedding bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'graph_unavailable' })
+  }
+})
+
+/** `{ tier }` → the extraction tier: haiku (Fast), sonnet (Balanced), opus (Deep). */
+memoryRouter.post('/context/graph/setup/extraction', async (req, res) => {
+  noStore(res)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  const tier = typeof (req.body as { tier?: unknown } | undefined)?.tier === 'string' ? (req.body as { tier: string }).tier : ''
+  if (!(EXTRACTION_TIERS as readonly string[]).includes(tier)) { res.status(400).json({ error: 'invalid_tier', message: `tier must be one of ${EXTRACTION_TIERS.join(', ')}` }); return }
+  try {
+    const data = await callPython(['graph-setup-extraction', `--tier=${tier}`], 15_000)
+    const code = bridgeErrorCode(data)
+    if (code) { sendSetupError(res, code, data); return }
+    res.json({ extraction: normalizeExtractionBlock((data as { extraction?: unknown }).extraction) })
+  } catch (error) {
+    console.warn('[context] extraction bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'graph_unavailable' })
+  }
+})
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : null
+}
+function integerOrNull(value: unknown): number | null {
+  return typeof value === 'number' && Number.isInteger(value) ? value : null
+}
+
 /** `{ enabled, interval_s? }` → install or remove the scheduled batch agent on the owner Mac. */
 memoryRouter.post('/context/graph/setup/schedule', async (req, res) => {
   noStore(res)