npm - @ijfw/memory-server - Versions diffs - 1.4.4 → 1.5.0 - Mend

@ijfw/memory-server 1.4.4 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (232) hide show

package/src/server.js CHANGED Viewed

@@ -33,9 +33,28 @@ import { checkPrompt } from './prompt-check.js';
 import { applyCaps, CAP_CONTENT } from './caps.js';
 import { ensureSchemaHeader, SCHEMA_HEADER } from './schema.js';
 import { searchCorpus } from './search-bm25.js';
+// r17 (cold-tier wire-up): hybrid BM25+vector ranking when IJFW_VECTORS=on AND
+// @xenova/transformers is installed. Silent BM25-only fallback otherwise.
+// Lives in its own module so tests can drive the rerank helper without
+// importing server.js (whose stdio bootstrap would hang the test runner).
+import { maybeRerankWithVectors } from './search-hybrid.js';
 import { crossProjectSearch } from './cross-project-search.js';
 // R2-E -- single source of truth for markdown/HTML/control-char defanger.
 import { sanitizeContent } from './sanitizer.js';
+// H5.5 / H5.6 — ingest-time fact extraction + semantic dedup. Closes
+// memory-engine.md competitor gaps (mem0/Zep extract facts; Graphiti dedups).
+// Both are pure-JS, zero-LLM, deterministic.
+import { extractFacts, factToJsonl } from './memory/fact-extractor.js';
+import { findNearDuplicate, readDedupConfig } from './memory/dedup.js';
+// v1.5.0 audit H5.4 — Graphiti-style bi-temporal validity. Lets storing a
+// contradictory fact close the prior's valid_to instead of accumulating.
+import {
+  openTemporalDbSync,
+  storeFactBitemporal,
+  getValidAt as temporalGetValidAt,
+  getHistory as temporalGetHistory,
+  getAllFactsWithWindows as temporalGetAllFactsWithWindows,
+} from './memory/temporal.js';
 // 1.1.6: update tools (cap 8 -> 10) -- token-issuance + OOB terminal confirm.
 // Per CLAUDE.md policy: future growth triggers retirement review, not raise.
 import { ijfwUpdateCheck, TOOL_DEF as UPDATE_CHECK_TOOL } from './update-check.js';
