hmem-mcp 2.0.3 → 2.2.0

package/dist/hmem-store.js

@@ -27,7 +27,7 @@
 import Database from "better-sqlite3";
 import fs from "node:fs";
 import path from "node:path";
-import { DEFAULT_CONFIG, DEFAULT_PREFIX_DESCRIPTIONS, resolveDepthForPosition } from "./hmem-config.js";
+import { DEFAULT_CONFIG, DEFAULT_PREFIX_DESCRIPTIONS } from "./hmem-config.js";
 // Prefixes are now loaded from config — see this.cfg.prefixes
 const ROLE_LEVEL = {
     worker: 0, al: 1, pl: 2, ceo: 3,
@@ -54,7 +54,8 @@ CREATE TABLE IF NOT EXISTS memories (
     links         TEXT,
     min_role      TEXT DEFAULT 'worker',
     obsolete      INTEGER DEFAULT 0,
-    favorite      INTEGER DEFAULT 0
+    favorite      INTEGER DEFAULT 0,
+    irrelevant    INTEGER DEFAULT 0
 );
 CREATE INDEX IF NOT EXISTS idx_prefix ON memories(prefix);
 CREATE INDEX IF NOT EXISTS idx_created ON memories(created_at);
@@ -85,6 +86,10 @@ const MIGRATIONS = [
     "ALTER TABLE memories ADD COLUMN min_role TEXT DEFAULT 'worker'",
     "ALTER TABLE memories ADD COLUMN obsolete INTEGER DEFAULT 0",
     "ALTER TABLE memories ADD COLUMN favorite INTEGER DEFAULT 0",
+    "ALTER TABLE memories ADD COLUMN title TEXT",
+    "ALTER TABLE memory_nodes ADD COLUMN title TEXT",
+    "ALTER TABLE memories ADD COLUMN irrelevant INTEGER DEFAULT 0",
+    "ALTER TABLE memory_nodes ADD COLUMN favorite INTEGER DEFAULT 0",
 ];
 // ---- HmemStore class ----
 export class HmemStore {
@@ -153,7 +158,7 @@ export class HmemStore {
         const seq = this.nextSeq(prefix);
         const rootId = `${prefix}${String(seq).padStart(4, "0")}`;
         const timestamp = new Date().toISOString();
-        const { level1, nodes } = this.parseTree(content, rootId);
+        const { title, level1, nodes } = this.parseTree(content, rootId);
         if (!level1) {
             throw new Error("Content must have at least one line (Level 1).");
         }
@@ -170,18 +175,18 @@ export class HmemStore {
             }
         }
         const insertRoot = this.db.prepare(`
-      INSERT INTO memories (id, prefix, seq, created_at, level_1, level_2, level_3, level_4, level_5, links, min_role, favorite)
-      VALUES (?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, ?, ?, ?)
+      INSERT INTO memories (id, prefix, seq, created_at, title, level_1, level_2, level_3, level_4, level_5, links, min_role, favorite)
+      VALUES (?, ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, ?, ?, ?)
     `);
         const insertNode = this.db.prepare(`
-      INSERT INTO memory_nodes (id, parent_id, root_id, depth, seq, content, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO memory_nodes (id, parent_id, root_id, depth, seq, title, content, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
     `);
         // Run in a transaction
         this.db.transaction(() => {
-            insertRoot.run(rootId, prefix, seq, timestamp, level1, links ? JSON.stringify(links) : null, minRole, favorite ? 1 : 0);
+            insertRoot.run(rootId, prefix, seq, timestamp, title, level1, links ? JSON.stringify(links) : null, minRole, favorite ? 1 : 0);
             for (const node of nodes) {
-                insertNode.run(node.id, node.parent_id, rootId, node.depth, node.seq, node.content, timestamp);
+                insertNode.run(node.id, node.parent_id, rootId, node.depth, node.seq, node.title, node.content, timestamp);
             }
         })();
         return { id: rootId, timestamp };
@@ -206,8 +211,14 @@ export class HmemStore {
                 if (!row)
                     return [];
                 this.bumpNodeAccess(opts.id);
-                const children = this.fetchChildren(opts.id);
-                return [this.nodeToEntry(this.rowToNode(row), children)];
+                const nodeDepth = row.depth ?? 2;
+                // expand: fetch requested depth + 1 extra level (for boundary titles)
+                const expandDepth = opts.expand ? (opts.depth || 5) + 1 : nodeDepth + 1;
+                const children = this.fetchChildrenDeep(opts.id, nodeDepth + 1, expandDepth);
+                const entry = this.nodeToEntry(this.rowToNode(row), children);
+                if (opts.expand)
+                    entry.expanded = true;
+                return [entry];
             }
             else {
                 // Root ID — fetch from memories
@@ -215,30 +226,53 @@ export class HmemStore {
                 const row = this.db.prepare(sql).get(opts.id, ...roleFilter.params);
                 if (!row)
                     return [];
-                this.bumpAccess(opts.id);
-                const children = this.fetchChildren(opts.id);
-                const entry = this.rowToEntry(row, children);
-                // Auto-resolve links with depth control and cycle detection
-                const linkDepth = opts.resolveLinks === false ? 0 : (opts.linkDepth ?? 1);
-                if (linkDepth > 0 && entry.links && entry.links.length > 0) {
-                    const visited = opts._visitedLinks ?? new Set();
-                    visited.add(opts.id);
-                    entry.linkedEntries = entry.links.flatMap(linkId => {
-                        if (visited.has(linkId))
-                            return []; // cycle detected — skip
-                        try {
-                            return this.read({
-                                id: linkId,
-                                agentRole: opts.agentRole,
-                                linkDepth: linkDepth - 1,
-                                _visitedLinks: visited,
-                            });
+                // ── Obsolete chain resolution ──
+                const shouldFollow = opts.followObsolete !== false; // default: true
+                if (shouldFollow && row.obsolete === 1) {
+                    const { finalId, chain } = this.resolveObsoleteChain(opts.id);
+                    if (chain.length > 1) {
+                        // Chain resolved — return final entry (or full path)
+                        if (opts.showObsoletePath) {
+                            // Return ALL entries in the chain
+                            const entries = [];
+                            for (const chainId of chain) {
+                                const chainRow = this.db.prepare(sql).get(chainId, ...roleFilter.params);
+                                if (!chainRow)
+                                    continue;
+                                const children = this.fetchChildren(chainId);
+                                const entry = this.rowToEntry(chainRow, children);
+                                entry.obsoleteChain = chain;
+                                entries.push(entry);
+                            }
+                            // Bump access on the final (valid) entry only
+                            this.bumpAccess(finalId);
+                            return entries;
                         }
-                        catch {
-                            return [];
+                        else {
+                            // Return ONLY the final valid entry
+                            this.bumpAccess(finalId);
+                            const finalRow = this.db.prepare(sql).get(finalId, ...roleFilter.params);
+                            if (!finalRow)
+                                return []; // correction target inaccessible
+                            const children = this.fetchChildren(finalId);
+                            const entry = this.rowToEntry(finalRow, children);
+                            entry.obsoleteChain = chain;
+                            // Resolve links on the final entry
+                            this.resolveEntryLinks(entry, opts);
+                            return [entry];
                         }
-                    }).filter(e => !e.obsolete);
+                    }
+                    // chain.length <= 1: no correction found, fall through to normal behavior
                 }
+                this.bumpAccess(opts.id);
+                // expand: fetch requested depth + 1 extra level (for boundary titles)
+                const expandDepth = opts.expand ? (opts.depth || 5) + 1 : 2;
+                const children = this.fetchChildrenDeep(opts.id, 2, expandDepth);
+                const entry = this.rowToEntry(row, children);
+                if (opts.expand)
+                    entry.expanded = true;
+                // Auto-resolve links
+                this.resolveEntryLinks(entry, opts);
                 return [entry];
             }
         }
@@ -343,67 +377,20 @@ export class HmemStore {
             for (const row of rows)
                 this.bumpAccess(row.id);
         }
-        // Dispatch: V1 (legacy) or V2 (new default)
-        if (opts.recentDepthTiers) {
-            return this.readBulkV1(rows, opts);
-        }
         return this.readBulkV2(rows, opts);
     }
-    /**
-     * V1 bulk-read algorithm (legacy): recency gradient with depth tiers.
-     * Kept for backward compatibility when recentDepthTiers is explicitly passed.
-     */
-    readBulkV1(rows, opts) {
-        const tiers = opts.recentDepthTiers ?? this.cfg.recentDepthTiers;
-        // Identify top-N entries by access_count ("organic favorites")
-        const topN = this.cfg.accessCountTopN ?? 5;
-        const topAccessIds = topN > 0
-            ? new Set([...rows]
-                .filter(r => r.access_count > 0)
-                .sort((a, b) => b.access_count - a.access_count)
-                .slice(0, topN)
-                .map(r => r.id))
-            : new Set();
-        return rows.map((r, i) => {
-            let depth = resolveDepthForPosition(i, tiers);
-            let promoted;
-            if (r.favorite === 1) {
-                promoted = "favorite";
-                if (depth < 2)
-                    depth = 2;
-            }
-            else if (topAccessIds.has(r.id)) {
-                promoted = "access";
-                if (depth < 2)
-                    depth = 2;
-            }
-            let children;
-            let hiddenChildrenCount;
-            if (depth >= 2) {
-                const latest = this.fetchLatestChild(r.id, depth);
-                if (latest) {
-                    children = [latest.node];
-                    hiddenChildrenCount = latest.totalSiblings - 1;
-                }
-                else {
-                    hiddenChildrenCount = 0;
-                }
-            }
-            const entry = this.rowToEntry(r, children);
-            entry.promoted = promoted;
-            entry.hiddenChildrenCount = hiddenChildrenCount;
-            return entry;
-        });
-    }
     /**
      * V2 bulk-read algorithm: per-prefix expansion, smart obsolete filtering,
      * expanded entries with all L2 children + links.
      */
     readBulkV2(rows, opts) {
         const v2 = this.cfg.bulkReadV2;
+        // Step 0: Filter out irrelevant entries (never shown in bulk reads)
+        const irrelevantCount = rows.filter(r => r.irrelevant === 1).length;
+        const activeRows = rows.filter(r => r.irrelevant !== 1);
         // Step 1: Separate obsolete from non-obsolete FIRST
-        const obsoleteRows = rows.filter(r => r.obsolete === 1);
-        const nonObsoleteRows = rows.filter(r => r.obsolete !== 1);
+        const obsoleteRows = activeRows.filter(r => r.obsolete === 1);
+        const nonObsoleteRows = activeRows.filter(r => r.obsolete !== 1);
         // Step 2: Group NON-OBSOLETE by prefix (obsolete must not steal expansion slots)
         const byPrefix = new Map();
         for (const r of nonObsoleteRows) {
@@ -413,46 +400,102 @@ export class HmemStore {
             else
                 byPrefix.set(r.prefix, [r]);
         }
+        // Session cache: filter out already-seen entries completely
+        const suppressed = opts.suppressedIds ?? new Set();
+        const hasCacheActive = suppressed.size > 0;
         // Step 3: Build expansion set from non-obsolete rows
         const expandedIds = new Set();
-        // Per prefix: top N newest + top M most-accessed
+        // Mode-based ratios: essentials shifts weight from newest to most-accessed
+        const isEssentials = opts.mode === "essentials";
+        const totalSlots = v2.topNewestCount + v2.topAccessCount; // 8 by default
+        const baseNewest = isEssentials ? Math.max(1, Math.floor(v2.topNewestCount * 0.4)) : v2.topNewestCount;
+        const baseAccess = isEssentials ? totalSlots - baseNewest : v2.topAccessCount;
+        // Fibonacci-limited counts (when cache is active, use separate Fibonacci values)
+        const newestCount = (hasCacheActive && opts.maxNewNewest !== undefined)
+            ? opts.maxNewNewest : baseNewest;
+        const accessCount = (hasCacheActive && opts.maxNewAccess !== undefined)
+            ? opts.maxNewAccess : baseAccess;
+        // Per prefix: top N newest (sliding window) + top M most-accessed (backfill)
         for (const [, prefixRows] of byPrefix) {
-            // Newest (already sorted by effective_date DESC)
-            for (const r of prefixRows.slice(0, v2.topNewestCount)) {
+            // Newest: sliding window — only from unseen entries
+            const unseenRows = hasCacheActive
+                ? prefixRows.filter(r => !suppressed.has(r.id))
+                : prefixRows;
+            for (const r of unseenRows.slice(0, newestCount)) {
                 expandedIds.add(r.id);
             }
-            // Most-accessed
-            const mostAccessed = [...prefixRows]
-                .filter(r => r.access_count > 0)
-                .sort((a, b) => b.access_count - a.access_count)
-                .slice(0, v2.topAccessCount);
+            // Most-accessed: from unseen entries, excluding those already picked as newest.
+            // Minimum threshold: access_count >= 2 — a single access can be noise.
+            const mostAccessed = [...unseenRows]
+                .filter(r => r.access_count >= 2 && !expandedIds.has(r.id))
+                .sort((a, b) => this.weightedAccessScore(b) - this.weightedAccessScore(a))
+                .slice(0, accessCount);
             for (const r of mostAccessed)
                 expandedIds.add(r.id);
         }
-        // Global: all favorites (from non-obsolete)
+        // Global: all unseen favorites
         for (const r of nonObsoleteRows) {
-            if (r.favorite === 1)
+            if (r.favorite === 1 && !suppressed.has(r.id)) {
                 expandedIds.add(r.id);
+            }
         }
-        // topAccess reference for promoted marker
+        // topAccess reference for promoted marker (time-weighted, min 2 accesses)
         const topAccess = [...nonObsoleteRows]
-            .filter(r => r.access_count > 0)
-            .sort((a, b) => b.access_count - a.access_count)
+            .filter(r => r.access_count >= 2)
+            .sort((a, b) => this.weightedAccessScore(b) - this.weightedAccessScore(a))
             .slice(0, v2.topAccessCount);
-        let visibleObsolete;
-        if (opts.showObsolete) {
-            visibleObsolete = obsoleteRows;
-        }
-        else {
-            // Keep only top N most-accessed obsolete entries ("biggest mistakes")
-            visibleObsolete = [...obsoleteRows]
-                .sort((a, b) => b.access_count - a.access_count)
-                .slice(0, v2.topObsoleteCount);
-        }
-        const hiddenObsoleteCount = obsoleteRows.length - visibleObsolete.length;
-        // Step 4: Only show expanded entries + visible obsolete (non-expanded are hidden from bulk output)
+        // Obsolete entries: only shown when explicitly requested
+        const visibleObsolete = opts.showObsolete ? obsoleteRows : [];
+        // Step 4: Show expanded entries + visible obsolete (cached entries completely hidden)
         const expandedNonObsolete = nonObsoleteRows.filter(r => expandedIds.has(r.id));
         const visibleRows = [...expandedNonObsolete, ...visibleObsolete];
+        const visibleIds = new Set(visibleRows.map(r => r.id));
+        // titles_only: V2 selection applies, but skip link resolution
+        if (opts.titlesOnly) {
+            // Bulk-fetch L2 child counts (one query for all visible entries)
+            const allIds = visibleRows.map(r => r.id);
+            const childCounts = this.bulkChildCount(allIds);
+            return visibleRows.map(r => {
+                const isExpanded = expandedIds.has(r.id);
+                const totalChildren = childCounts.get(r.id) ?? 0;
+                let children;
+                let hiddenCount;
+                if (isExpanded && totalChildren > 0) {
+                    // Fetch L2 children with V2 selection (top newest + accessed), no links
+                    const allChildren = this.fetchChildren(r.id);
+                    if (allChildren.length > v2.topNewestCount) {
+                        const newestSet = new Set([...allChildren]
+                            .sort((a, b) => (b.created_at || "").localeCompare(a.created_at || ""))
+                            .slice(0, v2.topNewestCount)
+                            .map(c => c.id));
+                        const accessSet = new Set([...allChildren]
+                            .filter(c => c.access_count >= 2)
+                            .sort((a, b) => this.weightedAccessScore(b) - this.weightedAccessScore(a))
+                            .slice(0, v2.topAccessCount)
+                            .map(c => c.id));
+                        const selectedIds = new Set([...newestSet, ...accessSet]);
+                        children = allChildren.filter(c => selectedIds.has(c.id));
+                        hiddenCount = allChildren.length - children.length;
+                    }
+                    else {
+                        children = allChildren;
+                    }
+                }
+                else if (totalChildren > 0) {
+                    hiddenCount = totalChildren;
+                }
+                const entry = this.rowToEntry(r, children);
+                if (r.favorite === 1)
+                    entry.promoted = "favorite";
+                else if (topAccess.some(t => t.id === r.id))
+                    entry.promoted = "access";
+                if (isExpanded)
+                    entry.expanded = true;
+                if (hiddenCount !== undefined && hiddenCount > 0)
+                    entry.hiddenChildrenCount = hiddenCount;
+                return entry;
+            });
+        }
         return visibleRows.map(r => {
             const isExpanded = expandedIds.has(r.id);
             let promoted;
@@ -462,27 +505,64 @@ export class HmemStore {
                 promoted = "access";
             let children;
             let linkedEntries;
+            let hiddenChildrenCount;
+            let hiddenObsoleteLinks = 0;
+            let hiddenIrrelevantLinks = 0;
             if (isExpanded) {
-                // Expanded: ALL direct L2 children + resolve links
-                children = this.fetchChildren(r.id);
-                // Resolve links (depth 1, no family)
+                // Fetch all L2 children, then apply V2 selection (same params as L1)
+                const allChildren = this.fetchChildren(r.id);
+                if (allChildren.length > v2.topNewestCount) {
+                    const newestSet = new Set([...allChildren]
+                        .sort((a, b) => (b.created_at || "").localeCompare(a.created_at || ""))
+                        .slice(0, v2.topNewestCount)
+                        .map(c => c.id));
+                    const accessSet = new Set([...allChildren]
+                        .filter(c => c.access_count > 0)
+                        .sort((a, b) => this.weightedAccessScore(b) - this.weightedAccessScore(a))
+                        .slice(0, v2.topAccessCount)
+                        .map(c => c.id));
+                    const selectedIds = new Set([...newestSet, ...accessSet]);
+                    children = allChildren.filter(c => selectedIds.has(c.id));
+                    if (children.length < allChildren.length) {
+                        hiddenChildrenCount = allChildren.length - children.length;
+                    }
+                }
+                else {
+                    children = allChildren;
+                }
+                // Resolve links — skip entries already visible in bulk read
                 const links = r.links ? JSON.parse(r.links) : [];
                 if (links.length > 0) {
-                    linkedEntries = links.flatMap(linkId => {
+                    const allLinked = links.flatMap(linkId => {
+                        if (visibleIds.has(linkId))
+                            return []; // already shown in bulk read
                         try {
                             return this.read({ id: linkId, resolveLinks: false, linkDepth: 0 });
                         }
                         catch {
                             return [];
                         }
-                    }).filter(e => !e.obsolete);
+                    });
+                    for (const e of allLinked) {
+                        if (e.obsolete)
+                            hiddenObsoleteLinks++;
+                        else if (e.irrelevant)
+                            hiddenIrrelevantLinks++;
+                    }
+                    linkedEntries = allLinked.filter(e => !e.obsolete && !e.irrelevant);
                 }
             }
             const entry = this.rowToEntry(r, children);
             entry.promoted = promoted;
             entry.expanded = isExpanded;
+            if (hiddenChildrenCount !== undefined)
+                entry.hiddenChildrenCount = hiddenChildrenCount;
             if (linkedEntries && linkedEntries.length > 0)
                 entry.linkedEntries = linkedEntries;
+            if (hiddenObsoleteLinks > 0)
+                entry.hiddenObsoleteLinks = hiddenObsoleteLinks;
+            if (hiddenIrrelevantLinks > 0)
+                entry.hiddenIrrelevantLinks = hiddenIrrelevantLinks;
             return entry;
         });
     }
@@ -570,7 +650,7 @@ export class HmemStore {
             if (key === "links" && Array.isArray(val)) {
                 params.push(JSON.stringify(val));
             }
-            else if (key === "obsolete" || key === "favorite") {
+            else if (key === "obsolete" || key === "favorite" || key === "irrelevant") {
                 params.push(val ? 1 : 0);
             }
             else {
@@ -600,7 +680,7 @@ export class HmemStore {
      * For sub-nodes: updates node content only.
      * Does NOT modify children — use appendChildren to extend the tree.
      */
-    updateNode(id, newContent, links, obsolete, favorite, curatorBypass) {
+    updateNode(id, newContent, links, obsolete, favorite, curatorBypass, irrelevant) {
         this.guardCorrupted();
         const trimmed = newContent.trim();
         if (id.includes(".")) {
@@ -612,7 +692,14 @@ export class HmemStore {
             if (trimmed.length > nodeLimit) {
                 throw new Error(`Content exceeds ${nodeLimit} character limit (${trimmed.length} chars) for L${nodeRow.depth}.`);
             }
-            const result = this.db.prepare("UPDATE memory_nodes SET content = ? WHERE id = ?").run(trimmed, id);
+            const sets = ["content = ?", "title = ?"];
+            const params = [trimmed, this.autoExtractTitle(trimmed)];
+            if (favorite !== undefined) {
+                sets.push("favorite = ?");
+                params.push(favorite ? 1 : 0);
+            }
+            params.push(id);
+            const result = this.db.prepare(`UPDATE memory_nodes SET ${sets.join(", ")} WHERE id = ?`).run(...params);
             return result.changes > 0;
         }
         else {
@@ -651,8 +738,8 @@ export class HmemStore {
                     }
                 }
             }
-            const sets = ["level_1 = ?"];
-            const params = [trimmed];
+            const sets = ["level_1 = ?", "title = ?"];
+            const params = [trimmed, this.autoExtractTitle(trimmed)];
             if (links !== undefined) {
                 sets.push("links = ?");
                 params.push(links.length > 0 ? JSON.stringify(links) : null);
@@ -668,6 +755,10 @@ export class HmemStore {
                 sets.push("favorite = ?");
                 params.push(favorite ? 1 : 0);
             }
+            if (irrelevant !== undefined) {
+                sets.push("irrelevant = ?");
+                params.push(irrelevant ? 1 : 0);
+            }
             params.push(id);
             const result = this.db.prepare(`UPDATE memories SET ${sets.join(", ")} WHERE id = ?`).run(...params);
             return result.changes > 0;
@@ -713,13 +804,13 @@ export class HmemStore {
         }
         const timestamp = new Date().toISOString();
         const insertNode = this.db.prepare(`
-      INSERT INTO memory_nodes (id, parent_id, root_id, depth, seq, content, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO memory_nodes (id, parent_id, root_id, depth, seq, title, content, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
     `);
         const topLevelIds = [];
         this.db.transaction(() => {
             for (const node of nodes) {
-                insertNode.run(node.id, node.parent_id, rootId, node.depth, node.seq, node.content, timestamp);
+                insertNode.run(node.id, node.parent_id, rootId, node.depth, node.seq, this.autoExtractTitle(node.content), node.content, timestamp);
                 if (node.parent_id === parentId)
                     topLevelIds.push(node.id);
             }
@@ -928,13 +1019,97 @@ export class HmemStore {
         const row = this.db.prepare("SELECT MAX(seq) as maxSeq FROM memories WHERE prefix = ?").get(prefix);
         return (row?.maxSeq || 0) + 1;
     }
+    /** Auto-resolve linked entries on an entry (extracted for reuse in chain resolution). */
+    resolveEntryLinks(entry, opts) {
+        const linkDepth = opts.resolveLinks === false ? 0 : (opts.linkDepth ?? 1);
+        if (linkDepth > 0 && entry.links && entry.links.length > 0) {
+            const visited = opts._visitedLinks ?? new Set();
+            visited.add(entry.id);
+            const allLinked = entry.links.flatMap(linkId => {
+                if (visited.has(linkId))
+                    return []; // cycle detected — skip
+                try {
+                    return this.read({
+                        id: linkId,
+                        agentRole: opts.agentRole,
+                        linkDepth: linkDepth - 1,
+                        _visitedLinks: visited,
+                        followObsolete: false, // don't chain-resolve inside link resolution
+                    });
+                }
+                catch {
+                    return [];
+                }
+            });
+            let hiddenObsolete = 0;
+            let hiddenIrrelevant = 0;
+            for (const e of allLinked) {
+                if (e.obsolete)
+                    hiddenObsolete++;
+                else if (e.irrelevant)
+                    hiddenIrrelevant++;
+            }
+            entry.linkedEntries = allLinked.filter(e => !e.obsolete && !e.irrelevant);
+            if (hiddenObsolete > 0)
+                entry.hiddenObsoleteLinks = hiddenObsolete;
+            if (hiddenIrrelevant > 0)
+                entry.hiddenIrrelevantLinks = hiddenIrrelevant;
+        }
+    }
     bumpAccess(id) {
         this.db.prepare("UPDATE memories SET access_count = access_count + 1, last_accessed = ? WHERE id = ?").run(new Date().toISOString(), id);
     }
     bumpNodeAccess(id) {
         this.db.prepare("UPDATE memory_nodes SET access_count = access_count + 1, last_accessed = ? WHERE id = ?").run(new Date().toISOString(), id);
     }
+    /**
+     * Follow the obsolete chain from an entry to its final valid correction.
+     * Parses [✓ID] from level_1 of each obsolete entry and follows the chain.
+     * Returns the final (non-obsolete) entry ID and the full chain of IDs traversed.
+     */
+    resolveObsoleteChain(id) {
+        const chain = [id];
+        let currentId = id;
+        const visited = new Set();
+        for (let i = 0; i < 10; i++) { // max 10 hops
+            visited.add(currentId);
+            const row = this.db.prepare("SELECT id, level_1, obsolete FROM memories WHERE id = ?").get(currentId);
+            if (!row || !row.obsolete)
+                break; // not obsolete or not found → stop
+            // Parse [✓ID] from level_1
+            const match = row.level_1?.match(/\[✓([A-Z]\d{4}(?:\.\d+)*)\]/);
+            if (!match)
+                break; // no correction reference → stop
+            const nextId = match[1];
+            if (visited.has(nextId))
+                break; // cycle detected → stop
+            chain.push(nextId);
+            currentId = nextId;
+        }
+        return { finalId: currentId, chain };
+    }
     /** Fetch direct children of a node (root or compound), including their grandchild counts. */
+    /** Bulk-fetch direct child counts for multiple parent IDs in one query. */
+    bulkChildCount(parentIds) {
+        if (parentIds.length === 0)
+            return new Map();
+        const placeholders = parentIds.map(() => "?").join(", ");
+        const rows = this.db.prepare(`SELECT parent_id, COUNT(*) as cnt FROM memory_nodes WHERE parent_id IN (${placeholders}) GROUP BY parent_id`).all(...parentIds);
+        const map = new Map();
+        for (const r of rows)
+            map.set(r.parent_id, r.cnt);
+        return map;
+    }
+    /**
+     * Time-weighted access score: newer entries with fewer accesses can outrank
+     * older entries with more accesses. Uses logarithmic age decay:
+     *   score = access_count / log2(age_in_days + 2)
+     */
+    weightedAccessScore(row) {
+        const ageMs = Date.now() - new Date(row.created_at).getTime();
+        const ageDays = Math.max(ageMs / 86_400_000, 0);
+        return (row.access_count || 0) / Math.log2(ageDays + 2);
+    }
     fetchChildren(parentId) {
         return this.fetchChildrenDeep(parentId, 2, 2);
     }
@@ -978,10 +1153,12 @@ export class HmemStore {
             root_id: row.root_id,
             depth: row.depth,
             seq: row.seq,
+            title: row.title ?? this.autoExtractTitle(row.content),
             content: row.content,
             created_at: row.created_at,
             access_count: row.access_count || 0,
             last_accessed: row.last_accessed || null,
+            favorite: row.favorite === 1 ? true : undefined,
             child_count: childCount,
         };
     }
@@ -991,6 +1168,7 @@ export class HmemStore {
             prefix: row.prefix,
             seq: row.seq,
             created_at: row.created_at,
+            title: row.title ?? this.autoExtractTitle(row.level_1),
             level_1: row.level_1,
             level_2: null, // always null post-migration
             level_3: null,
@@ -1002,6 +1180,7 @@ export class HmemStore {
             min_role: row.min_role || "worker",
             obsolete: row.obsolete === 1,
             favorite: row.favorite === 1,
+            irrelevant: row.irrelevant === 1,
             children,
         };
     }
@@ -1016,6 +1195,7 @@ export class HmemStore {
             prefix: node.root_id.match(/^([A-Z]+)/)?.[1] ?? "?",
             seq: node.seq,
             created_at: node.created_at,
+            title: node.title,
             level_1: node.content,
             level_2: null,
             level_3: null,
@@ -1029,7 +1209,28 @@ export class HmemStore {
         };
     }
     /**
-     * Parse tab-indented content into L1 text + a list of tree nodes.
+     * Auto-extract a short title from text.
+     * Priority: text before " — " > word-boundary truncation > hard truncation.
+     */
+    autoExtractTitle(text) {
+        const maxLen = this.cfg.maxTitleChars;
+        const dashIdx = text.indexOf(" — ");
+        if (dashIdx > 0 && dashIdx <= maxLen)
+            return text.substring(0, dashIdx);
+        if (text.length <= maxLen)
+            return text;
+        // Truncate at last word boundary before maxLen
+        const lastSpace = text.lastIndexOf(" ", maxLen);
+        if (lastSpace > maxLen * 0.4)
+            return text.substring(0, lastSpace);
+        return text.substring(0, maxLen);
+    }
+    /**
+     * Parse tab-indented content into title + L1 text + a list of tree nodes.
+     *
+     * Title extraction:
+     *   - 2+ non-indented lines: first line = explicit title, rest = level_1
+     *   - 1 non-indented line: title = auto-extracted (~30 chars), level_1 = full line
      *
      * Algorithm:
      *   - seqAtParent: Map<parentId, number> — sibling counter per parent
@@ -1047,7 +1248,7 @@ export class HmemStore {
         const seqAtParent = new Map();
         const lastIdAtDepth = new Map();
         const nodes = [];
-        let level1 = "";
+        const l1Lines = [];
         // Auto-detect space indentation unit: use first indented line (if no tabs present)
         const rawLines = content.split("\n").map(l => l.trimEnd()).filter(Boolean);
         let spaceUnit = 4;
@@ -1078,8 +1279,7 @@ export class HmemStore {
             }
             const text = trimmedEnd.trim();
             if (depth === 1) {
-                // L1 — multiple L1 lines joined (should be rare)
-                level1 = level1 ? level1 + " | " + text : text;
+                l1Lines.push(text);
                 continue;
             }
             // L2+: determine parent and generate compound ID
@@ -1088,9 +1288,21 @@ export class HmemStore {
             seqAtParent.set(parentId, seq);
             const nodeId = `${parentId}.${seq}`;
             lastIdAtDepth.set(depth, nodeId);
-            nodes.push({ id: nodeId, parent_id: parentId, depth, seq, content: text });
+            nodes.push({ id: nodeId, parent_id: parentId, depth, seq, content: text, title: this.autoExtractTitle(text) });
+        }
+        // Title: first L1 line (explicit). Content: remaining L1 lines joined.
+        // If only 1 L1 line: title is auto-extracted, level1 = full line.
+        let title;
+        let level1;
+        if (l1Lines.length >= 2) {
+            title = l1Lines[0];
+            level1 = l1Lines.slice(1).join(" | ");
+        }
+        else {
+            level1 = l1Lines[0] ?? "";
+            title = this.autoExtractTitle(level1);
         }
-        return { level1, nodes };
+        return { title, level1, nodes };
     }
     /**
      * Parse tab-indented content relative to a parent node.