hmem-mcp 2.5.4 → 2.7.0

package/dist/hmem-store.d.ts

@@ -48,6 +48,8 @@ export interface MemoryEntry {
     favorite?: boolean;
     /** True if the agent marked this entry as irrelevant. Hidden from bulk reads, no correction needed. */
     irrelevant?: boolean;
+    /** True if this entry is actively relevant (root-only). When any entry in a prefix has active=1, only active entries of that prefix are expanded in bulk reads. */
+    active?: boolean;
     /** True if this entry was already delivered in a previous bulk read (session cache). */
     suppressed?: boolean;
     /**
@@ -153,6 +155,10 @@ export interface ReadOptions {
     tag?: string;
     /** Show entries not accessed in the last N days (stale detection). Sorted oldest-access first. */
     staleDays?: number;
+    /** Find all entries related to a given entry via per-node tag scoring + direct links. */
+    contextFor?: string;
+    /** Minimum weighted tag score for context_for matches. Default: 4. Tier weights: rare(<=5)=3, medium(6-20)=2, common(>20)=1. */
+    minTagScore?: number;
 }
 export interface WriteResult {
     id: string;
@@ -245,7 +251,7 @@ export declare class HmemStore {
     /**
      * Update specific fields of an existing root entry (curator use only).
      */
-    update(id: string, fields: Partial<Pick<MemoryEntry, "level_1" | "level_2" | "level_3" | "level_4" | "level_5" | "links" | "min_role" | "obsolete" | "favorite" | "irrelevant">>): boolean;
+    update(id: string, fields: Partial<Pick<MemoryEntry, "level_1" | "level_2" | "level_3" | "level_4" | "level_5" | "links" | "min_role" | "obsolete" | "favorite" | "irrelevant" | "active">>): boolean;
     /**
      * Delete an entry by ID (curator use only).
      * Also deletes all associated memory_nodes.
@@ -257,7 +263,7 @@ export declare class HmemStore {
      * For sub-nodes: updates node content only.
      * Does NOT modify children — use appendChildren to extend the tree.
      */
-    updateNode(id: string, newContent: string, links?: string[], obsolete?: boolean, favorite?: boolean, curatorBypass?: boolean, irrelevant?: boolean, tags?: string[], pinned?: boolean): boolean;
+    updateNode(id: string, newContent: string, links?: string[], obsolete?: boolean, favorite?: boolean, curatorBypass?: boolean, irrelevant?: boolean, tags?: string[], pinned?: boolean, active?: boolean): boolean;
     /**
      * Append new child nodes under an existing entry (root or node).
      * Content is tab-indented relative to the parent:
@@ -301,7 +307,7 @@ export declare class HmemStore {
         tags: string[];
     }[];
     /** Bulk-assign tags to entries + their children from a single fetchTagsBulk call. */
-    private assignBulkTags;
+    assignBulkTags(entries: MemoryEntry[]): void;
     /** Recursively collect all node IDs from a tree of MemoryNodes. */
     private collectNodeIds;
     /** Get root IDs that have a specific tag (for bulk-read filtering). */
@@ -462,6 +468,24 @@ export declare class HmemStore {
         created_at: string;
         tags: string[];
     }[];
+    /**
+     * Find all entries contextually related to a given entry.
+     * Uses per-node weighted tag scoring: for each node of the source entry,
+     * compute weighted overlap with each candidate entry's full tag set.
+     * Tier weights: rare (<=5 entries) = 3, medium (6-20) = 2, common (>20) = 1.
+     * A candidate matches if ANY source node scores >= minTagScore against it.
+     * Bidirectional direct links are always included.
+     */
+    findContext(entryId: string, minTagScore?: number, limit?: number): {
+        linked: MemoryEntry[];
+        tagRelated: {
+            entry: MemoryEntry;
+            score: number;
+            matchNode: string;
+        }[];
+    };
+    /** Resolve bidirectional direct links for an entry, filtering obsolete/irrelevant. */
+    private resolveDirectLinks;
     /** Audit report: broken links, orphaned entries, stale favorites, broken obsolete chains, tag orphans. */
     healthCheck(): {
         brokenLinks: {

package/dist/hmem-store.js

@@ -157,6 +157,8 @@ const MIGRATIONS = [
     // Sync support: track last content modification (separate from last_accessed)
     "ALTER TABLE memories ADD COLUMN updated_at TEXT",
     "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",
 ];
 // ---- HmemStore class ----
 export class HmemStore {
@@ -258,8 +260,11 @@ export class HmemStore {
       INSERT INTO memory_nodes (id, parent_id, root_id, depth, seq, title, content, created_at, updated_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
-        // Validate tags before transaction
-        const validatedTags = tags && tags.length > 0 ? this.validateTags(tags) : [];
+        // Tags are mandatory — at least 1 required for discoverability
+        if (!tags || tags.length === 0) {
+            throw new Error("Tags are required. Provide at least 1 tag (3+ recommended) for discoverability. Example: tags=['#hmem', '#sqlite', '#bug']");
+        }
+        const validatedTags = this.validateTags(tags);
         // Run in a transaction
         this.db.transaction(() => {
             insertRoot.run(rootId, prefix, seq, timestamp, timestamp, title, level1, links ? JSON.stringify(links) : null, minRole, favorite ? 1 : 0, pinned ? 1 : 0);
@@ -558,6 +563,75 @@ export class HmemStore {
         // 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 0.5: Detect active-prefixes — prefixes where at least one entry has active=1.
+        // Non-active entries in these prefixes are still shown (as compact titles) but don't get expansion slots.
+        const activePrefixes = new Set();
+        for (const r of activeRows) {
+            if (r.active === 1)
+                activePrefixes.add(r.prefix);
+        }
+        // Step 0.6: Cascading related-suppression — entries in OTHER prefixes that are thematically
+        // related ONLY to suppressed (non-active) entries get demoted to title-only too.
+        // Logic: collect tags from non-active entries, subtract tags from active entries,
+        // then find entries in other prefixes that share ONLY the remaining "suppressed" tags.
+        const relatedSuppressed = new Set();
+        if (activePrefixes.size > 0) {
+            const activeEntryIds = [];
+            const nonActiveEntryIds = [];
+            for (const r of activeRows) {
+                if (activePrefixes.has(r.prefix)) {
+                    if (r.active === 1)
+                        activeEntryIds.push(r.id);
+                    else
+                        nonActiveEntryIds.push(r.id);
+                }
+            }
+            if (nonActiveEntryIds.length > 0 && activeEntryIds.length > 0) {
+                // Fetch tags for active and non-active entries (root-level tags + child tags)
+                const activeTagRows = activeEntryIds.length > 0
+                    ? this.db.prepare(`SELECT DISTINCT tag FROM memory_tags WHERE ${activeEntryIds.map(() => "entry_id = ? OR entry_id LIKE ?").join(" OR ")}`).all(...activeEntryIds.flatMap(id => [id, `${id}.%`]))
+                    : [];
+                const activeTags = new Set(activeTagRows.map(r => r.tag));
+                const nonActiveTagRows = this.db.prepare(`SELECT DISTINCT tag FROM memory_tags WHERE ${nonActiveEntryIds.map(() => "entry_id = ? OR entry_id LIKE ?").join(" OR ")}`).all(...nonActiveEntryIds.flatMap(id => [id, `${id}.%`]));
+                // Suppressed tags = tags that appear in non-active entries but NOT in active entries
+                const suppressedTags = nonActiveTagRows.map(r => r.tag).filter(t => !activeTags.has(t));
+                if (suppressedTags.length > 0) {
+                    // Find root entries in OTHER prefixes that have ONLY suppressed tags (no active tags)
+                    const prefixList = [...activePrefixes];
+                    const otherEntries = activeRows.filter(r => !activePrefixes.has(r.prefix) && r.obsolete !== 1);
+                    if (otherEntries.length > 0) {
+                        const otherIds = otherEntries.map(r => r.id);
+                        const otherTagMap = this.fetchTagsBulk(otherIds);
+                        // Also fetch child tags for better coverage
+                        const otherChildIds = otherIds.flatMap(id => {
+                            const children = this.db.prepare("SELECT id FROM memory_nodes WHERE root_id = ?").all(id);
+                            return children.map(c => c.id);
+                        });
+                        const childTagMap = otherChildIds.length > 0 ? this.fetchTagsBulk(otherChildIds) : new Map();
+                        // Merge child tags into parent
+                        for (const e of otherEntries) {
+                            const rootTags = otherTagMap.get(e.id) ?? [];
+                            const childNodes = this.db.prepare("SELECT id FROM memory_nodes WHERE root_id = ?").all(e.id);
+                            const allTags = new Set(rootTags);
+                            for (const cn of childNodes) {
+                                const ct = childTagMap.get(cn.id);
+                                if (ct)
+                                    ct.forEach(t => allTags.add(t));
+                            }
+                            if (allTags.size === 0)
+                                continue;
+                            // Check: does this entry have ANY active tags?
+                            const hasActiveTags = [...allTags].some(t => activeTags.has(t));
+                            const hasSuppressedTags = [...allTags].some(t => suppressedTags.includes(t));
+                            // Only suppress if entry shares suppressed tags but NO active tags
+                            if (hasSuppressedTags && !hasActiveTags) {
+                                relatedSuppressed.add(e.id);
+                            }
+                        }
+                    }
+                }
+            }
+        }
         // Step 1: Separate obsolete from non-obsolete FIRST
         const obsoleteRows = activeRows.filter(r => r.obsolete === 1);
         const nonObsoleteRows = activeRows.filter(r => r.obsolete !== 1);
@@ -614,10 +688,15 @@ export class HmemStore {
         const expandedIds = new Set();
         const isEssentials = opts.mode === "essentials";
         // Per prefix: top N newest + top M most-accessed — slot counts scale with prefix size
-        for (const [, prefixRows] of byPrefix) {
-            const { newestCount, accessCount } = this.calcV2Slots(prefixRows.length, isEssentials, fraction);
+        for (const [prefix, prefixRows] of byPrefix) {
+            // In active-prefixes, only active entries compete for expansion slots.
+            // Related-suppressed entries in OTHER prefixes also don't compete.
+            const candidateRows = activePrefixes.has(prefix)
+                ? prefixRows.filter(r => r.active === 1)
+                : prefixRows.filter(r => !relatedSuppressed.has(r.id));
+            const { newestCount, accessCount } = this.calcV2Slots(candidateRows.length, isEssentials, fraction);
             // Newest: skip cached AND hidden entries, fill from fresh entries only
-            const uncachedRows = prefixRows.filter(r => !cached.has(r.id) && !hidden.has(r.id));
+            const uncachedRows = candidateRows.filter(r => !cached.has(r.id) && !hidden.has(r.id));
             for (const r of uncachedRows.slice(0, newestCount)) {
                 expandedIds.add(r.id);
             }
@@ -630,9 +709,18 @@ export class HmemStore {
             for (const r of mostAccessed)
                 expandedIds.add(r.id);
         }
-        // Global: all uncached+unhidden favorites
+        // Global: uncached+unhidden favorites/pinned + all active entries
         for (const r of nonObsoleteRows) {
             if ((r.favorite === 1 || r.pinned === 1) && !cached.has(r.id) && !hidden.has(r.id)) {
+                // In active-prefixes, only active entries get expansion even if favorite/pinned
+                if (!activePrefixes.has(r.prefix) || r.active === 1) {
+                    // Related-suppressed entries don't get expansion even if favorite/pinned
+                    if (!relatedSuppressed.has(r.id)) {
+                        expandedIds.add(r.id);
+                    }
+                }
+            }
+            if (r.active === 1) {
                 expandedIds.add(r.id);
             }
         }
@@ -643,6 +731,13 @@ export class HmemStore {
             const nodeCounts = this.db.prepare("SELECT root_id, COUNT(*) as cnt FROM memory_nodes GROUP BY root_id ORDER BY cnt DESC LIMIT ?").all(topSubnodeCount);
             for (const row of nodeCounts) {
                 if (!hidden.has(row.root_id)) {
+                    // In active-prefixes, don't expand non-active entries even if they have many sub-nodes
+                    const entryRow = nonObsoleteRows.find(r => r.id === row.root_id);
+                    if (entryRow && activePrefixes.has(entryRow.prefix) && entryRow.active !== 1)
+                        continue;
+                    // Related-suppressed entries don't get topSubnode expansion either
+                    if (relatedSuppressed.has(row.root_id))
+                        continue;
                     expandedIds.add(row.root_id);
                     topSubnodeIds.add(row.root_id);
                 }
@@ -659,9 +754,17 @@ export class HmemStore {
         // Step 4: Build visible rows (hidden entries completely excluded)
         // - Expanded entries: full content with children
         // - Cached entries: title-only (no expansion, no children)
+        // - Non-active in active-prefixes: title-only
+        // - Related-suppressed in other prefixes: title-only
         const expandedNonObsolete = nonObsoleteRows.filter(r => expandedIds.has(r.id));
         const cachedVisible = nonObsoleteRows.filter(r => cached.has(r.id) && !expandedIds.has(r.id) && !hidden.has(r.id));
-        const visibleRows = [...expandedNonObsolete, ...cachedVisible, ...visibleObsolete];
+        const nonActiveVisible = activePrefixes.size > 0
+            ? nonObsoleteRows.filter(r => activePrefixes.has(r.prefix) && r.active !== 1 && !expandedIds.has(r.id) && !cached.has(r.id) && !hidden.has(r.id))
+            : [];
+        const relatedSuppressedVisible = relatedSuppressed.size > 0
+            ? nonObsoleteRows.filter(r => relatedSuppressed.has(r.id) && !expandedIds.has(r.id) && !cached.has(r.id) && !hidden.has(r.id))
+            : [];
+        const visibleRows = [...expandedNonObsolete, ...cachedVisible, ...nonActiveVisible, ...relatedSuppressedVisible, ...visibleObsolete];
         const visibleIds = new Set(visibleRows.map(r => r.id));
         // titles_only: V2 selection applies, but skip link resolution
         if (opts.titlesOnly) {
@@ -1187,7 +1290,7 @@ export class HmemStore {
             if (key === "links" && Array.isArray(val)) {
                 params.push(JSON.stringify(val));
             }
-            else if (key === "obsolete" || key === "favorite" || key === "irrelevant") {
+            else if (key === "obsolete" || key === "favorite" || key === "irrelevant" || key === "active") {
                 params.push(val ? 1 : 0);
             }
             else {
@@ -1221,7 +1324,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, irrelevant, tags, pinned) {
+    updateNode(id, newContent, links, obsolete, favorite, curatorBypass, irrelevant, tags, pinned, active) {
         this.guardCorrupted();
         const trimmed = newContent.trim();
         if (id.includes(".")) {
@@ -1338,6 +1441,10 @@ export class HmemStore {
                 sets.push("pinned = ?");
                 params.push(pinned ? 1 : 0);
             }
+            if (active !== undefined) {
+                sets.push("active = ?");
+                params.push(active ? 1 : 0);
+            }
             if (sets.length === 0) {
                 // Only tags to update — no SQL UPDATE needed
                 if (tags !== undefined) {
@@ -1987,6 +2094,7 @@ export class HmemStore {
             obsolete: row.obsolete === 1,
             favorite: row.favorite === 1,
             irrelevant: row.irrelevant === 1,
+            active: row.active === 1,
             pinned: row.pinned === 1,
             children,
         };
@@ -2308,6 +2416,146 @@ export class HmemStore {
             return [];
         }
     }
+    /**
+     * Find all entries contextually related to a given entry.
+     * Uses per-node weighted tag scoring: for each node of the source entry,
+     * compute weighted overlap with each candidate entry's full tag set.
+     * Tier weights: rare (<=5 entries) = 3, medium (6-20) = 2, common (>20) = 1.
+     * A candidate matches if ANY source node scores >= minTagScore against it.
+     * Bidirectional direct links are always included.
+     */
+    findContext(entryId, minTagScore = 4, limit = 30) {
+        this.guardCorrupted();
+        // 1. Source node IDs
+        const childRows = this.db.prepare("SELECT id FROM memory_nodes WHERE root_id = ?").all(entryId);
+        const nodeIds = [entryId, ...childRows.map(r => r.id)];
+        // 2. Tags per source node
+        const nodeTagMap = this.fetchTagsBulk(nodeIds);
+        // 3. All unique source tags
+        const allSourceTags = new Set();
+        for (const tags of nodeTagMap.values()) {
+            if (tags)
+                tags.forEach(t => allSourceTags.add(t));
+        }
+        if (allSourceTags.size === 0) {
+            return { linked: this.resolveDirectLinks(entryId), tagRelated: [] };
+        }
+        // 4. Global tag frequencies (count distinct root entries per tag)
+        const freqRows = this.db.prepare(`
+      SELECT tag, COUNT(DISTINCT
+        CASE WHEN entry_id LIKE '%.%'
+        THEN SUBSTR(entry_id, 1, INSTR(entry_id, '.') - 1)
+        ELSE entry_id END
+      ) as freq
+      FROM memory_tags GROUP BY tag
+    `).all();
+        const tagFreq = new Map();
+        for (const r of freqRows)
+            tagFreq.set(r.tag, r.freq);
+        // 5. Find candidate entries sharing any source tag
+        const srcTagArr = [...allSourceTags];
+        const placeholders = srcTagArr.map(() => "?").join(", ");
+        const candidateRows = this.db.prepare(`
+      SELECT
+        CASE WHEN entry_id LIKE '%.%'
+        THEN SUBSTR(entry_id, 1, INSTR(entry_id, '.') - 1)
+        ELSE entry_id END as root_id,
+        tag
+      FROM memory_tags
+      WHERE tag IN (${placeholders})
+    `).all(...srcTagArr);
+        // 6. Group candidate tags by root_id (skip self)
+        const candidateTagMap = new Map();
+        for (const r of candidateRows) {
+            if (r.root_id === entryId)
+                continue;
+            let set = candidateTagMap.get(r.root_id);
+            if (!set) {
+                set = new Set();
+                candidateTagMap.set(r.root_id, set);
+            }
+            set.add(r.tag);
+        }
+        // 7. Score each candidate per source node
+        const scored = [];
+        for (const [candidateId, candidateTags] of candidateTagMap) {
+            let bestScore = 0;
+            let bestNode = "";
+            for (const [nodeId, nodeTags] of nodeTagMap) {
+                if (!nodeTags)
+                    continue;
+                let score = 0;
+                for (const tag of nodeTags) {
+                    if (candidateTags.has(tag)) {
+                        const freq = tagFreq.get(tag) ?? 999;
+                        if (freq <= 5)
+                            score += 3;
+                        else if (freq <= 20)
+                            score += 2;
+                        else
+                            score += 1;
+                    }
+                }
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestNode = nodeId;
+                }
+            }
+            if (bestScore >= minTagScore) {
+                scored.push({ id: candidateId, score: bestScore, matchNode: bestNode });
+            }
+        }
+        // Sort by score DESC
+        scored.sort((a, b) => b.score - a.score);
+        const topScored = scored.slice(0, limit);
+        // 8. Fetch full entries, filter obsolete + irrelevant
+        const tagRelated = [];
+        for (const s of topScored) {
+            const row = this.db.prepare("SELECT * FROM memories WHERE id = ? AND obsolete != 1 AND irrelevant != 1").get(s.id);
+            if (!row)
+                continue;
+            const children = this.fetchChildren(row.id);
+            const entry = this.rowToEntry(row, children);
+            entry.tags = this.fetchTags(row.id);
+            tagRelated.push({ entry, score: s.score, matchNode: s.matchNode });
+        }
+        // 9. Direct links (bidirectional)
+        const linked = this.resolveDirectLinks(entryId);
+        return { linked, tagRelated };
+    }
+    /** Resolve bidirectional direct links for an entry, filtering obsolete/irrelevant. */
+    resolveDirectLinks(entryId) {
+        const linkIds = new Set();
+        // Forward links
+        const row = this.db.prepare("SELECT links FROM memories WHERE id = ?").get(entryId);
+        if (row?.links) {
+            try {
+                JSON.parse(row.links).forEach((id) => linkIds.add(id));
+            }
+            catch { }
+        }
+        // Reverse links: entries whose links field contains this ID
+        const reverseRows = this.db.prepare("SELECT id, links FROM memories WHERE links LIKE ? AND id != ?").all(`%${entryId}%`, entryId);
+        for (const r of reverseRows) {
+            try {
+                if (JSON.parse(r.links).includes(entryId))
+                    linkIds.add(r.id);
+            }
+            catch { }
+        }
+        // Fetch entries
+        const results = [];
+        for (const lid of linkIds) {
+            const lr = this.db.prepare("SELECT * FROM memories WHERE id = ? AND obsolete != 1 AND irrelevant != 1").get(lid);
+            if (!lr)
+                continue;
+            const children = this.fetchChildren(lr.id);
+            const entry = this.rowToEntry(lr, children);
+            entry.tags = this.fetchTags(lr.id);
+            results.push(entry);
+        }
+        return results;
+    }
     /** Audit report: broken links, orphaned entries, stale favorites, broken obsolete chains, tag orphans. */
     healthCheck() {
         const result = {