@gamaze/hicortex 0.7.0 → 0.7.1

package/dist/consolidate.js

@@ -43,6 +43,7 @@ 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");
@@ -487,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);
@@ -500,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.
@@ -660,8 +717,8 @@ 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

package/dist/graph.d.ts

@@ -50,5 +50,5 @@ export interface GraphNeighbor {
     content: string;
     project: string | null;
 }
-export declare function getNeighbors(db: Database.Database, memoryId: string, limit?: number): GraphNeighbor[];
+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

@@ -175,14 +175,20 @@ function detectHubs(db, thresholdMultiplier = 2, minLinks = 3) {
     }
     return hubs;
 }
-function getNeighbors(db, memoryId, limit = 10) {
-    const rows = db
-        .prepare(`SELECT source_id, target_id, relationship, strength
+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 = ?
-       ORDER BY strength DESC
-       LIMIT ?`)
-        .all(memoryId, memoryId, limit);
+       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;

package/dist/mcp-server.js

@@ -251,7 +251,8 @@ function createMcpServer() {
         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 }) => {
+        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 {
@@ -261,7 +262,7 @@ function createMcpServer() {
                 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);
+                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");

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;
@@ -76,6 +80,8 @@ export interface ConsolidationReport {
         };
         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.7.0",
+  "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.7.0",
+  "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": {