hmem-mcp 1.1.0

package/dist/memory-search.js

@@ -0,0 +1,294 @@
+// Semantic Memory Search — Full-text search over .hmem files and optionally project docs.
+//
+// Lightweight: No external dependencies (no ChromaDB/Faiss).
+// Uses keyword matching with TF-based relevance scoring.
+//
+// Searches:
+//   - *.hmem files in PROJECT_DIR and subdirectories (agent memories — SQLite, hierarchical)
+//   - Optional: Personality.md, project docs, skill docs (if directories exist)
+import fs from "node:fs";
+import path from "node:path";
+import { HmemStore } from "./hmem-store.js";
+// ---- .hmem search (memories scope) ----
+/**
+ * Searches a single .hmem SQLite file for the given keywords.
+ * Returns a SearchResult or null if no matches found.
+ */
+function searchHmemFile(hmemPath, agentName, keywords, query, projectDir) {
+    let store = null;
+    try {
+        store = new HmemStore(hmemPath);
+        const entries = store.read({ search: query });
+        if (entries.length === 0)
+            return null;
+        // Score: number of matching entries weighted by keyword matches in L1
+        let score = 0;
+        const excerpts = [];
+        for (const entry of entries.slice(0, 3)) {
+            const text = entry.level_1 || "";
+            const entryScore = scoreText(text, keywords);
+            score += entryScore + 1; // +1 per match regardless of keyword density
+            // Build excerpt: [ID] L1 text + up to 1 child
+            let excerpt = `[${entry.id}] ${entry.level_1}`;
+            if (entry.children && entry.children.length > 0) {
+                const child = entry.children[0];
+                const preview = child.content.length > 120
+                    ? child.content.substring(0, 117) + "..."
+                    : child.content;
+                excerpt += `\n  └ ${preview}`;
+            }
+            excerpts.push(excerpt);
+        }
+        if (score <= 0)
+            return null;
+        return {
+            file: path.relative(projectDir, hmemPath),
+            agent: agentName,
+            scope: "memories",
+            score: Math.round(score * 100) / 100,
+            excerpts,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        store?.close();
+    }
+}
+/**
+ * Collects all .hmem files for the memories scope.
+ * Scans PROJECT_DIR root + common subdirectory patterns (Agents/, Assistenten/, agents/).
+ */
+function collectHmemFiles(projectDir) {
+    const results = [];
+    // Scan common agent directory patterns
+    for (const subdir of ["Agents", "Assistenten", "agents"]) {
+        const dir = path.join(projectDir, subdir);
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const d of entries) {
+                if (!d.isDirectory())
+                    continue;
+                const hmemPath = path.join(dir, d.name, `${d.name}.hmem`);
+                if (fs.existsSync(hmemPath)) {
+                    results.push({ hmemPath, agentName: d.name });
+                }
+            }
+        }
+        catch { /* dir does not exist */ }
+    }
+    // Check for standalone .hmem files in PROJECT_DIR root
+    try {
+        const rootEntries = fs.readdirSync(projectDir, { withFileTypes: true });
+        for (const entry of rootEntries) {
+            if (entry.isFile() && entry.name.endsWith(".hmem")) {
+                const name = entry.name.replace(/\.hmem$/, "");
+                const hmemPath = path.join(projectDir, entry.name);
+                // Avoid duplicates (agent dirs already scanned above)
+                if (!results.some(r => r.hmemPath === hmemPath)) {
+                    results.push({ hmemPath, agentName: name === "memory" ? "default" : name });
+                }
+            }
+        }
+    }
+    catch { /* */ }
+    return results;
+}
+// ---- File-based search (personalities, projects, skills) ----
+/**
+ * Collects searchable .md files based on scope.
+ */
+function collectMdFiles(dir, results, scope, maxDepth, currentDepth = 0) {
+    if (currentDepth > maxDepth)
+        return;
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isFile() && entry.name.endsWith(".md")) {
+                results.push({ file: fullPath, scope });
+            }
+            else if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+                collectMdFiles(fullPath, results, scope, maxDepth, currentDepth + 1);
+            }
+        }
+    }
+    catch { /* Access error */ }
+}
+function collectMdFilesByScope(projectDir, scope) {
+    const results = [];
+    const agentsDir = path.join(projectDir, "Agents");
+    const projectsDir = path.join(projectDir, "Projects");
+    const skillsDir = path.join(projectDir, "skills");
+    if (scope === "personalities" || scope === "all") {
+        try {
+            const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+            for (const d of entries) {
+                if (!d.isDirectory())
+                    continue;
+                const persFile = path.join(agentsDir, d.name, "Personality.md");
+                if (fs.existsSync(persFile)) {
+                    results.push({ file: persFile, scope: "personalities" });
+                }
+            }
+        }
+        catch { /* */ }
+    }
+    if (scope === "projects" || scope === "all") {
+        try {
+            const projects = fs.readdirSync(projectsDir, { withFileTypes: true });
+            for (const p of projects) {
+                if (!p.isDirectory())
+                    continue;
+                collectMdFiles(path.join(projectsDir, p.name), results, "projects", 2);
+            }
+        }
+        catch { /* */ }
+    }
+    if (scope === "skills" || scope === "all") {
+        try {
+            const skills = fs.readdirSync(skillsDir, { withFileTypes: true });
+            for (const s of skills) {
+                if (!s.isDirectory())
+                    continue;
+                collectMdFiles(path.join(skillsDir, s.name), results, "skills", 1);
+            }
+        }
+        catch { /* */ }
+    }
+    return results;
+}
+// ---- Keyword scoring ----
+/**
+ * Tokenizes a search query into keywords.
+ */
+function tokenize(query) {
+    const stopwords = new Set([
+        "der", "die", "das", "ein", "eine", "und", "oder", "in", "von", "zu",
+        "mit", "auf", "fuer", "ist", "sind", "was", "wie", "wo", "wer",
+        "the", "a", "an", "and", "or", "in", "of", "to", "with", "on",
+        "for", "is", "are", "what", "how", "where", "who",
+    ]);
+    return query
+        .toLowerCase()
+        .replace(/[^a-z0-9äöüß_-]/g, " ")
+        .split(/\s+/)
+        .filter(w => w.length > 1 && !stopwords.has(w));
+}
+/**
+ * Scores a text string based on keyword frequency.
+ */
+function scoreText(content, keywords) {
+    const lower = content.toLowerCase();
+    let score = 0;
+    for (const kw of keywords) {
+        let idx = 0;
+        let count = 0;
+        while ((idx = lower.indexOf(kw, idx)) !== -1) {
+            count++;
+            idx += kw.length;
+        }
+        if (count > 0) {
+            score += count * (1 + kw.length / 5);
+        }
+    }
+    return Math.round(score * 100) / 100;
+}
+/**
+ * Extracts text excerpts around keyword matches.
+ */
+function extractExcerpts(content, keywords, contextLines) {
+    const lines = content.split("\n");
+    const matchedLineNums = new Set();
+    for (const kw of keywords) {
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].toLowerCase().includes(kw)) {
+                matchedLineNums.add(i);
+            }
+        }
+    }
+    if (matchedLineNums.size === 0)
+        return [];
+    const sorted = Array.from(matchedLineNums).sort((a, b) => a - b);
+    const excerpts = [];
+    let currentGroup = [];
+    for (const lineNum of sorted) {
+        if (currentGroup.length === 0 || lineNum - currentGroup[currentGroup.length - 1] <= contextLines * 2 + 1) {
+            currentGroup.push(lineNum);
+        }
+        else {
+            excerpts.push(buildExcerpt(lines, currentGroup, contextLines));
+            currentGroup = [lineNum];
+        }
+    }
+    if (currentGroup.length > 0) {
+        excerpts.push(buildExcerpt(lines, currentGroup, contextLines));
+    }
+    return excerpts.slice(0, 3);
+}
+function buildExcerpt(lines, matchedLines, contextLines) {
+    const start = Math.max(0, matchedLines[0] - contextLines);
+    const end = Math.min(lines.length - 1, matchedLines[matchedLines.length - 1] + contextLines);
+    const excerpt = lines.slice(start, end + 1).join("\n").trim();
+    return excerpt.length > 500 ? excerpt.substring(0, 497) + "..." : excerpt;
+}
+// ---- Main export ----
+/**
+ * Searches the knowledge base across agent memories (.hmem), personalities,
+ * project docs, and skills.
+ */
+export function searchMemory(projectDir, query, options = {}) {
+    const { scope = "all", maxResults = 10, contextLines = 2 } = options;
+    const keywords = tokenize(query);
+    if (keywords.length === 0)
+        return [];
+    const results = [];
+    // --- Memories scope: .hmem SQLite ---
+    if (scope === "memories" || scope === "all") {
+        const hmemFiles = collectHmemFiles(projectDir);
+        for (const { hmemPath, agentName } of hmemFiles) {
+            const result = searchHmemFile(hmemPath, agentName, keywords, query, projectDir);
+            if (result)
+                results.push(result);
+        }
+    }
+    // --- File-based scopes: personalities, projects, skills ---
+    if (scope !== "memories") {
+        const mdScope = scope === "all" ? "all" : scope;
+        const mdFiles = collectMdFilesByScope(projectDir, mdScope);
+        for (const { file, scope: fileScope } of mdFiles) {
+            let content;
+            try {
+                const stat = fs.statSync(file);
+                if (stat.size > 500 * 1024)
+                    continue;
+                content = fs.readFileSync(file, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            if (content.trim().length < 50)
+                continue;
+            const score = scoreText(content, keywords);
+            if (score <= 0)
+                continue;
+            const relPath = path.relative(projectDir, file);
+            let agent;
+            const agentMatch = relPath.match(/^Agents\/([^/]+)\//);
+            if (agentMatch)
+                agent = agentMatch[1];
+            const excerpts = extractExcerpts(content, keywords, contextLines);
+            results.push({
+                file: relPath,
+                agent,
+                scope: fileScope,
+                score,
+                excerpts,
+            });
+        }
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, maxResults);
+}
+//# sourceMappingURL=memory-search.js.map

package/dist/memory-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-search.js","sourceRoot":"","sources":["../src/memory-search.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,EAAE;AACF,6DAA6D;AAC7D,yDAAyD;AACzD,EAAE;AACF,YAAY;AACZ,6FAA6F;AAC7F,gFAAgF;AAEhF,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAkB5C,0CAA0C;AAE1C;;;GAGG;AACH,SAAS,cAAc,CACrB,QAAgB,EAChB,SAAiB,EACjB,QAAkB,EAClB,KAAa,EACb,UAAkB;IAElB,IAAI,KAAK,GAAqB,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,SAAS,CAAC,QAAQ,CAAC,CAAC;QAChC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEtC,sEAAsE;QACtE,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,MAAM,QAAQ,GAAa,EAAE,CAAC;QAE9B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;YACjC,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC7C,KAAK,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC,6CAA6C;YAEtE,8CAA8C;YAC9C,IAAI,OAAO,GAAG,IAAI,KAAK,CAAC,EAAE,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;YAC/C,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChD,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;gBAChC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,GAAG;oBACxC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK;oBACzC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;gBAClB,OAAO,IAAI,SAAS,OAAO,EAAE,CAAC;YAChC,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QAED,IAAI,KAAK,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAE5B,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;YACzC,KAAK,EAAE,SAAS;YAChB,KAAK,EAAE,UAAU;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG;YACpC,QAAQ;SACT,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,KAAK,EAAE,KAAK,EAAE,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,UAAkB;IAC1C,MAAM,OAAO,GAA8C,EAAE,CAAC;IAE9D,uCAAuC;IACvC,KAAK,MAAM,MAAM,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,CAAC;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7D,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;gBACxB,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE;oBAAE,SAAS;gBAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC;gBAC1D,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC5B,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBAChD,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,wBAAwB,CAAC,CAAC;IACtC,CAAC;IAED,uDAAuD;IACvD,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,EAAE,CAAC,WAAW,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACxE,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;YAChC,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACnD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;gBAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBACnD,sDAAsD;gBACtD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,EAAE,CAAC;oBAChD,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC9E,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;IAEjB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,gEAAgE;AAEhE;;GAEG;AACH,SAAS,cAAc,CACrB,GAAW,EACX,OAA+C,EAC/C,KAAkB,EAClB,QAAgB,EAChB,YAAY,GAAG,CAAC;IAEhB,IAAI,YAAY,GAAG,QAAQ;QAAE,OAAO;IACpC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1C,CAAC;iBAAM,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;gBAC/F,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,GAAG,CAAC,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,qBAAqB,CAC5B,UAAkB,EAClB,KAAuC;IAEvC,MAAM,OAAO,GAA2C,EAAE,CAAC;IAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAElD,IAAI,KAAK,KAAK,eAAe,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YACnE,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;gBACxB,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE;oBAAE,SAAS;gBAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;gBAChE,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC5B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;gBAC3D,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IAED,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YACtE,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;gBACzB,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE;oBAAE,SAAS;gBAC/B,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IAED,IAAI,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QAC1C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YAClE,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;gBACvB,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE;oBAAE,SAAS;gBAC/B,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;YACrE,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,4BAA4B;AAE5B;;GAEG;AACH,SAAS,QAAQ,CAAC,KAAa;IAC7B,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;QACxB,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI;QACpE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK;QAC9D,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI;QAC7D,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK;KAClD,CAAC,CAAC;IAEH,OAAO,KAAK;SACT,WAAW,EAAE;SACb,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC;SAChC,KAAK,CAAC,KAAK,CAAC;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,OAAe,EAAE,QAAkB;IACpD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,OAAO,CAAC,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAC7C,KAAK,EAAE,CAAC;YACR,GAAG,IAAI,EAAE,CAAC,MAAM,CAAC;QACnB,CAAC;QACD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,SAAS,eAAe,CAAC,OAAe,EAAE,QAAkB,EAAE,YAAoB;IAChF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;IAE1C,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;gBACxC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,eAAe,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE1C,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,YAAY,GAAa,EAAE,CAAC;IAEhC,KAAK,MAAM,OAAO,IAAI,MAAM,EAAE,CAAC;QAC7B,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,GAAG,YAAY,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,YAAY,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACzG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;YAC/D,YAAY,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,YAAY,CAAC,KAAe,EAAE,YAAsB,EAAE,YAAoB;IACjF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,YAAY,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC;IAC7F,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9D,OAAO,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;AAC5E,CAAC;AAED,wBAAwB;AAExB;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,UAAkB,EAClB,KAAa,EACb,UAAyB,EAAE;IAE3B,MAAM,EAAE,KAAK,GAAG,KAAK,EAAE,UAAU,GAAG,EAAE,EAAE,YAAY,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;IACrE,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEjC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAErC,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,uCAAuC;IACvC,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QAC5C,MAAM,SAAS,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;QAC/C,KAAK,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,SAAS,EAAE,CAAC;YAChD,MAAM,MAAM,GAAG,cAAc,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;YAChF,IAAI,MAAM;gBAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;QAChD,MAAM,OAAO,GAAG,qBAAqB,CAAC,UAAU,EAAE,OAA2C,CAAC,CAAC;QAE/F,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,OAAO,EAAE,CAAC;YACjD,IAAI,OAAe,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAC/B,IAAI,IAAI,CAAC,IAAI,GAAG,GAAG,GAAG,IAAI;oBAAE,SAAS;gBACrC,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC3C,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YAED,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,EAAE;gBAAE,SAAS;YAEzC,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAC3C,IAAI,KAAK,IAAI,CAAC;gBAAE,SAAS;YAEzB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YAEhD,IAAI,KAAyB,CAAC;YAC9B,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;YACvD,IAAI,UAAU;gBAAE,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAEtC,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;YAElE,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,OAAO;gBACb,KAAK;gBACL,KAAK,EAAE,SAAS;gBAChB,KAAK;gBACL,QAAQ;aACT,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1C,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AACtC,CAAC"}

package/dist/types.js

@@ -0,0 +1,53 @@
+export const DEFAULT_CONFIG = {
+    projectDir: "",
+    pollMs: 1000,
+    ackTimeoutMs: 30_000,
+    execWarningMs: 600_000,
+    zombieKillMs: 900_000,
+    maxSpawnDepth: 3,
+    maxSpawnsPerAgent: 5,
+    logMaxBytes: 10 * 1024 * 1024,
+    logJsonMode: false,
+    archiveDays: 7,
+    retry: {
+        maxRetries: 2,
+        retryDelayMs: 10_000,
+        backoffMultiplier: 2,
+    },
+    autoSynthesize: false,
+    synthesizeTemplate: "consolidator",
+    logLevel: "info",
+    enableSurveys: false,
+    surveyTemplate: "agent-survey",
+    maxConcurrentAgents: 10,
+    maxConcurrentOpencode: 2,
+    loadThrottleAvg1: 0, // 0 = disabled
+    loadKillAvg1: 12, // Kill agents when avg1 > 12
+    workerModelBlacklist: [],
+    scheduledAgents: [],
+};
+export const MODEL_ALIASES = {
+    // Claude (via claude CLI)
+    "opus": "claude-opus-4-6",
+    "sonnet": "claude-sonnet-4-5-20250929",
+    "haiku": "claude-haiku-4-5-20251001",
+    // Gemini (via gemini CLI)
+    "gemini-pro": "gemini-3-pro-preview",
+    "gemini-flash": "gemini-3-flash-preview",
+    // OpenRouter (via opencode) — Format: openrouter/provider/model
+    "deepseek": "openrouter/deepseek/deepseek-v3.2",
+    "qwen-coder": "openrouter/qwen/qwen3-coder",
+    "devstral": "openrouter/mistralai/devstral-2512",
+    "mistral": "openrouter/mistralai/mistral-medium-3.1",
+    "grok-fast": "openrouter/x-ai/grok-4.1-fast",
+    "glm": "openrouter/z-ai/glm-5",
+    "glm-flash": "openrouter/z-ai/glm-4.7-flash",
+    "gpt-mini": "openrouter/openai/gpt-5.1-codex-mini",
+    // New frontier models (via opencode/openrouter)
+    "minimax": "openrouter/minimax/minimax-m2.5",
+    "kimi": "openrouter/moonshotai/kimi-k2.5",
+    // Free Tier (via opencode/openrouter)
+    "deepseek-free": "openrouter/deepseek/deepseek-r1-0528:free",
+    "devstral-free": "openrouter/mistralai/devstral-small-2505:free",
+    "qwen-free": "openrouter/qwen/qwen3-235b-a22b:free",
+};

package/hmem.config.example.json

@@ -0,0 +1,13 @@
+{
+  "_comment": "Copy this file to your project root as hmem.config.json and adjust to taste.",
+
+  "maxL1Chars": 500,
+  "maxLnChars": 50000,
+
+  "_comment_limits": "Instead of maxL1Chars/maxLnChars you can set all levels explicitly:",
+  "_example_explicit": { "maxCharsPerLevel": [500, 5000, 15000, 30000, 50000] },
+
+  "maxDepth": 5,
+  "recentChildrenCount": 10,
+  "defaultReadLimit": 100
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "hmem-mcp",
+  "version": "1.1.0",
+  "description": "Humanlike memory for AI agents — MCP server with 5-level lazy-loaded SQLite memory",
+  "author": "Bumblebiber",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bumblebiber/hmem.git"
+  },
+  "homepage": "https://github.com/Bumblebiber/hmem#readme",
+  "bugs": {
+    "url": "https://github.com/Bumblebiber/hmem/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "hmem": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "hmem.config.example.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/mcp-server.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "memory",
+    "agents",
+    "llm",
+    "sqlite",
+    "humanlike",
+    "hierarchical",
+    "long-term-memory",
+    "claude",
+    "gemini",
+    "persistent-memory"
+  ],
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.2.3",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "zod": "^4.3.6"
+  }
+}

package/skills/hmem-read/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: hmem-read
+description: Load your long-term memory. Call this skill at session start or after context reset.
+---
+
+# ACTION REQUIRED: Call read_memory() NOW
+
+When this skill is invoked, you MUST immediately call the MCP tool `read_memory` with no arguments.
+Do NOT just read this document — execute the tool call.
+
+```
+read_memory()
+```
+
+This returns your Level 1 memory summaries. Show them to the user.
+
+If the tool `read_memory` is not available, tell the user:
+"read_memory tool not found. Run `hmem init` to configure the MCP server."
+
+---
+
+## Lazy Loading Protocol (for subsequent reads)
+
+After the initial `read_memory()`, use these patterns to drill deeper:
+
+```
+# Filter by category
+read_memory(prefix="E")          # only errors
+read_memory(store="company")     # shared company knowledge
+
+# Expand a root entry → shows L2 children
+read_memory(id="E0042")
+
+# Expand an L2 node → shows L3 children
+read_memory(id="E0042.2")
+
+# Expand further (rarely needed)
+read_memory(id="E0042.2.1")
+```
+
+**Rule: depth parameter is only useful for listings (max 3), not for ID queries.**
+
+```
+read_memory(depth=2)             # all entries with L2 children
+read_memory(prefix="L", depth=2) # all lessons with details
+```
+
+---
+
+## Search
+
+```
+search_memory(query="Node.js startup crash")
+search_memory(query="auth token", scope="memories")
+```
+
+---
+
+## Anti-Patterns
+
+| Wrong | Right |
+|-------|-------|
+| `read_memory(id="E0042", depth=3)` | `read_memory(id="E0042.2")` — branch by branch |
+| Load everything without purpose | Check L1 first, then expand selectively |
+| Read .hmem file directly | Always use MCP tools — it's a SQLite binary |
+| Just display this skill text | **Call read_memory() immediately** |