@gamaze/hicortex 0.6.0 → 0.7.0

package/README.md

@@ -45,12 +45,14 @@ openclaw gateway restart
 
 ## Agent Tools (MCP)
 
-6 tools available via MCP:
+8 tools available via MCP:
 
 - **hicortex_search** — Semantic search across all stored memories
 - **hicortex_context** — Get recent decisions and project state
 - **hicortex_ingest** — Store a memory directly
 - **hicortex_lessons** — Get actionable lessons from reflection
+- **hicortex_index** — Get the knowledge domain index (what topics are stored)
+- **hicortex_graph** — Graph traversal: neighbors, hubs, shortest paths
 - **hicortex_update** — Fix incorrect memories (re-embeds on content change)
 - **hicortex_delete** — Remove memories with cascade cleanup
 
@@ -104,6 +106,9 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `reflectBaseUrl` | Separate Ollama instance for reflection |
 | `authToken` | Bearer token for endpoint auth |
 | `licenseKey` | License key for higher tiers |
+| `lessonTarget` | Injection target file (default: `~/.claude/CLAUDE.md`) |
+| `moduleIndexTokenBudget` | Max tokens for domain index in injection (default: 500) |
+| `telemetry` | Anonymous usage telemetry, `false` to opt out |
 
 Full docs: [hicortex.gamaze.com/docs/configuration.html](https://hicortex.gamaze.com/docs/configuration.html)
 

package/dist/consolidate.js

@@ -48,6 +48,7 @@ const storage = __importStar(require("./storage.js"));
 const prompts_js_1 = require("./prompts.js");
 const node_crypto_1 = require("node:crypto");
 const features_js_1 = require("./features.js");
+const graph_js_1 = require("./graph.js");
 const state_js_1 = require("./state.js");
 // Default config constants (matching Python config.py)
 const CONSOLIDATE_MAX_LLM_CALLS = 200;
@@ -352,14 +353,49 @@ async function stageDomainCuration(db, llm, budget, dryRun, stateDir) {
     const totalLessons = lessonRows.reduce((s, r) => s + r.cnt, 0);
     let domains;
     if (!(0, features_js_1.isPro)()) {
-        // OSS fallback: each project is its own domain
-        domains = projectRows.map((r) => ({
-            name: r.project,
-            projects: [r.project],
-            memoryCount: r.cnt,
-            lessonCount: lessonsByProject.get(r.project) ?? 0,
-            keywords: [],
-        }));
+        // OSS: Louvain community detection on the memory_links graph (zero LLM cost)
+        const graph = (0, graph_js_1.louvainCommunities)(db);
+        if (graph.communities.length > 1 && graph.edgeCount >= 5) {
+            // Map communities to domains by finding the dominant project in each
+            // Pre-load all memory→project mappings in one query (avoids N+1)
+            const allProjectRows = db
+                .prepare("SELECT id, project FROM memories WHERE project IS NOT NULL")
+                .all();
+            const memProject = new Map(allProjectRows.map((r) => [r.id, r.project]));
+            domains = [];
+            for (const comm of graph.communities) {
+                const projectCounts = new Map();
+                for (const memId of comm.members) {
+                    const proj = memProject.get(memId);
+                    if (proj) {
+                        projectCounts.set(proj, (projectCounts.get(proj) ?? 0) + 1);
+                    }
+                }
+                const projects = [...projectCounts.keys()];
+                if (projects.length === 0)
+                    continue;
+                // Name domain after the dominant project or combine top 2
+                const sorted = [...projectCounts.entries()].sort((a, b) => b[1] - a[1]);
+                const name = sorted.length >= 2 && sorted[1][1] > sorted[0][1] * 0.3
+                    ? `${sorted[0][0]} + ${sorted[1][0]}`
+                    : sorted[0][0];
+                const memoryCount = projects.reduce((s, p) => s + (projectRows.find((r) => r.project === p)?.cnt ?? 0), 0);
+                const lessonCount = projects.reduce((s, p) => s + (lessonsByProject.get(p) ?? 0), 0);
+                domains.push({ name, projects, memoryCount, lessonCount, keywords: [] });
+            }
+            domains.sort((a, b) => b.memoryCount - a.memoryCount);
+            console.log(`[hicortex] Louvain clustering: ${graph.communities.length} communities, modularity ${graph.modularity.toFixed(3)}`);
+        }
+        else {
+            // Not enough edges for meaningful clustering — fall back to project=domain
+            domains = projectRows.map((r) => ({
+                name: r.project,
+                projects: [r.project],
+                memoryCount: r.cnt,
+                lessonCount: lessonsByProject.get(r.project) ?? 0,
+                keywords: [],
+            }));
+        }
     }
     else {
         // Pro: LLM-curated domains
@@ -510,6 +546,35 @@ function classifyRelationship(source, target, similarity) {
     return "relates_to";
 }
 // ---------------------------------------------------------------------------
+// Stage 3.5: Hub Detection & Strength Boost
+// ---------------------------------------------------------------------------
+const HUB_BOOST = 0.1;
+const HUB_STRENGTH_CAP = 1.0;
+function stageHubBoost(db, dryRun) {
+    const hubs = (0, graph_js_1.detectHubs)(db);
+    if (hubs.length === 0)
+        return { hubs_found: 0, boosted: 0 };
+    let boosted = 0;
+    if (!dryRun) {
+        const stmt = db.prepare("UPDATE memories SET base_strength = MIN(?, base_strength + ?) WHERE id = ? AND base_strength < ?");
+        const tx = db.transaction(() => {
+            for (const hub of hubs) {
+                const result = stmt.run(HUB_STRENGTH_CAP, HUB_BOOST, hub.id, HUB_STRENGTH_CAP);
+                if (result.changes > 0)
+                    boosted++;
+            }
+        });
+        tx();
+    }
+    else {
+        boosted = hubs.length;
+    }
+    if (hubs.length > 0) {
+        console.log(`[hicortex] Hub detection: ${hubs.length} hubs found, ${boosted} boosted (+${HUB_BOOST})`);
+    }
+    return { hubs_found: hubs.length, boosted };
+}
+// ---------------------------------------------------------------------------
 // Stage 4: Decay & Prune
 // ---------------------------------------------------------------------------
 function stageDecayPrune(db, dryRun) {
@@ -597,6 +662,8 @@ async function runConsolidation(db, llm, embedFn, dryRun = false, skipReflection
         report.stages.domain_curation = await stageDomainCuration(db, llm, budget, dryRun, stateDir);
         // Stage 3: Link Discovery
         report.stages.links = await stageLinks(db, precheck.newMemories, embedFn, dryRun);
+        // Stage 3.5: Hub Detection — boost highly-connected memories
+        report.stages.hub_boost = stageHubBoost(db, dryRun);
         // Stage 4: Decay & Prune
         report.stages.decay_prune = stageDecayPrune(db, dryRun);
     }

package/dist/graph.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Graph analysis for the memory link network.
+ *
+ * Pure-JS Louvain community detection + hub node identification.
+ * Operates on the memory_links table without external dependencies.
+ *
+ * Louvain algorithm: iteratively merges nodes into communities to maximize
+ * modularity. Produces quality comparable to Leiden for the graph sizes
+ * we deal with (hundreds to low thousands of nodes).
+ */
+import type Database from "better-sqlite3";
+export interface GraphCommunity {
+    id: number;
+    members: string[];
+    size: number;
+}
+export interface HubNode {
+    id: string;
+    linkCount: number;
+    project: string | null;
+    domain: string | null;
+    content: string;
+}
+export interface GraphAnalysis {
+    communities: GraphCommunity[];
+    hubs: HubNode[];
+    nodeCount: number;
+    edgeCount: number;
+    modularity: number;
+}
+/**
+ * Run Louvain community detection. Returns community assignments.
+ */
+export declare function louvainCommunities(db: Database.Database): {
+    communities: GraphCommunity[];
+    modularity: number;
+    nodeCount: number;
+    edgeCount: number;
+};
+/**
+ * Find hub nodes — memories with link count significantly above median.
+ * Returns nodes with links > threshold (default: 2x median, minimum 3 links).
+ */
+export declare function detectHubs(db: Database.Database, thresholdMultiplier?: number, minLinks?: number): HubNode[];
+export interface GraphNeighbor {
+    id: string;
+    relationship: string;
+    strength: number;
+    direction: "outgoing" | "incoming";
+    content: string;
+    project: string | null;
+}
+export declare function getNeighbors(db: Database.Database, memoryId: string, limit?: number): GraphNeighbor[];
+export declare function shortestPath(db: Database.Database, fromId: string, toId: string, maxDepth?: number): string[] | null;

package/dist/graph.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * Graph analysis for the memory link network.
+ *
+ * Pure-JS Louvain community detection + hub node identification.
+ * Operates on the memory_links table without external dependencies.
+ *
+ * Louvain algorithm: iteratively merges nodes into communities to maximize
+ * modularity. Produces quality comparable to Leiden for the graph sizes
+ * we deal with (hundreds to low thousands of nodes).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.louvainCommunities = louvainCommunities;
+exports.detectHubs = detectHubs;
+exports.getNeighbors = getNeighbors;
+exports.shortestPath = shortestPath;
+function loadGraph(db) {
+    const rows = db
+        .prepare("SELECT source_id, target_id, strength FROM memory_links")
+        .all();
+    const adj = new Map();
+    const nodes = new Set();
+    for (const { source_id, target_id, strength } of rows) {
+        nodes.add(source_id);
+        nodes.add(target_id);
+        const w = strength || 0.5;
+        if (!adj.has(source_id))
+            adj.set(source_id, []);
+        adj.get(source_id).push({ neighbor: target_id, weight: w });
+        if (!adj.has(target_id))
+            adj.set(target_id, []);
+        adj.get(target_id).push({ neighbor: source_id, weight: w });
+    }
+    return { adj, nodes, edgeCount: rows.length };
+}
+// ---------------------------------------------------------------------------
+// Louvain community detection
+// ---------------------------------------------------------------------------
+/**
+ * Compute modularity of the current partition.
+ * Q = (1/2m) * sum_ij [ A_ij - k_i*k_j/(2m) ] * delta(c_i, c_j)
+ */
+function computeModularity(adj, community, totalWeight) {
+    if (totalWeight === 0)
+        return 0;
+    const m2 = 2 * totalWeight;
+    let q = 0;
+    for (const [node, neighbors] of adj) {
+        const ki = neighbors.reduce((s, e) => s + e.weight, 0);
+        const ci = community.get(node);
+        for (const { neighbor, weight } of neighbors) {
+            const kj = adj.get(neighbor)?.reduce((s, e) => s + e.weight, 0) ?? 0;
+            const cj = community.get(neighbor);
+            if (ci === cj) {
+                q += weight - (ki * kj) / m2;
+            }
+        }
+    }
+    return q / m2;
+}
+/**
+ * Run Louvain community detection. Returns community assignments.
+ */
+function louvainCommunities(db) {
+    const { adj, nodes, edgeCount } = loadGraph(db);
+    if (nodes.size === 0) {
+        return { communities: [], modularity: 0, nodeCount: 0, edgeCount: 0 };
+    }
+    const totalWeight = [...adj.values()]
+        .reduce((s, edges) => s + edges.reduce((s2, e) => s2 + e.weight, 0), 0) / 2;
+    // Initialize: each node in its own community
+    const community = new Map();
+    let nextId = 0;
+    for (const node of nodes) {
+        community.set(node, nextId++);
+    }
+    // Phase 1: local moves — repeatedly move nodes to neighbor community with best modularity gain
+    let improved = true;
+    let iterations = 0;
+    const MAX_ITERATIONS = 50;
+    while (improved && iterations < MAX_ITERATIONS) {
+        improved = false;
+        iterations++;
+        for (const node of nodes) {
+            const currentComm = community.get(node);
+            const neighbors = adj.get(node) ?? [];
+            // Compute weight to each neighbor community
+            const commWeights = new Map();
+            for (const { neighbor, weight } of neighbors) {
+                const nc = community.get(neighbor);
+                commWeights.set(nc, (commWeights.get(nc) ?? 0) + weight);
+            }
+            // Find best community to move to
+            let bestComm = currentComm;
+            let bestGain = 0;
+            const ki = neighbors.reduce((s, e) => s + e.weight, 0);
+            for (const [targetComm, weightToComm] of commWeights) {
+                if (targetComm === currentComm)
+                    continue;
+                // Simplified modularity gain: delta_Q ~ weight_to_comm - ki * sum_comm / (2m)
+                const sumComm = [...community.entries()]
+                    .filter(([, c]) => c === targetComm)
+                    .reduce((s, [n]) => s + (adj.get(n)?.reduce((s2, e) => s2 + e.weight, 0) ?? 0), 0);
+                const gain = weightToComm - (ki * sumComm) / (2 * totalWeight);
+                if (gain > bestGain) {
+                    bestGain = gain;
+                    bestComm = targetComm;
+                }
+            }
+            if (bestComm !== currentComm) {
+                community.set(node, bestComm);
+                improved = true;
+            }
+        }
+    }
+    // Build community list
+    const commMembers = new Map();
+    for (const [node, comm] of community) {
+        if (!commMembers.has(comm))
+            commMembers.set(comm, []);
+        commMembers.get(comm).push(node);
+    }
+    // Renumber communities 0..N-1
+    const communities = [];
+    let idx = 0;
+    for (const [, members] of commMembers) {
+        if (members.length > 0) {
+            communities.push({ id: idx++, members, size: members.length });
+        }
+    }
+    // Sort by size desc
+    communities.sort((a, b) => b.size - a.size);
+    const modularity = computeModularity(adj, community, totalWeight);
+    return { communities, modularity, nodeCount: nodes.size, edgeCount };
+}
+// ---------------------------------------------------------------------------
+// Hub node detection
+// ---------------------------------------------------------------------------
+/**
+ * Find hub nodes — memories with link count significantly above median.
+ * Returns nodes with links > threshold (default: 2x median, minimum 3 links).
+ */
+function detectHubs(db, thresholdMultiplier = 2, minLinks = 3) {
+    const rows = db
+        .prepare(`SELECT id, cnt FROM (
+         SELECT id, COUNT(*) as cnt FROM (
+           SELECT source_id AS id FROM memory_links
+           UNION ALL
+           SELECT target_id AS id FROM memory_links
+         ) GROUP BY id
+       ) ORDER BY cnt DESC`)
+        .all();
+    if (rows.length === 0)
+        return [];
+    // Compute median link count
+    const sorted = rows.map((r) => r.cnt).sort((a, b) => a - b);
+    const median = sorted[Math.floor(sorted.length / 2)];
+    const threshold = Math.max(median * thresholdMultiplier, minLinks);
+    const hubs = [];
+    for (const { id, cnt } of rows) {
+        if (cnt < threshold)
+            break; // sorted desc, no more hubs
+        const mem = db
+            .prepare("SELECT content, project, domain FROM memories WHERE id = ?")
+            .get(id);
+        if (!mem)
+            continue;
+        hubs.push({
+            id,
+            linkCount: cnt,
+            project: mem.project,
+            domain: mem.domain,
+            content: mem.content.slice(0, 200),
+        });
+    }
+    return hubs;
+}
+function getNeighbors(db, memoryId, limit = 10) {
+    const rows = db
+        .prepare(`SELECT source_id, target_id, relationship, strength
+       FROM memory_links
+       WHERE source_id = ? OR target_id = ?
+       ORDER BY strength DESC
+       LIMIT ?`)
+        .all(memoryId, memoryId, limit);
+    const results = [];
+    for (const row of rows) {
+        const isOutgoing = row.source_id === memoryId;
+        const neighborId = isOutgoing ? row.target_id : row.source_id;
+        const mem = db
+            .prepare("SELECT content, project FROM memories WHERE id = ?")
+            .get(neighborId);
+        if (!mem)
+            continue;
+        results.push({
+            id: neighborId,
+            relationship: row.relationship,
+            strength: row.strength,
+            direction: isOutgoing ? "outgoing" : "incoming",
+            content: mem.content.slice(0, 200),
+            project: mem.project,
+        });
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Shortest path (for MCP tool)
+// ---------------------------------------------------------------------------
+function shortestPath(db, fromId, toId, maxDepth = 5) {
+    // BFS on the memory_links graph
+    const links = db
+        .prepare("SELECT source_id, target_id FROM memory_links")
+        .all();
+    const adj = new Map();
+    for (const { source_id, target_id } of links) {
+        if (!adj.has(source_id))
+            adj.set(source_id, new Set());
+        adj.get(source_id).add(target_id);
+        if (!adj.has(target_id))
+            adj.set(target_id, new Set());
+        adj.get(target_id).add(source_id);
+    }
+    if (!adj.has(fromId) || !adj.has(toId))
+        return null;
+    const visited = new Set([fromId]);
+    const parent = new Map();
+    const queue = [{ node: fromId, depth: 0 }];
+    while (queue.length > 0) {
+        const { node, depth } = queue.shift();
+        if (node === toId) {
+            // Reconstruct path
+            const path = [toId];
+            let current = toId;
+            while (parent.has(current)) {
+                current = parent.get(current);
+                path.unshift(current);
+            }
+            return path;
+        }
+        if (depth >= maxDepth)
+            continue;
+        for (const neighbor of adj.get(node) ?? []) {
+            if (!visited.has(neighbor)) {
+                visited.add(neighbor);
+                parent.set(neighbor, node);
+                queue.push({ node: neighbor, depth: depth + 1 });
+            }
+        }
+    }
+    return null;
+}

package/dist/mcp-server.js

@@ -59,6 +59,7 @@ const features_js_1 = require("./features.js");
 const state_js_1 = require("./state.js");
 const embedder_js_1 = require("./embedder.js");
 const storage = __importStar(require("./storage.js"));
+const graph_js_1 = require("./graph.js");
 const retrieval = __importStar(require("./retrieval.js"));
 const consolidate_js_1 = require("./consolidate.js");
 const seed_lesson_js_1 = require("./seed-lesson.js");
@@ -243,6 +244,61 @@ function createMcpServer() {
             : "No memories yet.";
         return { content: [{ type: "text", text }] };
     });
+    // -- hicortex_graph --
+    server.tool("hicortex_graph", "Query the memory knowledge graph — find connected memories, hub nodes, or paths between memories.", {
+        operation: zod_1.z.enum(["neighbors", "hubs", "path"]).describe("Graph operation to perform"),
+        id: zod_1.z.string().optional().describe("Memory ID (required for neighbors and path operations)"),
+        target_id: zod_1.z.string().optional().describe("Target memory ID (required for path operation)"),
+        limit: zod_1.z.coerce.number().optional().describe("Max results (default 10)"),
+        domain: zod_1.z.string().optional().describe("Filter hubs by domain"),
+    }, async ({ operation, id, target_id, limit: resultLimit, domain: filterDomain }) => {
+        if (!db)
+            return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
+        try {
+            if (operation === "neighbors") {
+                if (!id)
+                    return { content: [{ type: "text", text: "id is required for neighbors operation" }], isError: true };
+                const resolvedId = resolveMemoryId(db, id);
+                if (!resolvedId)
+                    return { content: [{ type: "text", text: `Memory not found: ${id}` }], isError: true };
+                const neighbors = (0, graph_js_1.getNeighbors)(db, resolvedId, resultLimit ?? 10);
+                if (neighbors.length === 0)
+                    return { content: [{ type: "text", text: "No connected memories found." }] };
+                const text = neighbors.map((n) => `[${n.direction}] ${n.relationship} (${n.strength.toFixed(2)})\n  ${n.id.slice(0, 8)} | ${n.project ?? "global"} | ${n.content}`).join("\n\n");
+                return { content: [{ type: "text", text }] };
+            }
+            if (operation === "hubs") {
+                let hubs = (0, graph_js_1.detectHubs)(db);
+                if (filterDomain) {
+                    hubs = hubs.filter((h) => h.domain === filterDomain || h.project === filterDomain);
+                }
+                if (hubs.length === 0)
+                    return { content: [{ type: "text", text: "No hub memories found." }] };
+                const text = hubs.slice(0, resultLimit ?? 10).map((h) => `**${h.id.slice(0, 8)}** (${h.linkCount} links) | ${h.domain ?? h.project ?? "global"}\n  ${h.content}`).join("\n\n");
+                return { content: [{ type: "text", text }] };
+            }
+            if (operation === "path") {
+                if (!id || !target_id)
+                    return { content: [{ type: "text", text: "id and target_id are required for path operation" }], isError: true };
+                const fromId = resolveMemoryId(db, id);
+                const toId = resolveMemoryId(db, target_id);
+                if (!fromId || !toId)
+                    return { content: [{ type: "text", text: "One or both memory IDs not found" }], isError: true };
+                const path = (0, graph_js_1.shortestPath)(db, fromId, toId);
+                if (!path)
+                    return { content: [{ type: "text", text: "No path found between these memories." }] };
+                const text = path.map((nodeId, i) => {
+                    const mem = storage.getMemory(db, nodeId);
+                    return `${i + 1}. ${nodeId.slice(0, 8)} | ${mem?.project ?? "?"} | ${mem?.content.slice(0, 150) ?? "?"}`;
+                }).join("\n");
+                return { content: [{ type: "text", text: `Path (${path.length} hops):\n${text}` }] };
+            }
+            return { content: [{ type: "text", text: `Unknown operation: ${operation}` }], isError: true };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Graph query failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        }
+    });
     return server;
 }
 // ---------------------------------------------------------------------------

package/dist/types.d.ts

@@ -70,6 +70,10 @@ export interface ConsolidationReport {
             domains: number;
             reason?: string;
         };
+        hub_boost?: {
+            hubs_found: number;
+            boosted: number;
+        };
         links?: {
             auto_linked: number;
             failed: number;

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hicortex",
   "name": "Hicortex — Long-term Memory That Learns",
   "description": "Your agents remember past decisions, avoid repeated mistakes, and get smarter every day. Nightly reflection generates actionable lessons that automatically update agent behavior.",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "kind": "lifecycle",
   "skills": ["./skills/hicortex-memory", "./skills/hicortex-learn", "./skills/hicortex-activate"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Human-like memory for self-improving AI agents. Automatic capturing, nightly reflection, and cross-agent learning. Works with Claude Code and OpenClaw.",
   "main": "dist/index.js",
   "bin": {