synabun 1.3.0 → 2.0.0-beta

package/mcp-server/src/services/memory-sessions.ts

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { getDb } from './sqlite.js';
+
+export interface MemoryEvent {
+  host: 'claude-code'|'codex'|'opencode'; session_id: string; source_id: string;
+  project: string; timestamp: string; role: 'user'|'assistant'|'tool'; text: string;
+  cwd?: string; tools?: string[]; files?: string[];
+}
+function stableId(value: string) {
+  const hex = createHash('sha256').update(value).digest('hex');
+  return `${hex.slice(0,8)}-${hex.slice(8,12)}-5${hex.slice(13,16)}-a${hex.slice(17,20)}-${hex.slice(20,32)}`;
+}
+function visibleText(content: any): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.filter(b=>['text','input_text','output_text'].includes(b?.type)).map(b=>b.text || '').join('\n');
+}
+function clean(text: string) {
+  return text.replace(/<(system-reminder|environment_context|permissions|INSTRUCTIONS)>[\s\S]*?<\/\1>/g,'').trim();
+}
+/** Normalize only visible provider records, never reasoning or system text. */
+export function normalizeMemoryEvents(host: MemoryEvent['host'], records: any[], context: {session_id:string;project:string;cwd?:string}): MemoryEvent[] {
+  const events: MemoryEvent[] = [];
+  for (const [index,record] of records.entries()) {
+    let role: MemoryEvent['role']|undefined;
+    let text = '';
+    let tools: string[] = [];
+    if (host === 'claude-code') {
+      if (record.isMeta || record.isSidechain) continue;
+      if (record.type === 'user' && !record.toolUseResult && !record.sourceToolAssistantUUID) role='user';
+      if (record.type === 'assistant') role='assistant';
+      text = visibleText(record.message?.content);
+      tools = (Array.isArray(record.message?.content) ? record.message.content : []).filter((b:any)=>b.type==='tool_use').map((b:any)=>String(b.name));
+    } else if (host === 'codex') {
+      const p = record.type === 'response_item' ? record.payload : record;
+      if (p?.type === 'message' && ['user','assistant'].includes(p.role)) { role=p.role; text=visibleText(p.content); }
+      if (p?.type === 'userMessage') { role='user'; text=visibleText(p.content); }
+      if (p?.type === 'agentMessage') { role='assistant'; text=String(p.text || ''); }
+      if (p?.type === 'commandExecution') { role='tool'; text=String(p.aggregatedOutput || ''); tools=['commandExecution']; }
+      if (p?.type === 'function_call_output') {role='tool';text=String(p.output || '');}
+    } else {
+      const info = record.info || record;
+      if (['user','assistant'].includes(info.role)) role=info.role;
+      text=visibleText(record.parts || record.content);
+      tools=(record.parts || []).filter((p:any)=>p.type==='tool').map((p:any)=>String(p.tool));
+    }
+    text=clean(text);
+    if (!role || !text || text.startsWith('# AGENTS.md')) continue;
+    const timestamp = record.timestamp || record.info?.time?.created || record.createdAt;
+    events.push({...context,host,source_id:String(record.uuid || record.id || record.info?.id || `${index}`),role,text,tools,
+      timestamp: timestamp && Number.isFinite(new Date(timestamp).getTime()) ? new Date(timestamp).toISOString() : '1970-01-01T00:00:00.000Z'});
+  }
+  return events;
+}
+
+/** Durable intake: immediately keyword searchable, semantic work queued.
+ * Stable source keys make replay and partial imports idempotent. */
+export function ingestMemoryEvents(events: MemoryEvent[]) {
+  const d = getDb();
+  let indexed = 0;
+  for (let offset=0; offset<events.length; offset+=50) {
+    d.exec('BEGIN IMMEDIATE');
+    try {
+      for (const event of events.slice(offset,offset+50)) {
+        const hash = createHash('sha256').update(JSON.stringify(event)).digest('hex');
+        const prior = d.prepare('SELECT content_hash,chunk_id FROM memory_session_sources WHERE host=? AND session_id=? AND source_id=?')
+          .get(event.host,event.session_id,event.source_id);
+        if (prior?.content_hash === hash) continue;
+        const id = prior?.chunk_id ? String(prior.chunk_id) : stableId(`${event.host}:${event.session_id}:${event.source_id}`);
+        const now = new Date().toISOString();
+        d.prepare(`INSERT INTO session_chunks(id,vector,content,summary,session_id,project,cwd,start_timestamp,end_timestamp,tools_used,files_modified,indexed_at)
+          VALUES(?,?,?,?,?,?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET vector=excluded.vector,content=excluded.content,summary=excluded.summary,
+          project=excluded.project,cwd=excluded.cwd,start_timestamp=excluded.start_timestamp,end_timestamp=excluded.end_timestamp,
+          tools_used=excluded.tools_used,files_modified=excluded.files_modified,indexed_at=excluded.indexed_at`)
+          .run(id,new Uint8Array(384*4),event.text,`${event.role}: ${event.text.slice(0,500)}`,`${event.host}:${event.session_id}`,event.project,event.cwd || null,
+            event.timestamp,event.timestamp,JSON.stringify(event.tools || []),JSON.stringify(event.files || []),now);
+        d.prepare(`INSERT INTO memory_session_sources VALUES(?,?,?,?,?) ON CONFLICT(host,session_id,source_id)
+          DO UPDATE SET content_hash=excluded.content_hash`).run(event.host,event.session_id,event.source_id,hash,id);
+        d.prepare(`INSERT INTO memory_jobs(id,kind,entity_id,updated_at) VALUES(?,'session',?,?)
+          ON CONFLICT(kind,entity_id) DO UPDATE SET status='pending',attempts=0,error=NULL,updated_at=excluded.updated_at`).run(`session:${id}`,id,now);
+        indexed++;
+      }
+      d.exec('COMMIT');
+    } catch (error) {d.exec('ROLLBACK');throw error;}
+  }
+  return { indexed };
+}

