clawmem 0.4.2 → 0.5.1

package/src/memory.ts

@@ -12,9 +12,13 @@
 export const HALF_LIVES: Record<string, number> = {
   handoff: 30,
   progress: 45,
+  conversation: 45,
+  problem: 60,
+  milestone: 60,
   note: 60,
   research: 90,
   project: 120,
+  preference: Infinity,
   decision: Infinity,
   hub: Infinity,
 };
@@ -25,10 +29,14 @@ export const HALF_LIVES: Record<string, number> = {
 
 export const TYPE_BASELINES: Record<string, number> = {
   decision: 0.85,
+  preference: 0.80,
   hub: 0.80,
+  problem: 0.75,
   research: 0.70,
+  milestone: 0.70,
   project: 0.65,
   handoff: 0.60,
+  conversation: 0.55,
   progress: 0.50,
   note: 0.50,
 };
@@ -37,7 +45,7 @@ export const TYPE_BASELINES: Record<string, number> = {
 // Content Type Inference
 // =============================================================================
 
-export type ContentType = "decision" | "hub" | "research" | "project" | "handoff" | "progress" | "note";
+export type ContentType = "decision" | "preference" | "hub" | "research" | "project" | "handoff" | "conversation" | "progress" | "milestone" | "problem" | "note";
 
 export function inferContentType(path: string, explicitType?: string): ContentType {
   if (explicitType && explicitType in TYPE_BASELINES) return explicitType as ContentType;
@@ -48,6 +56,7 @@ export function inferContentType(path: string, explicitType?: string): ContentTy
   if (lower.includes("research") || lower.includes("investigation") || lower.includes("analysis")) return "research";
   if (lower.includes("project") || lower.includes("epic") || lower.includes("initiative")) return "project";
   if (lower.includes("handoff") || lower.includes("handover") || lower.includes("session")) return "handoff";
+  if (lower.includes("conversation") || lower.includes("convo") || lower.includes("chat") || lower.includes("transcript")) return "conversation";
   if (lower.includes("progress") || lower.includes("status") || lower.includes("standup") || lower.includes("changelog")) return "progress";
   return "note";
 }
@@ -65,7 +74,7 @@ export type MemoryType = "episodic" | "semantic" | "procedural";
  * - procedural: how-to, patterns, workflows (actionable)
  */
 export function inferMemoryType(path: string, contentType: string, body?: string): MemoryType {
-  if (["handoff", "progress"].includes(contentType)) return "episodic";
+  if (["handoff", "progress", "conversation"].includes(contentType)) return "episodic";
   if (["decision", "hub", "research"].includes(contentType)) return "semantic";
   if (body && /\b(step\s+\d|workflow|recipe|how\s+to|procedure|runbook|playbook)\b/i.test(body)) return "procedural";
   if (path.includes("sop") || path.includes("runbook") || path.includes("playbook")) return "procedural";
@@ -141,7 +150,7 @@ export function confidenceScore(
   // Attention decay: reduce confidence if not accessed recently (5% per week)
   // Only apply to episodic/progress content — skip for durable types (decision, hub, research)
   // Also skip if last_accessed_at was backfilled from modified_at (no real access yet)
-  const DECAY_EXEMPT_TYPES = new Set(["decision", "hub", "research", "antipattern"]);
+  const DECAY_EXEMPT_TYPES = new Set(["decision", "hub", "research", "antipattern", "preference"]);
   let attentionDecay = 1.0;
   if (lastAccessedAt && !DECAY_EXEMPT_TYPES.has(contentType)) {
     const lastAccess = typeof lastAccessedAt === "string" ? new Date(lastAccessedAt) : lastAccessedAt;

package/src/normalize.ts

@@ -0,0 +1,390 @@
+/**
+ * normalize.ts — Conversation format normalizer for ClawMem
+ *
+ * Converts chat export files into normalized markdown documents suitable for
+ * ClawMem's indexing pipeline. Supports:
+ *   - Claude Code JSONL sessions
+ *   - Claude.ai JSON exports (flat + privacy export)
+ *   - ChatGPT conversations.json (mapping tree)
+ *   - Slack JSON exports (DMs + channels)
+ *   - Plain text with user/assistant markers
+ *
+ * Each exchange pair (user + assistant) becomes one markdown chunk.
+ * Inspired by MemPalace normalize.py, rewritten for TypeScript/Bun.
+ */
+
+import { readFileSync, readdirSync, statSync } from "fs";
+import { basename, extname, join, relative } from "path";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type Message = { role: "user" | "assistant"; content: string };
+
+export type NormalizedConversation = {
+  source: string;           // original filename
+  format: string;           // detected format
+  messages: Message[];      // normalized messages
+};
+
+export type ConversationChunk = {
+  title: string;            // "Exchange N" or extracted topic
+  body: string;             // markdown body
+  sourcePath: string;       // relative path of source file
+  chunkIndex: number;
+};
+
+// =============================================================================
+// Format Detection & Normalization
+// =============================================================================
+
+const CONVO_EXTENSIONS = new Set([".txt", ".md", ".json", ".jsonl"]);
+const SKIP_DIRS = new Set([".git", "node_modules", "__pycache__", ".venv", "venv", "dist", "build", ".next", ".mempalace", ".grepai", "tool-results"]);
+
+export function normalizeFile(filepath: string): NormalizedConversation | null {
+  let content: string;
+  try {
+    content = readFileSync(filepath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  if (!content.trim()) return null;
+
+  const ext = extname(filepath).toLowerCase();
+
+  // Try JSONL formats first (Claude Code, Codex CLI)
+  if (ext === ".jsonl" || (content.trim().startsWith("{") && content.includes("\n{"))) {
+    const cc = tryClaudeCodeJsonl(content);
+    if (cc) return { source: basename(filepath), format: "claude-code", messages: cc };
+
+    const codex = tryCodexJsonl(content);
+    if (codex) return { source: basename(filepath), format: "codex-cli", messages: codex };
+  }
+
+  // Try JSON formats
+  if (ext === ".json" || content.trim().startsWith("{") || content.trim().startsWith("[")) {
+    try {
+      const data = JSON.parse(content);
+
+      const claude = tryClaudeAiJson(data);
+      if (claude) return { source: basename(filepath), format: "claude-ai", messages: claude };
+
+      const chatgpt = tryChatGptJson(data);
+      if (chatgpt) return { source: basename(filepath), format: "chatgpt", messages: chatgpt };
+
+      const slack = trySlackJson(data);
+      if (slack) return { source: basename(filepath), format: "slack", messages: slack };
+    } catch {
+      // Not valid JSON
+    }
+  }
+
+  // Try plain text with user/assistant markers
+  const plain = tryPlainText(content);
+  if (plain) return { source: basename(filepath), format: "plain-text", messages: plain };
+
+  return null;
+}
+
+// =============================================================================
+// Format Parsers
+// =============================================================================
+
+function tryClaudeCodeJsonl(content: string): Message[] | null {
+  const lines = content.trim().split("\n").filter(l => l.trim());
+  const messages: Message[] = [];
+
+  for (const line of lines) {
+    let entry: any;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (typeof entry !== "object" || !entry) continue;
+
+    const msgType = entry.type ?? "";
+    const message = entry.message ?? {};
+
+    if (msgType === "human" || msgType === "user") {
+      const text = extractContent(message.content);
+      if (text) messages.push({ role: "user", content: text });
+    } else if (msgType === "assistant") {
+      const text = extractContent(message.content);
+      if (text) messages.push({ role: "assistant", content: text });
+    }
+  }
+
+  return messages.length >= 2 ? messages : null;
+}
+
+function tryCodexJsonl(content: string): Message[] | null {
+  const lines = content.trim().split("\n").filter(l => l.trim());
+  const messages: Message[] = [];
+  let hasSessionMeta = false;
+
+  for (const line of lines) {
+    let entry: any;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (typeof entry !== "object" || !entry) continue;
+
+    if (entry.type === "session_meta") { hasSessionMeta = true; continue; }
+    if (entry.type !== "event_msg") continue;
+
+    const payload = entry.payload;
+    if (typeof payload !== "object" || !payload) continue;
+
+    const text = typeof payload.message === "string" ? payload.message.trim() : "";
+    if (!text) continue;
+
+    if (payload.type === "user_message") messages.push({ role: "user", content: text });
+    else if (payload.type === "agent_message") messages.push({ role: "assistant", content: text });
+  }
+
+  return messages.length >= 2 && hasSessionMeta ? messages : null;
+}
+
+function tryClaudeAiJson(data: any): Message[] | null {
+  // Privacy export: array of conversation objects with chat_messages
+  if (Array.isArray(data) && data.length > 0 && data[0]?.chat_messages) {
+    const messages: Message[] = [];
+    for (const convo of data) {
+      for (const item of convo.chat_messages ?? []) {
+        const role = item.role ?? "";
+        const text = extractContent(item.content);
+        if ((role === "user" || role === "human") && text) messages.push({ role: "user", content: text });
+        else if ((role === "assistant" || role === "ai") && text) messages.push({ role: "assistant", content: text });
+      }
+    }
+    return messages.length >= 2 ? messages : null;
+  }
+
+  // Flat messages list or wrapped in { messages: [...] }
+  let msgs = data;
+  if (typeof data === "object" && !Array.isArray(data)) {
+    msgs = data.messages ?? data.chat_messages ?? [];
+  }
+  if (!Array.isArray(msgs)) return null;
+
+  const messages: Message[] = [];
+  for (const item of msgs) {
+    if (typeof item !== "object" || !item) continue;
+    const role = item.role ?? "";
+    const text = extractContent(item.content);
+    if ((role === "user" || role === "human") && text) messages.push({ role: "user", content: text });
+    else if ((role === "assistant" || role === "ai") && text) messages.push({ role: "assistant", content: text });
+  }
+  return messages.length >= 2 ? messages : null;
+}
+
+function tryChatGptJson(data: any): Message[] | null {
+  if (typeof data !== "object" || !data?.mapping) return null;
+  const mapping = data.mapping;
+  const messages: Message[] = [];
+
+  // Find root node (parent=null, no message)
+  let rootId: string | null = null;
+  let fallback: string | null = null;
+  for (const [nodeId, node] of Object.entries(mapping) as [string, any][]) {
+    if (node.parent === null) {
+      if (!node.message) { rootId = nodeId; break; }
+      else if (!fallback) fallback = nodeId;
+    }
+  }
+  rootId = rootId ?? fallback;
+  if (!rootId) return null;
+
+  // Walk the tree
+  let currentId: string | null = rootId;
+  const visited = new Set<string>();
+  while (currentId && !visited.has(currentId)) {
+    visited.add(currentId);
+    const node = (mapping as any)[currentId];
+    if (node?.message) {
+      const role = node.message.author?.role ?? "";
+      const content = node.message.content;
+      const parts = content?.parts ?? [];
+      const text = parts.filter((p: any) => typeof p === "string").join(" ").trim();
+      if (role === "user" && text) messages.push({ role: "user", content: text });
+      else if (role === "assistant" && text) messages.push({ role: "assistant", content: text });
+    }
+    currentId = node?.children?.[0] ?? null;
+  }
+  return messages.length >= 2 ? messages : null;
+}
+
+function trySlackJson(data: any): Message[] | null {
+  if (!Array.isArray(data)) return null;
+
+  // Count unique speakers — only support 2-party DMs
+  const speakers = new Set<string>();
+  for (const item of data) {
+    if (typeof item !== "object" || item?.type !== "message") continue;
+    const userId = item.user ?? item.username ?? "";
+    if (userId) speakers.add(userId);
+    if (speakers.size > 2) return null; // multi-person channel, unsupported
+  }
+  if (speakers.size < 2) return null;
+
+  const messages: Message[] = [];
+  const speakerList = [...speakers];
+  const roleMap: Record<string, "user" | "assistant"> = {
+    [speakerList[0]]: "user",
+    [speakerList[1]]: "assistant",
+  };
+
+  for (const item of data) {
+    if (typeof item !== "object" || item?.type !== "message") continue;
+    const userId = item.user ?? item.username ?? "";
+    const text = (item.text ?? "").trim();
+    if (!text || !roleMap[userId]) continue;
+    messages.push({ role: roleMap[userId], content: text });
+  }
+  return messages.length >= 2 ? messages : null;
+}
+
+function tryPlainText(content: string): Message[] | null {
+  const messages: Message[] = [];
+  // Only match explicit role prefixes (User:, Human:, Assistant:, etc.)
+  // Do NOT match bare blockquotes (> ) — too many false positives with markdown
+  const lines = content.split("\n");
+  let currentRole: "user" | "assistant" | null = null;
+  let currentText: string[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    let newRole: "user" | "assistant" | null = null;
+
+    if (/^(User|Human)\s*:\s*/i.test(trimmed)) {
+      newRole = "user";
+    } else if (/^(Assistant|AI|Claude|GPT|Bot)\s*:\s*/i.test(trimmed)) {
+      newRole = "assistant";
+    }
+
+    if (newRole) {
+      if (currentRole && currentText.length > 0) {
+        const text = currentText.join("\n").trim();
+        if (text) messages.push({ role: currentRole, content: text });
+      }
+      currentRole = newRole;
+      // Strip the role prefix
+      const cleaned = trimmed.replace(/^(User|Human|Assistant|AI|Claude|GPT|Bot)\s*:\s*/i, "");
+      currentText = cleaned ? [cleaned] : [];
+    } else if (currentRole) {
+      currentText.push(trimmed);
+    }
+  }
+
+  // Flush last
+  if (currentRole && currentText.length > 0) {
+    const text = currentText.join("\n").trim();
+    if (text) messages.push({ role: currentRole, content: text });
+  }
+
+  // Require at least 2 exchanges AND both roles present (prevents false positives)
+  const hasUser = messages.some(m => m.role === "user");
+  const hasAssistant = messages.some(m => m.role === "assistant");
+  return messages.length >= 4 && hasUser && hasAssistant ? messages : null;
+}
+
+// =============================================================================
+// Content Extraction
+// =============================================================================
+
+function extractContent(content: any): string {
+  if (typeof content === "string") return content.trim();
+  if (Array.isArray(content)) {
+    return content
+      .map(item => {
+        if (typeof item === "string") return item;
+        if (typeof item === "object" && item?.type === "text") return item.text ?? "";
+        return "";
+      })
+      .join(" ")
+      .trim();
+  }
+  if (typeof content === "object" && content) return (content.text ?? "").trim();
+  return "";
+}
+
+// =============================================================================
+// Chunking — Exchange Pairs
+// =============================================================================
+
+const MIN_CHUNK_CHARS = 30;
+
+export function chunkConversation(conv: NormalizedConversation): ConversationChunk[] {
+  const chunks: ConversationChunk[] = [];
+  const { messages, source } = conv;
+
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i].role !== "user") continue;
+
+    const userMsg = messages[i].content;
+    // Collect ALL consecutive assistant messages (handles split replies)
+    const assistantParts: string[] = [];
+    while (i + 1 < messages.length && messages[i + 1].role === "assistant") {
+      assistantParts.push(messages[i + 1].content);
+      i++;
+    }
+    const assistantMsg = assistantParts.join("\n\n");
+
+    // Build markdown chunk
+    const title = extractExchangeTitle(userMsg, chunks.length + 1);
+    const body = formatExchangeMarkdown(userMsg, assistantMsg);
+
+    if (body.length >= MIN_CHUNK_CHARS) {
+      chunks.push({
+        title,
+        body,
+        sourcePath: source,
+        chunkIndex: chunks.length,
+      });
+    }
+  }
+
+  return chunks;
+}
+
+function extractExchangeTitle(userMessage: string, index: number): string {
+  // Use the first line/sentence of the user message, capped at 80 chars
+  const firstLine = userMessage.split("\n")[0].trim();
+  if (firstLine.length <= 80) return firstLine;
+  return firstLine.slice(0, 77) + "...";
+}
+
+function formatExchangeMarkdown(userMsg: string, assistantMsg: string): string {
+  const lines: string[] = [];
+  lines.push("**User:**", userMsg, "");
+  if (assistantMsg) {
+    lines.push("**Assistant:**", assistantMsg, "");
+  }
+  return lines.join("\n");
+}
+
+// =============================================================================
+// Directory Scanner
+// =============================================================================
+
+export function scanConversationDir(dir: string): string[] {
+  const files: string[] = [];
+
+  function walk(d: string) {
+    let entries: string[];
+    try { entries = readdirSync(d); } catch { return; }
+
+    for (const entry of entries) {
+      const fullPath = join(d, entry);
+      try {
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          if (!SKIP_DIRS.has(entry)) walk(fullPath);
+        } else if (stat.isFile()) {
+          const ext = extname(entry).toLowerCase();
+          if (CONVO_EXTENSIONS.has(ext)) files.push(fullPath);
+        }
+      } catch { continue; }
+    }
+  }
+
+  walk(dir);
+  return files;
+}

package/src/observer.ts

@@ -15,7 +15,7 @@ import { MAX_LLM_GENERATE_TIMEOUT_MS } from "./limits.ts";
 // =============================================================================
 
 export type Observation = {
-  type: "decision" | "bugfix" | "feature" | "refactor" | "discovery" | "change";
+  type: "decision" | "bugfix" | "feature" | "refactor" | "discovery" | "change" | "preference" | "milestone" | "problem";
   title: string;
   facts: string[];
   narrative: string;
@@ -51,7 +51,7 @@ const OBSERVATION_SYSTEM_PROMPT = `You are an observer analyzing a coding sessio
 For each significant action, decision, or discovery, output an <observation> XML element.
 
 <observation>
-  <type>one of: decision, bugfix, feature, refactor, discovery, change</type>
+  <type>one of: decision, bugfix, feature, refactor, discovery, change, preference, milestone, problem</type>
   <title>Brief descriptive title (max 80 chars)</title>
   <facts>
     <fact>Individual atomic fact</fact>
@@ -69,7 +69,12 @@ Rules:
 - Each fact should be a standalone, atomic piece of information
 - The narrative should explain WHY something was done, not just WHAT
 - Only include files that were explicitly mentioned in the transcript
-- If no significant observations, output nothing`;
+- If no significant observations, output nothing
+
+Type guidance:
+- preference: user expresses a preference, habit, or way of working (e.g., "don't use subagents for this", "I prefer single PRs")
+- milestone: significant completion point, version release, deployment, or phase transition
+- problem: persistent issue, recurring bug, architectural limitation, or unresolved blocker`;
 
 const SUMMARY_SYSTEM_PROMPT = `You are a session summarizer. Analyze this coding session transcript and output a structured summary.
 
@@ -118,6 +123,7 @@ function prepareTranscript(messages: TranscriptMessage[]): string {
 
 const VALID_OBSERVATION_TYPES = new Set([
   "decision", "bugfix", "feature", "refactor", "discovery", "change",
+  "preference", "milestone", "problem",
 ]);
 
 const VALID_CONCEPTS = new Set([

package/src/store.ts

@@ -708,6 +708,31 @@ function initializeDatabase(db: Database): void {
   db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_cooccurrences_a ON entity_cooccurrences(entity_a)`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_cooccurrences_b ON entity_cooccurrences(entity_b)`);
 
+  // SPO knowledge graph: temporal entity-relationship triples
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS entity_triples (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      subject_entity_id TEXT NOT NULL,
+      predicate TEXT NOT NULL,
+      object_entity_id TEXT,
+      object_literal TEXT,
+      valid_from TEXT,
+      valid_to TEXT,
+      confidence REAL DEFAULT 1.0,
+      source_doc_id INTEGER,
+      source_fact TEXT,
+      created_at TEXT DEFAULT (datetime('now')),
+      FOREIGN KEY (subject_entity_id) REFERENCES entity_nodes(entity_id),
+      FOREIGN KEY (object_entity_id) REFERENCES entity_nodes(entity_id),
+      FOREIGN KEY (source_doc_id) REFERENCES documents(id)
+    )
+  `);
+
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_triples_subject ON entity_triples(subject_entity_id)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_triples_object ON entity_triples(object_entity_id)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_triples_predicate ON entity_triples(predicate)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_triples_valid ON entity_triples(valid_from, valid_to)`);
+
   // Entity FTS5 for fuzzy name lookup
   db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(entity_id, name, entity_type)`);
 
@@ -904,6 +929,12 @@ export type Store = {
   searchEntities: (query: string, limit?: number) => { entity_id: string; name: string; type: string; mention_count: number; cooccurrence_count: number }[];
   getEntityGraphNeighbors: (seedDocIds: number[], limit?: number) => { docId: number; score: number; viaEntity: string }[];
 
+  // SPO knowledge graph
+  addTriple: (subjectEntityId: string, predicate: string, objectEntityId: string | null, objectLiteral: string | null, options?: { validFrom?: string; validTo?: string; confidence?: number; sourceDocId?: number; sourceFact?: string }) => number;
+  invalidateTriple: (subjectEntityId: string, predicate: string, objectEntityId: string | null, objectLiteral: string | null, endedDate?: string) => number;
+  queryEntityTriples: (entityId: string, options?: { asOf?: string; direction?: "outgoing" | "incoming" | "both" }) => { id: number; direction: string; subject: string; predicate: string; object: string; validFrom: string | null; validTo: string | null; confidence: number; current: boolean }[];
+  getTripleStats: () => { totalTriples: number; currentFacts: number; expiredFacts: number; predicateTypes: string[] };
+
   // Co-activation tracking
   recordCoActivation: (paths: string[]) => void;
   getCoActivated: (path: string, limit?: number) => { path: string; count: number }[];
@@ -1070,6 +1101,93 @@ export function createStore(dbPath?: string, opts?: { readonly?: boolean; busyTi
     searchEntities: (query: string, limit?: number) => searchEntities(db, query, limit),
     getEntityGraphNeighbors: (seedDocIds: number[], limit?: number) => getEntityGraphNeighbors(db, seedDocIds, limit),
 
+    // SPO knowledge graph
+    addTriple: (subjectEntityId: string, predicate: string, objectEntityId: string | null, objectLiteral: string | null, options?: { validFrom?: string; validTo?: string; confidence?: number; sourceDocId?: number; sourceFact?: string }) => {
+      const pred = predicate.toLowerCase().replace(/\s+/g, "_");
+      const now = new Date().toISOString();
+      const objClause = objectEntityId
+        ? "object_entity_id = ? AND object_literal IS NULL"
+        : "object_entity_id IS NULL AND object_literal = ?";
+      const objParam = objectEntityId ?? objectLiteral;
+      const existing = db.prepare(
+        `SELECT id FROM entity_triples WHERE subject_entity_id = ? AND predicate = ? AND ${objClause} AND valid_to IS NULL`
+      ).get(subjectEntityId, pred, objParam) as { id: number } | null;
+      if (existing) return existing.id;
+
+      const result = db.prepare(`
+        INSERT INTO entity_triples (subject_entity_id, predicate, object_entity_id, object_literal, valid_from, valid_to, confidence, source_doc_id, source_fact, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        subjectEntityId, pred, objectEntityId, objectLiteral,
+        options?.validFrom ?? null, options?.validTo ?? null,
+        options?.confidence ?? 1.0, options?.sourceDocId ?? null,
+        options?.sourceFact ?? null, now
+      );
+      return Number(result.lastInsertRowid);
+    },
+
+    invalidateTriple: (subjectEntityId: string, predicate: string, objectEntityId: string | null, objectLiteral: string | null, endedDate?: string) => {
+      const pred = predicate.toLowerCase().replace(/\s+/g, "_");
+      const ended = endedDate || new Date().toISOString().slice(0, 10);
+      const objClause = objectEntityId
+        ? "object_entity_id = ? AND object_literal IS NULL"
+        : "object_entity_id IS NULL AND object_literal = ?";
+      const objParam = objectEntityId ?? objectLiteral;
+      const result = db.prepare(
+        `UPDATE entity_triples SET valid_to = ? WHERE subject_entity_id = ? AND predicate = ? AND ${objClause} AND valid_to IS NULL`
+      ).run(ended, subjectEntityId, pred, objParam);
+      return result.changes;
+    },
+
+    queryEntityTriples: (entityId: string, options?: { asOf?: string; direction?: "outgoing" | "incoming" | "both" }) => {
+      const direction = options?.direction ?? "both";
+      const asOf = options?.asOf;
+      const results: { id: number; direction: string; subject: string; predicate: string; object: string; validFrom: string | null; validTo: string | null; confidence: number; current: boolean }[] = [];
+
+      if (direction === "outgoing" || direction === "both") {
+        let query = `SELECT t.id, t.predicate, t.object_entity_id, t.object_literal, t.valid_from, t.valid_to, t.confidence,
+                      COALESCE(s.name, t.subject_entity_id) as sub_name, COALESCE(o.name, t.object_literal, t.object_entity_id) as obj_name
+                     FROM entity_triples t
+                     LEFT JOIN entity_nodes s ON t.subject_entity_id = s.entity_id
+                     LEFT JOIN entity_nodes o ON t.object_entity_id = o.entity_id
+                     WHERE t.subject_entity_id = ?`;
+        const params: any[] = [entityId];
+        if (asOf) {
+          query += " AND (t.valid_from IS NULL OR t.valid_from <= ?) AND (t.valid_to IS NULL OR t.valid_to >= ?)";
+          params.push(asOf, asOf);
+        }
+        for (const row of db.prepare(query).all(...params) as any[]) {
+          results.push({ id: row.id, direction: "outgoing", subject: row.sub_name, predicate: row.predicate, object: row.obj_name, validFrom: row.valid_from, validTo: row.valid_to, confidence: row.confidence, current: row.valid_to === null });
+        }
+      }
+
+      if (direction === "incoming" || direction === "both") {
+        let query = `SELECT t.id, t.predicate, t.valid_from, t.valid_to, t.confidence,
+                      COALESCE(s.name, t.subject_entity_id) as sub_name, COALESCE(o.name, t.object_literal, t.object_entity_id) as obj_name
+                     FROM entity_triples t
+                     LEFT JOIN entity_nodes s ON t.subject_entity_id = s.entity_id
+                     LEFT JOIN entity_nodes o ON t.object_entity_id = o.entity_id
+                     WHERE t.object_entity_id = ?`;
+        const params: any[] = [entityId];
+        if (asOf) {
+          query += " AND (t.valid_from IS NULL OR t.valid_from <= ?) AND (t.valid_to IS NULL OR t.valid_to >= ?)";
+          params.push(asOf, asOf);
+        }
+        for (const row of db.prepare(query).all(...params) as any[]) {
+          results.push({ id: row.id, direction: "incoming", subject: row.sub_name, predicate: row.predicate, object: row.obj_name, validFrom: row.valid_from, validTo: row.valid_to, confidence: row.confidence, current: row.valid_to === null });
+        }
+      }
+
+      return results;
+    },
+
+    getTripleStats: () => {
+      const total = (db.prepare("SELECT COUNT(*) as n FROM entity_triples").get() as any).n;
+      const current = (db.prepare("SELECT COUNT(*) as n FROM entity_triples WHERE valid_to IS NULL").get() as any).n;
+      const predicates = db.prepare("SELECT DISTINCT predicate FROM entity_triples ORDER BY predicate").all().map((r: any) => r.predicate);
+      return { totalTriples: total, currentFacts: current, expiredFacts: total - current, predicateTypes: predicates };
+    },
+
     // Co-activation tracking
     recordCoActivation: (paths: string[]) => {
       if (paths.length < 2) return;
@@ -1333,6 +1451,7 @@ export type DocumentRow = {
   confidence: number;
   accessCount: number;
   bodyLength: number;
+  pinned: number;
 };
 
 // =============================================================================
@@ -3560,7 +3679,7 @@ function getDocumentsByTypeFn(db: Database, contentType: string, limit: number =
     SELECT d.id, d.collection, d.path, d.title, d.hash, d.modified_at as modifiedAt,
            d.domain, d.workstream, d.tags, d.content_type as contentType,
            d.review_by as reviewBy, d.confidence, d.access_count as accessCount,
-           LENGTH(c.doc) as bodyLength
+           LENGTH(c.doc) as bodyLength, d.pinned
     FROM documents d
     JOIN content c ON c.hash = d.hash
     WHERE d.active = 1 AND d.content_type = ?