@icex-labs/openclaw-memory-engine 3.3.1

package/lib/episodes.js

@@ -0,0 +1,133 @@
+/**
+ * Episodic memory: conversation-level summaries with decisions, mood, and topics.
+ * Enables "what did we discuss last time about X?" queries.
+ *
+ * Storage: memory/episodes.jsonl — one episode per line.
+ */
+
+import { readFileSync, appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { episodesPath } from "./paths.js";
+import { getEmbedding, cosineSimilarity, loadEmbeddingCache, saveEmbeddingCache } from "./embedding.js";
+
+// ─── In-memory cache ───
+
+const cache = new Map();
+
+export function loadEpisodes(ws) {
+  if (cache.has(ws) && cache.get(ws).loaded) return cache.get(ws).episodes;
+  const p = episodesPath(ws);
+  let episodes = [];
+  if (existsSync(p)) {
+    episodes = readFileSync(p, "utf-8")
+      .trim().split("\n").filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  }
+  cache.set(ws, { episodes, loaded: true });
+  return episodes;
+}
+
+/**
+ * Save a conversation episode.
+ * @returns {object} the saved episode record
+ */
+export function saveEpisode(ws, { summary, decisions = [], mood = "", topics = [], participants = [], duration_minutes = null }) {
+  const episode = {
+    id: `ep-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+    type: "episode",
+    ts: new Date().toISOString(),
+    summary,
+    decisions,
+    mood,
+    topics,
+    participants,
+    duration_minutes,
+  };
+
+  mkdirSync(join(ws, "memory"), { recursive: true });
+  appendFileSync(episodesPath(ws), JSON.stringify(episode) + "\n", "utf-8");
+
+  if (cache.has(ws) && cache.get(ws).loaded) {
+    cache.get(ws).episodes.push(episode);
+  }
+
+  return episode;
+}
+
+/**
+ * Search episodes by query (hybrid: keyword + semantic) or get recent N.
+ * @param {string} [query] - search query (if null, returns recent episodes)
+ * @param {number} [lastN=5] - number of results
+ * @returns {Promise<object[]>}
+ */
+export async function recallEpisodes(ws, query = null, lastN = 5) {
+  const episodes = loadEpisodes(ws);
+  if (episodes.length === 0) return [];
+
+  // If no query, return most recent
+  if (!query) {
+    return episodes.slice(-lastN).reverse();
+  }
+
+  const queryLower = query.toLowerCase();
+  const queryTerms = queryLower.split(/\s+/).filter((t) => t.length > 1);
+
+  // Try semantic search
+  const queryEmb = await getEmbedding(query);
+  const embCache = loadEmbeddingCache(ws);
+
+  const scored = episodes.map((ep) => {
+    // Build searchable text from all episode fields
+    const text = [
+      ep.summary || "",
+      ...(ep.decisions || []),
+      ...(ep.topics || []),
+      ep.mood || "",
+    ].join(" ").toLowerCase();
+
+    // Keyword score
+    let kwScore = 0;
+    for (const term of queryTerms) {
+      if (text.includes(term)) kwScore += 1;
+    }
+    if (queryTerms.length > 1 && text.includes(queryLower)) kwScore += 3;
+
+    // Semantic score
+    let semScore = 0;
+    if (queryEmb && ep.id && embCache[ep.id]) {
+      semScore = Math.max(0, cosineSimilarity(queryEmb, embCache[ep.id]));
+    }
+
+    // Recency bonus
+    let recencyScore = 0;
+    if (ep.ts) {
+      const ageDays = (Date.now() - new Date(ep.ts).getTime()) / 86400000;
+      recencyScore = Math.max(0, 1 - ageDays / 90); // episodes decay faster (90 days)
+    }
+
+    const total = kwScore * 2 + semScore * 5 + recencyScore;
+    return total > 0 ? { episode: ep, score: total } : null;
+  }).filter(Boolean);
+
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, lastN).map((s) => s.episode);
+}
+
+/**
+ * Index episode embedding for semantic search.
+ */
+export async function indexEpisodeEmbedding(ws, episode) {
+  const text = [
+    episode.summary,
+    ...(episode.decisions || []),
+    ...(episode.topics || []),
+  ].filter(Boolean).join(" ");
+
+  const emb = await getEmbedding(text);
+  if (emb) {
+    const embCache = loadEmbeddingCache(ws);
+    embCache[episode.id] = emb;
+    saveEmbeddingCache(ws);
+  }
+}

package/lib/graph.js

@@ -0,0 +1,148 @@
+/**
+ * Knowledge Graph: triple store (subject, relation, object).
+ * Enables relational queries like "who is George's doctor" or "what treats 荨麻疹".
+ *
+ * Storage: memory/graph.jsonl — one triple per line.
+ * Auto-extraction: pattern-based extraction from archival insert content.
+ */
+
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { graphPath } from "./paths.js";
+
+// ─── In-memory cache ───
+
+const cache = new Map(); // ws → { triples: [], loaded: false }
+
+export function loadGraph(ws) {
+  if (cache.has(ws) && cache.get(ws).loaded) return cache.get(ws).triples;
+  const p = graphPath(ws);
+  let triples = [];
+  if (existsSync(p)) {
+    triples = readFileSync(p, "utf-8")
+      .trim().split("\n").filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  }
+  cache.set(ws, { triples, loaded: true });
+  return triples;
+}
+
+export function addTriple(ws, subject, relation, object, sourceId = null) {
+  const triples = loadGraph(ws);
+
+  // Deduplicate: same subject+relation+object
+  const exists = triples.some(
+    (t) => t.s === subject && t.r === relation && t.o === object,
+  );
+  if (exists) return null;
+
+  const triple = {
+    id: `tri-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+    s: subject,
+    r: relation,
+    o: object,
+    ts: new Date().toISOString(),
+    source: sourceId,
+  };
+
+  mkdirSync(join(ws, "memory"), { recursive: true });
+  appendFileSync(graphPath(ws), JSON.stringify(triple) + "\n", "utf-8");
+  triples.push(triple);
+  return triple;
+}
+
+export function removeTriple(ws, tripleId) {
+  const triples = loadGraph(ws);
+  const idx = triples.findIndex((t) => t.id === tripleId);
+  if (idx === -1) return false;
+  triples.splice(idx, 1);
+  writeFileSync(graphPath(ws), triples.map((t) => JSON.stringify(t)).join("\n") + (triples.length ? "\n" : ""), "utf-8");
+  return true;
+}
+
+/**
+ * Query the graph from a starting entity, optionally filtering by relation.
+ * @param {string} entity - starting node
+ * @param {string} [relation] - optional relation filter
+ * @param {number} [depth=2] - traversal depth
+ * @returns {Array<{ path: string[], triple: object }>}
+ */
+export function queryGraph(ws, entity, relation = null, depth = 2) {
+  const triples = loadGraph(ws);
+  const entityLower = entity.toLowerCase();
+  const results = [];
+  const visited = new Set();
+
+  function traverse(current, currentDepth, path) {
+    if (currentDepth > depth) return;
+    const key = `${current}:${currentDepth}`;
+    if (visited.has(key)) return;
+    visited.add(key);
+
+    const currentLower = current.toLowerCase();
+    for (const t of triples) {
+      // Forward: subject matches
+      if (t.s.toLowerCase() === currentLower) {
+        if (relation && t.r.toLowerCase() !== relation.toLowerCase()) continue;
+        results.push({ path: [...path, `--${t.r}-->`], node: t.o, triple: t });
+        traverse(t.o, currentDepth + 1, [...path, `--${t.r}-->`, t.o]);
+      }
+      // Reverse: object matches
+      if (t.o.toLowerCase() === currentLower) {
+        if (relation && t.r.toLowerCase() !== relation.toLowerCase()) continue;
+        results.push({ path: [...path, `<--${t.r}--`], node: t.s, triple: t });
+        traverse(t.s, currentDepth + 1, [...path, `<--${t.r}--`, t.s]);
+      }
+    }
+  }
+
+  traverse(entity, 1, [entity]);
+  return results;
+}
+
+// ─── Auto-extraction patterns ───
+
+const EXTRACTION_PATTERNS = [
+  // "X's doctor is Y" / "X的医生是Y"
+  { re: /(.+?)(?:'s|的)\s*(?:doctor|医生|主治医生)\s*(?:is|是|为)\s*(.+)/i, r: "has_doctor" },
+  // "X lives in Y" / "X住在Y"
+  { re: /(.+?)\s*(?:lives? in|住在|位于)\s*(.+)/i, r: "lives_in" },
+  // "X works at Y" / "X在Y工作"
+  { re: /(.+?)\s*(?:works? at|在(.+?)工作)/i, r: "works_at" },
+  // "X has condition Y" / disease / 疾病
+  { re: /(.+?)\s*(?:has|有|患有)\s*(?:chronic |慢性)?\s*(.+?(?:症|病|urticaria|condition|disease))/i, r: "has_condition" },
+  // "X treated by/takes Y" / 用药
+  { re: /(.+?)\s*(?:takes?|服用|用药|treated (?:by|with))\s*(.+)/i, r: "treated_by" },
+  // "X's wife/husband is Y"
+  { re: /(.+?)(?:'s|的)\s*(wife|husband|妻子|丈夫|老婆|老公)\s*(?:is|是|为)\s*(.+)/i, r: "spouse", triple: true },
+  // "X's son/daughter is Y"
+  { re: /(.+?)(?:'s|的)\s*(son|daughter|儿子|女儿)\s*(?:is|是|为)\s*(.+)/i, r: "has_child", triple: true },
+  // "X costs/price Y" / 定价
+  { re: /(.+?)\s*(?:costs?|定价|售价|price[ds]?\s*(?:at)?)\s*\$?([\d,.]+)/i, r: "price" },
+  // "X's lawyer is Y"
+  { re: /(.+?)(?:'s|的)\s*(?:lawyer|律师|attorney)\s*(?:is|是|为)\s*(.+)/i, r: "has_lawyer" },
+  // "X owns Y" / 拥有
+  { re: /(.+?)\s*(?:owns?|拥有|有一辆|drives?)\s*(.+)/i, r: "owns" },
+  // "X studies/attends Y" / 就读
+  { re: /(.+?)\s*(?:attends?|studies? at|就读于?|在(.+?)(?:上学|读书))/i, r: "attends" },
+];
+
+/**
+ * Extract triples from a text string.
+ * @returns {Array<{ s: string, r: string, o: string }>}
+ */
+export function extractTriples(text) {
+  const results = [];
+  for (const pat of EXTRACTION_PATTERNS) {
+    const m = text.match(pat.re);
+    if (m) {
+      const s = (m[1] || "").trim();
+      const o = (pat.triple ? m[3] : m[2] || "").trim();
+      if (s && o && s.length < 50 && o.length < 80) {
+        results.push({ s, r: pat.r, o });
+      }
+    }
+  }
+  return results;
+}

package/lib/paths.js

@@ -0,0 +1,80 @@
+/**
+ * Shared path resolution and config helpers.
+ */
+
+import { join } from "node:path";
+
+export const DEFAULT_CORE_SIZE_LIMIT = 3072;
+export const DEFAULT_TOP_K = 5;
+export const MAX_TOP_K = 20;
+export const EMBEDDING_MODEL = "text-embedding-3-small";
+export const EMBEDDING_DIM = 512;
+export const DEDUP_SIMILARITY_THRESHOLD = 0.92;
+
+import { readFileSync as _readFileSync, existsSync as _existsSync } from "node:fs";
+
+/**
+ * Agent→workspace mapping, loaded once from openclaw.json.
+ * Since OpenClaw v2026.3.x doesn't pass agentId/workspaceDir to plugin tools,
+ * we read the config and let agents pass their ID via tool params.
+ */
+let _agentMap = null;
+
+function loadAgentMap() {
+  if (_agentMap) return _agentMap;
+  _agentMap = {};
+  try {
+    const configPath = join(process.env.HOME || "/tmp", ".openclaw", "openclaw.json");
+    if (_existsSync(configPath)) {
+      const cfg = JSON.parse(_readFileSync(configPath, "utf-8"));
+      const defaultWs = cfg?.agents?.defaults?.workspace || join(process.env.HOME || "/tmp", ".openclaw", "workspace");
+      _agentMap._default = defaultWs;
+      for (const agent of cfg?.agents?.list || []) {
+        _agentMap[agent.id] = agent.workspace || defaultWs;
+      }
+    }
+  } catch { /* ignore */ }
+  return _agentMap;
+}
+
+/**
+ * Resolve workspace.
+ * @param {object} ctx - OpenClaw tool context
+ * @param {string} [agentId] - optional agent ID from tool params (workaround for OpenClaw not passing ctx)
+ */
+export function resolveWorkspace(ctx, agentId = null) {
+  // 1. ctx.workspaceDir (future OpenClaw versions)
+  if (ctx?.workspaceDir) return ctx.workspaceDir;
+  // 2. Explicit agentId → lookup from config
+  const aid = agentId || ctx?.agentId;
+  if (aid) {
+    const map = loadAgentMap();
+    if (map[aid]) return map[aid];
+  }
+  // 3. Plugin config workspace
+  if (ctx?.config?.workspace) return ctx.config.workspace;
+  // 4. Env
+  if (process.env.OPENCLAW_WORKSPACE) return process.env.OPENCLAW_WORKSPACE;
+  // 5. Default
+  return join(process.env.HOME || "/tmp", ".openclaw", "workspace");
+}
+
+export function getCoreSizeLimit(ctx) {
+  return ctx?.config?.coreSizeLimit || DEFAULT_CORE_SIZE_LIMIT;
+}
+
+export function corePath(ws) { return join(ws, "memory", "core.json"); }
+export function archivalPath(ws) { return join(ws, "memory", "archival.jsonl"); }
+export function embeddingCachePath(ws) { return join(ws, "memory", "archival.embeddings.json"); }
+export function graphPath(ws) { return join(ws, "memory", "graph.jsonl"); }
+export function episodesPath(ws) { return join(ws, "memory", "episodes.jsonl"); }
+
+export const DEFAULT_IMPORTANCE = 5;
+export const FORGETTING_DECAY_RATE = 0.01; // importance decays by this per day without access
+export const FORGETTING_THRESHOLD = 1.0;   // below this = candidate for archiving
+
+// Multi-agent sharing (default: on for single-user multi-agent setups)
+// Set to false in config for privacy-sensitive scenarios (e.g., separate users per agent)
+export function isSharingEnabled(ctx) {
+  return ctx?.config?.sharing !== false; // default true, explicitly set false to disable
+}

package/lib/reflection.js

@@ -0,0 +1,188 @@
+/**
+ * Reflective memory: statistical analysis over recent archival + episodes
+ * to surface behavioral patterns, topic trends, and emotional shifts.
+ *
+ * This module does data analysis only — pattern interpretation is left
+ * to the agent (which has LLM reasoning the plugin doesn't).
+ */
+
+import { loadArchival } from "./archival.js";
+import { loadEpisodes } from "./episodes.js";
+import { loadGraph } from "./graph.js";
+
+/**
+ * Analyze recent memory for patterns and trends.
+ * @param {string} ws - workspace path
+ * @param {number} [windowDays=7] - analysis window in days
+ * @returns {object} structured analysis
+ */
+export function analyzePatterns(ws, windowDays = 7) {
+  const allRecords = loadArchival(ws);
+  const allEpisodes = loadEpisodes(ws);
+  const graph = loadGraph(ws);
+
+  const cutoff = Date.now() - windowDays * 86400000;
+
+  const recentRecords = allRecords.filter(
+    (r) => r.ts && new Date(r.ts).getTime() > cutoff,
+  );
+  const recentEpisodes = allEpisodes.filter(
+    (e) => e.ts && new Date(e.ts).getTime() > cutoff,
+  );
+
+  // ─── 1. Topic frequency ───
+  const topicCounts = {};
+  for (const r of recentRecords) {
+    for (const tag of r.tags || []) {
+      topicCounts[tag] = (topicCounts[tag] || 0) + 1;
+    }
+    if (r.entity) {
+      topicCounts[`entity:${r.entity}`] = (topicCounts[`entity:${r.entity}`] || 0) + 1;
+    }
+  }
+  for (const ep of recentEpisodes) {
+    for (const topic of ep.topics || []) {
+      topicCounts[`episode:${topic}`] = (topicCounts[`episode:${topic}`] || 0) + 1;
+    }
+  }
+  const topTopics = Object.entries(topicCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10);
+
+  // ─── 2. Time-of-day distribution ───
+  const hourBuckets = { morning: 0, afternoon: 0, evening: 0, night: 0 };
+  for (const r of recentRecords) {
+    if (!r.ts) continue;
+    const hour = new Date(r.ts).getHours();
+    if (hour >= 6 && hour < 12) hourBuckets.morning++;
+    else if (hour >= 12 && hour < 18) hourBuckets.afternoon++;
+    else if (hour >= 18 && hour < 23) hourBuckets.evening++;
+    else hourBuckets.night++;
+  }
+
+  // ─── 3. Mood trend (from episodes) ───
+  const moodCounts = {};
+  for (const ep of recentEpisodes) {
+    if (ep.mood) {
+      moodCounts[ep.mood] = (moodCounts[ep.mood] || 0) + 1;
+    }
+  }
+
+  // ─── 4. Importance distribution ───
+  const importanceHigh = recentRecords.filter((r) => (r.importance || 5) >= 7).length;
+  const importanceLow = recentRecords.filter((r) => (r.importance || 5) <= 3).length;
+  const importanceMid = recentRecords.length - importanceHigh - importanceLow;
+
+  // ─── 5. Decision velocity (from episodes) ───
+  const totalDecisions = recentEpisodes.reduce(
+    (sum, ep) => sum + (ep.decisions?.length || 0), 0,
+  );
+
+  // ─── 6. Graph growth ───
+  const recentTriples = graph.filter(
+    (t) => t.ts && new Date(t.ts).getTime() > cutoff,
+  );
+
+  // ─── 7. Neglected entities (in graph but not accessed recently) ───
+  const graphEntities = new Set();
+  for (const t of graph) {
+    graphEntities.add(t.s);
+    graphEntities.add(t.o);
+  }
+  const recentEntities = new Set();
+  for (const r of recentRecords) {
+    if (r.entity) recentEntities.add(r.entity);
+  }
+  const neglected = [...graphEntities].filter((e) => !recentEntities.has(e));
+
+  // ─── 8. Forgetting candidates ───
+  const forgettingCandidates = allRecords.filter((r) => {
+    const importance = r.importance || 5;
+    const daysSinceAccess = r.last_accessed
+      ? (Date.now() - new Date(r.last_accessed).getTime()) / 86400000
+      : (Date.now() - new Date(r.ts || Date.now()).getTime()) / 86400000;
+    const effective = importance * Math.exp(-0.01 * daysSinceAccess);
+    return effective < 1.0;
+  });
+
+  return {
+    window_days: windowDays,
+    period: {
+      from: new Date(cutoff).toISOString().slice(0, 10),
+      to: new Date().toISOString().slice(0, 10),
+    },
+    activity: {
+      new_facts: recentRecords.length,
+      new_episodes: recentEpisodes.length,
+      new_graph_triples: recentTriples.length,
+      total_decisions: totalDecisions,
+    },
+    top_topics: topTopics,
+    time_distribution: hourBuckets,
+    mood_trend: moodCounts,
+    importance_distribution: {
+      high: importanceHigh,
+      medium: importanceMid,
+      low: importanceLow,
+    },
+    health: {
+      total_archival: allRecords.length,
+      total_episodes: allEpisodes.length,
+      total_graph: graph.length,
+      neglected_entities: neglected.slice(0, 10),
+      forgetting_candidates: forgettingCandidates.length,
+    },
+  };
+}
+
+/**
+ * Format analysis into a human-readable report for the agent.
+ */
+export function formatReflection(analysis) {
+  const lines = [
+    `📊 Memory Reflection (${analysis.period.from} → ${analysis.period.to}, ${analysis.window_days}d window)`,
+    ``,
+    `Activity:`,
+    `  New facts: ${analysis.activity.new_facts}`,
+    `  New episodes: ${analysis.activity.new_episodes}`,
+    `  New graph relations: ${analysis.activity.new_graph_triples}`,
+    `  Decisions made: ${analysis.activity.total_decisions}`,
+  ];
+
+  if (analysis.top_topics.length > 0) {
+    lines.push(``, `Top topics:`);
+    for (const [topic, count] of analysis.top_topics) {
+      lines.push(`  ${topic}: ${count}`);
+    }
+  }
+
+  const td = analysis.time_distribution;
+  const peakTime = Object.entries(td).sort((a, b) => b[1] - a[1])[0];
+  if (peakTime && peakTime[1] > 0) {
+    lines.push(``, `Time pattern: most active during ${peakTime[0]} (${peakTime[1]} events)`);
+    lines.push(`  morning=${td.morning} afternoon=${td.afternoon} evening=${td.evening} night=${td.night}`);
+  }
+
+  if (Object.keys(analysis.mood_trend).length > 0) {
+    lines.push(``, `Mood trend:`);
+    for (const [mood, count] of Object.entries(analysis.mood_trend)) {
+      lines.push(`  ${mood}: ${count}`);
+    }
+  }
+
+  const imp = analysis.importance_distribution;
+  lines.push(``, `Importance: high(≥7)=${imp.high} medium=${imp.medium} low(≤3)=${imp.low}`);
+
+  if (analysis.health.neglected_entities.length > 0) {
+    lines.push(``, `Neglected entities (in graph but no recent activity):`);
+    lines.push(`  ${analysis.health.neglected_entities.join(", ")}`);
+  }
+
+  if (analysis.health.forgetting_candidates > 0) {
+    lines.push(``, `⚠️ ${analysis.health.forgetting_candidates} facts below forgetting threshold — consider archival_deduplicate or cleanup`);
+  }
+
+  lines.push(``, `Totals: ${analysis.health.total_archival} facts, ${analysis.health.total_episodes} episodes, ${analysis.health.total_graph} graph triples`);
+
+  return lines.join("\n");
+}

package/lib/search.js

@@ -0,0 +1,90 @@
+/**
+ * Hybrid search: keyword + embedding cosine similarity + recency + access decay.
+ */
+
+import { loadArchival, rewriteArchival } from "./archival.js";
+import { loadEmbeddingCache, getEmbedding, cosineSimilarity } from "./embedding.js";
+import { DEFAULT_IMPORTANCE, FORGETTING_DECAY_RATE } from "./paths.js";
+
+/**
+ * Search archival records with hybrid scoring.
+ * @param {string} ws - workspace path
+ * @param {string} query - search query
+ * @param {number} topK - max results
+ * @returns {Promise<object[]>} matched records
+ */
+export async function hybridSearch(ws, query, topK) {
+  const records = loadArchival(ws);
+  if (records.length === 0) return [];
+
+  const queryLower = query.toLowerCase();
+  const queryTerms = queryLower.split(/\s+/).filter((t) => t.length > 1);
+
+  const queryEmb = await getEmbedding(query);
+  const embCache = loadEmbeddingCache(ws);
+
+  const scored = records
+    .map((record) => {
+      const text = [record.content || "", record.entity || "", ...(record.tags || [])]
+        .join(" ")
+        .toLowerCase();
+
+      // Keyword score
+      let kwScore = 0;
+      for (const term of queryTerms) {
+        if (text.includes(term)) kwScore += 1;
+      }
+      if (queryTerms.length > 1 && text.includes(queryLower)) kwScore += 3;
+
+      // Semantic score
+      let semScore = 0;
+      if (queryEmb && record.id) {
+        const recEmb = embCache[record.id] || null;
+        if (recEmb) {
+          semScore = Math.max(0, cosineSimilarity(queryEmb, recEmb));
+        }
+      }
+
+      // Recency bonus (0–1, decays over 1 year)
+      let recencyScore = 0;
+      if (record.ts) {
+        const ageDays = (Date.now() - new Date(record.ts).getTime()) / 86400000;
+        recencyScore = Math.max(0, 1 - ageDays / 365);
+      }
+
+      // Access decay bonus (0–0.5)
+      let accessScore = 0;
+      if (record.last_accessed) {
+        const accessAgeDays =
+          (Date.now() - new Date(record.last_accessed).getTime()) / 86400000;
+        accessScore = Math.max(0, 0.5 - accessAgeDays / 180);
+      }
+
+      // Importance score with forgetting curve
+      const importance = record.importance ?? DEFAULT_IMPORTANCE;
+      const daysSinceAccess = record.last_accessed
+        ? (Date.now() - new Date(record.last_accessed).getTime()) / 86400000
+        : (Date.now() - new Date(record.ts || Date.now()).getTime()) / 86400000;
+      const effectiveImportance = importance * Math.exp(-FORGETTING_DECAY_RATE * daysSinceAccess);
+      const importanceScore = effectiveImportance * 0.5;
+
+      const total = kwScore * 2 + semScore * 5 + recencyScore + accessScore + importanceScore;
+      return total > 0 ? { record, score: total } : null;
+    })
+    .filter(Boolean);
+
+  scored.sort((a, b) => b.score - a.score);
+  const results = scored.slice(0, topK);
+
+  // Update access tracking
+  const now = new Date().toISOString();
+  let dirty = false;
+  for (const s of results) {
+    s.record.last_accessed = now;
+    s.record.access_count = (s.record.access_count || 0) + 1;
+    dirty = true;
+  }
+  if (dirty) rewriteArchival(ws, records);
+
+  return results.map((s) => s.record);
+}