wendkeep 0.73.0 → 0.74.0

package/packages/vault/src/memory-store.mjs

@@ -14,6 +14,12 @@ import {
   sanitizeMemoryText,
   validateMemoryEvent,
 } from './memory-schema.mjs';
+import {
+  effectiveMemoryScope,
+  isRegisterMemoryKey,
+  memoryRecordKey,
+  sameMemoryScope,
+} from './memory-scope.mjs';
 import {
   assertVaultPathSafe, assertVaultPathsSafe, mkdirVaultPath, unlinkVaultFile,
   VAULT_LOCK_BUSY, withVaultPathLock, writeVaultFileAtomic,
@@ -376,6 +382,7 @@ function sameCompleteCausalLineage(left, right) {
 }
 
 function comparable(left, right) {
+  if (left?.project_id !== right?.project_id || !sameMemoryScope(left, right)) return false;
   if (sameCausalActivation(left, right)) return true;
   const leftSupersedes = left.supersedes_event_id || left.supersedes;
   const rightSupersedes = right.supersedes_event_id || right.supersedes;
@@ -387,7 +394,7 @@ function comparable(left, right) {
 function conflictGroupKey(event) {
   if (event.operation !== 'replace') return null;
   if (!Number.isInteger(event.base_revision) || typeof event.base_value_hash !== 'string') return null;
-  return `${event.memory_key}\u0000${event.base_revision}\u0000${event.base_value_hash}`;
+  return `${memoryRecordKey(event)}\u0000${event.base_revision}\u0000${event.base_value_hash}`;
 }
 
 function candidateId(reason, memoryKey, eventIds) {
@@ -421,6 +428,7 @@ function blockedByCoreCandidate(event, coreValue) {
     reason: 'blocked_by_core',
     status: 'blocked_by_core',
     memory_key: event.memory_key,
+    ...(event.scope ? { scope: effectiveMemoryScope(event), record_key: memoryRecordKey(event) } : {}),
     event_ids: [event.event_id],
     proposed_value: event.value,
     core_value: coreValue,
@@ -442,6 +450,10 @@ function conflictCandidate(memoryKey, events, currentEvent = null) {
     candidate_id: candidateId('conflict', memoryKey, eventIds),
     reason: 'conflict',
     memory_key: memoryKey,
+    ...((ordered[0] || currentEvent)?.scope ? {
+      scope: effectiveMemoryScope(ordered[0] || currentEvent || {}),
+      record_key: memoryRecordKey(ordered[0] || currentEvent || { memory_key: memoryKey }),
+    } : {}),
     event_ids: eventIds,
     values: eventIds.map((id) => byId.get(id).value),
     base_revision: ordered[0]?.base_revision ?? currentEvent?.revision ?? 0,
@@ -459,6 +471,7 @@ function conflictReviewEvent(candidate, candidateCount = 1) {
     event_id: `mem-review-${candidate.candidate_id}`,
     project_id: source.project_id || '',
     memory_key: candidate.memory_key,
+    scope: candidate.scope,
     operation: 'assert',
     value: `[revisão pendente: ${memoryKey}; candidates: ${candidateCount}; events: ${eventCount}]`,
     authority: 'candidate',
@@ -508,7 +521,9 @@ function isCausallyOlder(event, current) {
   if (sameCausalActivation(event, current)) {
     return Number(event.turn_sequence) < Number(current.turn_sequence);
   }
-  if (Number.isInteger(event.activation_epoch) && Number.isInteger(current.activation_epoch)
+  if (event.canonical_session_id && event.canonical_session_id === current.canonical_session_id
+      && sameMemoryScope(event, current)
+      && Number.isInteger(event.activation_epoch) && Number.isInteger(current.activation_epoch)
       && event.activation_epoch !== current.activation_epoch) {
     return event.activation_epoch < current.activation_epoch;
   }
@@ -518,6 +533,30 @@ function isCausallyOlder(event, current) {
     && eventEffective < currentEffective;
 }
 
+const AUTHORITY_RANK = Object.freeze({ candidate: 0, reported: 1, verified: 2 });
+
+function sameRegisterLineage(left, right) {
+  return Boolean(left?.canonical_session_id)
+    && left.canonical_session_id === right?.canonical_session_id
+    && left.project_id === right?.project_id
+    && sameMemoryScope(left, right);
+}
+
+/** Positive means `incoming` is a safe successor; null means human comparison is required. */
+function registerPrecedence(incoming, current) {
+  if (!incoming?.scope || !current?.scope
+      || !isRegisterMemoryKey(incoming?.memory_key) || !sameRegisterLineage(incoming, current)) return null;
+  const epoch = Number(incoming.activation_epoch ?? -1) - Number(current.activation_epoch ?? -1);
+  if (epoch) return epoch;
+  const turn = Number(incoming.turn_sequence ?? -1) - Number(current.turn_sequence ?? -1);
+  if (turn) return turn;
+  const authority = (AUTHORITY_RANK[incoming.authority] ?? -1) - (AUTHORITY_RANK[current.authority] ?? -1);
+  if (authority) return authority;
+  const observed = String(incoming.observed_at || '').localeCompare(String(current.observed_at || ''));
+  if (observed) return observed;
+  return String(incoming.event_id || '').localeCompare(String(current.event_id || ''));
+}
+
 /**
  * Pure deterministic reducer. It pre-detects incomparable scalar siblings so replay order
  * never turns one concurrent writer into an accidental winner.
@@ -537,7 +576,21 @@ export function reduceMemoryEvents(inputEvents = [], {
     }
     if (!existing) unique.set(event.event_id, event);
   }
-  const events = [...unique.values()].sort(eventOrder);
+  const rescopeTargets = new Set(
+    [...unique.values()].flatMap((item) => [
+      item.rescopes_event_id,
+      ...(Array.isArray(item.rescopes_event_ids) ? item.rescopes_event_ids : []),
+    ]).filter(Boolean),
+  );
+  const projectIds = new Set([...unique.values()].map((item) => item.project_id).filter(Boolean));
+  if (projectIds.size > 1) {
+    const error = new TypeError('Memory reducer cannot compare events from different projects.');
+    error.code = 'MEMORY_PROJECT_MIXED';
+    throw error;
+  }
+  const events = [...unique.values()]
+    .filter((item) => !rescopeTargets.has(item.event_id))
+    .sort(eventOrder);
   const candidateDecisions = new Map();
   for (const item of events) {
     const decision = item.candidate_decision;
@@ -604,7 +657,8 @@ export function reduceMemoryEvents(inputEvents = [], {
       continue;
     }
 
-    const current = records.get(item.memory_key);
+    const recordKey = memoryRecordKey(item);
+    const current = records.get(recordKey);
     const currentSource = current?.source;
     if (isCausallyOlder(item, currentSource)) {
       superseded.push({ event_id: item.event_id, by_event_id: currentSource.event_id });
@@ -613,10 +667,12 @@ export function reduceMemoryEvents(inputEvents = [], {
 
     if (item.operation === 'assert') {
       if (current && hashMemoryValue(current.value) !== hashMemoryValue(item.value)) {
-        if (sameCausalActivation(item, currentSource)
-            && Number(item.turn_sequence) > Number(currentSource.turn_sequence)) {
-          records.set(item.memory_key, { value: item.value, revision: current.revision + 1, source: item });
-          tombstones.delete(item.memory_key);
+        const precedence = registerPrecedence(item, currentSource);
+        if ((sameCausalActivation(item, currentSource)
+              && Number(item.turn_sequence) > Number(currentSource.turn_sequence))
+            || precedence > 0) {
+          records.set(recordKey, { value: item.value, revision: current.revision + 1, source: item });
+          tombstones.delete(recordKey);
           superseded.push({ event_id: currentSource.event_id, by_event_id: item.event_id });
           revision += 1;
           appliedEventIds.push(item.event_id);
@@ -628,8 +684,8 @@ export function reduceMemoryEvents(inputEvents = [], {
         continue;
       }
       if (!current) {
-        records.set(item.memory_key, { value: item.value, revision: 1, source: item });
-        tombstones.delete(item.memory_key);
+        records.set(recordKey, { value: item.value, revision: 1, source: item });
+        tombstones.delete(recordKey);
         revision += 1;
       }
       appliedEventIds.push(item.event_id);
@@ -642,8 +698,8 @@ export function reduceMemoryEvents(inputEvents = [], {
       const byHash = new Map(oldValues.map((value) => [hashMemoryValue(value), value]));
       additions.forEach((value) => byHash.set(hashMemoryValue(value), value));
       const value = [...byHash.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([, entry]) => entry);
-      records.set(item.memory_key, { value, revision: (current?.revision || 0) + 1, source: item });
-      tombstones.delete(item.memory_key);
+      records.set(recordKey, { value, revision: (current?.revision || 0) + 1, source: item });
+      tombstones.delete(recordKey);
       revision += 1;
       appliedEventIds.push(item.event_id);
       continue;
@@ -664,13 +720,13 @@ export function reduceMemoryEvents(inputEvents = [], {
       if (item.value !== null && item.value !== undefined && Array.isArray(current.value)) {
         const removalHash = hashMemoryValue(item.value);
         const value = current.value.filter((entry) => hashMemoryValue(entry) !== removalHash);
-        records.set(item.memory_key, { value, revision: current.revision + 1, source: item });
-        tombstones.set(`${item.memory_key}:${removalHash}`, {
+        records.set(recordKey, { value, revision: current.revision + 1, source: item });
+        tombstones.set(`${recordKey}:${removalHash}`, {
           event_id: item.event_id, removed_event_id: current.source.event_id, value_hash: removalHash,
         });
       } else {
-        records.delete(item.memory_key);
-        tombstones.set(item.memory_key, {
+        records.delete(recordKey);
+        tombstones.set(recordKey, {
           event_id: item.event_id,
           removed_event_id: current.source.event_id,
           value_hash: hashMemoryValue(current.value),
@@ -691,8 +747,8 @@ export function reduceMemoryEvents(inputEvents = [], {
       candidates.push(conflictCandidate(item.memory_key, current ? [currentEventFromRecord(current), item] : [item]));
       continue;
     }
-    records.set(item.memory_key, { value: item.value, revision: current.revision + 1, source: item });
-    tombstones.delete(item.memory_key);
+    records.set(recordKey, { value: item.value, revision: current.revision + 1, source: item });
+    tombstones.delete(recordKey);
     const explicitlySupersededIds = new Set(
       Array.isArray(item.supersedes)
         ? item.supersedes
@@ -732,16 +788,16 @@ export function reduceMemoryEvents(inputEvents = [], {
       advanced = false;
       for (const pending of deferredAsserts) {
         if (resolvedCandidateIds.has(pending.candidate.candidate_id)) continue;
-        const current = records.get(pending.event.memory_key);
+        const current = records.get(memoryRecordKey(pending.event));
         const currentSource = current?.source;
         if (!sameCompleteCausalLineage(pending.event, currentSource)) continue;
         if (pending.event.turn_sequence > currentSource.turn_sequence) {
-          records.set(pending.event.memory_key, {
+          records.set(memoryRecordKey(pending.event), {
             value: pending.event.value,
             revision: current.revision + 1,
             source: pending.event,
           });
-          tombstones.delete(pending.event.memory_key);
+          tombstones.delete(memoryRecordKey(pending.event));
           superseded.push({ event_id: currentSource.event_id, by_event_id: pending.event.event_id });
           revision += 1;
           appliedEventIds.push(pending.event.event_id);
@@ -762,7 +818,7 @@ export function reduceMemoryEvents(inputEvents = [], {
     .map((candidate) => {
       const pending = pendingByCandidateId.get(candidate.candidate_id);
       if (!pending) return candidate;
-      const finalSource = currentEventFromRecord(records.get(candidate.memory_key));
+      const finalSource = currentEventFromRecord(records.get(candidate.record_key || candidate.memory_key));
       const previousSource = candidate.events?.find(
         (event) => event.event_id !== pending.event.event_id,
       );
@@ -791,10 +847,16 @@ export function reduceMemoryEvents(inputEvents = [], {
   superseded.sort((left, right) => left.event_id.localeCompare(right.event_id));
   const eventCursor = events.at(-1)?.event_id || 'none';
   const stateHash = hashMemoryValue({ state, tombstones: tombstoneObject });
+  const ambiguousRecordKeys = new Set(
+    unresolvedCandidates.map((candidate) => candidate.record_key || candidate.memory_key),
+  );
   const activeEvents = [
-    ...Object.entries(recordObject).map(([memoryKey, record]) => ({
+    ...Object.entries(recordObject)
+      .filter(([recordKey]) => !ambiguousRecordKeys.has(recordKey))
+      .map(([recordKey, record]) => ({
       ...record.source,
-      memory_key: memoryKey,
+      memory_key: record.source.memory_key,
+      projection_key: recordKey,
       operation: 'assert',
       value: record.value,
     })),

package/schema/observer/004-evidence-recall.sql

@@ -0,0 +1,25 @@
+CREATE TABLE IF NOT EXISTS document_chunks (
+  chunk_id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(project_id) ON DELETE CASCADE,
+  logical_path TEXT NOT NULL,
+  title TEXT NOT NULL DEFAULT '',
+  heading TEXT NOT NULL DEFAULT '',
+  entity_type TEXT NOT NULL DEFAULT 'document',
+  change_slug TEXT NOT NULL DEFAULT '',
+  session_id TEXT NOT NULL DEFAULT '',
+  work_session_id TEXT NOT NULL DEFAULT '',
+  authority TEXT NOT NULL DEFAULT 'candidate',
+  observed_at TEXT NOT NULL,
+  validity TEXT NOT NULL DEFAULT 'active',
+  content_hash TEXT NOT NULL,
+  ordinal INTEGER NOT NULL DEFAULT 0,
+  content TEXT NOT NULL,
+  FOREIGN KEY(project_id, logical_path) REFERENCES documents(project_id, logical_path) ON DELETE CASCADE,
+  UNIQUE(project_id, logical_path, ordinal)
+);
+
+CREATE INDEX IF NOT EXISTS idx_document_chunks_project_path
+  ON document_chunks(project_id, logical_path, ordinal);
+
+CREATE INDEX IF NOT EXISTS idx_document_chunks_project_type
+  ON document_chunks(project_id, entity_type, validity, observed_at);

package/src/memory.mjs

@@ -20,6 +20,7 @@ import {
 } from './validate-memory.mjs';
 import { validateCore } from './validate-core.mjs';
 import { checkMemoryBundle } from '../hooks/vault-health.mjs';
+import { scopeForMemoryKey } from '../hooks/memory-scope.mjs';
 
 const BRAIN = '.brain';
 const LEDGER = 'MEMORY_EVENTS.jsonl';
@@ -229,6 +230,92 @@ export function migrateMemory(vault, {
   }
 }
 
+function rescopeEventId(sourceEventId, scope) {
+  return `mem-rescope-${hash(`${sourceEventId}\0${scope.type}\0${scope.id}`).slice(0, 24)}`;
+}
+
+/** Plan an append-only migration without choosing a winner for ambiguous keys. */
+export function planScopedMemoryMigration(vault) {
+  const ledger = readMemoryLedger(vault);
+  if (ledger.status !== 'ok') throw new Error('Ledger corrompido; execute memory repair antes do rescope.');
+  const projection = deriveMemoryProjection(vault, ledger.events);
+  const ambiguous = new Set(projection.candidates.map((candidate) => candidate.record_key || candidate.memory_key));
+  const existingIds = new Set(ledger.events.map((event) => event.event_id));
+  const planned = [];
+
+  for (const [recordKey, record] of Object.entries(projection.records)) {
+    if (ambiguous.has(recordKey) || record.source?.scope) continue;
+    const source = record.source;
+    const sameLegacyKey = ledger.events.filter((event) => (
+      !event.scope && event.memory_key === source.memory_key && !event.rescopes_event_id
+    ));
+    const scope = scopeForMemoryKey(source.memory_key, {
+      ...source,
+      projectId: source.project_id,
+      workSessionId: source.work_session_id,
+      branch: source.value?.branch || source.value?.branch_name,
+      worktreeId: source.value?.worktree_id,
+      repositoryId: source.value?.repository_id,
+    });
+    const eventId = rescopeEventId(source.event_id, scope);
+    if (existingIds.has(eventId)) continue;
+    planned.push({
+      v: 1,
+      event_id: eventId,
+      project_id: source.project_id,
+      memory_key: source.memory_key,
+      scope,
+      operation: 'assert',
+      value: record.value,
+      authority: source.authority,
+      canonical_session_id: source.canonical_session_id || 'memory-rescope',
+      activation_id: source.activation_id || 'memory-rescope',
+      activation_epoch: Number.isInteger(source.activation_epoch) ? source.activation_epoch : 0,
+      turn_sequence: Number.isInteger(source.turn_sequence) ? source.turn_sequence : 0,
+      source_turn_id: source.source_turn_id || 'memory-rescope',
+      observed_at: source.observed_at || new Date(0).toISOString(),
+      evidence: [...new Set([...(source.evidence || []), `memory-rescope:${source.event_id}`])],
+      rescopes_event_id: source.event_id,
+      rescopes_event_ids: sameLegacyKey.map((event) => event.event_id).sort(),
+    });
+  }
+
+  return {
+    status: 'dry-run',
+    ledger_events: ledger.events.length,
+    planned: planned.length,
+    ambiguous: projection.candidates.length,
+    events: planned,
+  };
+}
+
+export function rescopeMemoryEvents(vault, { apply = false } = {}) {
+  projectId(vault);
+  const plan = planScopedMemoryMigration(vault);
+  if (!apply) {
+    return {
+      status: 'dry-run',
+      ledger_events: plan.ledger_events,
+      planned: plan.planned,
+      ambiguous: plan.ambiguous,
+      scopes: plan.events.map((event) => ({
+        event_id: event.event_id, memory_key: event.memory_key, scope: event.scope,
+      })),
+    };
+  }
+  if (!plan.events.length) {
+    return { status: 'unchanged', migrated: 0, ambiguous: plan.ambiguous };
+  }
+  for (const event of plan.events) enqueueMemoryEvent(vault, event);
+  const projection = projectMemoryOutbox(vault);
+  return {
+    status: projection.status === 'projected' ? 'migrated' : projection.status,
+    migrated: plan.events.length,
+    ambiguous: plan.ambiguous,
+    checkpoint: projection.checkpoint || null,
+  };
+}
+
 function readCandidates(vault) {
   const path = brainPath(vault, CANDIDATES);
   const checked = checkedVaultFile(vault, path, 'MEMORY_CANDIDATES.jsonl');
@@ -266,6 +353,7 @@ function sanitizedCandidate(candidate, index) {
     reason: candidate.reason,
     status: candidate.status || 'active',
     memory_key: candidate.memory_key,
+    ...(candidate.scope ? { scope: candidate.scope } : {}),
     event_ids: [...eventIds].sort(lexicalCompare),
   };
 }
@@ -328,6 +416,7 @@ export function listMemoryCandidatesForCuration(vault) {
         reason: safe.reason,
         status: safe.status,
         memory_key: safe.memory_key,
+        ...(safe.scope ? { scope: safe.scope } : {}),
         events: safe.event_ids.map((eventId) => sanitizedCurationEvent(candidate, eventId, index)),
       };
     })
@@ -388,7 +477,7 @@ function promotedSupersedes(vault, candidate, selected) {
   const ledger = readMemoryLedger(vault);
   if (ledger.status !== 'ok') throw new Error('Ledger de memória inválido durante a promoção.');
   const projection = deriveMemoryProjection(vault, ledger.events);
-  const current = projection.records?.[candidate.memory_key]?.source;
+  const current = projection.records?.[candidate.record_key || candidate.memory_key]?.source;
   if (!current?.event_id) return [...memberIds].sort();
   if (memberIds.has(current.event_id)) {
     projection.superseded
@@ -572,6 +661,9 @@ export function decideMemoryCandidate(vault, {
     event_id: `cli-${action}-${hash(`${candidateId}\0${selected?.event_id || ''}`).slice(0, 20)}`,
     project_id: projectId(vault),
     memory_key: action === 'promote' ? candidate.memory_key : `candidate.decision.${candidateId}`,
+    scope: action === 'promote'
+      ? (candidate.scope || selected?.scope || { type: 'project', id: projectId(vault) })
+      : { type: 'project', id: projectId(vault) },
     operation: action === 'promote' && selected ? 'replace' : 'assert',
     value: action === 'promote' ? promotedMemoryValue(selectedValue) : 'rejected',
     authority: 'verified',
@@ -2087,6 +2179,7 @@ export function runMemory(argv) {
       result = listMemoryCandidates(vault, { activeOnly: candidatesArgs.activeOnly });
     }
     else if (sub === 'migrate') result = migrateMemory(vault, { apply: argv.includes('--apply') });
+    else if (sub === 'rescope') result = rescopeMemoryEvents(vault, { apply: argv.includes('--apply') });
     else if (sub === 'repair') result = repairMemory(vault);
     else if (sub === 'reconcile') {
       result = reconcileMemory(vault, {
@@ -2109,7 +2202,7 @@ export function runMemory(argv) {
         action: sub, candidateId: positional, ...(eventId ? { eventId } : {}),
       });
     }
-    else { process.stderr.write('wendkeep memory: use status | candidates [--active] | migrate [--apply] | repair | recover-attempt <session> [--apply] | reconcile <session> --by-session <session> --reason <text> [--apply] | promote <candidate> [--event <event-id>] | reject <candidate>.\n'); process.exitCode = 2; return; }
+    else { process.stderr.write('wendkeep memory: use status | candidates [--active] | curate | migrate [--apply] | rescope [--apply] | repair | recover-attempt <session> [--apply] | reconcile <session> --by-session <session> --reason <text> [--apply] | promote <candidate> [--event <event-id>] | reject <candidate>.\n'); process.exitCode = 2; return; }
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     if (sub === 'status' && argv.includes('--gate')) process.exitCode = result.status === 'blocked' ? 1 : 0;
     else if (sub === 'reconcile' && reconcileArgs.apply) process.exitCode = result.health?.status === 'blocked' ? 1 : 0;

package/src/observer-sql-store.mjs

@@ -4,9 +4,12 @@ import { createRequire } from 'node:module';
 import { join, basename, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { decodeTranscript, encodeTranscript } from './observer-transcript-store.mjs';
+import {
+  chunkMarkdownDocument, recallEvidence, recallTerms,
+} from '../packages/vault/src/evidence-recall.mjs';
 
 export const OBSERVER_SQL_FILE = 'observer.sqlite';
-export const OBSERVER_SQL_SCHEMA_VERSION = 3;
+export const OBSERVER_SQL_SCHEMA_VERSION = 4;
 export const OBSERVER_EVENT_SCHEMA_VERSION = 1;
 
 const SCHEMA_DIR = fileURLToPath(new URL('../schema/observer/', import.meta.url));
@@ -117,12 +120,106 @@ export function migrateObserverDatabase(db) {
       throw error;
     }
   }
+  rebuildSqlEvidenceIndex(db, { missingOnly: true });
   return {
     version: Number(db.prepare('SELECT COALESCE(MAX(version), 0) AS version FROM schema_migrations').get().version || 0),
     applied: db.prepare('SELECT version, name, applied_at FROM schema_migrations ORDER BY version').all(),
   };
 }
 
+export function observerFts5Support(db) {
+  try {
+    db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS evidence_chunks_fts USING fts5(
+      chunk_id UNINDEXED,
+      project_id UNINDEXED,
+      logical_path,
+      title,
+      heading,
+      content,
+      tokenize = 'unicode61 remove_diacritics 2'
+    )`);
+    return { supported: true, engine: 'fts5' };
+  } catch (error) {
+    return { supported: false, engine: 'lexical-fallback', reason: text(error?.message || error) };
+  }
+}
+
+function synchronizeSqlFts(db) {
+  const support = observerFts5Support(db);
+  if (!support.supported) return support;
+  const chunks = Number(db.prepare('SELECT COUNT(*) AS count FROM document_chunks').get().count || 0);
+  const indexed = Number(db.prepare('SELECT COUNT(*) AS count FROM evidence_chunks_fts').get().count || 0);
+  if (chunks === indexed) return support;
+  db.exec(`DELETE FROM evidence_chunks_fts;
+    INSERT INTO evidence_chunks_fts(chunk_id, project_id, logical_path, title, heading, content)
+    SELECT chunk_id, project_id, logical_path, title, heading, content
+    FROM document_chunks;`);
+  return { ...support, rebuilt: true, chunks };
+}
+
+function writeSqlDocumentChunks(db, {
+  projectId, logicalPath, content, metadata = {}, entityType = 'document', capturedAt = '',
+} = {}) {
+  const chunks = chunkMarkdownDocument({
+    projectId,
+    logicalPath,
+    content,
+    metadata: { ...metadata, observed_at: metadata.observed_at || capturedAt },
+    entityType,
+  });
+  db.prepare('DELETE FROM document_chunks WHERE project_id = ? AND logical_path = ?').run(projectId, logicalPath);
+  const fts = observerFts5Support(db);
+  if (fts.supported) {
+    db.prepare('DELETE FROM evidence_chunks_fts WHERE project_id = ? AND logical_path = ?').run(projectId, logicalPath);
+  }
+  const insert = db.prepare(`INSERT INTO document_chunks(
+    chunk_id, project_id, logical_path, title, heading, entity_type, change_slug,
+    session_id, work_session_id, authority, observed_at, validity, content_hash, ordinal, content
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+  const insertFts = fts.supported
+    ? db.prepare('INSERT INTO evidence_chunks_fts(chunk_id, project_id, logical_path, title, heading, content) VALUES (?, ?, ?, ?, ?, ?)')
+    : null;
+  for (const chunk of chunks) {
+    insert.run(
+      chunk.chunk_id, chunk.project_id, chunk.logical_path, chunk.title, chunk.heading,
+      chunk.entity_type, chunk.change_slug, chunk.session_id, chunk.work_session_id,
+      chunk.authority, chunk.observed_at, chunk.validity, chunk.content_hash,
+      chunk.ordinal, chunk.content,
+    );
+    insertFts?.run(chunk.chunk_id, chunk.project_id, chunk.logical_path, chunk.title, chunk.heading, chunk.content);
+  }
+  return { chunks: chunks.length, fts };
+}
+
+export function rebuildSqlEvidenceIndex(db, { missingOnly = false } = {}) {
+  const table = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'document_chunks'").get();
+  if (!table) return { documents: 0, chunks: 0, fts: { supported: false, engine: 'unavailable' } };
+  const documents = db.prepare(`SELECT d.project_id, d.logical_path, d.content, d.metadata_json, d.entity_type, d.captured_at
+    FROM documents d
+    WHERE d.deleted_at IS NULL
+      AND (? = 0 OR NOT EXISTS (
+        SELECT 1 FROM document_chunks c
+        WHERE c.project_id = d.project_id AND c.logical_path = d.logical_path
+      ))
+    ORDER BY d.project_id, d.logical_path`).all(missingOnly ? 1 : 0);
+  let chunks = 0;
+  let fts = observerFts5Support(db);
+  for (const document of documents) {
+    const result = writeSqlDocumentChunks(db, {
+      projectId: document.project_id,
+      logicalPath: document.logical_path,
+      content: document.content,
+      metadata: parseJson(document.metadata_json),
+      entityType: document.entity_type,
+      capturedAt: document.captured_at,
+    });
+    chunks += result.chunks;
+    fts = result.fts;
+  }
+  fts = synchronizeSqlFts(db);
+  return { documents: documents.length, chunks, fts };
+}
+
 export function ensureObserverDatabase(dataDir) {
   const db = openObserverDatabase(dataDir);
   try {
@@ -266,6 +363,14 @@ function applyDocument(db, event) {
     VALUES (?, ?, ?, ?, 'upsert', ?, ?, ?, ?, ?, ?)
   `).run(event.event_id, event.project_id, text(p.entity_type || p.entityType, 'memory'), logicalPath, revision, contentHash,
     text(p.source_session_id || p.sourceSessionId), text(p.source_turn_id || p.sourceTurnId), event.occurred_at, json(p));
+  writeSqlDocumentChunks(db, {
+    projectId: event.project_id,
+    logicalPath,
+    content,
+    metadata: p.metadata,
+    entityType: text(p.entity_type || p.entityType, 'memory'),
+    capturedAt: text(p.captured_at || event.occurred_at),
+  });
   return { stale: false };
 }
 
@@ -279,6 +384,10 @@ function applyDocumentDelete(db, event) {
     VALUES (?, ?, ?, ?, 'delete', ?, '', ?, ?, ?, ?)
   `).run(event.event_id, event.project_id, text(event.payload.entity_type || event.payload.entityType, 'memory'), logicalPath,
     integer(event.payload.revision, 1), text(event.payload.source_session_id || event.payload.sourceSessionId), text(event.payload.source_turn_id || event.payload.sourceTurnId), event.occurred_at, json(event.payload));
+  db.prepare('DELETE FROM document_chunks WHERE project_id = ? AND logical_path = ?').run(event.project_id, logicalPath);
+  if (observerFts5Support(db).supported) {
+    db.prepare('DELETE FROM evidence_chunks_fts WHERE project_id = ? AND logical_path = ?').run(event.project_id, logicalPath);
+  }
   return { stale: false };
 }
 
@@ -542,11 +651,38 @@ export function readSqlTree(db, projectId, prefix = '') {
   return { schema_version: OBSERVER_SQL_SCHEMA_VERSION, project_id: projectId, prefix, documents: rows };
 }
 
-export function searchSqlDocuments(db, projectId, query = '') {
+export function searchSqlDocuments(db, projectId, query = '', { forceLexical = false } = {}) {
   requireProject(db, projectId);
-  const q = `%${text(query).replace(/[%_]/g, '\\$&')}%`;
-  const rows = db.prepare(`SELECT logical_path, entity_type, title, content_hash, revision, captured_at, source_session_id, content FROM documents WHERE project_id = ? AND deleted_at IS NULL AND (logical_path LIKE ? ESCAPE '\\' OR title LIKE ? ESCAPE '\\' OR content LIKE ? ESCAPE '\\') ORDER BY captured_at DESC, logical_path LIMIT 100`).all(projectId, q, q, q);
-  return rows.map((row) => ({ ...row, excerpt: row.content.slice(0, 240) }));
+  const terms = recallTerms(query);
+  if (!terms.length) return [];
+  const fts = forceLexical
+    ? { supported: false, engine: 'lexical-fallback' }
+    : observerFts5Support(db);
+  const columns = `c.chunk_id, c.project_id, c.logical_path, c.title, c.heading,
+    c.entity_type, c.change_slug, c.session_id, c.work_session_id, c.authority,
+    c.observed_at, c.validity, c.content_hash AS chunk_content_hash, c.ordinal, c.content,
+    d.content_hash, d.revision, d.captured_at, d.source_session_id`;
+  let rows;
+  if (fts.supported) {
+    const expression = [...new Set(terms)]
+      .map((term) => `"${term.replaceAll('"', '""')}"`)
+      .join(' OR ');
+    rows = db.prepare(`SELECT ${columns} FROM evidence_chunks_fts f
+      JOIN document_chunks c ON c.chunk_id = f.chunk_id
+      JOIN documents d ON d.project_id = c.project_id AND d.logical_path = c.logical_path
+      WHERE evidence_chunks_fts MATCH ? AND c.project_id = ? AND d.deleted_at IS NULL
+      ORDER BY bm25(evidence_chunks_fts, 0, 0, 1.5, 3.0, 2.5, 1.0), c.observed_at DESC
+      LIMIT 200`).all(expression, projectId);
+  } else {
+    // FTS5 may be unavailable in a valid Observer runtime. Rank the complete project corpus
+    // instead of truncating by recency before matching, which would make old exact evidence
+    // permanently unreachable.
+    rows = db.prepare(`SELECT ${columns} FROM document_chunks c
+      JOIN documents d ON d.project_id = c.project_id AND d.logical_path = c.logical_path
+      WHERE c.project_id = ? AND d.deleted_at IS NULL
+      ORDER BY c.observed_at DESC, c.logical_path, c.ordinal`).all(projectId);
+  }
+  return recallEvidence(rows, query, { topK: 5 });
 }
 
 export function readSqlSync(db, projectId) {

package/src/taxonomy.mjs

@@ -65,6 +65,8 @@ export const HOOK_FILES = [
   'subagent-usage.mjs',
   'pricing.json',
   'brain-core.mjs',
+  'evidence-recall.mjs',
+  'memory-scope.mjs',
   'memory-schema.mjs',
   'memory-store.mjs',
   'memory-handoff.mjs',
@@ -83,6 +85,7 @@ export const HOOK_FILES = [
   'harness-doctor.mjs',
   'lessons-core.mjs',
   'brain-inject.mjs',
+  'evidence-context.mjs',
   'brain-recall.mjs',
   'brain-reindex.mjs',
   'session-backfill.mjs',
@@ -114,6 +117,7 @@ export const RUNNABLE_HOOKS = [
   'subagent-stop',
   'task-log',
   'brain-inject',
+  'evidence-context',
   'brain-recall',
   'brain-reindex',
   'vault-health',