@gamaze/hicortex 0.6.1 → 0.7.1

package/README.md

@@ -45,13 +45,14 @@ openclaw gateway restart
 
 ## Agent Tools (MCP)
 
-7 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
 

package/dist/consolidate.js

@@ -43,11 +43,13 @@ exports.parseJsonLenient = parseJsonLenient;
 exports.runConsolidation = runConsolidation;
 exports.msUntilHour = msUntilHour;
 exports.scheduleConsolidation = scheduleConsolidation;
+const types_js_1 = require("./types.js");
 const retrieval_js_1 = require("./retrieval.js");
 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 +354,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
@@ -451,12 +488,17 @@ async function stageDomainCuration(db, llm, budget, dryRun, stateDir) {
     console.log(`[hicortex] Domain curation: ${domains.length} domains from ${projectRows.length} projects`);
     return { curated: true, domains: domains.length };
 }
-// ---------------------------------------------------------------------------
-// Stage 3: Link Discovery (vector similarity auto-link)
-// ---------------------------------------------------------------------------
-async function stageLinks(db, memories, embedFn, dryRun) {
+/** Batch size for LLM edge classification calls. */
+const EDGE_CLASSIFICATION_BATCH_SIZE = 8;
+/** Valid relationship type set for fast lookup. */
+const VALID_REL_SET = new Set(types_js_1.VALID_RELATIONSHIP_TYPES);
+async function stageLinks(db, memories, embedFn, dryRun, llm, budget) {
     let autoLinked = 0;
+    let llmClassified = 0;
+    let heuristicFallback = 0;
     let failed = 0;
+    // Phase A: Discovery — collect candidates via vector similarity
+    const candidates = [];
     for (const mem of memories) {
         try {
             const embedding = await embedFn(mem.content);
@@ -464,27 +506,78 @@ async function stageLinks(db, memories, embedFn, dryRun) {
             for (const neighbor of neighbors) {
                 const similarity = 1.0 - neighbor.distance;
                 if (similarity > CONSOLIDATE_LINK_THRESHOLD) {
-                    const relationship = classifyRelationship(mem, neighbor, similarity);
-                    if (!dryRun) {
-                        try {
-                            storage.addLink(db, mem.id, neighbor.id, relationship, similarity);
-                            autoLinked++;
+                    const heuristicType = classifyRelationship(mem, neighbor, similarity);
+                    candidates.push({ source: mem, target: neighbor, similarity, heuristicType });
+                }
+            }
+        }
+        catch {
+            failed++;
+        }
+    }
+    if (candidates.length === 0) {
+        return { auto_linked: 0, llm_classified: 0, heuristic_fallback: 0, failed };
+    }
+    // Phase B: LLM batch classification
+    // Build batches and classify with LLM where budget allows
+    const classifiedTypes = new Array(candidates.length);
+    for (let i = 0; i < candidates.length; i += EDGE_CLASSIFICATION_BATCH_SIZE) {
+        const batch = candidates.slice(i, i + EDGE_CLASSIFICATION_BATCH_SIZE);
+        // Attempt LLM classification if budget allows
+        if (budget.use("edge_classification")) {
+            try {
+                const pairsBlock = batch.map((c, idx) => {
+                    const srcContent = c.source.content.slice(0, 200);
+                    const tgtContent = c.target.content.slice(0, 200);
+                    return `[${idx}] SOURCE: ${c.source.memory_type} | ${c.source.project ?? "global"} | ${srcContent}\n    TARGET: ${c.target.memory_type} | ${c.target.project ?? "global"} | ${tgtContent}\n    similarity: ${c.similarity.toFixed(2)}`;
+                }).join("\n\n");
+                const prompt = (0, prompts_js_1.edgeClassification)(pairsBlock);
+                const raw = await llm.completeFast(prompt, 512);
+                const parsed = parseJsonLenient(raw, []);
+                if (Array.isArray(parsed) && parsed.length > 0) {
+                    for (let j = 0; j < batch.length; j++) {
+                        const llmType = parsed[j];
+                        if (typeof llmType === "string" && VALID_REL_SET.has(llmType)) {
+                            classifiedTypes[i + j] = llmType;
+                            llmClassified++;
                         }
-                        catch {
-                            failed++;
+                        else {
+                            // Invalid type from LLM — fall back to heuristic
+                            classifiedTypes[i + j] = batch[j].heuristicType;
+                            heuristicFallback++;
                         }
                     }
-                    else {
-                        autoLinked++;
-                    }
+                    continue;
                 }
             }
+            catch {
+                // LLM call failed — fall through to heuristic for this batch
+            }
         }
-        catch {
-            failed++;
+        // Budget exhausted or LLM failed — use heuristic for entire batch
+        for (let j = 0; j < batch.length; j++) {
+            classifiedTypes[i + j] = batch[j].heuristicType;
+            heuristicFallback++;
+        }
+    }
+    // Phase C: Store all classified links
+    for (let i = 0; i < candidates.length; i++) {
+        const c = candidates[i];
+        const relationship = classifiedTypes[i];
+        if (!dryRun) {
+            try {
+                storage.addLink(db, c.source.id, c.target.id, relationship, c.similarity);
+                autoLinked++;
+            }
+            catch {
+                failed++;
+            }
+        }
+        else {
+            autoLinked++;
         }
     }
-    return { auto_linked: autoLinked, failed };
+    return { auto_linked: autoLinked, llm_classified: llmClassified, heuristic_fallback: heuristicFallback, failed };
 }
 /**
  * Classify the relationship between two memories based on type, temporal ordering, and similarity.
@@ -510,6 +603,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) {
@@ -595,8 +717,10 @@ async function runConsolidation(db, llm, embedFn, dryRun = false, skipReflection
         }
         // Stage 2.7: Domain Curation
         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: Link Discovery (with LLM-assisted edge classification)
+        report.stages.links = await stageLinks(db, precheck.newMemories, embedFn, dryRun, llm, budget);
+        // 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, relationship?: string): GraphNeighbor[];
+export declare function shortestPath(db: Database.Database, fromId: string, toId: string, maxDepth?: number): string[] | null;

package/dist/graph.js

@@ -0,0 +1,257 @@
+"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, relationship) {
+    let sql = `SELECT source_id, target_id, relationship, strength
+       FROM memory_links
+       WHERE (source_id = ? OR target_id = ?)`;
+    const params = [memoryId, memoryId];
+    if (relationship) {
+        sql += ` AND relationship = ?`;
+        params.push(relationship);
+    }
+    sql += ` ORDER BY strength DESC LIMIT ?`;
+    params.push(limit);
+    const rows = db
+        .prepare(sql)
+        .all(...params);
+    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,62 @@ 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"),
+        relationship: zod_1.z.string().optional().describe("Filter neighbors by relationship type (e.g., CONTRADICTS, SUPERSEDES, derives)"),
+    }, async ({ operation, id, target_id, limit: resultLimit, domain: filterDomain, relationship: filterRelationship }) => {
+        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, filterRelationship);
+                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/prompts.d.ts

@@ -19,3 +19,8 @@ export declare function distillation(projectName: string, date: string, transcri
  * Used during consolidation (Pro only, one call per nightly when projects change).
  */
 export declare function domainCuration(projectLines: string): string;
+/**
+ * Edge classification prompt. Presents memory pairs and asks the LLM to
+ * choose the most specific relationship type for each.
+ */
+export declare function edgeClassification(pairsBlock: string): string;

package/dist/prompts.js

@@ -8,6 +8,7 @@ exports.importanceScoring = importanceScoring;
 exports.reflection = reflection;
 exports.distillation = distillation;
 exports.domainCuration = domainCuration;
+exports.edgeClassification = edgeClassification;
 /**
  * Importance scoring prompt. Takes a {memories_block} with indexed memories.
  */
@@ -169,3 +170,31 @@ Rules:
 
 Respond with ONLY a JSON array. No explanations.`;
 }
+/**
+ * Edge classification prompt. Presents memory pairs and asks the LLM to
+ * choose the most specific relationship type for each.
+ */
+function edgeClassification(pairsBlock) {
+    return `You are a memory graph analyst. Classify the relationship between each memory pair.
+
+VALID RELATIONSHIP TYPES:
+- derives: A lesson or fact was derived from episodes (lesson ← episode)
+- updates: A newer memory updates/replaces an older one on the same topic
+- extends: Memory adds detail to another within the same project
+- relates_to: Generic association (use ONLY when no specific type fits)
+- CONTRADICTS: Memories give opposite advice or conflicting information
+- SUPERSEDES: One memory fully replaces another (stronger than "updates")
+- DEPENDS_ON: One memory's validity requires the other (prerequisite)
+- CAUSED_BY: One event/decision directly caused the other
+- VALIDATES: One memory confirms or provides evidence for the other
+
+Choose the MOST SPECIFIC type. Prefer specific types over "relates_to".
+
+MEMORY PAIRS:
+${pairsBlock}
+
+Respond with ONLY a JSON array of relationship type strings, one per pair, in order.
+Example for 3 pairs: ["CAUSED_BY", "extends", "VALIDATES"]
+
+No explanations. Just the JSON array.`;
+}

package/dist/types.d.ts

@@ -27,6 +27,10 @@ export interface MemoryLink {
     strength: number;
     created_at: string;
 }
+/** All valid relationship types for memory links.
+ *  lowercase = heuristic (legacy), UPPER_SNAKE_CASE = LLM-classified (v0.7+). */
+export declare const VALID_RELATIONSHIP_TYPES: readonly ["derives", "updates", "extends", "relates_to", "CONTRADICTS", "SUPERSEDES", "DEPENDS_ON", "CAUSED_BY", "VALIDATES"];
+export type RelationshipType = typeof VALID_RELATIONSHIP_TYPES[number];
 /** A search result with scoring metadata. */
 export interface MemorySearchResult {
     id: string;
@@ -70,8 +74,14 @@ export interface ConsolidationReport {
             domains: number;
             reason?: string;
         };
+        hub_boost?: {
+            hubs_found: number;
+            boosted: number;
+        };
         links?: {
             auto_linked: number;
+            llm_classified?: number;
+            heuristic_fallback?: number;
             failed: number;
         };
         decay_prune?: {

package/dist/types.js

@@ -4,3 +4,10 @@
  * Ported from the Python hicortex codebase.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_RELATIONSHIP_TYPES = void 0;
+/** All valid relationship types for memory links.
+ *  lowercase = heuristic (legacy), UPPER_SNAKE_CASE = LLM-classified (v0.7+). */
+exports.VALID_RELATIONSHIP_TYPES = [
+    "derives", "updates", "extends", "relates_to",
+    "CONTRADICTS", "SUPERSEDES", "DEPENDS_ON", "CAUSED_BY", "VALIDATES",
+];

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.1",
+  "version": "0.7.1",
   "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.1",
+  "version": "0.7.1",
   "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": {