@voidwire/lore 1.5.0 → 1.6.1

package/cli.ts

@@ -59,6 +59,7 @@ import {
   type ObservationSubtype,
   type ObservationConfidence,
   type PurgeableSource,
+  type ContradictionDecision,
 } from "./index";
 import { isValidLoreType, LORE_TYPES } from "./lib/types";
 import { runIndexer } from "./lib/indexer";
@@ -164,6 +165,26 @@ function fail(error: string, code: number = 1): never {
   process.exit(code);
 }
 
+/**
+ * Log contradiction decisions to stderr (CLI context).
+ * Only logs non-ADD actions — ADD is the default/expected path.
+ */
+function logContradictionDecisions(decisions: ContradictionDecision[]): void {
+  for (const d of decisions) {
+    if (d.action === "NOOP") {
+      console.error(
+        `[contradiction] NOOP: skipped as redundant (topic: ${d.topic})`,
+      );
+    } else if (d.action === "DELETE+ADD") {
+      console.error(
+        `[contradiction] DELETE+ADD: replaced rowid ${d.deleteRowid} (topic: ${d.topic})`,
+      );
+    } else if (d.error) {
+      console.error(`[contradiction] ADD (fallback): ${d.error}`);
+    }
+  }
+}
+
 // ============================================================================
 // Search Command
 // ============================================================================
@@ -691,15 +712,24 @@ async function handlePurge(args: string[]): Promise<void> {
       }
     }
 
-    const result = deleteEntries(matches.map((m) => m.rowid));
+    const result = deleteEntries(
+      matches.map((m) => m.rowid),
+      matches.map((m) => m.content),
+    );
 
     output({
       success: true,
       matches: matches.length,
       deleted: result.deleted,
       rowids: result.rowids,
+      logEntriesRemoved: result.logEntriesRemoved,
     });