package/mcp-server/src/services/memory-triage.ts

@@ -0,0 +1,182 @@
+/**
+ * Trash triage: rank forget candidates by how little they would be missed.
+ *
+ * Candidates come from cheap local signals — exact duplicate groups, the
+ * duplicate side of a judged `duplicate_of` relation, and old low-importance
+ * memories that were never recalled. The judgment scores each one on the
+ * expendability rubric so the list leads with the safest deletions. Nothing
+ * here deletes: the `memories` tool action `triage` and the Judgments tab
+ * render the list, and a person decides.
+ *
+ * Batches of candidates are judged in parallel and each fails alone. A score
+ * is stored beside the memory's metadata with a fingerprint of what was
+ * judged, and reused until that changes or a week passes, so a repeat triage
+ * only asks about new or changed candidates.
+ */
+
+import { getDb } from './sqlite.js';
+import { projectAliases } from '../config.js';
+import { judgeExpendability, expendabilityBasis, EXPENDABILITY_LEVELS, type ExpendabilityCandidate } from './memory-judgments.js';
+import { surfaceConfig, typesafeConfig } from './typesafe-config.js';
+import { typesafeEnabled, typesafeRetryAfterMs } from './typesafe.js';
+
+export interface TriageRow {
+  id: string; project: string; category: string; importance: number; created_at: string; access_count: number;
+  preview: string; reasons: string[];
+  /** 0 (irreplaceable) … 4 (expendable), or null when unjudged. */
+  expendability: number | null;
+  level: string | null;
+}
+
+const LEVEL_NAMES = EXPENDABILITY_LEVELS.map(l => l.split(':')[0]);
+const BATCH = 10;
+const JUDGE_CONCURRENCY = 6;
+const SCORE_TTL_MS = 7 * 86_400_000;
+/** Ceiling on candidates considered in one run: every one of them is judged and returned. */
+export const MAX_TRIAGE_LIMIT = 2000;
+/** Rows carried by a progress snapshot; the finished result carries all of them. */
+const PROGRESS_ROWS = 50;
+
+/** Local candidate discovery; no API calls. */
+export function findTriageCandidates(options: { project?: string | null; limit?: number } = {}): Array<TriageRow & { content: string; duplicateOf: string | null }> {
+  const d = getDb();
+  const limit = Math.max(1, Math.min(MAX_TRIAGE_LIMIT, Math.floor(options.limit ?? 20)));
+  const where: string[] = ['m.trashed_at IS NULL'];
+  const params: string[] = [];
+  if (options.project) {
+    const aliases = projectAliases(options.project).map(p => p.toLowerCase());
+    where.push(`lower(m.project) IN (${aliases.map(() => '?').join(',')})`);
+    params.push(...aliases);
+  }
+  const scope = where.join(' AND ');
+  const rows = new Map<string, TriageRow & { content: string; duplicateOf: string | null }>();
+  const add = (row: Record<string, unknown>, reason: string, duplicateOf: string | null = null) => {
+    const id = String(row.id);
+    const existing = rows.get(id);
+    if (existing) { if (!existing.reasons.includes(reason)) existing.reasons.push(reason); if (duplicateOf && !existing.duplicateOf) existing.duplicateOf = duplicateOf; return; }
+    rows.set(id, {
+      id, project: String(row.project), category: String(row.category), importance: Number(row.importance), created_at: String(row.created_at),
+      access_count: Number(row.access_count ?? 0), preview: String(row.content).slice(0, 240), content: String(row.content),
+      reasons: [reason], expendability: null, level: null, duplicateOf,
+    });
+  };
+  // Exact copies: every member but the oldest. CROSS JOIN pins the join order so
+  // the oldest-copy lookup starts from the content_hash index; left to itself the
+  // planner scanned the whole project once per copy (3.3 s on 24k memories).
+  for (const row of d.prepare(`SELECT m.id,m.project,m.category,m.importance,m.created_at,m.access_count,m.content,
+      (SELECT o.id FROM memory_metadata om CROSS JOIN memories o ON o.id=om.memory_id WHERE om.content_hash=md.content_hash AND o.trashed_at IS NULL AND o.project=m.project ORDER BY o.created_at,o.id LIMIT 1) AS oldest
+    FROM memories m JOIN memory_metadata md ON md.memory_id=m.id
+    WHERE ${scope} AND md.content_hash IN (SELECT md2.content_hash FROM memory_metadata md2 JOIN memories m2 ON m2.id=md2.memory_id WHERE m2.trashed_at IS NULL GROUP BY md2.content_hash,m2.project HAVING count(*)>1)
+    ORDER BY m.created_at DESC LIMIT ?`).all(...params, limit)) {
+    if (String(row.oldest) !== String(row.id)) add(row, `exact copy of ${String(row.oldest).slice(0, 8)}`, String(row.oldest));
+  }
+  // The newer side of a judged duplicate relation.
+  for (const row of d.prepare(`SELECT m.id,m.project,m.category,m.importance,m.created_at,m.access_count,m.content,r.to_id AS canonical
+    FROM memory_relations r JOIN memories m ON m.id=r.from_id JOIN memories t ON t.id=r.to_id
+    WHERE r.kind='duplicate_of' AND r.active=1 AND t.trashed_at IS NULL AND ${scope} ORDER BY r.created_at DESC LIMIT ?`).all(...params, limit)) {
+    add(row, `judged duplicate of ${String(row.canonical).slice(0, 8)}`, String(row.canonical));
+  }
+  // Old, unimportant, never recalled.
+  const cutoff = new Date(Date.now() - 90 * 86_400_000).toISOString();
+  for (const row of d.prepare(`SELECT m.id,m.project,m.category,m.importance,m.created_at,m.access_count,m.content FROM memories m
+    WHERE ${scope} AND m.importance<=3 AND m.access_count=0 AND m.created_at<? ORDER BY m.importance,m.created_at LIMIT ?`).all(...params, cutoff, limit)) {
+    add(row, 'importance ≤ 3, never recalled, older than 90 days');
+  }
+  return [...rows.values()]
+    .sort((a, b) => b.reasons.length - a.reasons.length || a.importance - b.importance || a.created_at.localeCompare(b.created_at))
+    .slice(0, limit);
+}
+
+type Candidate = ReturnType<typeof findTriageCandidates>[number];
+
+export interface TriageResult {
+  rows: TriageRow[]; judged: boolean; candidates: number;
+  /** Candidates still waiting on a judgment; above 0 only in progress snapshots. */
+  pending: number;
+  /** Candidates whose stored score was reused instead of asked again. */
+  saved: number;
+}
+
+const toCandidate = (c: Candidate): ExpendabilityCandidate => ({ id: c.id, content: c.content, category: c.category, importance: c.importance, createdAt: c.created_at, accessCount: c.access_count, duplicateOf: c.duplicateOf });
+
+function setScore(c: Candidate, s: number): void {
+  c.expendability = Number(s.toFixed(2));
+  c.level = LEVEL_NAMES[Math.max(0, Math.min(LEVEL_NAMES.length - 1, Math.round(s)))];
+}
+
+function rank(candidates: Candidate[], limit: number): TriageRow[] {
+  return [...candidates].sort((a, b) => {
+    if (a.expendability !== null && b.expendability !== null && a.expendability !== b.expendability) return b.expendability - a.expendability;
+    if ((a.expendability === null) !== (b.expendability === null)) return a.expendability === null ? 1 : -1;
+    return b.reasons.length - a.reasons.length || a.importance - b.importance || a.created_at.localeCompare(b.created_at);
+  }).slice(0, limit).map(({ content: _content, duplicateOf: _dup, ...row }) => row);
+}
+
+/** Reuse stored scores whose basis matches what would be sent now and that are younger than the TTL. */
+function applySavedScores(candidates: Candidate[], bases: Map<string, string>): number {
+  if (!candidates.length) return 0;
+  const stored = new Map(getDb().prepare(`SELECT memory_id,expendability,expendability_at,expendability_basis FROM memory_metadata
+    WHERE memory_id IN (${candidates.map(() => '?').join(',')}) AND expendability IS NOT NULL`).all(...candidates.map(c => c.id)).map(row => [String(row.memory_id), row]));
+  const cutoff = Date.now() - SCORE_TTL_MS;
+  let saved = 0;
+  for (const c of candidates) {
+    const row = stored.get(c.id);
+    if (!row || row.expendability_basis !== bases.get(c.id) || !(Date.parse(String(row.expendability_at)) > cutoff)) continue;
+    setScore(c, Number(row.expendability));
+    saved++;
+  }
+  return saved;
+}
+
+/** Store a batch's fresh scores. Update-only: a busy database or a missing metadata row costs a re-judgment next time, never the ranking. */
+function saveScores(batch: Candidate[], bases: Map<string, string>): void {
+  const d = getDb();
+  try { d.exec('BEGIN IMMEDIATE'); } catch { return; }
+  try {
+    const update = d.prepare('UPDATE memory_metadata SET expendability=?,expendability_at=?,expendability_basis=? WHERE memory_id=?');
+    const at = new Date().toISOString();
+    for (const c of batch) if (c.expendability !== null) update.run(c.expendability, at, bases.get(c.id) ?? null, c.id);
+    d.exec('COMMIT');
+  } catch {
+    try { d.exec('ROLLBACK'); } catch { /* already rolled back */ }
+  }
+}
+
+/**
+ * Candidates ranked by judged expendability, or by the local ordering when the
+ * judgment is unavailable. Stored scores are reused; the rest are judged in
+ * parallel batches that fail alone, and nothing new is sent while a 429's
+ * retry-after holds. `onProgress` gets the ranking so far as batches land.
+ */
+export async function triageMemories(options: { project?: string | null; limit?: number; onProgress?: (snapshot: TriageResult) => void; origin?: 'tool' | 'ui' } = {}): Promise<TriageResult> {
+  const limit = Math.max(1, Math.min(MAX_TRIAGE_LIMIT, Math.floor(options.limit ?? 20)));
+  const candidates = findTriageCandidates({ project: options.project, limit });
+  let saved = 0;
+  let pending = 0;
+  const snapshot = (rowCap = limit): TriageResult => ({ rows: rank(candidates, Math.min(limit, rowCap)), judged: candidates.some(c => c.expendability !== null), candidates: candidates.length, pending, saved });
+  const emit = () => { try { options.onProgress?.(snapshot(PROGRESS_ROWS)); } catch { /* a closed stream must not stop the judging */ } };
+  if (typesafeEnabled() && surfaceConfig('trash-triage').enabled) {
+    const model = typesafeConfig().model;
+    const bases = new Map(candidates.map(c => [c.id, expendabilityBasis(toCandidate(c), model)]));
+    saved = applySavedScores(candidates, bases);
+    const todo = candidates.filter(c => c.expendability === null);
+    const batches: Candidate[][] = [];
+    for (let i = 0; i < todo.length; i += BATCH) batches.push(todo.slice(i, i + BATCH));
+    pending = todo.length;
+    if (pending && !typesafeRetryAfterMs()) emit();
+    for (let i = 0; i < batches.length; i += JUDGE_CONCURRENCY) {
+      if (typesafeRetryAfterMs() > 0) break;
+      await Promise.allSettled(batches.slice(i, i + JUDGE_CONCURRENCY).map(async batch => {
+        const scores = await judgeExpendability(batch.map(toCandidate), { entityId: batch[0].id, origin: options.origin ?? 'tool', project: options.project ?? null, sessionId: null });
+        if (scores) {
+          for (const c of batch) { const s = scores.get(c.id); if (s !== undefined) setScore(c, s); }
+          saveScores(batch, bases);
+        }
+        pending -= batch.length;
+        if (pending > 0) emit();
+      }));
+    }
+    pending = 0;
+  }
+  return snapshot();
+}

