hmem-mcp 2.0.3 → 2.2.0

package/dist/mcp-server.js

@@ -22,6 +22,7 @@ import path from "node:path";
 import { searchMemory } from "./memory-search.js";
 import { openAgentMemory, openCompanyMemory, resolveHmemPath, HmemStore } from "./hmem-store.js";
 import { loadHmemConfig, formatPrefixList } from "./hmem-config.js";
+import { SessionCache } from "./session-cache.js";
 // ---- Environment ----
 // HMEM_* vars are the canonical names; COUNCIL_* kept for backwards compatibility
 const PROJECT_DIR = process.env.HMEM_PROJECT_DIR || process.env.COUNCIL_PROJECT_DIR || "";
@@ -52,11 +53,13 @@ function log(msg) {
 }
 // Load hmem config (hmem.config.json in project dir, falls back to defaults)
 const hmemConfig = loadHmemConfig(PROJECT_DIR);
-log(`Config: levels=[${hmemConfig.maxCharsPerLevel.join(",")}] depth=${hmemConfig.maxDepth} tiers=${JSON.stringify(hmemConfig.recentDepthTiers)}`);
+log(`Config: levels=[${hmemConfig.maxCharsPerLevel.join(",")}] depth=${hmemConfig.maxDepth}`);
+// Session-scoped cache — persists across tool calls within this MCP connection
+const sessionCache = new SessionCache();
 // ---- Server ----
 const server = new McpServer({
     name: "hmem",
-    version: "1.1.0",
+    version: "2.2.0",
 });
 // ---- Tool: search_memory ----
 server.tool("search_memory", "Searches the collective memory: agent memories (lessons learned, evaluations), " +
@@ -199,7 +202,9 @@ server.tool("update_memory", "Update the text of an existing memory entry or sub
     "- Mark as obsolete: FIRST write the correction, THEN update with [✓ID] reference:\n" +
     "  1. write_memory(prefix='E', content='Correct fix is...') → E0076\n" +
     "  2. update_memory(id='E0042', content='Wrong — see [✓E0076]', obsolete=true)\n" +
-    "- Mark as favorite: update_memory(id='D0010', content='...', favorite=true)\n\n" +
+    "- Mark as favorite: update_memory(id='D0010', content='...', favorite=true)\n" +
+    "- Mark as irrelevant: update_memory(id='L0042', content='...', irrelevant=true)\n" +
+    "  No correction entry needed (unlike obsolete). Hidden from bulk reads.\n\n" +
     "To add new child nodes, use append_memory. " +
     "To replace the entire tree, use delete_agent_memory + write_memory (curator only).", {
     id: z.string().describe("ID of the entry or node to update, e.g. 'L0003' or 'L0003.2'"),
@@ -207,10 +212,12 @@ server.tool("update_memory", "Update the text of an existing memory entry or sub
     links: z.array(z.string()).optional().describe("Optional: update linked entry IDs (root entries only). Replaces existing links."),
     obsolete: z.boolean().optional().describe("Mark this root entry as no longer valid (root entries only). " +
         "Requires [✓ID] correction reference in content (e.g. 'Wrong — see [✓E0076]')."),
-    favorite: z.boolean().optional().describe("Set or clear the [♥] favorite flag on this root entry (root entries only). " +
-        "Favorites are always shown with L2 detail in bulk reads."),
+    favorite: z.boolean().optional().describe("Set or clear the [♥] favorite flag. Works on root entries and sub-nodes. " +
+        "Root favorites are always shown with L2 detail in bulk reads."),
+    irrelevant: z.boolean().optional().describe("Mark this root entry as irrelevant [-] (root entries only). " +
+        "No correction entry needed (unlike obsolete). Irrelevant entries are hidden from bulk reads."),
     store: z.enum(["personal", "company"]).default("personal").describe("Target store: 'personal' or 'company'"),
-}, async ({ id, content, links, obsolete, favorite, store: storeName }) => {
+}, async ({ id, content, links, obsolete, favorite, irrelevant, store: storeName }) => {
     const templateName = AGENT_ID.replace(/_\d+$/, "");
     const agentRole = (ROLE || "worker");
     if (storeName === "company") {
@@ -233,9 +240,9 @@ server.tool("update_memory", "Update the text of an existing memory entry or sub
                     isError: true,
                 };
             }
-            const ok = hmemStore.updateNode(id, content, links, obsolete, favorite);
+            const ok = hmemStore.updateNode(id, content, links, obsolete, favorite, undefined, irrelevant);
             const storeLabel = storeName === "company" ? "company" : (templateName || "memory");
-            log(`update_memory [${storeLabel}]: ${id} → ${ok ? "updated" : "not found"}${obsolete ? " (marked obsolete)" : ""}${favorite !== undefined ? ` (favorite=${favorite})` : ""}`);
+            log(`update_memory [${storeLabel}]: ${id} → ${ok ? "updated" : "not found"}${obsolete ? " (marked obsolete)" : ""}${irrelevant ? " (marked irrelevant)" : ""}${favorite !== undefined ? ` (favorite=${favorite})` : ""}`);
             if (!ok) {
                 return {
                     content: [{ type: "text", text: `ERROR: Entry "${id}" not found in ${storeLabel}.` }],
@@ -247,6 +254,10 @@ server.tool("update_memory", "Update the text of an existing memory entry or sub
                 parts.push("links updated");
             if (obsolete === true)
                 parts.push("marked as [!] obsolete");
+            if (irrelevant === true)
+                parts.push("marked as [-] irrelevant");
+            if (irrelevant === false)
+                parts.push("irrelevant flag cleared");
             if (favorite === true)
                 parts.push("marked as [♥] favorite");
             if (favorite === false)
@@ -338,7 +349,8 @@ server.tool("read_memory", "Read from your hierarchical long-term memory (.hmem)
     "- By prefix: read_memory({ prefix: 'L' }) → All Lessons Learned (Level 1)\n" +
     "- By time: read_memory({ after: '2026-02-15', before: '2026-02-17' })\n" +
     "- Search: read_memory({ search: 'SSE' }) → Full-text search across all levels\n" +
-    "- Time-around: read_memory({ time_around: 'P0001' }) → entries near P0001's timestamp\n\n" +
+    "- Time-around: read_memory({ time_around: 'P0001' }) → entries near P0001's timestamp\n" +
+    "- Title listing: read_memory({ titles_only: true }) → compact table of contents (ID + date + title)\n\n" +
     "Lazy loading: ID queries always return the node + its DIRECT children only.\n" +
     "To go deeper, call read_memory(id=child_id). depth parameter is ignored for ID queries.\n\n" +
     "Store types:\n" +
@@ -354,9 +366,20 @@ server.tool("read_memory", "Read from your hierarchical long-term memory (.hmem)
     period: z.string().optional().describe("Time window: '+4h' (after), '-2h' (before), '4h' (±4h symmetric), 'both' (±2h default)"),
     time_around: z.string().optional().describe("Reference entry ID — find entries created around the same time"),
     show_obsolete: z.boolean().optional().describe("Include all obsolete entries (default: only top 3 most-accessed)"),
+    show_obsolete_path: z.boolean().optional().describe("When reading an obsolete entry by ID, show the full correction chain instead of just the final valid entry."),
+    titles_only: z.boolean().optional().describe("Compact title listing — shows all entries as ID + date + title, without V2 selection or children. " +
+        "Like a table of contents. Combine with prefix to filter by category."),
+    expand: z.boolean().optional().describe("Expand full tree with complete node content (ID queries only). " +
+        "Use to deep-dive into a project after a long break. " +
+        "depth controls how deep (default: 5 = full tree). " +
+        "Example: read_memory({ id: 'P0001', expand: true, depth: 3 })"),
+    mode: z.enum(["discover", "essentials"]).optional().describe("Bulk read mode. 'discover' (default for first read): newest-heavy — good for getting an overview. " +
+        "'essentials': importance-heavy (more favorites + most-accessed, fewer newest) — " +
+        "use after context compression to recover key knowledge. " +
+        "Auto-selected if omitted: first bulk read → discover, subsequent → essentials."),
     store: z.enum(["personal", "company"]).default("personal").describe("Source store: 'personal' or 'company'"),
     curator: z.boolean().optional().describe("Set true to show full metadata (access counts, roles, dates). For curators only."),
-}, async ({ id, depth, prefix, after, before, search, limit: maxResults, time, period, time_around, show_obsolete, store: storeName, curator }) => {
+}, async ({ id, depth, prefix, after, before, search, limit: maxResults, time, period, time_around, show_obsolete, show_obsolete_path, titles_only, expand, mode, store: storeName, curator }) => {
     if (AGENT_ID === "UNKNOWN") {
         return {
             content: [{ type: "text", text: "ERROR: Agent-ID unknown. read_memory is only available for spawned agents." }],
@@ -374,12 +397,27 @@ server.tool("read_memory", "Read from your hierarchical long-term memory (.hmem)
                 ? "⚠ WARNING: Memory database is corrupted! Reads may be incomplete. A backup (.corrupt) was saved.\n\n"
                 : "";
             const effectiveDepth = depth || (id ? 2 : 1);
+            // Session cache: apply sliding window for bulk reads (personal store only)
+            const isBulkListing = !id && !search && !time_around;
+            const useCache = isBulkListing && storeName === "personal";
+            const suppressedIds = useCache ? sessionCache.getSuppressedIds() : undefined;
+            const maxNewNewest = useCache ? sessionCache.getNewestSlotCount() : undefined;
+            const maxNewAccess = useCache ? sessionCache.getAccessSlotCount() : undefined;
+            // Auto-select mode: first bulk read → discover, subsequent → essentials
+            const effectiveMode = mode ?? (useCache && sessionCache.readCount > 0 ? "essentials" : "discover");
             const entries = hmemStore.read({
                 id, depth: effectiveDepth, prefix, after, before, search,
                 limit: maxResults,
                 agentRole: storeName === "company" ? agentRole : undefined,
                 time, period, timeAround: time_around,
                 showObsolete: show_obsolete,
+                showObsoletePath: show_obsolete_path,
+                titlesOnly: titles_only,
+                expand,
+                suppressedIds,
+                maxNewNewest,
+                maxNewAccess,
+                mode: isBulkListing ? effectiveMode : undefined,
             });
             if (entries.length === 0) {
                 const hint = id ? `No memory with ID "${id}".` :
@@ -388,17 +426,30 @@ server.tool("read_memory", "Read from your hierarchical long-term memory (.hmem)
                             "No memories found for this query.";
                 return { content: [{ type: "text", text: hint }] };
             }
+            // Update session cache after bulk read
+            if (useCache) {
+                const allIds = entries.filter(e => !e.obsolete).map(e => e.id);
+                const promotedIds = new Set(entries.filter(e => e.promoted === "favorite" || e.promoted === "access").map(e => e.id));
+                sessionCache.registerDelivered(allIds, promotedIds);
+            }
             // Format output
-            const isBulkListing = !id && !search && !time_around;
-            const output = isBulkListing
-                ? formatGroupedOutput(hmemStore, entries, curator ?? false, hmemConfig)
-                : formatFlatOutput(entries, curator ?? false);
+            const output = titles_only
+                ? formatTitlesOnly(entries, hmemConfig)
+                : isBulkListing
+                    ? formatGroupedOutput(hmemStore, entries, curator ?? false, hmemConfig)
+                    : formatFlatOutput(entries, curator ?? false, expand ?? false);
             const stats = hmemStore.stats();
             const storeLabel = storeName === "company" ? "company" : templateName;
             const visibleCount = entries.length;
+            // Cache status in header (when active)
+            const cacheInfo = useCache && sessionCache.size > 0
+                ? ` | Cache: ${sessionCache.size} seen`
+                : "";
+            // Mode info in header (only for bulk reads)
+            const modeInfo = isBulkListing ? ` | Mode: ${effectiveMode}` : "";
             const header = `## Memory: ${storeLabel} (${stats.total} total entries)\n` +
-                `Query: ${id ? `id=${id}` : ""}${prefix ? `prefix=${prefix}` : ""}${search ? `search="${search}"` : ""}${time_around ? `time_around=${time_around}` : ""}${after ? ` after=${after}` : ""}${before ? ` before=${before}` : ""}${time ? ` time=${time}` : ""} | Depth: ${effectiveDepth} | Results: ${visibleCount}\n`;
-            log(`read_memory [${storeLabel}]: ${visibleCount} results (depth=${effectiveDepth}, role=${agentRole})`);
+                `Query: ${id ? `id=${id}` : ""}${prefix ? `prefix=${prefix}` : ""}${search ? `search="${search}"` : ""}${time_around ? `time_around=${time_around}` : ""}${after ? ` after=${after}` : ""}${before ? ` before=${before}` : ""}${time ? ` time=${time}` : ""} | Depth: ${effectiveDepth} | Results: ${visibleCount}${modeInfo}${cacheInfo}\n`;
+            log(`read_memory [${storeLabel}]: ${visibleCount} results (depth=${effectiveDepth}, role=${agentRole}${cacheInfo})`);
             return {
                 content: [{
                         type: "text",
@@ -418,6 +469,24 @@ server.tool("read_memory", "Read from your hierarchical long-term memory (.hmem)
     }
 });
 // bump_memory removed — access_count is auto-incremented on reads, favorites cover explicit importance
+// ---- Session Cache Reset ----
+server.tool("reset_memory_cache", "Clear the session cache so all entries are treated as unseen again. " +
+    "The next bulk read will behave like the first read of a fresh session " +
+    "(full Fibonacci slots, no suppressed entries).\n\n" +
+    "Use when you need a clean slate — e.g., after a major topic change " +
+    "or when you suspect important entries were suppressed.", {}, async () => {
+    const before = sessionCache.size;
+    const readsBefore = sessionCache.readCount;
+    sessionCache.reset();
+    return {
+        content: [{
+                type: "text",
+                text: `Session cache reset. Cleared ${before} tracked entries, ` +
+                    `bulk read counter ${readsBefore} → 0. ` +
+                    `Next read_memory() will return the full first-read selection.`,
+            }],
+    };
+});
 // ---- Curator Tools (ceo role only) ----
 const AUDIT_STATE_FILE = process.env.HMEM_AUDIT_STATE_PATH
     || path.join(PROJECT_DIR, "audit_state.json");
@@ -527,16 +596,22 @@ server.tool("read_agent_memory", "CURATOR ONLY (ceo role). Read the full memory
             const date = e.created_at.substring(0, 10);
             const role = e.min_role !== "worker" ? ` [${e.min_role}+]` : "";
             const access = e.access_count > 0 ? ` (${e.access_count}x)` : "";
-            lines.push(`[${e.id}] ${date}${role}${access}`);
-            lines.push(`  L1: ${e.level_1}`);
-            if (e.level_2)
-                lines.push(`  L2: ${e.level_2}`);
-            if (e.level_3)
-                lines.push(`  L3: ${e.level_3}`);
-            if (e.level_4)
-                lines.push(`  L4: ${e.level_4}`);
-            if (e.level_5)
-                lines.push(`  L5: ${e.level_5}`);
+            const obsoleteTag = e.obsolete ? " [⚠ OBSOLETE]" : "";
+            const irrelevantTag = e.irrelevant ? " [- IRRELEVANT]" : "";
+            const favTag = e.favorite ? " [♥]" : "";
+            lines.push(`[${e.id}] ${date}${role}${favTag}${obsoleteTag}${irrelevantTag}${access}`);
+            lines.push(`  ${e.title}`);
+            if (e.level_1 !== e.title)
+                lines.push(`  ${e.level_1}`);
+            if (e.children && e.children.length > 0) {
+                for (const child of e.children) {
+                    const indent = "  ".repeat(child.depth - 1);
+                    const hint = (child.child_count ?? 0) > 0
+                        ? `  (${child.child_count} — use id="${child.id}" to expand)`
+                        : "";
+                    lines.push(`${indent}[${child.id}] ${child.title}${hint}`);
+                }
+            }
             if (e.links?.length)
                 lines.push(`  Links: ${e.links.join(", ")}`);
             lines.push("");
@@ -550,7 +625,7 @@ server.tool("read_agent_memory", "CURATOR ONLY (ceo role). Read the full memory
 });
 server.tool("fix_agent_memory", "CURATOR ONLY (ceo role). Correct a specific entry or node in any agent's memory.\n\n" +
     "Accepts both root IDs ('L0003') and compound node IDs ('L0003.2'):\n" +
-    "- Root ID: updates L1 summary text, min_role clearance, and/or obsolete flag\n" +
+    "- Root ID: updates L1 summary text, min_role clearance, obsolete/irrelevant/favorite flags\n" +
     "- Compound node ID: updates the content of that specific node\n\n" +
     "To fix wrong prefix: delete + re-add (prefix cannot be changed in-place).\n" +
     "To consolidate fragmented P entries: use read_agent_memory to read them, " +
@@ -564,7 +639,8 @@ server.tool("fix_agent_memory", "CURATOR ONLY (ceo role). Correct a specific ent
     obsolete: z.boolean().optional().describe("Mark or unmark as obsolete (root entries only). " +
         "Obsolete entries stay in memory but are shown with [⚠ OBSOLETE]."),
     favorite: z.boolean().optional().describe("Set or clear the [♥] favorite flag (root entries only)."),
-}, async ({ agent_name, entry_id, content, min_role, obsolete, favorite }) => {
+    irrelevant: z.boolean().optional().describe("Mark or unmark as irrelevant (root entries only). Irrelevant entries are hidden from bulk reads. No correction entry needed."),
+}, async ({ agent_name, entry_id, content, min_role, obsolete, favorite, irrelevant }) => {
     if (!isCurator()) {
         return {
             content: [{ type: "text", text: "ERROR: fix_agent_memory is only available to the ceo/curator role." }],
@@ -597,19 +673,21 @@ server.tool("fix_agent_memory", "CURATOR ONLY (ceo role). Correct a specific ent
         }
         else {
             // Root entry — update memories table
-            if (!content && min_role === undefined && obsolete === undefined && favorite === undefined) {
+            if (!content && min_role === undefined && obsolete === undefined && favorite === undefined && irrelevant === undefined) {
                 return {
-                    content: [{ type: "text", text: "ERROR: Provide at least one of: content, min_role, obsolete, favorite." }],
+                    content: [{ type: "text", text: "ERROR: Provide at least one of: content, min_role, obsolete, favorite, irrelevant." }],
                     isError: true,
                 };
             }
             if (content) {
-                ok = store.updateNode(entry_id, content, undefined, obsolete, favorite, true /* curatorBypass */);
+                ok = store.updateNode(entry_id, content, undefined, obsolete, favorite, true /* curatorBypass */, irrelevant);
                 changed.push("L1");
                 if (obsolete !== undefined)
                     changed.push("obsolete");
                 if (favorite !== undefined)
                     changed.push("favorite");
+                if (irrelevant !== undefined)
+                    changed.push("irrelevant");
             }
             else {
                 const fields = {};
@@ -619,6 +697,8 @@ server.tool("fix_agent_memory", "CURATOR ONLY (ceo role). Correct a specific ent
                     fields.obsolete = obsolete;
                 if (favorite !== undefined)
                     fields.favorite = favorite;
+                if (irrelevant !== undefined)
+                    fields.irrelevant = irrelevant;
                 ok = store.update(entry_id, fields);
             }
             if (min_role !== undefined)
@@ -627,6 +707,8 @@ server.tool("fix_agent_memory", "CURATOR ONLY (ceo role). Correct a specific ent
                 changed.push("obsolete");
             if (!content && favorite !== undefined)
                 changed.push("favorite");
+            if (!content && irrelevant !== undefined)
+                changed.push("irrelevant");
         }
         log(`fix_agent_memory [CURATOR]: ${agent_name} ${entry_id} → ${ok ? "updated" : "not found"} (${changed.join(", ")})`);
         return {
@@ -752,6 +834,55 @@ server.tool("mark_audited", "CURATOR ONLY (ceo role). Mark an agent as audited (
  * Format bulk-read output grouped by prefix with header entries.
  * Non-curator: strips [♥], [★] markers, shortens [OBSOLETE] to [!].
  */
+/**
+ * Format compact title listing — ID + date + title, grouped by prefix.
+ * V2 selection applies. Favorites/top-accessed show L2 children titles.
+ * Non-expanded entries show (N) child count indicator.
+ */
+function formatTitlesOnly(entries, config) {
+    const CHILD_TITLE_LEN = 50;
+    const lines = [];
+    const byPrefix = new Map();
+    for (const e of entries) {
+        const arr = byPrefix.get(e.prefix);
+        if (arr)
+            arr.push(e);
+        else
+            byPrefix.set(e.prefix, [e]);
+    }
+    for (const [prefix, prefixEntries] of byPrefix) {
+        const desc = config.prefixDescriptions[prefix] ?? config.prefixes[prefix] ?? prefix;
+        lines.push(`## ${desc} (${prefixEntries.length} total)\n`);
+        for (const e of prefixEntries) {
+            const mmdd = e.created_at.substring(5, 10);
+            const fav = e.favorite ? " [♥]" : "";
+            const obs = e.obsolete ? " [!]" : "";
+            const irr = e.irrelevant ? " [-]" : "";
+            if (e.expanded && e.children && e.children.length > 0) {
+                // Expanded entry (favorite/top-accessed): show with L2 children
+                lines.push(`${e.id} ${mmdd}${fav}${obs}  ${e.title}`);
+                for (const child of e.children) {
+                    const short = child.title || (child.content.length > CHILD_TITLE_LEN
+                        ? child.content.substring(0, CHILD_TITLE_LEN)
+                        : child.content);
+                    const grandchildren = (child.child_count ?? 0) > 0 ? ` (${child.child_count})` : "";
+                    const cfav = child.favorite ? " [♥]" : "";
+                    lines.push(`  ${child.id}${cfav}  ${short}${grandchildren}`);
+                }
+                if (e.hiddenChildrenCount && e.hiddenChildrenCount > 0) {
+                    lines.push(`  [+${e.hiddenChildrenCount} more → ${e.id}]`);
+                }
+            }
+            else {
+                // Non-expanded: compact line with child count
+                const childHint = (e.hiddenChildrenCount ?? 0) > 0 ? ` (${e.hiddenChildrenCount})` : "";
+                lines.push(`${e.id} ${mmdd}${fav}${obs}  ${e.title}${childHint}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
 function formatGroupedOutput(store, entries, curator, config) {
     const lines = [];
     const headers = store.getHeaders();
@@ -787,122 +918,199 @@ function formatGroupedOutput(store, entries, curator, config) {
     }
     return lines.join("\n");
 }
-function formatFlatOutput(entries, curator) {
+function formatFlatOutput(entries, curator, expand = false) {
     const lines = [];
+    // Obsolete chain resolution note
+    if (entries.length > 0 && entries[0].obsoleteChain && entries[0].obsoleteChain.length > 1) {
+        const chain = entries[0].obsoleteChain;
+        if (entries.length === 1) {
+            const chainStr = chain.slice(0, -1).map(id => `${id} [!]`).join(" → ") + ` → ${chain[chain.length - 1]} ✓`;
+            lines.push(`[Resolved: ${chainStr}]\n`);
+        }
+        else {
+            lines.push(`[Chain: ${chain.join(" → ")}]\n`);
+        }
+    }
     for (const e of entries) {
-        renderEntryFormatted(lines, e, curator);
+        renderEntryFormatted(lines, e, curator, expand);
     }
     return lines.join("\n");
 }
-function renderEntryFormatted(lines, e, curator) {
+/** Favorite marker for child nodes. */
+function nodeFav(node) {
+    return node.favorite ? " [♥]" : "";
+}
+function renderEntryFormatted(lines, e, curator, expand = false) {
     const isNode = e.id.includes(".");
+    const hasDetail = !!(e.children?.length || e.linkedEntries?.length);
+    // Headline: use title for navigation, show full content below when drilling in
     if (isNode) {
         if (curator) {
-            const nodeDepth = (e.id.match(/\./g) || []).length + 1;
-            lines.push(`[${e.id}] L${nodeDepth}: ${e.level_1}`);
+            lines.push(`[${e.id}] ${e.title}`);
         }
         else {
-            lines.push(`${e.id}  ${e.level_1}`);
+            lines.push(`${e.id}  ${e.title}`);
+        }
+        // Node drilldown: show full content below title
+        if (hasDetail && e.level_1 !== e.title) {
+            lines.push(`  ${e.level_1}`);
         }
     }
     else {
         if (curator) {
             const promotedTag = e.promoted === "favorite" ? " [♥]" : e.promoted === "access" ? " [★]" : "";
             const obsoleteTag = e.obsolete ? " [⚠ OBSOLETE]" : "";
+            const irrelevantTag = e.irrelevant ? " [- IRRELEVANT]" : "";
             const date = e.created_at.substring(0, 10);
             const accessed = e.access_count > 0 ? ` (${e.access_count}x accessed)` : "";
             const roleTag = e.min_role !== "worker" ? ` [${e.min_role}+]` : "";
-            lines.push(`[${e.id}] ${date}${roleTag}${promotedTag}${obsoleteTag}${accessed}`);
-            lines.push(`  L1: ${e.level_1}`);
+            lines.push(`[${e.id}] ${date}${roleTag}${promotedTag}${obsoleteTag}${irrelevantTag}${accessed}`);
+            lines.push(`  ${e.title}`);
         }
         else {
-            // Non-curator: [♥] favorites, [★] promoted, [!] obsolete
             const promotedTag = e.promoted === "favorite" ? " [♥]" : e.promoted === "access" ? " [★]" : "";
             const obsoleteTag = e.obsolete ? " [!]" : "";
+            const irrelevantTag = e.irrelevant ? " [-]" : "";
             const mmdd = e.created_at.substring(5, 10);
-            lines.push(`${e.id} ${mmdd}${promotedTag}${obsoleteTag}  ${e.level_1}`);
+            lines.push(`${e.id} ${mmdd}${promotedTag}${obsoleteTag}${irrelevantTag}  ${e.title}`);
+        }
+        // Show full level_1 content below title when entry is expanded/drilled
+        if (hasDetail && e.level_1 !== e.title) {
+            lines.push(`  ${e.level_1}`);
         }
     }
+    // Children
     if (e.children && e.children.length > 0) {
-        if (e.expanded) {
-            if (curator) {
-                lines.push(`  ${e.children.length} ${e.children.length === 1 ? "child" : "children"}:`);
-            }
+        if (expand) {
+            // Expand mode: full content + recursive children
+            renderChildrenExpanded(lines, e.children, curator);
+        }
+        else if (e.expanded && !expand) {
             renderChildrenFormatted(lines, e.children, curator);
+            if (e.hiddenChildrenCount && e.hiddenChildrenCount > 0) {
+                lines.push(`  [+${e.hiddenChildrenCount} more → ${e.id}]`);
+            }
         }
         else if (e.hiddenChildrenCount !== undefined) {
+            // Non-expanded bulk read: show only the latest child title
             const child = e.children[0];
+            const fav = nodeFav(child);
+            const hint = (child.child_count ?? 0) > 0
+                ? `  [+${child.child_count} → ${child.id}]`
+                : "";
             if (curator) {
-                const hint = (child.child_count ?? 0) > 0
-                    ? `  (${child.child_count} — use id="${child.id}" to expand)`
-                    : "";
-                lines.push(`  [${child.id}] L${child.depth}: ${child.content}${hint}`);
+                lines.push(`  [${child.id}]${fav} ${child.title}${hint}`);
             }
             else {
-                const hint = (child.child_count ?? 0) > 0
-                    ? `  [+${child.child_count} → ${child.id}]`
-                    : "";
-                lines.push(`  ${child.depth}.${child.seq}  ${child.content}${hint}`);
-            }
-            if (child.children && child.children.length > 0) {
-                renderChildrenFormatted(lines, child.children, curator);
+                lines.push(`  ${child.id}${fav}  ${child.title}${hint}`);
             }
             if (e.hiddenChildrenCount > 0) {
                 lines.push(`  [+${e.hiddenChildrenCount} more → ${e.id}]`);
             }
         }
         else {
-            if (curator) {
-                lines.push(`  ${e.children.length} ${e.children.length === 1 ? "child" : "children"}:`);
-            }
+            // ID-based read: show all direct children as titles
             renderChildrenFormatted(lines, e.children, curator);
         }
     }
-    if (e.links && e.links.length > 0)
-        lines.push(`  Links: ${e.links.join(", ")}`);
+    // Links
+    if (e.links && e.links.length > 0) {
+        const parts = [`Links: ${e.links.join(", ")}`];
+        const hiddenParts = [];
+        if (e.hiddenObsoleteLinks && e.hiddenObsoleteLinks > 0)
+            hiddenParts.push(`${e.hiddenObsoleteLinks} obsolete`);
+        if (e.hiddenIrrelevantLinks && e.hiddenIrrelevantLinks > 0)
+            hiddenParts.push(`${e.hiddenIrrelevantLinks} irrelevant`);
+        if (hiddenParts.length > 0)
+            parts.push(`(+${hiddenParts.join(", ")} hidden)`);
+        lines.push(`  ${parts.join(" ")}`);
+    }
+    // Auto-resolved linked entries
     if (e.linkedEntries && e.linkedEntries.length > 0) {
         lines.push(`  --- Linked entries ---`);
         for (const linked of e.linkedEntries) {
             const isLinkedNode = linked.id.includes(".");
             if (isLinkedNode) {
-                const d = (linked.id.match(/\./g) || []).length + 1;
-                lines.push(`  [${linked.id}] L${d}: ${linked.level_1}`);
+                lines.push(`  [${linked.id}] ${linked.title}`);
             }
             else {
                 const ldate = linked.created_at.substring(0, 10);
                 lines.push(`  [${linked.id}] ${ldate}`);
-                lines.push(`    L1: ${linked.level_1}`);
+                lines.push(`    ${linked.title}`);
             }
+            // Linked children as titles
             if (linked.children && linked.children.length > 0) {
                 for (const lchild of linked.children) {
-                    const cd = (lchild.id.match(/\./g) || []).length + 1;
                     const hint = (lchild.child_count ?? 0) > 0
                         ? ` (${lchild.child_count} ${lchild.child_count === 1 ? "child" : "children"} — use id="${lchild.id}" to expand)`
                         : "";
-                    lines.push(`    [${lchild.id}] L${cd}: ${lchild.content}${hint}`);
+                    lines.push(`    [${lchild.id}]${nodeFav(lchild)} ${lchild.title}${hint}`);
                 }
             }
         }
     }
     lines.push("");
 }
+/**
+ * Render a list of child nodes — shows titles for navigation.
+ * Use read_memory(id=child.id) to see full content.
+ */
 function renderChildrenFormatted(lines, children, curator) {
     for (const child of children) {
         const indent = "  ".repeat(child.depth - 1);
+        const fav = nodeFav(child);
+        const hint = (child.child_count ?? 0) > 0
+            ? `  [+${child.child_count} → ${child.id}]`
+            : "";
         if (curator) {
-            const hint = (child.child_count ?? 0) > 0
-                ? `  (${child.child_count} — use id="${child.id}" to expand)`
-                : "";
-            lines.push(`${indent}[${child.id}] L${child.depth}: ${child.content}${hint}`);
+            lines.push(`${indent}[${child.id}]${fav} ${child.title}${hint}`);
         }
         else {
-            const hint = (child.child_count ?? 0) > 0
-                ? `  [+${child.child_count} → ${child.id}]`
-                : "";
-            lines.push(`${indent}${child.depth}.${child.seq}  ${child.content}${hint}`);
+            lines.push(`${indent}${child.id}${fav}  ${child.title}${hint}`);
         }
-        if (child.children && child.children.length > 0) {
-            renderChildrenFormatted(lines, child.children, curator);
+        // Don't recurse into grandchildren — titles only, drill for content
+    }
+}
+/**
+ * Render children with full content (expand mode).
+ * Shows complete node text and recurses into grandchildren.
+ * At the depth boundary (children loaded but THEIR children are not),
+ * renders as titles instead of full content.
+ */
+function renderChildrenExpanded(lines, children, curator) {
+    for (const child of children) {
+        const indent = "  ".repeat(child.depth - 1);
+        const fav = nodeFav(child);
+        const hasLoadedChildren = child.children && child.children.length > 0;
+        const isBoundary = !hasLoadedChildren && (child.child_count ?? 0) > 0;
+        if (hasLoadedChildren) {
+            // Inner node: full content + recurse
+            if (curator) {
+                lines.push(`${indent}[${child.id}]${fav} ${child.content}`);
+            }
+            else {
+                lines.push(`${indent}${child.id}${fav}  ${child.content}`);
+            }
+            renderChildrenExpanded(lines, child.children, curator);
+        }
+        else if (isBoundary) {
+            // Boundary: title only + child count hint
+            const hint = `  [+${child.child_count} → ${child.id}]`;
+            if (curator) {
+                lines.push(`${indent}[${child.id}]${fav} ${child.title}${hint}`);
+            }
+            else {
+                lines.push(`${indent}${child.id}${fav}  ${child.title}${hint}`);
+            }
+        }
+        else {
+            // Leaf node (no children at all): full content
+            if (curator) {
+                lines.push(`${indent}[${child.id}]${fav} ${child.content}`);
+            }
+            else {
+                lines.push(`${indent}${child.id}${fav}  ${child.content}`);
+            }
         }
     }
 }