hmem-mcp 5.0.0 → 5.1.21

package/dist/hmem-store.js

@@ -159,6 +159,8 @@ const MIGRATIONS = [
     "ALTER TABLE memory_nodes ADD COLUMN updated_at TEXT",
     // Active flag: marks entries as currently relevant — non-active entries in same prefix shown title-only
     "ALTER TABLE memories ADD COLUMN active INTEGER DEFAULT 0",
+    // Links: JSON array of related entry IDs (cross-references between entries)
+    "ALTER TABLE memories ADD COLUMN links TEXT",
 ];
 // ---- HmemStore class ----
 export class HmemStore {
@@ -241,8 +243,10 @@ export class HmemStore {
         }
         const l1Limit = this.cfg.maxCharsPerLevel[0];
         const t = HmemStore.CHAR_LIMIT_TOLERANCE;
-        if (level1.length > l1Limit * t) {
-            throw new Error(`Level 1 exceeds ${l1Limit} character limit (${level1.length} chars). Keep L1 compact.`);
+        // Only check title length for the L1 limit — body lines (>) are stored separately
+        // and hidden in listings, so they don't affect display compactness
+        if (title.length > l1Limit * t) {
+            throw new Error(`Level 1 title exceeds ${l1Limit} character limit (${title.length} chars). Keep the title compact and move detail to body lines (> prefix) or L2 children.`);
         }
         for (const node of nodes) {
             // depth 2-5 → index 1-4
@@ -693,6 +697,20 @@ export class HmemStore {
      */
     readBulkV2(rows, opts) {
         const v2 = this.cfg.bulkReadV2;
+        // Direct results mode: bypass V2 selection, project gate, session cache.
+        // Used for explicit filters (after, before, prefix, tag, stale_days) where the user
+        // expects ALL matching rows, not a curated V2 subset.
+        if (opts.directResults) {
+            const visibleRows = rows.filter(r => r.irrelevant !== 1);
+            const entries = visibleRows.map(r => {
+                const children = this.fetchChildren(r.id).filter(c => !c.irrelevant);
+                const entry = this.rowToEntry(r, children);
+                entry.expanded = true;
+                return entry;
+            });
+            this.assignBulkTags(entries);
+            return entries;
+        }
         // Step 0: Filter out irrelevant entries (never shown in bulk reads)
         // O-prefix excluded from unfiltered bulk reads (but shown when explicitly requested via prefix="O")
         const explicitPrefix = !!opts.prefix;
@@ -1478,16 +1496,24 @@ export class HmemStore {
      * Exchange structure: L2 = title, L4 (X.1) = user message, L5 (X.1.1) = agent response.
      * Returns newest first.
      */
-    getOEntryExchanges(oEntryId, limit) {
+    getOEntryExchanges(oEntryId, limit, skipSkillDialogs = false) {
         if (limit <= 0)
             return [];
         // Get the last N L2 nodes (exchanges) by seq DESC
-        const l2Nodes = this.db.prepare(`SELECT id, seq FROM memory_nodes WHERE root_id = ? AND depth = 2 ORDER BY seq DESC LIMIT ?`).all(oEntryId, limit);
+        let l2Nodes;
+        // Always exclude checkpoint-summary nodes (they're not exchanges)
+        const excludeTags = ["'#checkpoint-summary'"];
+        if (skipSkillDialogs)
+            excludeTags.push("'#skill-dialog'");
+        l2Nodes = this.db.prepare(`SELECT id, seq FROM memory_nodes WHERE root_id = ? AND depth = 2
+       AND id NOT IN (SELECT entry_id FROM memory_tags WHERE tag IN (${excludeTags.join(",")}))
+       ORDER BY seq DESC LIMIT ?`).all(oEntryId, limit);
         const exchanges = [];
         for (const l2 of l2Nodes) {
             const l4 = this.db.prepare(`SELECT content FROM memory_nodes WHERE parent_id = ? AND depth = 4 LIMIT 1`).get(l2.id);
             const l5 = this.db.prepare(`SELECT content FROM memory_nodes WHERE root_id = ? AND depth = 5 AND parent_id = ? LIMIT 1`).get(oEntryId, l2.id + ".1");
             exchanges.push({
+                nodeId: l2.id,
                 seq: l2.seq,
                 userText: l4?.content || "",
                 agentText: l5?.content || "",
@@ -1574,8 +1600,26 @@ export class HmemStore {
                 if (trimmed.length > nodeLimit * HmemStore.CHAR_LIMIT_TOLERANCE) {
                     throw new Error(`Content exceeds ${nodeLimit} character limit (${trimmed.length} chars) for L${nodeRow.depth}.`);
                 }
-                sets.push("content = ?", "title = ?");
-                params.push(trimmed, this.autoExtractTitle(trimmed));
+                // Parse > body lines: first non-> line = title, > lines = body (content)
+                const lines = trimmed.split("\n");
+                const titleLines = [];
+                const bodyLines = [];
+                for (const line of lines) {
+                    if (line.startsWith("> ") || line === ">") {
+                        bodyLines.push(line.replace(/^> ?/, ""));
+                    }
+                    else {
+                        titleLines.push(line);
+                    }
+                }
+                if (bodyLines.length > 0) {
+                    sets.push("content = ?", "title = ?");
+                    params.push(bodyLines.join("\n"), titleLines.join(" ").trim());
+                }
+                else {
+                    sets.push("content = ?", "title = ?");
+                    params.push(trimmed, this.autoExtractTitle(trimmed));
+                }
             }
             if (favorite !== undefined) {
                 sets.push("favorite = ?");
@@ -1618,41 +1662,43 @@ export class HmemStore {
         }
         else {
             // Root entry in memories
-            // If content has tab-indented children, split L1 from children
-            if (trimmed && (trimmed.includes("\n\t") || trimmed.includes("\n "))) {
-                // Extract L1 (non-indented lines) and child content (indented lines)
+            if (trimmed) {
+                // Split into title lines, body lines (> prefix), and child lines (indented)
                 const lines = trimmed.split("\n");
-                const l1Lines = [];
+                const titleLines = [];
+                const bodyLines = [];
                 const childLines = [];
                 for (const line of lines) {
                     if (line.startsWith("\t") || (line.length > 0 && line[0] === " " && line.trimStart() !== line)) {
                         childLines.push(line);
                     }
+                    else if (line.startsWith("> ") || line === ">") {
+                        bodyLines.push(line.replace(/^> ?/, ""));
+                    }
                     else {
-                        l1Lines.push(line);
+                        titleLines.push(line);
                     }
                 }
-                const l1Text = l1Lines.join(" | ").trim();
+                const hasBody = bodyLines.length > 0;
+                const hasChildren = childLines.length > 0;
+                const titleText = titleLines.join(" | ").trim();
+                const l1Text = hasBody ? bodyLines.join("\n") : titleText;
+                const newTitle = hasBody ? titleText : this.autoExtractTitle(titleText);
                 const l1Limit = this.cfg.maxCharsPerLevel[0];
-                if (l1Text.length > l1Limit * HmemStore.CHAR_LIMIT_TOLERANCE) {
+                // For body mode, check body length against a generous limit (L2-level)
+                // For non-body mode, check title against L1 limit
+                if (!hasBody && l1Text.length > l1Limit * HmemStore.CHAR_LIMIT_TOLERANCE) {
                     throw new Error(`Level 1 exceeds ${l1Limit} character limit (${l1Text.length} chars). Keep L1 compact.`);
                 }
                 // Update L1
                 const updateTs = new Date().toISOString();
-                const newTitle = this.autoExtractTitle(l1Text);
                 this.db.prepare("UPDATE memories SET level_1 = ?, title = ?, updated_at = ? WHERE id = ?")
                     .run(l1Text, newTitle, updateTs, id);
                 // Append children via appendChildren (handles seq numbering correctly)
-                if (childLines.length > 0) {
+                if (hasChildren) {
                     this.appendChildren(id, childLines.join("\n"));
                 }
             }
-            else if (trimmed) {
-                const l1Limit = this.cfg.maxCharsPerLevel[0];
-                if (trimmed.length > l1Limit * HmemStore.CHAR_LIMIT_TOLERANCE) {
-                    throw new Error(`Level 1 exceeds ${l1Limit} character limit (${trimmed.length} chars). Keep L1 compact.`);
-                }
-            }
             // Obsolete enforcement: require [✓ID] correction reference
             if (obsolete === true && !curatorBypass) {
                 const contentToCheck = trimmed ?? this.db.prepare("SELECT level_1 FROM memories WHERE id = ?").get(id)?.level_1 ?? "";
@@ -1688,10 +1734,6 @@ export class HmemStore {
             }
             const sets = [];
             const params = [];
-            if (trimmed) {
-                sets.push("level_1 = ?", "title = ?");
-                params.push(trimmed, this.autoExtractTitle(trimmed));
-            }
             if (links !== undefined) {
                 sets.push("links = ?");
                 params.push(links.length > 0 ? JSON.stringify(links) : null);
@@ -1743,12 +1785,11 @@ export class HmemStore {
                 }
             }
             if (sets.length === 0) {
-                // Only tags to update — no SQL UPDATE needed
+                // No flag updates — but content may have been updated above (> body parsing)
                 if (tags !== undefined) {
                     this.setTags(id, tags.length > 0 ? this.validateTags(tags) : []);
-                    return true;
                 }
-                return false;
+                return !!trimmed || tags !== undefined;
             }
             sets.push("updated_at = ?");
             params.push(new Date().toISOString());
@@ -1807,7 +1848,7 @@ export class HmemStore {
         const topLevelIds = [];
         this.db.transaction(() => {
             for (const node of nodes) {
-                insertNode.run(node.id, node.parent_id, rootId, node.depth, node.seq, this.autoExtractTitle(node.content), node.content, timestamp, timestamp);
+                insertNode.run(node.id, node.parent_id, rootId, node.depth, node.seq, node.title, node.content, timestamp, timestamp);
                 if (node.parent_id === parentId)
                     topLevelIds.push(node.id);
             }
@@ -1838,11 +1879,11 @@ export class HmemStore {
         const parentIsRoot = !parentId.includes(".");
         const rootId = parentIsRoot ? parentId : parentId.split(".")[0];
         const timestamp = new Date().toISOString();
-        // Find next available seq
-        const maxSeq = parentIsRoot
-            ? this.db.prepare("SELECT MAX(seq) as m FROM memory_nodes WHERE parent_id = ? AND depth = 2").get(parentId)?.m ?? 0
-            : this.db.prepare("SELECT MAX(seq) as m FROM memory_nodes WHERE parent_id = ?").get(parentId)?.m ?? 0;
-        const seq = maxSeq + 1;
+        // Find next available seq — scan ALL nodes under this parent (any depth) to avoid
+        // ID collisions with checkpoint summaries or other nodes appended at different depths
+        const maxSeqRow = this.db.prepare(`SELECT MAX(CAST(SUBSTR(id, LENGTH(?) + 1) AS INTEGER)) as m
+       FROM memory_nodes WHERE id LIKE ? AND id NOT LIKE ?`).get(parentId + ".", parentId + ".%", parentId + ".%.%");
+        const seq = (maxSeqRow?.m ?? 0) + 1;
         const title = this.autoExtractTitle(userText.split("\n")[0].replace(/[<>\[\]]/g, ""));
         const l2Id = `${parentId}.${seq}`;
         const l4Id = `${l2Id}.1`;
@@ -1856,6 +1897,38 @@ export class HmemStore {
         })();
         return { id: l2Id };
     }
+    /**
+     * Append a checkpoint summary as a tagged L2 node under an O-entry.
+     * The summary sits alongside exchanges in the L2 sequence.
+     * Returns the node ID.
+     */
+    appendCheckpointSummary(oEntryId, summaryText) {
+        this.guardCorrupted();
+        const timestamp = new Date().toISOString();
+        // Scan all direct children IDs (any depth) to avoid collisions with exchanges
+        const maxSeqRow = this.db.prepare(`SELECT MAX(CAST(SUBSTR(id, LENGTH(?) + 1) AS INTEGER)) as m
+       FROM memory_nodes WHERE id LIKE ? AND id NOT LIKE ?`).get(oEntryId + ".", oEntryId + ".%", oEntryId + ".%.%");
+        const seq = (maxSeqRow?.m ?? 0) + 1;
+        const nodeId = `${oEntryId}.${seq}`;
+        const title = this.autoExtractTitle(summaryText);
+        this.db.transaction(() => {
+            this.db.prepare("INSERT INTO memory_nodes (id, parent_id, root_id, depth, seq, title, content, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)").run(nodeId, oEntryId, oEntryId, 2, seq, title, summaryText, timestamp, timestamp);
+            this.addTag(nodeId, "#checkpoint-summary");
+            this.db.prepare("UPDATE memories SET updated_at = ? WHERE id = ?").run(timestamp, oEntryId);
+        })();
+        return nodeId;
+    }
+    /**
+     * Get checkpoint summaries for an O-entry, newest first.
+     * Returns the summary content + the seq number (to know which exchanges it covers).
+     */
+    getCheckpointSummaries(oEntryId, limit = 2) {
+        return this.db.prepare(`SELECT mn.id as nodeId, mn.seq, mn.content, mn.created_at
+       FROM memory_nodes mn
+       JOIN memory_tags mt ON mt.entry_id = mn.id AND mt.tag = '#checkpoint-summary'
+       WHERE mn.root_id = ?
+       ORDER BY mn.seq DESC LIMIT ?`).all(oEntryId, limit);
+    }
     /**
      * Bump access_count on a root entry or node.
      * Returns true if the entry was found and bumped.
@@ -1921,6 +1994,20 @@ export class HmemStore {
             insert.run(entryId, tag);
         }
     }
+    /** Add a single tag to an entry/node without removing existing tags. */
+    addTag(entryId, tag) {
+        this.db.prepare("INSERT OR IGNORE INTO memory_tags (entry_id, tag) VALUES (?, ?)").run(entryId, tag);
+    }
+    /** Find and tag untagged checkpoint summary nodes ([CP] prefix) under an O-entry. */
+    tagNewCheckpointSummaries(oEntryId) {
+        const nodes = this.db.prepare(`SELECT id FROM memory_nodes WHERE root_id = ?
+       AND (content LIKE '[CP]%' OR title LIKE '[CP]%')
+       AND id NOT IN (SELECT entry_id FROM memory_tags WHERE tag = '#checkpoint-summary')
+       ORDER BY seq`).all(oEntryId);
+        for (const n of nodes)
+            this.addTag(n.id, "#checkpoint-summary");
+        return nodes.map(n => n.id);
+    }
     /** Get tags for a single entry/node. */
     fetchTags(entryId) {
         return this.db.prepare("SELECT tag FROM memory_tags WHERE entry_id = ? ORDER BY tag").all(entryId)
@@ -2283,9 +2370,11 @@ export class HmemStore {
                 const links = row.links ? JSON.parse(row.links) : [];
                 if (links.includes(activeProject.id))
                     return row.id;
-                // Project mismatch — deactivate old O-entry, create new one below
-                this.db.prepare("UPDATE memories SET active = 0, updated_at = ? WHERE id = ?")
-                    .run(new Date().toISOString(), row.id);
+                // Project mismatch — deactivate old O-entry, mark irrelevant if ≤1 exchange
+                const childCount = this.countDirectChildren(row.id);
+                const irrelevant = childCount <= 1 ? 1 : 0;
+                this.db.prepare("UPDATE memories SET active = 0, irrelevant = ?, updated_at = ? WHERE id = ?")
+                    .run(irrelevant, new Date().toISOString(), row.id);
             }
             else {
                 return row.id; // No active project — keep using current O-entry
@@ -2328,7 +2417,31 @@ export class HmemStore {
         return row?.id ?? null;
     }
     bumpAccess(id) {
-        this.db.prepare("UPDATE memories SET access_count = access_count + 1, last_accessed = ? WHERE id = ?").run(new Date().toISOString(), id);
+        // Clear irrelevant flag on explicit read — if someone reads it, it matters
+        this.db.prepare("UPDATE memories SET access_count = access_count + 1, last_accessed = ?, irrelevant = 0 WHERE id = ?").run(new Date().toISOString(), id);
+    }
+    /**
+     * Auto-purge: physically delete irrelevant entries older than maxAgeDays.
+     * Only deletes entries where irrelevant=1 — entries rescued by bumpAccess survive.
+     * Returns the number of deleted entries.
+     */
+    purgeIrrelevant(maxAgeDays = 30) {
+        const cutoff = new Date(Date.now() - maxAgeDays * 86400_000).toISOString();
+        const rows = this.db.prepare("SELECT id FROM memories WHERE irrelevant = 1 AND updated_at < ?").all(cutoff);
+        if (rows.length === 0)
+            return 0;
+        const deleteNodes = this.db.prepare("DELETE FROM memory_nodes WHERE root_id = ?");
+        const deleteRoot = this.db.prepare("DELETE FROM memories WHERE id = ?");
+        const deleteTags = this.db.prepare("DELETE FROM tags WHERE root_id = ?");
+        const purge = this.db.transaction(() => {
+            for (const { id } of rows) {
+                deleteNodes.run(id);
+                deleteTags.run(id);
+                deleteRoot.run(id);
+            }
+        });
+        purge();
+        return rows.length;
     }
     bumpNodeAccess(id) {
         this.db.prepare("UPDATE memory_nodes SET access_count = access_count + 1, last_accessed = ? WHERE id = ?").run(new Date().toISOString(), id);
@@ -2526,6 +2639,7 @@ export class HmemStore {
      * Priority: text before " — " > word-boundary truncation > hard truncation.
      */
     autoExtractTitle(text) {
+        text = text.replace(/[\t\r\n]/g, " ").replace(/  +/g, " ").trim();
         const maxLen = Math.floor(this.cfg.maxTitleChars * HmemStore.CHAR_LIMIT_TOLERANCE);
         const dashIdx = text.indexOf(" — ");
         if (dashIdx > 0 && dashIdx <= maxLen)
@@ -2561,7 +2675,8 @@ export class HmemStore {
         const seqAtParent = new Map();
         const lastIdAtDepth = new Map();
         const nodes = [];
-        const l1Lines = [];
+        const l1Title = [];
+        const l1Body = [];
         // 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;
@@ -2591,8 +2706,30 @@ export class HmemStore {
                 depth = spaceTabs > 0 ? Math.min(spaceTabs, 4) + 1 : 1;
             }
             const text = trimmedEnd.trim();
+            // Body line detection: "> " prefix marks body text for the preceding node
+            const isBodyLine = text.startsWith("> ") || text === ">";
+            const bodyText = isBodyLine ? text.replace(/^> ?/, "") : "";
             if (depth === 1) {
-                l1Lines.push(text);
+                if (isBodyLine) {
+                    l1Body.push(bodyText);
+                }
+                else {
+                    l1Title.push(text);
+                }
+                continue;
+            }
+            if (isBodyLine) {
+                // Append body to the last node at this depth
+                const lastNode = nodes.length > 0 ? nodes[nodes.length - 1] : null;
+                if (lastNode && lastNode.depth === depth) {
+                    // If content was just the title (no body yet), start fresh body
+                    if (lastNode.content === lastNode.title) {
+                        lastNode.content = bodyText;
+                    }
+                    else {
+                        lastNode.content += "\n" + bodyText;
+                    }
+                }
                 continue;
             }
             // L2+: determine parent and generate compound ID
@@ -2601,18 +2738,30 @@ 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, title: this.autoExtractTitle(text) });
+            const sanitizedTitle = text.replace(/[\t\r\n]/g, " ").replace(/  +/g, " ").trim();
+            nodes.push({ id: nodeId, parent_id: parentId, depth, seq, content: text, title: sanitizedTitle });
         }
-        // Title: first L1 line (explicit). Content: remaining L1 lines joined.
-        // If only 1 L1 line: title is auto-extracted, level1 = full line.
+        // Backward-compatible: nodes without body lines get autoExtractTitle fallback
+        for (const node of nodes) {
+            if (node.content === node.title || node.content.replace(/[\t\r\n]/g, " ").replace(/  +/g, " ").trim() === node.title) {
+                // No body was added — old format: content = full text, title = auto-extracted
+                node.title = this.autoExtractTitle(node.content);
+            }
+            // else: body was added — title stays as explicit title text
+        }
+        // L1: first non-body line = title, body lines = level1
         let title;
         let level1;
-        if (l1Lines.length >= 2) {
-            title = l1Lines[0];
-            level1 = l1Lines.slice(1).join(" | ");
+        if (l1Body.length > 0) {
+            title = (l1Title[0] ?? "").replace(/[\t\r\n]/g, " ").replace(/  +/g, " ").trim();
+            level1 = l1Body.join("\n");
+        }
+        else if (l1Title.length >= 2) {
+            title = l1Title[0].replace(/[\t\r\n]/g, " ").replace(/  +/g, " ").trim();
+            level1 = l1Title.slice(1).join(" | ");
         }
         else {
-            level1 = l1Lines[0] ?? "";
+            level1 = l1Title[0] ?? "";
             title = this.autoExtractTitle(level1);
         }
         return { title, level1, nodes };
@@ -2659,6 +2808,21 @@ export class HmemStore {
             const absDepth = parentDepth + 1 + relDepth;
             if (absDepth > maxAbsDepth)
                 continue; // silently skip beyond max depth
+            // Body line detection: "> " prefix marks body text for the preceding node
+            const isBodyLine = text.startsWith("> ") || text === ">";
+            if (isBodyLine) {
+                const bodyText = text.replace(/^> ?/, "");
+                const lastNode = nodes.length > 0 ? nodes[nodes.length - 1] : null;
+                if (lastNode && lastNode.depth === absDepth) {
+                    if (lastNode.content === lastNode.title) {
+                        lastNode.content = bodyText;
+                    }
+                    else {
+                        lastNode.content += "\n" + bodyText;
+                    }
+                }
+                continue;
+            }
             const myParentId = relDepth === 0
                 ? parentId
                 : (lastIdAtRelDepth.get(relDepth - 1) ?? parentId);
@@ -2666,7 +2830,14 @@ export class HmemStore {
             seqAtParent.set(myParentId, seq);
             const nodeId = `${myParentId}.${seq}`;
             lastIdAtRelDepth.set(relDepth, nodeId);
-            nodes.push({ id: nodeId, parent_id: myParentId, depth: absDepth, seq, content: text });
+            const sanitizedTitle = text.replace(/[\t\r\n]/g, " ").replace(/  +/g, " ").trim();
+            nodes.push({ id: nodeId, parent_id: myParentId, depth: absDepth, seq, content: text, title: sanitizedTitle });
+        }
+        // Backward-compatible: nodes without body lines get autoExtractTitle fallback
+        for (const node of nodes) {
+            if (node.content === node.title || node.content.replace(/[\t\r\n]/g, " ").replace(/  +/g, " ").trim() === node.title) {
+                node.title = this.autoExtractTitle(node.content);
+            }
         }
         return nodes;
     }