package/mcp-server/src/services/memory-verification.ts

@@ -0,0 +1,68 @@
+import { createReadStream } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { isAbsolute, resolve } from 'node:path';
+import type { DatabaseSync } from 'node:sqlite';
+import { projectRoot } from '../config.js';
+import { surfaceConfig } from './typesafe-config.js';
+
+/** One file's edit-time stale verdict, stored per memory in memory_metadata.stale_verdicts. */
+export interface StaleVerdictRecord { p: number; hash: string | null; rev: number; at: string; session?: string | null }
+
+export function readStaleVerdicts(raw: unknown): Record<string, StaleVerdictRecord> {
+  try {
+    const value = JSON.parse(String(raw || '{}'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, StaleVerdictRecord> : {};
+  } catch { return {}; }
+}
+
+/**
+ * File checks are asynchronous and bounded, never on the recall request path.
+ *
+ * Relative paths resolve against the memory's registered project root — the
+ * process running this job may be the Neural Interface or any stdio server, so
+ * its own cwd says nothing about where the file lives. A relative path that
+ * cannot be anchored, or that is missing once anchored, is `unknown` rather
+ * than `stale`: the base may be wrong, and "stale" makes recall say so.
+ *
+ * A changed checksum counts as current when an edit-time judgment of this
+ * exact file content and this revision found the memory still accurate.
+ */
+export async function verifyMemorySources(d: DatabaseSync,id:string) {
+  const row=d.prepare('SELECT file_checksums,project FROM memories WHERE id=?').get(id);
+  if(!row)return;
+  const revision=Number(d.prepare('SELECT MAX(revision) AS n FROM memory_revisions WHERE memory_id=?').get(id)?.n || 1);
+  let checks: Record<string,string>;
+  try {checks=JSON.parse(String(row.file_checksums || '{}'));}catch{checks={};}
+  const files=Object.entries(checks);
+  const base=projectRoot(String(row.project || ''));
+  const verdicts=readStaleVerdicts(d.prepare('SELECT stale_verdicts FROM memory_metadata WHERE memory_id=?').get(id)?.stale_verdicts);
+  const floor=surfaceConfig('edit-stale').minProbability ?? 0.4;
+  let unknown=!files.length || files.length>10;
+  let stale=false;
+  for(const [file,expected] of files.slice(0,10)) {
+    const relative=!isAbsolute(file);
+    const target=relative ? (base ? resolve(base,file) : null) : file;
+    if(!target){unknown=true;continue;}
+    const hash=createHash('sha256');
+    const stream=createReadStream(target,{highWaterMark:64*1024});
+    let bytes=0;
+    try {
+      for await(const chunk of stream) {
+        bytes+=chunk.length;
+        if(bytes>4*1024*1024){unknown=true;break;}
+        hash.update(chunk);
+      }
+      if(bytes<=4*1024*1024) {
+        const digest=hash.digest('hex');
+        const judged=verdicts[file];
+        const judgedAccurate=judged && judged.hash===digest && judged.rev===revision && judged.p>=floor;
+        if(digest!==expected && !judgedAccurate)stale=true;
+      }
+    }catch(error){if((error as NodeJS.ErrnoException).code==='ENOENT'){if(relative)unknown=true;else stale=true;}else unknown=true;}
+    finally{stream.destroy();}
+  }
+  if(Number(d.prepare('SELECT MAX(revision) AS n FROM memory_revisions WHERE memory_id=?').get(id)?.n || 0)!==revision)return;
+  d.prepare(`INSERT INTO memory_metadata(memory_id,verification,verified_revision,checked_at) VALUES(?,?,?,?)
+    ON CONFLICT(memory_id) DO UPDATE SET verification=excluded.verification,verified_revision=excluded.verified_revision,checked_at=excluded.checked_at`)
+    .run(id,stale ? 'stale' : unknown ? 'unknown' : 'current',revision,new Date().toISOString());
+}

package/mcp-server/src/services/memory-writer.ts

@@ -0,0 +1,125 @@
+import { randomUUID, createHash } from 'node:crypto';
+import type { DatabaseSync } from 'node:sqlite';
+import { getDb, upsertMemory, memoryVectors } from './sqlite.js';
+import { generateEmbedding } from './local-embeddings.js';
+import { invalidateCache } from './neural-interface.js';
+import { projectAliases } from '../config.js';
+import { judgeDuplicates, type JudgeContext } from './memory-judgments.js';
+import { surfaceConfig } from './typesafe-config.js';
+import type { MemoryPayload } from '../types.js';
+
+export class IdempotencyConflict extends Error {}
+
+export interface WriteMemoryOptions {
+  idempotencyKey?: string;
+  kind?: string;
+  sourceRef?: string | null;
+  // Hooks can adopt a verified pre-upgrade receipt without creating a new row.
+  existingId?: string;
+  /** The id a new row gets, chosen by the caller so its judgments can be logged against it. */
+  id?: string;
+  /** Attribution for the duplicate-gate judgment. */
+  judge?: JudgeContext;
+}
+
+export interface WriteMemoryResult {
+  id: string;
+  existing: boolean;
+  pending: boolean;
+  /** Set when the duplicate gate refused the write: `id` is the memory it duplicates. */
+  duplicate?: { probability: number };
+}
+
+/** Cosine floor for "worth asking": generous, because the judgment decides. */
+const DUPLICATE_CANDIDATE_THRESHOLD = 0.9;
+
+/**
+ * Before insert, ask whether the new memory restates a fact already stored
+ * in the same project. Judged before any transaction; a null judgment means
+ * "store it" — maintenance still relates duplicates after the fact.
+ */
+async function duplicateGate(d: DatabaseSync, vector: number[], payload: MemoryPayload, context: JudgeContext = {}): Promise<{ id: string; probability: number } | null> {
+  const settings = surfaceConfig('duplicate-gate');
+  if (!settings.enabled) return null;
+  const aliases = projectAliases(payload.project).map(p => p.toLowerCase());
+  const ids = new Set(d.prepare(`SELECT id FROM memories WHERE trashed_at IS NULL AND lower(project) IN (${aliases.map(() => '?').join(',')})`).all(...aliases).map(r => String(r.id)));
+  if (!ids.size) return null;
+  const hits = memoryVectors.topK(vector, 3, DUPLICATE_CANDIDATE_THRESHOLD, ids);
+  if (!hits.length) return null;
+  const candidates = hits.map(hit => {
+    const row = d.prepare('SELECT content,created_at FROM memories WHERE id=? AND trashed_at IS NULL').get(hit.id) as { content?: string; created_at?: string } | undefined;
+    return { id: hit.id, content: String(row?.content ?? ''), recordedAt: row?.created_at ? String(row.created_at) : undefined };
+  }).filter(c => c.content);
+  if (!candidates.length) return null;
+  const verdicts = await judgeDuplicates(payload.content, candidates, context);
+  if (!verdicts?.size) return null;
+  let best: { id: string; probability: number } | null = null;
+  for (const [id, probability] of verdicts) if (!best || probability > best.probability) best = { id, probability };
+  return best && best.probability >= (settings.minConfidence ?? 0.85) ? best : null;
+}
+
+/** The receipt and new memory commit together, across MCP and hook processes. */
+export async function writeMemory(payload: MemoryPayload, options: WriteMemoryOptions = {}): Promise<WriteMemoryResult> {
+  const d = getDb();
+  const hash = createHash('sha256').update(payload.content).digest('hex');
+  const findRetry = () => options.idempotencyKey ? d.prepare(`
+    SELECT m.id, md.request_hash FROM memory_metadata md JOIN memories m ON m.id=md.memory_id
+    WHERE md.project=? AND md.category=? AND md.idempotency_key=?
+  `).get(payload.project, payload.category, options.idempotencyKey) : undefined;
+  const receipt = (row: Record<string, unknown>) => {
+    if (row.request_hash !== hash) throw new IdempotencyConflict('Idempotency key already belongs to different content.');
+    return { id: String(row.id), existing: true, pending: false };
+  };
+  const previous = findRetry();
+  if (previous) return receipt(previous);
+
+  // Check the old hook tracker inside the same transaction used by new writes.
+  const adopt = () => {
+    if (!options.existingId || !options.idempotencyKey) return undefined;
+    const row = d.prepare(`SELECT m.id, md.idempotency_key FROM memories m
+      LEFT JOIN memory_metadata md ON md.memory_id=m.id
+      WHERE m.id=? AND m.project=? AND m.category=? AND m.content=? AND m.source=? AND m.trashed_at IS NULL`)
+      .get(options.existingId, payload.project, payload.category, payload.content, payload.source);
+    if (!row || (row.idempotency_key && row.idempotency_key !== options.idempotencyKey)) return undefined;
+    d.prepare(`INSERT INTO memory_metadata(memory_id,kind,source_ref,content_hash,idempotency_key,project,category,request_hash)
+      VALUES(?,?,?,?,?,?,?,?) ON CONFLICT(memory_id) DO UPDATE SET idempotency_key=excluded.idempotency_key,request_hash=excluded.request_hash`)
+      .run(row.id, options.kind || 'note', options.sourceRef || null, hash, options.idempotencyKey, payload.project, payload.category, hash);
+    return { id: String(row.id), existing: true, pending: false };
+  };
+  if (options.existingId) {
+    d.exec('BEGIN IMMEDIATE');
+    try {
+      const found = findRetry();
+      const adopted = found ? receipt(found) : adopt();
+      d.exec('COMMIT');
+      if (adopted) return adopted;
+    } catch (error) { d.exec('ROLLBACK'); throw error; }
+  }
+
+  let pending = false;
+  let vector: number[];
+  try { vector = await generateEmbedding(payload.content); }
+  catch { vector = new Array(384).fill(0); pending = true; }
+  // The gate needs a real vector to find candidates; a pending embedding
+  // means maintenance will judge relations once it exists.
+  if (!pending) {
+    const duplicate = await duplicateGate(d, vector, payload, options.judge);
+    if (duplicate) return { id: duplicate.id, existing: true, pending: false, duplicate: { probability: duplicate.probability } };
+  }
+  const id = options.id ?? randomUUID();
+  d.exec('BEGIN IMMEDIATE');
+  try {
+    const retry = findRetry();
+    if (retry) {
+      const result = receipt(retry);
+      d.exec('COMMIT');
+      return result;
+    }
+    upsertMemory(id, vector, payload);
+    d.prepare('INSERT INTO memory_metadata(memory_id,kind,source_ref,content_hash,idempotency_key,project,category,request_hash) VALUES(?,?,?,?,?,?,?,?)')
+      .run(id, options.kind || 'note', options.sourceRef || null, hash, options.idempotencyKey || null, payload.project, payload.category, hash);
+    d.exec('COMMIT');
+  } catch (error) { d.exec('ROLLBACK'); memoryVectors.invalidate(); throw error; }
+  invalidateCache('remember', id);
+  return { id, existing: false, pending };
+}