@gamaze/hicortex 0.2.0

package/dist/storage.js

@@ -0,0 +1,326 @@
+"use strict";
+/**
+ * Storage layer — CRUD operations for the SQLite + sqlite-vec database.
+ * Ported from hicortex/storage.py. All functions are synchronous (better-sqlite3).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.embedToBlob = embedToBlob;
+exports.insertMemory = insertMemory;
+exports.getMemory = getMemory;
+exports.updateMemory = updateMemory;
+exports.strengthenMemory = strengthenMemory;
+exports.deleteMemory = deleteMemory;
+exports.vectorSearch = vectorSearch;
+exports.searchFts = searchFts;
+exports.addLink = addLink;
+exports.getLinks = getLinks;
+exports.deleteLinks = deleteLinks;
+exports.insertMemoriesBatch = insertMemoriesBatch;
+exports.countMemories = countMemories;
+exports.getRecentMemories = getRecentMemories;
+exports.getMemoriesSince = getMemoriesSince;
+exports.getLessons = getLessons;
+exports.getPruneCandidates = getPruneCandidates;
+exports.getAllLinkCounts = getAllLinkCounts;
+exports.getUnscoredMemories = getUnscoredMemories;
+const node_crypto_1 = require("node:crypto");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Serialize a Float32Array embedding to a Buffer for sqlite-vec.
+ */
+function embedToBlob(embedding) {
+    return Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+}
+function rowToMemory(row) {
+    return row;
+}
+// ---------------------------------------------------------------------------
+// Single memory CRUD
+// ---------------------------------------------------------------------------
+/**
+ * Insert a memory and its vector embedding. Returns the generated UUID.
+ */
+function insertMemory(db, content, embedding, opts = {}) {
+    const id = (0, node_crypto_1.randomUUID)();
+    const ts = opts.createdAt ?? nowIso();
+    const ingestedTs = nowIso();
+    db.prepare(`INSERT INTO memories
+     (id, content, base_strength, last_accessed, access_count,
+      created_at, ingested_at, source_agent, source_session, project,
+      privacy, memory_type)
+     VALUES (?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?)`).run(id, content, opts.baseStrength ?? 0.5, ts, ts, ingestedTs, opts.sourceAgent ?? "default", opts.sourceSession ?? null, opts.project ?? null, opts.privacy ?? "WORK", opts.memoryType ?? "episode");
+    db.prepare("INSERT INTO memory_vectors (id, embedding) VALUES (?, ?)").run(id, embedToBlob(embedding));
+    return id;
+}
+/**
+ * Get a single memory by ID. Returns null if not found.
+ */
+function getMemory(db, memoryId) {
+    const row = db
+        .prepare("SELECT * FROM memories WHERE id = ?")
+        .get(memoryId);
+    return row ? rowToMemory(row) : null;
+}
+// Allowed columns for updateMemory
+const ALLOWED_UPDATE_FIELDS = new Set([
+    "content",
+    "base_strength",
+    "last_accessed",
+    "access_count",
+    "source_agent",
+    "source_session",
+    "project",
+    "privacy",
+    "memory_type",
+]);
+/**
+ * Update specific fields on a memory.
+ */
+function updateMemory(db, memoryId, fields) {
+    const keys = Object.keys(fields);
+    if (keys.length === 0)
+        return;
+    for (const k of keys) {
+        if (!ALLOWED_UPDATE_FIELDS.has(k)) {
+            throw new Error(`Cannot update field: ${k}`);
+        }
+    }
+    const setClause = keys.map((k) => `"${k}" = ?`).join(", ");
+    const values = keys.map((k) => fields[k]);
+    values.push(memoryId);
+    db.prepare(`UPDATE memories SET ${setClause} WHERE id = ?`).run(...values);
+}
+/**
+ * Atomically increment access_count and reset last_accessed.
+ */
+function strengthenMemory(db, memoryId, nowIsoStr) {
+    db.prepare(`UPDATE memories
+     SET access_count = access_count + 1, last_accessed = ?
+     WHERE id = ?`).run(nowIsoStr, memoryId);
+}
+/**
+ * Delete a memory, its vector, and all its links.
+ */
+function deleteMemory(db, memoryId) {
+    db.prepare("DELETE FROM memory_links WHERE source_id = ? OR target_id = ?").run(memoryId, memoryId);
+    db.prepare("DELETE FROM memory_vectors WHERE id = ?").run(memoryId);
+    db.prepare("DELETE FROM memories WHERE id = ?").run(memoryId);
+}
+// ---------------------------------------------------------------------------
+// Vector search
+// ---------------------------------------------------------------------------
+/**
+ * Find similar memories by vector distance. Returns memories with distance field.
+ */
+function vectorSearch(db, queryEmbedding, limit = 10, excludeIds = []) {
+    const rows = db
+        .prepare("SELECT id, distance FROM memory_vectors WHERE embedding MATCH ? AND k = ? ORDER BY distance")
+        .all(embedToBlob(queryEmbedding), limit);
+    const excludeSet = new Set(excludeIds);
+    const results = [];
+    for (const row of rows) {
+        if (excludeSet.has(row.id))
+            continue;
+        const mem = db
+            .prepare("SELECT * FROM memories WHERE id = ?")
+            .get(row.id);
+        if (!mem)
+            continue;
+        results.push({ ...rowToMemory(mem), distance: row.distance });
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// FTS5 search
+// ---------------------------------------------------------------------------
+/**
+ * Full-text search using FTS5 BM25 ranking.
+ * Returns memories with a rank field (lower is better).
+ */
+function searchFts(db, query, limit = 10, privacy, sourceAgent) {
+    const conditions = ["memories_fts MATCH ?"];
+    const params = [query];
+    if (privacy && privacy.length > 0) {
+        const placeholders = privacy.map(() => "?").join(", ");
+        conditions.push(`m.privacy IN (${placeholders})`);
+        params.push(...privacy);
+    }
+    if (sourceAgent) {
+        conditions.push("m.source_agent = ?");
+        params.push(sourceAgent);
+    }
+    const where = conditions.join(" AND ");
+    params.push(limit);
+    const rows = db
+        .prepare(`SELECT m.*, fts.rank
+       FROM memories_fts fts
+       JOIN memories m ON m.rowid = fts.rowid
+       WHERE ${where}
+       ORDER BY fts.rank
+       LIMIT ?`)
+        .all(...params);
+    return rows.map((r) => {
+        const rank = r.rank;
+        const mem = rowToMemory(r);
+        return { ...mem, rank };
+    });
+}
+// ---------------------------------------------------------------------------
+// Links
+// ---------------------------------------------------------------------------
+/**
+ * Create a link between two memories.
+ */
+function addLink(db, sourceId, targetId, relationship, strength = 0.5) {
+    db.prepare(`INSERT OR REPLACE INTO memory_links
+     (source_id, target_id, relationship, strength, created_at)
+     VALUES (?, ?, ?, ?, ?)`).run(sourceId, targetId, relationship, strength, nowIso());
+}
+/**
+ * Get links for a memory. direction: 'outgoing', 'incoming', or 'both'.
+ */
+function getLinks(db, memoryId, direction = "both") {
+    let rows;
+    if (direction === "outgoing") {
+        rows = db
+            .prepare("SELECT * FROM memory_links WHERE source_id = ?")
+            .all(memoryId);
+    }
+    else if (direction === "incoming") {
+        rows = db
+            .prepare("SELECT * FROM memory_links WHERE target_id = ?")
+            .all(memoryId);
+    }
+    else {
+        rows = db
+            .prepare("SELECT * FROM memory_links WHERE source_id = ? OR target_id = ?")
+            .all(memoryId, memoryId);
+    }
+    return rows;
+}
+/**
+ * Delete all links involving a memory.
+ */
+function deleteLinks(db, memoryId) {
+    db.prepare("DELETE FROM memory_links WHERE source_id = ? OR target_id = ?").run(memoryId, memoryId);
+}
+// ---------------------------------------------------------------------------
+// Batch & query helpers
+// ---------------------------------------------------------------------------
+/**
+ * Batch insert memories. Returns count inserted.
+ */
+function insertMemoriesBatch(db, memories) {
+    const insertMem = db.prepare(`INSERT INTO memories
+     (id, content, base_strength, last_accessed, access_count,
+      created_at, ingested_at, source_agent, source_session, project,
+      privacy, memory_type)
+     VALUES (?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?)`);
+    const insertVec = db.prepare("INSERT INTO memory_vectors (id, embedding) VALUES (?, ?)");
+    const tx = db.transaction(() => {
+        let count = 0;
+        for (const mem of memories) {
+            const id = (0, node_crypto_1.randomUUID)();
+            const ts = nowIso();
+            insertMem.run(id, mem.content, mem.baseStrength ?? 0.5, ts, ts, ts, mem.sourceAgent ?? "default", mem.sourceSession ?? null, mem.project ?? null, mem.privacy ?? "WORK", mem.memoryType ?? "episode");
+            insertVec.run(id, embedToBlob(mem.embedding));
+            count++;
+        }
+        return count;
+    });
+    return tx();
+}
+/**
+ * Return total memory count.
+ */
+function countMemories(db) {
+    return db.prepare("SELECT count(*) as cnt FROM memories").get().cnt;
+}
+/**
+ * Get memories created in the last N days, newest first.
+ */
+function getRecentMemories(db, days = 7, limit = 50) {
+    const rows = db
+        .prepare(`SELECT * FROM memories
+       WHERE created_at >= datetime('now', ?)
+       ORDER BY created_at DESC LIMIT ?`)
+        .all(`-${days} days`, limit);
+    return rows.map(rowToMemory);
+}
+/**
+ * Get all memories ingested after a timestamp.
+ * Uses ingested_at (when the memory entered the DB) for consolidation correctness.
+ */
+function getMemoriesSince(db, sinceIso) {
+    const rows = db
+        .prepare(`SELECT * FROM memories
+       WHERE ingested_at > ?
+       ORDER BY ingested_at ASC`)
+        .all(sinceIso);
+    return rows.map(rowToMemory);
+}
+/**
+ * Get lesson-type memories from the last N days.
+ */
+function getLessons(db, days = 7, project) {
+    const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+    if (project) {
+        const rows = db
+            .prepare(`SELECT * FROM memories
+         WHERE memory_type = 'lesson' AND created_at > ? AND project = ?
+         ORDER BY created_at DESC`)
+            .all(cutoff, project);
+        return rows.map(rowToMemory);
+    }
+    const rows = db
+        .prepare(`SELECT * FROM memories
+       WHERE memory_type = 'lesson' AND created_at > ?
+       ORDER BY created_at DESC`)
+        .all(cutoff);
+    return rows.map(rowToMemory);
+}
+/**
+ * Get memories older than cutoff with zero access (prune candidates).
+ */
+function getPruneCandidates(db, cutoffIso) {
+    const rows = db
+        .prepare(`SELECT * FROM memories
+       WHERE created_at < ? AND access_count = 0
+       ORDER BY created_at ASC`)
+        .all(cutoffIso);
+    return rows.map(rowToMemory);
+}
+/**
+ * Get link counts for all memories in a single query.
+ * Returns a map of memory_id -> total link count (both directions).
+ */
+function getAllLinkCounts(db) {
+    const rows = db
+        .prepare(`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`)
+        .all();
+    const counts = new Map();
+    for (const row of rows) {
+        counts.set(row.id, row.cnt);
+    }
+    return counts;
+}
+/**
+ * Get all memories with default base_strength (never scored).
+ */
+function getUnscoredMemories(db) {
+    const rows = db
+        .prepare(`SELECT * FROM memories
+       WHERE base_strength = 0.5
+       ORDER BY ingested_at ASC`)
+        .all();
+    return rows.map(rowToMemory);
+}

package/dist/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Type definitions for Hicortex OpenClaw plugin.
+ * Ported from the Python hicortex codebase.
+ */
+/** A stored memory record. */
+export interface Memory {
+    id: string;
+    content: string;
+    base_strength: number;
+    last_accessed: string | null;
+    access_count: number;
+    created_at: string;
+    ingested_at: string;
+    source_agent: string;
+    source_session: string | null;
+    project: string | null;
+    privacy: "PUBLIC" | "WORK" | "PERSONAL" | "SENSITIVE";
+    memory_type: "episode" | "lesson" | "fact" | "decision";
+}
+/** A link between two memories. */
+export interface MemoryLink {
+    source_id: string;
+    target_id: string;
+    relationship: string;
+    strength: number;
+    created_at: string;
+}
+/** A search result with scoring metadata. */
+export interface MemorySearchResult {
+    id: string;
+    content: string;
+    score: number;
+    effective_strength: number;
+    access_count: number;
+    memory_type: string;
+    project: string | null;
+    created_at: string;
+    connections: number;
+}
+/** Report returned by the consolidation pipeline. */
+export interface ConsolidationReport {
+    started_at: string;
+    completed_at?: string;
+    dry_run: boolean;
+    status: "completed" | "skipped" | "failed";
+    elapsed_seconds?: number;
+    stages: {
+        precheck?: {
+            skip: boolean;
+            reason: string;
+            new_memory_count: number;
+            unscored_count: number;
+        };
+        importance?: {
+            scored: number;
+            failed: number;
+            skipped_budget: number;
+        };
+        reflection?: {
+            lessons_generated: number;
+            failed?: boolean;
+            skipped?: boolean;
+            reason?: string;
+        };
+        links?: {
+            auto_linked: number;
+            failed: number;
+        };
+        decay_prune?: {
+            candidates: number;
+            pruned: number;
+            failed: number;
+        };
+    };
+    budget?: {
+        max_calls: number;
+        calls_used: number;
+        calls_remaining: number;
+        calls_by_stage: Record<string, number>;
+    };
+}
+/** Plugin configuration from openclaw.plugin.json configSchema. */
+export interface HicortexConfig {
+    licenseKey?: string;
+    llmBaseUrl?: string;
+    llmApiKey?: string;
+    llmModel?: string;
+    reflectModel?: string;
+    consolidateHour?: number;
+    dbPath?: string;
+}
+/** Response from license validation API. */
+export interface LicenseInfo {
+    valid: boolean;
+    tier: "free" | "pro" | "lifetime" | "team";
+    features: {
+        reflection: boolean;
+        vectorSearch: boolean;
+        maxMemories: number;
+        crossAgent: boolean;
+    };
+    email?: string;
+    expires_at?: string;
+}
+/** Options for inserting a memory. */
+export interface InsertMemoryOptions {
+    sourceAgent?: string;
+    sourceSession?: string | null;
+    project?: string | null;
+    privacy?: string;
+    memoryType?: string;
+    baseStrength?: number;
+    createdAt?: string;
+}
+/** Options for vector search. */
+export interface VectorSearchOptions {
+    limit?: number;
+    excludeIds?: string[];
+}
+/** Options for FTS search. */
+export interface FtsSearchOptions {
+    limit?: number;
+    privacy?: string[];
+    sourceAgent?: string;
+}
+/** Options for retrieval. */
+export interface RetrievalOptions {
+    limit?: number;
+    project?: string | null;
+    privacy?: string[];
+    sourceAgent?: string;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Type definitions for Hicortex OpenClaw plugin.
+ * Ported from the Python hicortex codebase.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/openclaw.plugin.json

@@ -0,0 +1,70 @@
+{
+  "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.2.0",
+  "kind": "lifecycle",
+  "skills": ["./skills/hicortex-memory", "./skills/hicortex-learn", "./skills/hicortex-activate"],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "licenseKey": {
+        "type": "string",
+        "description": "Hicortex license key (hctx-...). Leave empty for free tier (100 memory cap)."
+      },
+      "llmBaseUrl": {
+        "type": "string",
+        "description": "LLM API base URL. Auto-detected from OpenClaw config or env vars if omitted."
+      },
+      "llmApiKey": {
+        "type": "string",
+        "description": "LLM API key. Auto-detected from OpenClaw config or env vars if omitted."
+      },
+      "llmModel": {
+        "type": "string",
+        "default": "qwen3.5:4b",
+        "description": "Model for importance scoring and distillation (local recommended)"
+      },
+      "reflectModel": {
+        "type": "string",
+        "default": "qwen3.5:cloud",
+        "description": "Model for nightly reflection (cloud recommended)"
+      },
+      "consolidateHour": {
+        "type": "number",
+        "default": 2,
+        "description": "Hour (0-23, local time) to run nightly consolidation"
+      },
+      "dbPath": {
+        "type": "string",
+        "description": "Custom path for the SQLite database file"
+      }
+    },
+    "required": []
+  },
+  "uiHints": {
+    "licenseKey": {
+      "label": "License Key",
+      "placeholder": "hctx-... (optional, free tier without key)",
+      "sensitive": true
+    },
+    "llmBaseUrl": {
+      "label": "LLM API URL",
+      "placeholder": "Auto-detected if empty"
+    },
+    "llmApiKey": {
+      "label": "LLM API Key",
+      "sensitive": true,
+      "placeholder": "Auto-detected if empty"
+    },
+    "llmModel": {
+      "label": "Scoring Model"
+    },
+    "reflectModel": {
+      "label": "Reflection Model"
+    },
+    "consolidateHour": {
+      "label": "Consolidation Hour"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@gamaze/hicortex",
+  "version": "0.2.0",
+  "description": "Long-term memory for AI agents \u2014 local embeddings, semantic search, and self-improving reflection. OpenClaw plugin.",
+  "main": "dist/index.js",
+  "openclaw": {
+    "extensions": ["./dist/index.js"]
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "skills/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^22.0.0",
+    "@types/better-sqlite3": "^7.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mha33/hicortex.git",
+    "directory": "packages/openclaw-plugin"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "sqlite-vec": "^0.1.7",
+    "@huggingface/transformers": "^3.0.0"
+  }
+}

package/skills/hicortex-activate/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: hicortex-activate
+description: Activate a Hicortex license key. Use when the user says they purchased Hicortex, has a license key, or wants to upgrade from the free tier.
+version: 0.2.0
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Activate Hicortex License
+
+When the user wants to activate their license key, guide them through it.
+
+## If they provide the key (e.g. `/hicortex-activate hctx-abc123`)
+
+Run this command to apply the key:
+
+```bash
+openclaw config set plugins.entries.hicortex.config.licenseKey "THE_KEY_HERE"
+```
+
+Then restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+Tell the user: "License activated! Hicortex now has unlimited memory. Your agent will keep learning and improving from every session."
+
+## If they don't have a key yet
+
+Tell them:
+
+"You can get a license key at https://hicortex.gamaze.com/ — after purchase, you'll receive your key by email. Then come back and tell me the key, and I'll activate it for you."
+
+## If activation fails
+
+If the `openclaw config set` command fails, fall back to telling the user to manually add it:
+
+"Open ~/.openclaw/openclaw.json, find the hicortex plugin entry, and add your key:
+
+```json
+"config": {
+  "licenseKey": "hctx-your-key-here"
+}
+```
+
+Then restart: `openclaw gateway restart`"
+
+## Rules
+
+- Never ask the user to open a terminal or edit files unless the automatic method fails
+- Always confirm the key was applied by checking the gateway log after restart
+- Be encouraging — they just bought the product

package/skills/hicortex-learn/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: hicortex-learn
+description: Save an explicit learning or insight to Hicortex long-term memory. Use when you discover something worth remembering across sessions — a lesson, a correction, a pattern, a decision.
+version: 0.2.0
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Save Learning to Hicortex
+
+When invoked with `/learn <text>`, store the learning in long-term memory via hicortex_ingest.
+
+## Steps
+
+1. Parse the text after `/learn`
+2. Clean it up into a clear, self-contained statement that will make sense months from now
+3. Add today's date
+4. Call the `hicortex_ingest` tool with:
+   - `content`: The learning text
+   - `project`: "global" (unless clearly project-specific)
+   - `memory_type`: "lesson"
+
+## Example
+
+```
+/learn z.ai API uses Bearer auth on all endpoints, not x-api-key
+```
+
+Becomes:
+```
+hicortex_ingest(content="LEARNING: z.ai API uses Bearer auth on all three endpoints (paas, coding, anthropic). Not x-api-key. (2026-03-24)", project="global", memory_type="lesson")
+```
+
+## Rules
+
+- Keep it concise — one clear statement
+- Include the "why" when relevant
+- Include the date for temporal context
+- Prefix with "LEARNING:" so it's identifiable in search
+- Confirm to the user what was saved (title + confirmation)