@@ -394,8 +413,11 @@ function readOr(filepath, fallback = '') {
 // --- Append helper (atomic for entries < PIPE_BUF; append-only growth) ---
 //
 // We rely on POSIX O_APPEND atomicity for entries under 4KB. Sanitized
-// entries are bounded at MAX_STORE_LENGTH=5000 chars, but the entry header
-// keeps each *line* well under 4KB after sanitization (single-line collapse).
+// entries are bounded at MAX_STORE_LENGTH=4096 chars (CAP_CONTENT in caps.js),
+// but the entry header keeps each *line* well under 4KB after sanitization
+// (single-line collapse). Audit MED #8 / F-COR-1: doc-vs-code parity fix --
+// the prior text said 5000, which had drifted from the actual cap.
 function appendLine(filepath, line) {
   try {
     if (!existsSync(filepath)) {
@@ -593,6 +615,105 @@ function getRecentJournalEntries(count = 5) {
   return entries.slice(-count).join('\n');
 }
+// H5.6 — dedup needs `recents` shaped as { id, content } for findNearDuplicate.
+// We synthesize id from the timestamp (project-journal entries are unique by ts
+// down to ms; collisions would only happen on near-simultaneous writes which
+// our atomic-append + fs flush ordering already serialise).
+function getRecentMemoriesForDedup(limit = 50) {
+  const journal = readOr(join(MEMORY_DIR, 'project-journal.md'));
+  if (!journal) return [];
+  const lines = journal.split('\n').filter(l => /^- \[\d{4}-/.test(l));
+  // Most-recent-last in the file → reverse so findNearDuplicate sees newest first.
+  const slice = lines.slice(-limit).reverse();
+  return slice.map(line => {
+    // Format: "- [<iso>] <body>"   →   { id: iso, content: body }
+    const m = line.match(/^- \[([^\]]+)\]\s*(.*)$/);
+    if (!m) return null;
+    return { id: m[1], content: m[2] };
+  }).filter(Boolean);
+}
+// H5.5 — sidecar file for structured facts (one JSON object per line).
+// Append-only; consumed by handleRecall({context_hint:'facts'}).
+const FACTS_FILE = join(MEMORY_DIR, 'facts.jsonl');
+// Stable short id for joining a fact back to its journal entry. We don't have
+// a uuid; the journal-line text itself + ts is unique enough for cross-ref.
+function factMemoryIdFor(journalEntryText) {
+  return 'm-' + createHash('sha256')
+    .update(String(journalEntryText) + ':' + Date.now())
+    .digest('hex')
+    .slice(0, 10);
+}
+function appendFactsToSidecar(facts, meta) {
+  if (!Array.isArray(facts) || facts.length === 0) return { ok: true, written: 0 };
+  try {
+    const lines = facts.map(f => factToJsonl(f, meta)).join('\n') + '\n';
+    appendFileSync(FACTS_FILE, lines);
+    return { ok: true, written: facts.length };
+  } catch (err) {
+    // Non-fatal: facts are augmentation, not source-of-truth. Journal already
+    // captured the raw memory.
+    return { ok: false, code: err.code || 'EUNKNOWN', message: err.message };
+  }
+}
+// v1.5.0 audit H5.4 — sibling SQL store for bi-temporal facts. Lives next to
+// facts.jsonl so the JSONL sidecar (append-only timeline log) and the SQL
+// table (queryable point-in-time view) stay co-located. Lazy-opened on first
+// use so a project that never stores a memory never pays the better-sqlite3
+// load cost.
+const FACTS_DB_FILE = join(MEMORY_DIR, 'facts.db');
+let _factsDbHandle = null;
+function getFactsDb() {
+  if (_factsDbHandle) return _factsDbHandle;
+  try {
+    _factsDbHandle = openTemporalDbSync(FACTS_DB_FILE);
+    return _factsDbHandle;
+  } catch (err) {
+    // Non-fatal. JSONL sidecar still gets written; we just lose the bi-temporal
+    // SQL view for this process. Surface via stderr so operators see the
+    // degradation but the user-facing store result still says "ok".
+    try {
+      process.stderr.write(`[ijfw temporal] facts.db unavailable (${err.code || err.message}); SQL fact view degraded\n`);
+    } catch { /* stderr may be detached */ }
+    return null;
+  }
+}
+// writeFactsBitemporal -- for each extracted fact, close any prior currently-
+// valid fact with the same (subject, predicate) but different object, then
+// insert the new fact. Wrapped in a per-fact transaction inside temporal.js's
+// storeFactBitemporal helper. Best-effort: a SQL failure logs to stderr but
+// never breaks the journal-or-JSONL path.
+function writeFactsBitemporal(facts, meta) {
+  if (!Array.isArray(facts) || facts.length === 0) return { ok: true, written: 0, invalidated: 0 };
+  const db = getFactsDb();
+  if (!db) return { ok: false, code: 'ENOFACTSDB', written: 0, invalidated: 0 };
+  let written = 0;
+  let invalidated = 0;
+  for (const f of facts) {
+    try {
+      const r = storeFactBitemporal(db, {
+        subject: f.subject,
+        predicate: f.predicate,
+        object: f.object,
+        confidence: f.confidence,
+        memory_id: meta && meta.memory_id,
+        source: meta && meta.source,
+      }, meta && meta.ts);
+      invalidated += r.invalidated;
+      if (!r.deduped) written += 1;
+    } catch (err) {
+      try {
+        process.stderr.write(`[ijfw temporal] storeFactBitemporal failed: ${err.message}\n`);
+      } catch { /* stderr may be detached */ }
+    }
+  }
+  return { ok: true, written, invalidated };
+}
 // --- Cross-project registry (Phase 3) ---
 //
 // Registry lines look like: <abs-path> | <sha256-12> | <first-seen-iso>
@@ -635,55 +756,81 @@ function readProjectMemory(projectPath) {
   };
 }
-function searchAcrossProjects(query, limit) {
-  const queryLower = String(query).toLowerCase();
-  const keywords = queryLower.split(/\s+/).filter(w => w.length > 2);
-  if (keywords.length === 0) return [];
-  const results = [];
-  for (const entry of readRegistry()) {
-    const tag = basename(entry.path);
-    const mem = readProjectMemory(entry.path);
-    for (const [src, content] of Object.entries(mem)) {
-      if (!content) continue;
-      const lines = content.split('\n');
-      for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (line.trim().length === 0) continue;
-        const score = keywords.filter(k => line.toLowerCase().includes(k)).length;
-        if (score > 0) {
-          results.push({
-            source: `${src}@${tag}`,
-            line: i + 1,
-            content: `[project:${tag}] ${line.trim().substring(0, 200)}`,
-            score
-          });
-        }
-      }
-    }
-  }
-  results.sort((a, b) => b.score - a.score);
-  return results.slice(0, limit);
-}
+// v1.5.1 H1.5 (audit memory-engine.md F-FUN-4): the legacy naive-keyword-count
+// `searchAcrossProjects` was removed. `scope:'all'` now routes to the BM25-
+// ranked `crossProjectSearch` in cross-project-search.js (which already
+// returns the same `{ source, line, content, score }` shape via the
+// `[project:<name>]` content prefix). Two parallel cross-project surfaces
+// existed; the worse one was the default. Now there is one.
 // --- Search ---
 // P5.1 / H4 -- BM25 ranking over line-level docs. Source tags and line
 // numbers preserved so callers get the same output shape; scoring is
 // BM25 (IDF + TF + length-normalized) with per-source boost. Team tier
 // ranks first via a score bump for ties.
-function searchMemory(query, limit = 10, scope = 'project') {
+//
+// r17 (cold-tier wire-up): when IJFW_VECTORS=on AND @xenova/transformers is
+// installed AND the model is loadable, the BM25 top-K is reranked via cosine
+// similarity over the snippet text (blended weights wBm25=0.6, wVec=0.4 from
+// vectors.js defaults). Async because embedder load + embed() are async. The
+// `opts.embedder` parameter lets tests inject a mock embedder without
+// installing @xenova/transformers.
+// v1.5.0 wire-W1.C — lazy memory.db handle for the embedding cache.
+// Opens once per process and reuses thereafter. Returns null when the
+// project has no .ijfw/index/memory.db (e.g. fresh checkout that never
+// stored a memory) so the rerank still falls back to live embed.
+let _memoryDbForRerank = null;
+async function getMemoryDbForRerank() {
+  if (_memoryDbForRerank) return _memoryDbForRerank;
+  try {
+    const { openDb } = await import('./memory/fts5.js');
+    _memoryDbForRerank = await openDb(PROJECT_DIR);
+    return _memoryDbForRerank;
+  } catch {
+    _memoryDbForRerank = null;
+    return null;
+  }
+}
+async function searchMemory(query, limit = 10, scope = 'project', opts = {}) {
   limit = Math.min(Math.max(1, limit | 0), MAX_SEARCH_RESULTS);
-  if (scope === 'all') return searchAcrossProjects(query, limit);
+  if (scope === 'all') {
+    // v1.5.1 H1.5 (audit memory-engine.md F-FUN-4): use BM25-ranked
+    // crossProjectSearch, not the legacy naive keyword-count scan.
+    const projects = readRegistry();
+    if (projects.length === 0) return [];
+    return crossProjectSearch(query, projects, readProjectMemory, { limit });
+  }
   const sources = [
-    { name: 'team',          content: readTeamKnowledge(),                          boost: 1.25 },
-    { name: 'knowledge',     content: readKnowledgeBase(),                          boost: 1.15 },
-    { name: 'journal',       content: readOr(join(MEMORY_DIR, 'project-journal.md')), boost: 1.0  },
-    { name: 'handoff',       content: readHandoff(),                                boost: 1.1  },
-    { name: 'global',        content: readGlobalKnowledge(),                        boost: 0.95 },
-    { name: 'claude-native', content: readNativeClaudeMemory(),                     boost: 0.95 },
+    { name: 'team',          content: readTeamKnowledge(),                          boost: 1.25, path: join(MEMORY_DIR, 'team-knowledge.md') },
+    { name: 'knowledge',     content: readKnowledgeBase(),                          boost: 1.15, path: join(MEMORY_DIR, 'knowledge.md') },
+    { name: 'journal',       content: readOr(join(MEMORY_DIR, 'project-journal.md')), boost: 1.0,  path: join(MEMORY_DIR, 'project-journal.md') },
+    { name: 'handoff',       content: readHandoff(),                                boost: 1.1,  path: join(MEMORY_DIR, 'handoff.md') },
+    { name: 'global',        content: readGlobalKnowledge(),                        boost: 0.95, path: null },
+    { name: 'claude-native', content: readNativeClaudeMemory(),                     boost: 0.95, path: null },
   ];
+  // v1.5.0 audit MED #12 (memory-engine.md F-FUN-5): recency decay on the
+  // boosted map. Each source file has an mtime; per-result age (days since
+  // mtime) feeds Math.exp(-ageDays / 90), so a 90-day-old source decays
+  // by ~1/e (0.37) and a 1-year-old source by ~0.018. Fresh entries
+  // (< 1 day) stay essentially unchanged (~0.99). Sources without a file
+  // (global, claude-native) get no decay (multiplier 1.0).
+  const RECENCY_HALFLIFE_DAYS = 90;
+  const nowMs = Date.now();
+  const sourceDecay = new Map();
+  for (const src of sources) {
+    if (!src.path) { sourceDecay.set(src.name, 1); continue; }
+    let ageDays = 0;
+    try {
+      const st = statSync(src.path);
+      ageDays = Math.max(0, (nowMs - st.mtimeMs) / 86400000);
+    } catch { ageDays = 0; }
+    sourceDecay.set(src.name, Math.exp(-ageDays / RECENCY_HALFLIFE_DAYS));
+  }
   const docs = [];
   const meta = new Map();
   for (const src of sources) {
@@ -702,19 +849,46 @@ function searchMemory(query, limit = 10, scope = 'project') {
   const ranked = searchCorpus(query, docs, { limit: limit * 3 });
   if (ranked.length === 0) return [];
-  const boosted = ranked.map(r => {
+  // r17: cold-tier hybrid rerank. Pure no-op when vectors disabled OR
+  // embedder unavailable. Never throws into the caller.
+  //
+  // v1.5.0 wire-W1.C: when the caller didn't supply a db handle but the
+  // memory.db exists for this project, open it lazily + thread through so
+  // the embedding cache backs the rerank. The default modelId mirrors
+  // vectors.js DEFAULT_MODEL so first-call writes match cache reads from
+  // the same process on later calls.
+  //
+  // r20-MED fix: previously the lazy-open was SKIPPED whenever opts.embedder
+  // was supplied (intended as a test-seam guard). That meant any caller
+  // passing a custom embedder (e.g. an HTTP-backed one) lost the cache.
+  // Now: always lazy-open when !opts.db. Tests that want to disable the
+  // cache pass opts.db = null explicitly.
+  const rerankOpts = { ...opts };
+  if (!rerankOpts.db && rerankOpts.db !== null) {
+    try {
+      rerankOpts.db = await getMemoryDbForRerank();
+    } catch { /* memory db unavailable -- skip cache, fall back to live embed */ }
+  }
+  if (!rerankOpts.modelId) {
+    rerankOpts.modelId = process.env.IJFW_VECTORS_MODEL || 'Xenova/all-MiniLM-L6-v2';
+  }
+  const reranked = await maybeRerankWithVectors(query, ranked, rerankOpts);
+  const boosted = reranked.map(r => {
     const m = meta.get(r.id);
+    const decay = sourceDecay.get(m.source) ?? 1;
     return {
       source: m.source,
       line: m.line,
       content: (r.snippet || '').substring(0, 200),
-      score: r.score * (m.boost || 1),
+      score: r.score * (m.boost || 1) * decay,
     };
   });
   boosted.sort((a, b) => b.score - a.score);
   return boosted.slice(0, limit);
 }
 // --- DESIGN picker (1.2.0 Phase 5) ---
 // MCP-only delivery of the 12-template design catalog for OpenCode / Qwen
 // Code / Kimi Code / OpenClaw / Aider. No new tool -- served via existing
@@ -805,7 +979,7 @@ const TOOLS = [
     inputSchema: {
       type: 'object',
       properties: {
-        content: { type: 'string', description: 'Full statement of what to remember. Max 5000 chars. Sanitised on storage.' },
+        content: { type: 'string', description: 'Full statement of what to remember. Max 4096 chars. Sanitised on storage.' },
         type: { type: 'string', enum: VALID_MEMORY_TYPES, description: 'Memory tier: decision or pattern -> knowledge base (frontmatter). handoff -> overwrites handoff.md. preference -> project-namespaced global. observation -> journal only.' },
         summary: { type: 'string', description: 'Optional 1-line summary (≤80 chars). Used as the frontmatter name for decisions/patterns.' },
         why: { type: 'string', description: 'Optional rationale -- why this decision was made. Populates the Why section in the knowledge base entry.' },
@@ -844,6 +1018,21 @@ const TOOLS = [
       required: []
     }
   },
+  {
+    // v1.5.0 M5 (INT.6) -- bi-temporal facts MCP surface.
+    name: 'ijfw_memory_facts',
+    description: 'Query the bi-temporal facts table (subject/predicate/object timeline with valid_from / valid_to). Default: current-valid rows only. Pass history=true for full timeline; pass valid_at=<ISO-8601> for point-in-time. Subject + predicate are required.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        subject:   { type: 'string', description: 'Fact subject (e.g. "v1.5.0").' },
+        predicate: { type: 'string', description: 'Fact predicate (e.g. "ship_date").' },
+        valid_at:  { type: 'string', description: 'Optional ISO-8601 timestamp. Returns rows whose validity window covers this instant.' },
+        history:   { type: 'boolean', description: 'If true, return all rows (current + invalidated) ordered DESC by valid_from.' }
+      },
+      required: ['subject', 'predicate']
+    }
+  },
   {
     name: 'ijfw_prompt_check',
     description: 'Call on the first turn when the user prompt is short (<30 tokens) or likely vague. Returns whether the prompt is under-specified and a sharpening suggestion. Deterministic regex detector -- no LLM call. Use for Codex/Cursor/Windsurf/Copilot/Gemini where pre-prompt hooks are not available.',
@@ -893,6 +1082,46 @@ const TOOLS = [
       },
       required: ['command'],
     },
+  },
+  {
+    // v1.5.0 T13: ijfw_state — single MCP face for the state-SDK verb facade.
+    // Absorbs the retired ijfw_subagent_post_done tool (post-done IS a state
+    // transition → reachable as the `subagent.post-done` verb). All 20 frozen
+    // verbs from STATE-SDK-CONTRACT §7 are reachable through this one tool,
+    // keeping the MCP cap at 12/12. The same `query(verb, payload, ctx)` core
+    // is also exposed as a JS import and a CLI colon-namespace (`ijfw state:<verb>`).
+    name: 'ijfw_state',
+    description: 'State-SDK verb facade — invoke any of the 20 frozen verbs (workflow.*, wave.*, phase.*, subagent.*, event.emit, telemetry.record, roster.*, extension.set-active, decision.add, blocker.*, state.replay, state.validate) over the canonical physical state files. Single MCP face for the state-SDK; subagent.post-done is the verb that absorbed the retired ijfw_subagent_post_done tool. Returns the verb result with `ok` + `verbId` + verb-specific fields (see STATE-SDK-CONTRACT §7).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        verb:        { type: 'string', description: 'Verb name from the frozen 20-verb registry (e.g. "workflow.get", "wave.advance", "subagent.post-done", "state.validate").' },
+        payload:     { type: 'object', description: 'Verb-specific payload (see STATE-SDK-CONTRACT §7 for each verb signature). Defaults to {} when omitted.' },
+        projectRoot: { type: 'string', description: 'Project root for ctx (defaults to process.cwd()).' },
+        subagentId:  { type: 'string', description: 'Subagent id stamped on event/telemetry records (defaults to "parent").' },
+        homeDir:     { type: 'string', description: 'Home dir override for the homedir-scope active-extension file (defaults to process.env.HOME / USERPROFILE / os.homedir()).' },
+      },
+      required: ['verb'],
+    },
+  },
+  {
+    // v1.5.0-major W12-C N03: Trident-as-a-service.  Multi-lens consensus
+    // convergence (lock-in #47 — canonical Phase E).  Dispatches all 3 lenses
+    // (codex/gemini/claude by default) in parallel; if verdicts diverge,
+    // re-runs with a CYCLE_SUMMARY of the disagreement until consensus or
+    // maxIterations (default 3).  Stall breaker halts on byte-identical
+    // iterations.  Fills the 12th tool-cap slot.
+    name: 'ijfw_cross_audit_converge',
+    description: 'Multi-lens Trident audit with consensus convergence loop. Dispatches codex/gemini/claude in parallel against a commit range, detects verdict divergence, and re-runs with a cycle summary until consensus or maxIterations. Returns {verdict, iterations, findings, divergence?, stalled?}. Verdict: PASS / CONDITIONAL / FAIL / consensus_failed / UNREACHABLE.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        commitRange:   { type: 'string',  description: 'Git commit range to audit (e.g. "HEAD~1..HEAD", "main..feature/x"). Required.' },
+        maxIterations: { type: 'number',  description: 'Max convergence iterations (default 3). 1 → single-shot (fallback mode).' },
+        lenses:        { type: 'array',   items: { type: 'string' }, description: 'Lens ids to dispatch (default ["codex","gemini","claude"]).' },
+      },
+      required: ['commitRange'],
+    },
   }
 ];
@@ -901,8 +1130,8 @@ const TOOLS = [
 function handleRecall({ context_hint, detail_level = 'standard', from_project }) {
   // Cross-project explicit pull. We bypass current-project sources and read
   // the target project's knowledge/handoff/journal directly. Search queries
-  // are routed through searchAcrossProjects via scope:'all' on the search tool;
-  // recall here is for "give me everything from X."
+  // are routed through crossProjectSearch (BM25) via scope:'all' on the
+  // search tool; recall here is for "give me everything from X."
   if (from_project) {
     const target = resolveProject(from_project);
     if (!target) {
@@ -949,6 +1178,95 @@ function handleRecall({ context_hint, detail_level = 'standard', from_project })
     return { text: getRecentJournalEntries(10) || 'No decisions recorded yet.' };
   }
+  // H5.5 / v1.5.0 H5.4 — structured facts feed.
+  //   context_hint === 'facts'         -> only currently-valid facts (SQL
+  //                                       getValidAt(now)); fallback to raw
+  //                                       facts.jsonl if the SQL table is
+  //                                       empty/unavailable (back-compat for
+  //                                       pre-H5.4 installations).
+  //   context_hint === 'facts:history' -> full timeline including invalidated
+  //                                       rows (with their valid_from/valid_to
+  //                                       windows). If the hint is followed by
+  //                                       ":subject/predicate" we narrow to
+  //                                       that pair; otherwise return every
+  //                                       row.
+  if (context_hint === 'facts' || (typeof context_hint === 'string' && context_hint.startsWith('facts:history'))) {
+    const isHistory = typeof context_hint === 'string' && context_hint.startsWith('facts:history');
+    try {
+      const db = getFactsDb();
+      if (db) {
+        if (isHistory) {
+          // Optional ":subject/predicate" narrow-down. Spec: "if subject+
+          // predicate keys can be inferred from the recall query; else return
+          // all facts with their validity windows".
+          const tail = context_hint.slice('facts:history'.length).replace(/^:/, '').trim();
+          let rows;
+          if (tail) {
+            const [subj, pred] = tail.split('/').map(s => s && s.trim()).filter(Boolean);
+            if (subj && pred) {
+              rows = temporalGetHistory(db, subj, pred);
+            } else {
+              rows = temporalGetAllFactsWithWindows(db);
+            }
+          } else {
+            rows = temporalGetAllFactsWithWindows(db);
+          }
+          if (!rows || rows.length === 0) {
+            return { text: 'No structured facts extracted yet. Store memories with key:value lines, "X uses Y", or "decided to ..." phrases to populate.' };
+          }
+          const lines = rows.map(r => JSON.stringify({
+            subject: r.subject,
+            predicate: r.predicate,
+            object: r.object,
+            confidence: r.confidence,
+            valid_from: r.valid_from,
+            valid_to: r.valid_to,
+            memory_id: r.memory_id,
+            source: r.source,
+          }));
+          if (detail_level === 'summary') {
+            const tailLines = lines.slice(-5).join('\n');
+            return { text: `## Fact history (${lines.length} rows)\n${tailLines}` };
+          }
+          return { text: `## Fact history (${lines.length} rows)\n${lines.join('\n')}` };
+        }
+        // Default: currently-valid facts only.
+        const rows = temporalGetValidAt(db, new Date().toISOString());
+        if (rows && rows.length > 0) {
+          const lines = rows.map(r => JSON.stringify({
+            subject: r.subject,
+            predicate: r.predicate,
+            object: r.object,
+            confidence: r.confidence,
+            valid_from: r.valid_from,
+            memory_id: r.memory_id,
+            source: r.source,
+          }));
+          if (detail_level === 'summary') {
+            const tail = lines.slice(-5).join('\n');
+            return { text: `## Currently-valid facts (${lines.length})\n${tail}` };
+          }
+          return { text: `## Currently-valid facts (${lines.length})\n${lines.join('\n')}` };
+        }
+        // SQL table empty -- fall through to JSONL back-compat path below.
+      }
+      if (!existsSync(FACTS_FILE)) {
+        return { text: 'No structured facts extracted yet. Store memories with key:value lines, "X uses Y", or "decided to ..." phrases to populate.' };
+      }
+      const raw = readFileSync(FACTS_FILE, 'utf8');
+      // detail_level === 'summary' → just count + a sample tail. Keeps token
+      // usage bounded for session-start hydration.
+      if (detail_level === 'summary') {
+        const lines = raw.split('\n').filter(Boolean);
+        const tail = lines.slice(-5).join('\n');
+        return { text: `## Structured facts (${lines.length} total)\n${tail}` };
+      }
+      return { text: raw || 'No structured facts extracted yet.' };
+    } catch (err) {
+      return { text: `Facts feed unreadable: ${err.code || err.message}`, isError: true };
+    }
+  }
   const results = searchMemory(context_hint);
   if (results.length === 0) return { text: `No memories matching: ${context_hint}` };
   return { text: results.map(r => `[${r.source}] ${r.content}`).join('\n') };
@@ -997,12 +1315,53 @@ function handleStore({ content, type, tags = [], summary, why, how_to_apply }) {
   const tagStr = tags.length > 0 ? ` [${tags.join(', ')}]` : '';
   const journalEntry = `**${type}**${tagStr}: ${safeSummary || safeContent.substring(0, 200)}`;
+  // H5.6 — Semantic dedup BEFORE append. If this memory is a near-duplicate
+  // of one already in the last N journal entries, short-circuit and return
+  // the existing entry's id. handoff is exempt (always overwrites a single
+  // file by design; deduping would silently drop a handoff swap).
+  const dedupCfg = readDedupConfig();
+  if (dedupCfg.enabled && type !== 'handoff') {
+    const recents = getRecentMemoriesForDedup(dedupCfg.windowSize);
+    // Dedup against the FULL journal-entry line shape -- that's what the next
+    // call would see in `recents`, so comparing apples to apples.
+    const dup = findNearDuplicate(journalEntry, recents);
+    if (dup) {
+      // Spec: emit a stderr line so the user/agent sees the elision.
+      try {
+        process.stderr.write(`[ijfw memory] dedup'd similar entry; keeping prior ${dup.match.id}\n`);
+      } catch { /* stderr may be detached in test harness */ }
+      return {
+        text: `Dedup'd: similar memory already exists (${dup.match.id}, similarity=${dup.similarity.toFixed(2)}). Not appended.`,
+        deduped: true,
+        existing_id: dup.match.id,
+        similarity: dup.similarity,
+      };
+    }
+  }
   // 1. Always append to journal (one-line timeline). Hard failure → report.
   const journalResult = appendToJournal(journalEntry);
   if (!journalResult.ok) {
     return { text: `Memory journal is not writable (${journalResult.code}) -- check .ijfw/ directory permissions and retry.`, isError: true };
   }
+  // H5.5 — Fact extraction AFTER successful append. Best-effort: a failure
+  // here is logged in the return text but does NOT poison the store result.
+  // Memory-id ties facts.jsonl rows back to their journal entry.
+  const factMeta = {
+    ts: new Date().toISOString(),
+    memory_id: factMemoryIdFor(journalEntry),
+    source: `memory_store:${type}`,
+  };
+  const facts = extractFacts(safeContent);
+  appendFactsToSidecar(facts, factMeta);
+  // v1.5.0 audit H5.4 — mirror to bi-temporal SQL store. For each fact,
+  // closes any prior currently-valid fact with the same (subject, predicate)
+  // but different object before inserting. Same-object stores are a no-op.
+  // Wrapped in a per-fact transaction inside temporal.js. Best-effort: any
+  // failure is logged to stderr but never breaks the journal-or-JSONL path.
+  writeFactsBitemporal(facts, factMeta);
   // 2. Type-specific secondary writes. Each tracked so we report partial
   // success accurately rather than lying about "stored."
   const failures = [];
@@ -1107,22 +1466,60 @@ async function handlePrelude({ detail_level = 'summary' } = {}) {
   const updateNudge = composeUpdateNudge();
   if (updateNudge) parts.push(updateNudge, '');
+  // v1.5.0 memory-moat M3 (INT.4): surface top-K recently-successful skills
+  // at session start. The Wayland-pattern "more-you-use-it-better-it-gets"
+  // feedback loop: every skill execution writes to skill_telemetry via the
+  // state-SDK telemetry.record verb (INT.3); this block reads top-5 by
+  // success-count and surfaces them as a hint to the model. Best-effort:
+  // an unmigrated db, empty telemetry, or read failure all skip the block
+  // silently — never breaks the prelude.
+  try {
+    const { topKSuccessfulSkills } = await import('./orchestrator/skill-telemetry.js');
+    const Database = (await import('better-sqlite3')).default;
+    const { join: joinP } = await import('node:path');
+    const root = process.env.IJFW_PROJECT_DIR || process.cwd();
+    const dbPath = joinP(root, '.ijfw', 'index', 'memory.db');
+    if (existsSync(dbPath)) {
+      const db = new Database(dbPath, { readonly: true });
+      try {
+        const top = topKSuccessfulSkills(db, { k: 5 });
+        if (top.length > 0) {
+          const names = top.map((r) => `${r.skill_id} (${r.success_count}×)`).join(', ');
+          parts.push(
+            '<ijfw-recommended-skills>',
+            `Observed success this project: ${names}`,
+            '</ijfw-recommended-skills>',
+            '',
+          );
+        }
+      } finally {
+        try { db.close(); } catch { /* best-effort */ }
+      }
+    }
+  } catch { /* best-effort; never block the prelude */ }
   // 1.2.0 Phase 5: surface the DESIGN picker to platforms without a skills tree.
   // Skip when the project already has a DESIGN.md (contract exists; no picker).
+  // Built into a standalone block so the abstention path below can re-emit it:
+  // a fresh project with no memory AND no DESIGN.md is exactly when the picker
+  // matters most, so it must survive the thin-memory short-circuit.
+  let designPickerBlock = '';
   try {
     if (!existsSync(join(PROJECT_DIR, 'DESIGN.md'))) {
       const names = DESIGN_TEMPLATE_CATALOG.map(([n]) => n);
-      parts.push('## Design picker');
-      parts.push('No DESIGN.md in project. 12 curated templates available:');
-      parts.push(names.slice(0, 5).join(', ') + ',');
-      parts.push(names.slice(5, 10).join(', ') + ',');
-      parts.push(names.slice(10).join(', ') + '.');
-      parts.push('');
-      parts.push('Pick one: ijfw_memory_recall({context_hint: "design_template:<name>"}).');
-      parts.push('Full catalog with descriptions: ijfw_memory_recall({context_hint: "design_template"}).');
-      parts.push('');
+      designPickerBlock = [
+        '## Design picker',
+        'No DESIGN.md in project. 12 curated templates available:',
+        names.slice(0, 5).join(', ') + ',',
+        names.slice(5, 10).join(', ') + ',',
+        names.slice(10).join(', ') + '.',
+        '',
+        'Pick one: ijfw_memory_recall({context_hint: "design_template:<name>"}).',
+        'Full catalog with descriptions: ijfw_memory_recall({context_hint: "design_template"}).',
+      ].join('\n');
     }
-  } catch { /* cwd unreadable -- skip picker block */ }
+  } catch { /* project dir unreadable -- skip picker block */ }
+  if (designPickerBlock) parts.push(designPickerBlock, '');
   // Team knowledge first -- shared decisions/patterns/stack rank above personal.
   const team = readTeamKnowledge();
@@ -1221,16 +1618,51 @@ async function handlePrelude({ detail_level = 'summary' } = {}) {
     // Best-effort; never fail the prelude on memory-feedback issues.
   }
+  // v1.5.0 audit-MED-update-M8 (F-REL-2): surface the last-N partial-deploy
+  // alerts so a half-deployed extension is visible at next session-start.
+  // Wrapped in try/catch — alert read failure must NEVER fail the prelude.
+  try {
+    const { renderDeployAlertsForPrelude } = await import('./deploy-alerts.js');
+    const block = await renderDeployAlertsForPrelude({ limit: 10 });
+    if (block && typeof block === 'string' && block.length > 0) {
+      parts.push(block);
+    }
+  } catch {
+    // Best-effort; never fail the prelude on deploy-alert read issues.
+  }
   parts.push('</ijfw-memory>');
   const text = parts.join('\n');
   if (text.length < 60) {
     return { text: 'Fresh project -- no memory stored yet. Proceed normally.' };
   }
+  // v1.5.0 audit MED #11 (memory-engine.md F-FUN-7): abstention.
+  // If memory exists but the body content is thin AND there are no recent
+  // journal entries, surface an honest abstention so the LLM doesn't try
+  // to over-fit a half-page of stale frontmatter to the user's prompt.
+  // Threshold: total content chars below MIN_CONTENT_CHARS for the
+  // knowledge/team/handoff sources combined AND zero recent journal lines.
+  const MIN_CONTENT_CHARS = 200;
+  const knowledgeChars = (knowledge ? knowledge.length : 0) + (team ? team.length : 0) + (handoff ? handoff.length : 0);
+  const recentLines = recent ? recent.split('\n').filter(l => l.trim()).length : 0;
+  if (knowledgeChars < MIN_CONTENT_CHARS && recentLines === 0) {
+    const abstain = [
+      '<ijfw-memory>',
+      'Memory present but nothing relevant to your prompt -- proceed and I\'ll store any decisions you make.',
+    ];
+    // The DESIGN picker is independent of memory richness — preserve it
+    // through the abstention path, otherwise a fresh project never sees it.
+    if (designPickerBlock) abstain.push('', designPickerBlock);
+    abstain.push('</ijfw-memory>');
+    return { text: abstain.join('\n') };
+  }
   return { text };
 }
-function handleSearch({ query, limit = 10, scope = 'project', label }) {
+async function handleSearch({ query, limit = 10, scope = 'project', label }) {
   if (scope === 'sandbox') {
     if (label) {
       const content = readFromSandbox(label);
@@ -1258,7 +1690,49 @@ function handleSearch({ query, limit = 10, scope = 'project', label }) {
   }
   if (query.length > 500) query = query.substring(0, 500);
   if (scope !== 'project' && scope !== 'all') scope = 'project';
-  const results = searchMemory(query, limit, scope);
+  // v1.5.0 memory-moat M1 (INT.5): "dv:" prefix routes to the declarative
+  // Dataview-grade query mode. Returns structured rows from the FTS5 +
+  // memory_links/_tags/_meta join populated at write time by M1.3 /
+  // INT.1. Best-effort: errors fall through to the standard NL/FTS5 path
+  // so the new mode never breaks existing callers.
+  if (query.startsWith('dv:')) {
+    try {
+      const body = query.slice(3).trim();
+      const dvMod = await import('./memory/query-dataview.js');
+      const fts5Mod = await import('./memory/fts5.js');
+      const root = process.env.IJFW_PROJECT_DIR || process.cwd();
+      const db = await fts5Mod.openDb(root);
+      try {
+        const parsed = dvMod.parseDataviewQuery(body);
+        const result = dvMod.runDataviewQuery(db, parsed);
+        const rows = result.rows.slice(0, limit);
+        if (rows.length === 0) {
+          return { text: `No results for dataview query: "${body}"`, mode: 'dataview', parsed };
+        }
+        // Render in the existing text shape so MCP clients that expect
+        // a single string field keep working.
+        return {
+          text: rows
+            .map((r) => `[id:${r.id} source:${r.source || '?'} created:${r.created_at}] ${(r.body || '').slice(0, 200)}`)
+            .join('\n'),
+          mode: 'dataview',
+          parsed,
+          rowCount: rows.length,
+        };
+      } finally {
+        try { fts5Mod.closeDb(db); } catch { /* best-effort */ }
+      }
+    } catch (e) {
+      return {
+        text: `Dataview query failed: ${e && e.message ? e.message : String(e)}`,
+        mode: 'dataview',
+        isError: true,
+      };
+    }
+  }
+  const results = await searchMemory(query, limit, scope);
   if (results.length === 0) {
     const where = scope === 'all' ? ' across all projects' : '';
     return { text: `No results for: "${query}"${where}` };
@@ -1471,11 +1945,68 @@ function handleMessage(msg) {
             result = { text: JSON.stringify(r, null, 2), isError: !!(r && r.error) };
             break;
           }
+          case 'ijfw_state': {
+            // v1.5.0 T13: single MCP face for the state-SDK. Routes every call
+            // into the same `query(verb, payload, ctx)` core that the JS module
+            // (`./orchestrator/state-sdk.js`) and the CLI colon-namespace
+            // (`ijfw state:<verb>`) use. The retired `ijfw_subagent_post_done`
+            // tool is now reachable as the `subagent.post-done` verb.
+            const a = args || {};
+            if (typeof a.verb !== 'string' || a.verb.length === 0) {
+              result = { text: JSON.stringify({ ok: false, error: 'verb (string) is required' }), isError: true };
+              break;
+            }
+            try {
+              const { query } = await import('./orchestrator/state-sdk.js');
+              const payload = (a.payload && typeof a.payload === 'object') ? a.payload : {};
+              const ctx = {
+                projectRoot: typeof a.projectRoot === 'string' && a.projectRoot.length > 0
+                  ? a.projectRoot
+                  : process.cwd(),
+              };
+              if (typeof a.subagentId === 'string' && a.subagentId.length > 0) ctx.subagentId = a.subagentId;
+              if (typeof a.homeDir === 'string' && a.homeDir.length > 0) ctx.homeDir = a.homeDir;
+              const r = await query(a.verb, payload, ctx);
+              // A verdict-fail refusal (Model 4) is the verb's correct hard-block —
+              // surface `isError: true` so the orchestrator-LLM treats it as a
+              // hard stop rather than an advisory note (mirrors the prior
+              // ijfw_subagent_post_done `block: true` contract).
+              const refused = r && r.refused === true;
+              result = { text: JSON.stringify(r, null, 2), isError: !!refused };
+            } catch (err) {
+              const msg = err && err.message ? err.message : String(err);
+              result = { text: JSON.stringify({ ok: false, error: msg }), isError: true };
+            }
+            break;
+          }
           case 'ijfw_update_apply': {
             const r = ijfwUpdateApply(args || {});
             result = { text: JSON.stringify(r, null, 2), isError: r && r.status === 'error' };
             break;
           }
+          case 'ijfw_cross_audit_converge': {
+            // v1.5.0-major W12-C N03: Trident-as-a-service.
+            const a = args || {};
+            if (!a.commitRange || typeof a.commitRange !== 'string') {
+              result = { text: JSON.stringify({ error: 'commitRange (string) is required' }), isError: true };
+              break;
+            }
+            const { runPhaseEConverge, defaultConvergeDispatch } = await import('./cross-orchestrator.js');
+            try {
+              const r = await runPhaseEConverge({
+                commitRange: a.commitRange,
+                maxIterations: typeof a.maxIterations === 'number' ? a.maxIterations : 3,
+                lenses: Array.isArray(a.lenses) && a.lenses.length > 0 ? a.lenses : undefined,
+                dispatch: defaultConvergeDispatch,
+                projectRoot: process.cwd(),
+              });
+              const isErr = r.verdict === 'consensus_failed' || r.verdict === 'FAIL' || r.verdict === 'UNREACHABLE';
+              result = { text: JSON.stringify(r, null, 2), isError: isErr };
+            } catch (err) {
+              result = { text: JSON.stringify({ error: err && err.message ? err.message : String(err) }), isError: true };
+            }
+            break;
+          }
           case 'ijfw_memory_recall':
             result = handleRecall(args || {});
             emitRecallObservation(args || {});
@@ -1504,7 +2035,7 @@ function handleMessage(msg) {
                 break;
               }
             }
-            result = handleSearch(searchArgs);
+            result = await handleSearch(searchArgs);
             break;
           }
           case 'ijfw_memory_status':
@@ -1513,6 +2044,12 @@ function handleMessage(msg) {
           case 'ijfw_memory_prelude':
             result = await handlePrelude(args || {});
             break;
+          case 'ijfw_memory_facts': {
+            // v1.5.0 M5 (INT.6) -- surface bi-temporal facts read path.
+            const mod = await import('./memory-facts-handler.js');
+            result = await mod.handleMemoryFacts(args || {});
+            break;
+          }
           case 'ijfw_metrics':
             result = handleMetrics(args || {});
             break;
@@ -1665,4 +2202,11 @@ process.on('unhandledRejection', (err) => {
 // Export for tests (Node ESM allows this -- only consumed when imported, not on stdio run)
 // gatePermissionAndQuota is exported inline at its declaration above (B16/SEC-M-03)
 // so test-server-quota-integration.js can drive it without spinning a server.
-export { sanitizeContent, atomicWrite, readMarkdownFile, PROJECT_HASH };
+// H5.5 / H5.6 — expose handleStore/handleRecall + path/helpers so the ingest
+// integration test can drive the full pipeline without spawning a subprocess.
+export {
+  sanitizeContent, atomicWrite, readMarkdownFile, PROJECT_HASH,
+  handleStore, handleRecall, handleSearch, handlePrelude,
+  MEMORY_DIR, FACTS_FILE, FACTS_DB_FILE,
+  getFactsDb,
+};