-    console.error(`Purged ${result.deleted} entries from search + embeddings.`);
+    console.error(
+      `Purged ${result.deleted} entries from search + embeddings` +
+        (result.logEntriesRemoved > 0
+          ? ` + ${result.logEntriesRemoved} from log.jsonl.`
+          : `.`),
+    );
     process.exit(0);
   } catch (error) {
     const message = error instanceof Error ? error.message : "Unknown error";
@@ -774,8 +804,9 @@ async function handleCaptureTask(args: string[]): Promise<void> {
 
   if (result.success && result.event) {
     try {
-      await indexAndEmbed([result.event]);
+      const decisions = await indexAndEmbed([result.event]);
       output(result);
+      logContradictionDecisions(decisions);
       console.error("✅ Task logged and indexed");
       process.exit(0);
     } catch (error) {
@@ -809,8 +840,9 @@ async function handleCaptureKnowledge(args: string[]): Promise<void> {
 
   if (result.success && result.event) {
     try {
-      await indexAndEmbed([result.event]);
+      const decisions = await indexAndEmbed([result.event]);
       output(result);
+      logContradictionDecisions(decisions);
       console.error("✅ Knowledge logged and indexed");
       process.exit(0);
     } catch (error) {
@@ -842,8 +874,9 @@ async function handleCaptureNote(args: string[]): Promise<void> {
 
   if (result.success && result.event) {
     try {
-      await indexAndEmbed([result.event]);
+      const decisions = await indexAndEmbed([result.event]);
       output(result);
+      logContradictionDecisions(decisions);
       console.error("✅ Note logged and indexed");
       process.exit(0);
     } catch (error) {
@@ -878,8 +911,9 @@ async function handleCaptureTeaching(args: string[]): Promise<void> {
 
   if (result.success && result.event) {
     try {
-      await indexAndEmbed([result.event]);
+      const decisions = await indexAndEmbed([result.event]);
       output(result);
+      logContradictionDecisions(decisions);
       console.error("✅ Teaching logged and indexed");
       process.exit(0);
     } catch (error) {
@@ -915,8 +949,9 @@ async function handleCaptureObservation(args: string[]): Promise<void> {
 
   if (result.success && result.event) {
     try {
-      await indexAndEmbed([result.event]);
+      const decisions = await indexAndEmbed([result.event]);
       output(result);
+      logContradictionDecisions(decisions);
       console.error("✅ Observation logged and indexed");
       process.exit(0);
     } catch (error) {

package/index.ts

@@ -102,6 +102,7 @@ export { LoreType, LORE_TYPES, isValidLoreType } from "./lib/types";
 
 // Real-time indexing
 export { indexAndEmbed } from "./lib/realtime";
+export { type ContradictionDecision } from "./lib/contradiction";
 
 // Purge
 export {

package/lib/contradiction.ts

@@ -0,0 +1,213 @@
+/**
+ * lib/contradiction.ts - Write-time contradiction detection
+ *
+ * Uses hybrid search + local MLX model to classify new captures against
+ * existing entries. Determines whether a new entry should ADD (new info),
+ * NOOP (redundant), or DELETE+ADD (supersedes existing).
+ *
+ * Fail-open design: any error defaults to ADD — never blocks a capture.
+ *
+ * Usage:
+ *   const candidates = await findCandidates(event);
+ *   const result = await classifyContradiction(event, candidates);
+ *   // result.action: "ADD" | "NOOP" | "DELETE+ADD"
+ *   // result.deleteRowid: number (only set for DELETE+ADD)
+ */
+
+import { hybridSearch, type HybridResult } from "./semantic.js";
+import { PURGEABLE_SOURCES } from "./purge.js";
+import type { CaptureEvent } from "./capture.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type ContradictionAction = "ADD" | "DELETE+ADD" | "NOOP";
+
+export interface ContradictionResult {
+  action: ContradictionAction;
+  deleteRowid?: number;
+}
+
+/** Decision record returned to callers for logging */
+export interface ContradictionDecision {
+  action: ContradictionAction;
+  topic: string;
+  source: string;
+  deleteRowid?: number;
+  error?: string;
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const MLX_URL = "http://localhost:8080/v1/chat/completions";
+const MLX_MODEL = "mlx-community/Qwen2.5-7B-Instruct-4bit";
+const MLX_TIMEOUT_MS = 1500;
+
+const CANDIDATE_LIMIT = 5;
+
+// Sources eligible for contradiction checking (same as purgeable)
+const CONTRADICTION_SOURCES = new Set<string>(PURGEABLE_SOURCES);
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Check if an event's source is eligible for contradiction detection.
+ */
+export function isContradictionCheckable(source: string): boolean {
+  return CONTRADICTION_SOURCES.has(source);
+}
+
+/**
+ * Find existing entries that may contradict or duplicate the new event.
+ * Uses hybrid search scoped by source + topic for precision.
+ *
+ * Opens its own read connection (hybridSearch uses openDatabase(true)).
+ * Safe in WAL mode — concurrent reads with the write connection in indexAndEmbed.
+ *
+ * Note: entries inserted in the current indexAndEmbed batch are not visible
+ * to this read connection (uncommitted). This is acceptable — same-batch
+ * entries are unlikely to contradict each other.
+ */
+export async function findCandidates(
+  event: CaptureEvent,
+): Promise<HybridResult[]> {
+  const data = event.data as Record<string, unknown>;
+  const content = String(data.content || data.text || "");
+  const topic = String(data.topic || "");
+  const source = getSourceForEvent(event);
+
+  if (!content) return [];
+
+  return hybridSearch(content, {
+    source,
+    project: topic || undefined,
+    limit: CANDIDATE_LIMIT,
+  });
+}
+
+/**
+ * Classify a new event against existing candidates using local MLX model.
+ *
+ * LLM returns one of:
+ *   ADD     — new information not covered by candidates
+ *   NOOP    — duplicate/redundant (already captured)
+ *   DELETE <rowid> — new info supersedes a specific candidate
+ *
+ * Fail-open: any error (timeout, parse failure, model down) defaults to ADD.
+ */
+export async function classifyContradiction(
+  event: CaptureEvent,
+  candidates: HybridResult[],
+): Promise<ContradictionResult> {
+  if (candidates.length === 0) {
+    return { action: "ADD" };
+  }
+
+  const data = event.data as Record<string, unknown>;
+  const content = String(data.content || data.text || "");
+  const topic = String(data.topic || "");
+  const source = getSourceForEvent(event);
+
+  const candidateLines = candidates
+    .map((c) => `[rowid: ${c.rowid}] ${c.content}`)
+    .join("\n");
+
+  const systemPrompt = `You classify knowledge contradictions. Reply with exactly one word: ADD, NOOP, or DELETE.
+  ADD: new information not covered by candidates
+  NOOP: duplicate or redundant (already captured)
+  DELETE: new information supersedes a candidate (also provide rowid)`;
+
+  const userPrompt = `New entry (source: ${source}, topic: ${topic}):
+${content}
+
+Existing entries:
+${candidateLines}
+
+If DELETE, reply: DELETE <rowid>
+Otherwise reply: ADD or NOOP`;
+
+  try {
+    const resp = await fetch(MLX_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: MLX_MODEL,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt },
+        ],
+        max_tokens: 20,
+        temperature: 0,
+      }),
+      signal: AbortSignal.timeout(MLX_TIMEOUT_MS),
+    });
+
+    if (!resp.ok) {
+      return { action: "ADD" };
+    }
+
+    const json = (await resp.json()) as {
+      choices?: Array<{ message?: { content?: string } }>;
+    };
+
+    const raw = json.choices?.[0]?.message?.content?.trim() || "";
+    return parseClassification(raw);
+  } catch {
+    // Timeout, network error, or model unavailable — fail open
+    return { action: "ADD" };
+  }
+}
+
+// ─── Internal Helpers ───────────────────────────────────────────────────────
+
+/**
+ * Parse LLM response into a ContradictionResult.
+ * Accepts: "ADD", "NOOP", "DELETE 123", "DELETE <rowid>"
+ * Any parse failure defaults to ADD.
+ */
+function parseClassification(raw: string): ContradictionResult {
+  const normalized = raw.toUpperCase().trim();
+
+  if (normalized === "NOOP") {
+    return { action: "NOOP" };
+  }
+
+  if (normalized === "ADD") {
+    return { action: "ADD" };
+  }
+
+  // Match "DELETE <number>" pattern
+  const deleteMatch = normalized.match(/^DELETE\s+(\d+)/);
+  if (deleteMatch) {
+    const rowid = parseInt(deleteMatch[1], 10);
+    if (!isNaN(rowid) && rowid > 0) {
+      return { action: "DELETE+ADD", deleteRowid: rowid };
+    }
+  }
+
+  // Unparseable — default to ADD
+  return { action: "ADD" };
+}
+
+/**
+ * Map event type to source name (mirrors realtime.ts getSourceForEvent).
+ */
+function getSourceForEvent(event: CaptureEvent): string {
+  switch (event.type) {
+    case "knowledge":
+      return "captures";
+    case "teaching":
+      return "teachings";
+    case "observation":
+      return "observations";
+    case "insight":
+      return "insights";
+    case "learning":
+      return "learnings";
+    case "task":
+      return "flux";
+    case "note":
+      return "captures";
+    default:
+      return "captures";
+  }
+}

package/lib/indexer.ts

@@ -40,6 +40,18 @@ export interface IndexerContext {
 
 export type IndexerFunction = (ctx: IndexerContext) => Promise<void>;
 
+/**
+ * Sources excluded from --rebuild because the DB is their source of truth.
+ * These sources use real-time indexing (indexAndEmbed) with contradiction
+ * resolution. Rebuilding from log.jsonl would resurrect purged/superseded
+ * entries, breaking the contradiction resolution invariant.
+ */
+export const REBUILD_EXCLUDED_SOURCES = new Set([
+  "captures",
+  "observations",
+  "teachings",
+]);
+
 /**
  * Check if a path is configured and exists on disk.
  * Logs a specific reason when the check fails:
@@ -231,6 +243,14 @@ export async function runIndexer(
         continue;
       }
 
+      // Skip rebuild-excluded sources — DB is source of truth, not log.jsonl
+      if (rebuild && REBUILD_EXCLUDED_SOURCES.has(src)) {
+        console.log(
+          `${src}: skipped (DB is source of truth — not rebuilt from log)`,
+        );
+        continue;
+      }
+
       console.log(`Indexing ${src}...`);
 
       // Clear source if rebuilding

package/lib/purge.ts

@@ -10,8 +10,16 @@
  */
 
 import { Database } from "bun:sqlite";
-import { existsSync } from "fs";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+} from "fs";
+import { join } from "path";
 import { getDatabasePath, openDatabase } from "./db.js";
+import { getConfig } from "./config.js";
 
 // Only these sources can be purged — indexed sources (blogs, commits, etc.) are never purgeable
 export const PURGEABLE_SOURCES = [
@@ -33,6 +41,7 @@ export interface PurgeMatch {
 export interface PurgeResult {
   deleted: number;
   rowids: number[];
+  logEntriesRemoved: number;
 }
 
 /**
@@ -76,14 +85,20 @@ export function findPurgeMatches(
 }
 
 /**
- * Delete entries from both FTS5 search table and vec0 embeddings table.
+ * Delete entries from FTS5 search table, vec0 embeddings table,
+ * and optionally clean matching lines from log.jsonl.
  *
- * FTS5 DELETE: DELETE FROM search WHERE rowid = ?
- * vec0 DELETE: DELETE FROM embeddings WHERE doc_id = ?
+ * @param rowids - Row IDs to delete from search + embeddings
+ * @param matchContents - Content strings from findPurgeMatches for log.jsonl filtering.
+ *   Optional (default []); when empty, log.jsonl cleanup is skipped.
+ *   This avoids a breaking change for existing callers.
  */
-export function deleteEntries(rowids: number[]): PurgeResult {
+export function deleteEntries(
+  rowids: number[],
+  matchContents: string[] = [],
+): PurgeResult {
   if (rowids.length === 0) {
-    return { deleted: 0, rowids: [] };
+    return { deleted: 0, rowids: [], logEntriesRemoved: 0 };
   }
 
   // Open DB directly for read-write (matches realtime.ts pattern —
@@ -118,8 +133,66 @@ export function deleteEntries(rowids: number[]): PurgeResult {
       deleted++;
     }
 
-    return { deleted, rowids };
+    // Clean matching lines from log.jsonl (best-effort)
+    const logEntriesRemoved = purgeLogEntries(matchContents);
+
+    return { deleted, rowids, logEntriesRemoved };
   } finally {
     db.close();
   }
 }
+
+/**
+ * Remove lines from log.jsonl whose content matches any of the given strings.
+ *
+ * Uses atomic write: writes filtered content to a temp file, then renames.
+ * Matches on event.data.content (the raw capture content), not the assembled
+ * search table content — task entries may use assembled content that differs.
+ * This is acceptable: the rebuild exclusion (Change 2) is the hard guard;
+ * log.jsonl cleanup is best-effort.
+ *
+ * @param matchContents - Content strings to filter out
+ * @returns Number of lines removed
+ */
+function purgeLogEntries(matchContents: string[]): number {
+  if (matchContents.length === 0) return 0;
+
+  const logPath = join(getConfig().paths.data, "log.jsonl");
+  const tmpPath = logPath + ".tmp";
+
+  if (!existsSync(logPath)) return 0;
+
+  try {
+    // Clean up stale temp file from a prior crash
+    if (existsSync(tmpPath)) {
+      unlinkSync(tmpPath);
+    }
+
+    const lines = readFileSync(logPath, "utf-8").split("\n").filter(Boolean);
+    const filtered = lines.filter((line) => {
+      try {
+        const event = JSON.parse(line) as {
+          data?: { content?: string; text?: string };
+        };
+        const content = event.data?.content || event.data?.text || "";
+        return !matchContents.some((mc) => content.includes(mc));
+      } catch {
+        return true; // Keep unparseable lines
+      }
+    });
+
+    writeFileSync(
+      tmpPath,
+      filtered.join("\n") + (filtered.length > 0 ? "\n" : ""),
+      "utf-8",
+    );
+    renameSync(tmpPath, logPath);
+
+    return lines.length - filtered.length;
+  } catch (err) {
+    // log.jsonl cleanup is best-effort — never fail the purge
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[purge] log.jsonl cleanup failed (${message})`);
+    return 0;
+  }
+}

package/lib/realtime.ts

@@ -25,6 +25,12 @@ import {
 } from "./semantic.js";
 import { hashContent, getCachedEmbedding, cacheEmbedding } from "./cache.js";
 import type { CaptureEvent } from "./capture.js";
+import {
+  isContradictionCheckable,
+  findCandidates,
+  classifyContradiction,
+  type ContradictionDecision,
+} from "./contradiction.js";
 
 /**
  * Index and embed capture events for immediate searchability
@@ -33,8 +39,10 @@ import type { CaptureEvent } from "./capture.js";
  * 2. Generate embeddings with cache (instant semantic search)
  * 3. Insert into embeddings table
  */
-export async function indexAndEmbed(events: CaptureEvent[]): Promise<void> {
-  if (events.length === 0) return;
+export async function indexAndEmbed(
+  events: CaptureEvent[],
+): Promise<ContradictionDecision[]> {
+  if (events.length === 0) return [];
 
   const dbPath = getDatabasePath();
   if (!existsSync(dbPath)) {
@@ -53,21 +61,70 @@ export async function indexAndEmbed(events: CaptureEvent[]): Promise<void> {
     }
     db.loadExtension(vecPath);
 
+    // 0. Contradiction detection — filter events before insert
+    //    For purgeable sources, check if the new event contradicts or
+    //    duplicates existing entries. NOOP skips the event, DELETE+ADD
+    //    removes the old entry before inserting the new one.
+    const eventsToIndex: CaptureEvent[] = [];
+    const decisions: ContradictionDecision[] = [];
+    for (const event of events) {
+      const source = getSourceForEvent(event);
+      const data = event.data as Record<string, unknown>;
+      const topic = String(data.topic || "");
+
+      if (isContradictionCheckable(source)) {
+        try {
+          const candidates = await findCandidates(event);
+          if (candidates.length > 0) {
+            const result = await classifyContradiction(event, candidates);
+
+            if (result.action === "NOOP") {
+              decisions.push({ action: "NOOP", topic, source });
+              continue;
+            }
+
+            if (result.action === "DELETE+ADD" && result.deleteRowid) {
+              deleteSearchAndEmbedding(db, result.deleteRowid);
+              decisions.push({
+                action: "DELETE+ADD",
+                topic,
+                source,
+                deleteRowid: result.deleteRowid,
+              });
+            } else {
+              decisions.push({ action: "ADD", topic, source });
+            }
+            // ADD falls through to normal insert
+          }
+        } catch (err) {
+          // Fail open — if contradiction check fails, proceed with ADD
+          const message = err instanceof Error ? err.message : String(err);
+          decisions.push({ action: "ADD", topic, source, error: message });
+        }
+      }
+
+      eventsToIndex.push(event);
+    }
+
+    if (eventsToIndex.length === 0) return decisions;
+
     // 1. Insert into FTS5 and collect doc IDs
     const docIds: number[] = [];
-    for (const event of events) {
+    for (const event of eventsToIndex) {
       const docId = insertSearchEntry(db, event);
       docIds.push(docId);
     }
 
     // 2. Generate embeddings with cache
-    const contents = events.map((e) => getContentForEmbedding(e));
+    const contents = eventsToIndex.map((e) => getContentForEmbedding(e));
     const embeddings = await embedWithCache(db, contents);
 
     // 3. Insert embeddings
-    for (let i = 0; i < events.length; i++) {
-      insertEmbedding(db, docIds[i], embeddings[i], events[i]);
+    for (let i = 0; i < eventsToIndex.length; i++) {
+      insertEmbedding(db, docIds[i], embeddings[i], eventsToIndex[i]);
     }
+
+    return decisions;
   } finally {
     db.close();
   }
@@ -104,6 +161,16 @@ function insertSearchEntry(db: Database, event: CaptureEvent): number {
   return Number(result.lastInsertRowid);
 }
 
+/**
+ * Delete an entry from both FTS5 search and vec0 embeddings tables.
+ * Used by contradiction resolution to remove superseded entries.
+ * Reuses the same prepared statement pattern as purge.ts:108-114.
+ */
+function deleteSearchAndEmbedding(db: Database, rowid: number): void {
+  db.prepare("DELETE FROM search WHERE rowid = ?").run(rowid);
+  db.prepare("DELETE FROM embeddings WHERE doc_id = ?").run(rowid);
+}
+
 /**
  * Map event type to source name used in search table
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidwire/lore",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Unified knowledge CLI - Search, list, and capture your indexed knowledge",
   "type": "module",
   "main": "./index.ts",