@gamaze/hicortex 0.3.16 → 0.4.0

package/README.md

@@ -1,137 +1,159 @@
-# @gamaze/hicortex — Human-like Memory for Self-Improving AI Agents
+# @gamaze/hicortex — Self-Learning Memory for AI Agents
 
-Upgrade your agents with Hicortex for automatic capturing of experiences, feedback, and decisions across all your connected agents. They start learning from every session, self-reflect, avoid past mistakes, and improve on their own — overnight, automatically. No configuration needed.
+Your agents learn from every session — successes and mistakes. Hicortex captures experiences, distills lessons, and applies them automatically. Connect multiple agents to shared memory and they improve together, overnight.
 
-Works with **OpenClaw** (in-process plugin) and **Claude Code** (HTTP/SSE MCP server).
+Works with **Claude Code** (primary), **OpenClaw** (in-process plugin), and any MCP-compatible agent.
 
-## Requirements
+**Website:** [hicortex.gamaze.com](https://hicortex.gamaze.com) · **Docs:** [hicortex.gamaze.com/docs](https://hicortex.gamaze.com/docs/)
 
-- Node.js 18+
-- LLM provider (auto-detected from OC config or `ANTHROPIC_API_KEY` for CC)
-- ~500MB disk for database + embedding model
-
-## Install — OpenClaw
+## Install — Server Mode (single machine)
 
 ```bash
-openclaw plugins install @gamaze/hicortex
-openclaw gateway restart
+npx @gamaze/hicortex init
 ```
 
-No configuration needed. The plugin auto-detects your LLM provider from OpenClaw settings on first startup.
+Detects your environment, installs a persistent MCP server daemon, auto-detects Ollama/Claude CLI/API keys, and registers with Claude Code. One command.
 
-## Install — Claude Code
+## Install — Client Mode (multi-client)
 
 ```bash
-npx @gamaze/hicortex init
+npx @gamaze/hicortex init --server https://your-server.example.com
 ```
 
-This detects your environment, installs a persistent MCP server daemon, registers it with Claude Code, and adds `/learn` and `/hicortex-activate` commands. Restart CC after setup.
+Connects to a remote Hicortex server. Sessions are distilled locally (privacy), memories are sent to the shared server. No local database needed.
 
-Or manually:
+## Install — OpenClaw
 
 ```bash
-# Start server
-npx @gamaze/hicortex server
-
-# Register with CC
-claude mcp add hicortex --transport http http://localhost:8787/sse
+openclaw plugins install @gamaze/hicortex
+openclaw gateway restart
 ```
 
-## Configure
-
-Optional config for OC (add to plugin entry in `~/.openclaw/openclaw.json`):
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `licenseKey` | _(none)_ | License key. Free tier (250 memories) without key. |
-| `llmBaseUrl` | _(auto)_ | Override LLM base URL |
-| `llmApiKey` | _(auto)_ | Override LLM API key |
-| `llmModel` | _(auto)_ | Override model for scoring and distillation |
-| `reflectModel` | _(auto)_ | Override model for nightly reflection |
-| `consolidateHour` | `2` | Hour (0-23, local time) for nightly consolidation |
-| `dbPath` | _(auto)_ | Custom database path |
+## Requirements
 
-For CC, set environment variables: `ANTHROPIC_API_KEY` (auto-detected), or `HICORTEX_LLM_BASE_URL` + `HICORTEX_LLM_API_KEY` + `HICORTEX_LLM_MODEL` for custom providers.
+- Node.js 18+
+- LLM: Ollama 9b+ (recommended), Claude CLI, or API key (Anthropic, OpenAI, etc.)
+- ~500MB disk for database + embedding model
 
 ## What Happens Automatically
 
 | When | What | How |
 |------|------|-----|
-| Agent start | Recent lessons injected into context | OC: `before_agent_start` hook / CC: CLAUDE.md block |
-| Agent end | Conversation captured and distilled | OC: `agent_end` hook / CC: nightly transcript scan |
-| Nightly | Score importance, reflect, link, decay | In-process consolidation pipeline |
+| Agent start | Recent lessons injected into context | CLAUDE.md block / OC hook |
+| Agent end | Conversation captured | CC: nightly transcript scan / OC: hook |
+| Nightly | Distill → score → reflect → link → inject | Automatic pipeline |
 
-## Agent Tools
+## Agent Tools (MCP)
 
-Available via MCP (both OC and CC):
+6 tools available via MCP:
 
-- **hicortex_search** — Semantic search across all stored knowledge
+- **hicortex_search** — Semantic search across all stored memories
 - **hicortex_context** — Get recent decisions and project state
-- **hicortex_ingest** — Store a piece of knowledge directly
+- **hicortex_ingest** — Store a memory directly
 - **hicortex_lessons** — Get actionable lessons from reflection
+- **hicortex_update** — Fix incorrect memories (re-embeds on content change)
+- **hicortex_delete** — Remove memories with cascade cleanup
 
 Skills: `/learn` to save explicit learnings.
 
 ## CLI Commands
 
 ```bash
-npx @gamaze/hicortex server      # Start MCP HTTP/SSE server (port 8787)
-npx @gamaze/hicortex init        # Set up for Claude Code
-npx @gamaze/hicortex nightly     # Run distill + consolidate + inject
-npx @gamaze/hicortex status      # Show config, DB stats, adapters
-npx @gamaze/hicortex uninstall   # Remove CC integration (keeps DB)
+npx @gamaze/hicortex server                    # Start MCP server (port 8787)
+npx @gamaze/hicortex init                      # Set up server mode
+npx @gamaze/hicortex init --server <url>       # Set up client mode
+npx @gamaze/hicortex nightly                   # Run distill + consolidate
+npx @gamaze/hicortex nightly --dry-run         # Preview without changes
+npx @gamaze/hicortex status                    # Show config, DB stats
+npx @gamaze/hicortex uninstall                 # Remove CC integration (keeps DB)
 ```
 
 ## Architecture
 
 ```
-@gamaze/hicortex (single npm package, dual mode)
-├── OpenClaw mode (in-process plugin)
-│   ├── before_agent_start → inject lessons
-│   ├── agent_end → capture + distill
-│   └── registerService → DB, LLM, consolidation timer
-│
-└── Claude Code mode (persistent HTTP/SSE server)
-    ├── MCP tools → hicortex_search, hicortex_context, hicortex_ingest, hicortex_lessons
-    ├── /health endpoint → monitoring
-    ├── Nightly → scan CC transcripts, distill, consolidate, inject CLAUDE.md
-    └── Shared DB at ~/.hicortex/hicortex.db
+  Client (MBP)              Server (bedrock)          Client (MBA)
+  ┌──────────┐              ┌──────────────┐          ┌──────────┐
+  │CC sessions│              │   Shared DB   │          │CC sessions│
+  │    ↓      │  POST        │              │  POST    │    ↓      │
+  │ Distill   │──/ingest───→│  Embed+Store  │←/ingest──│ Distill   │
+  │ (local)   │              │      ↓       │          │ (local)   │
+  │           │  MCP         │ Consolidate  │   MCP    │           │
+  │    CC    ←│──(search)───│ (score,link,  │──(search)→│   CC     │
+  │           │              │  reflect)    │          │           │
+  └──────────┘              └──────────────┘          └──────────┘
 
 Shared core:
-  ├── SQLite + sqlite-vec + FTS5 (single file)
+  ├── SQLite + sqlite-vec + FTS5
   ├── bge-small-en-v1.5 embeddings (ONNX, local CPU)
-  ├── BM25 + vector search with RRF fusion
-  └── Multi-provider LLM (20+ providers)
+  ├── BM25 + vector search with RRF fusion + graph traversal
+  └── Multi-provider LLM (Ollama, Claude CLI, 20+ cloud providers)
 ```
 
-## Database
+## Configuration
 
-Canonical location: `~/.hicortex/hicortex.db`. Existing OC installations at `~/.openclaw/data/hicortex.db` are automatically migrated on upgrade.
+Config at `~/.hicortex/config.json`. Created by `init`. Key options:
+
+| Field | Description |
+|-------|-------------|
+| `mode` | `"server"` (default) or `"client"` |
+| `serverUrl` | Remote server URL (client mode) |
+| `llmModel` | Model for importance scoring |
+| `distillModel` | Model for session distillation (9b+ recommended) |
+| `reflectModel` | Model for nightly reflection (largest available) |
+| `reflectBaseUrl` | Separate Ollama instance for reflection |
+| `authToken` | Bearer token for endpoint auth |
+| `licenseKey` | License key for higher tiers |
+
+Full docs: [hicortex.gamaze.com/docs/configuration.html](https://hicortex.gamaze.com/docs/configuration.html)
+
+## REST API
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/health` | GET | No | Server status, memory count, version |
+| `/ingest` | POST | Yes | Accept pre-distilled memories from clients |
+| `/sse` | GET | Yes | MCP SSE stream for agent connections |
+| `/messages` | POST | Yes | MCP message endpoint |
 
 ## Pricing
 
-| Tier | Price | Memories | Features |
-|------|-------|----------|----------|
-| Free | $0 | 250 | Full features: search, reflection, lessons, linking |
-| Pro | $9/month | Unlimited | Everything in Free, unlimited |
-| Lifetime | $149 | Unlimited | Pro forever |
-| Team | $29/month | Unlimited | Multi-agent shared memory |
+| Tier | Price | Memories | Clients |
+|------|-------|----------|---------|
+| Free | $0 | 250 | Unlimited (trial) |
+| Pro | $9/month | Unlimited | Single |
+| Team | $29/month | Unlimited | Unlimited |
+| Lifetime | $149 | Unlimited | Single |
 
-Get a license key at [hicortex.gamaze.com](https://hicortex.gamaze.com).
+[hicortex.gamaze.com](https://hicortex.gamaze.com)
 
 ## Uninstall
 
-**OpenClaw:**
 ```bash
-openclaw plugins uninstall hicortex
+npx @gamaze/hicortex uninstall    # Claude Code
+openclaw plugins uninstall hicortex  # OpenClaw
 ```
 
-**Claude Code:**
-```bash
-npx @gamaze/hicortex uninstall
-```
+Database preserved by default. Remove all data: `rm -rf ~/.hicortex`
 
-Your memory database is preserved by default. To remove all data: `rm -rf ~/.hicortex`
+## Configure — OpenClaw
+
+Optional config (add to plugin entry in `~/.openclaw/openclaw.json`):
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `licenseKey` | _(none)_ | License key. Free tier (250 memories) without key. |
+| `llmBaseUrl` | _(auto)_ | Override LLM base URL |
+| `llmApiKey` | _(auto)_ | Override LLM API key |
+| `llmModel` | _(auto)_ | Override model for scoring and distillation |
+| `reflectModel` | _(auto)_ | Override model for nightly reflection |
+| `consolidateHour` | `2` | Hour (0-23, local time) for nightly consolidation |
+| `dbPath` | _(auto)_ | Custom database path |
+
+For CC, set environment variables: `ANTHROPIC_API_KEY` (auto-detected), or `HICORTEX_LLM_BASE_URL` + `HICORTEX_LLM_API_KEY` + `HICORTEX_LLM_MODEL` for custom providers.
+
+## Database
+
+Canonical location: `~/.hicortex/hicortex.db`. Existing OC installations at `~/.openclaw/data/hicortex.db` are automatically migrated on upgrade.
 
 ## Development
 
@@ -152,6 +174,8 @@ npm test
 
 **First startup slow:** The embedding model (~130MB) downloads on first run. Allow up to 2 minutes.
 
-**Server won't start (CC):** Check `~/.hicortex/server.log` for errors. Verify port 8787 is free: `lsof -i :8787`.
+**Server won't start (CC):** Check `~/.hicortex/nightly.log` for errors. Verify port 8787 is free: `lsof -i :8787`.
 
 **Multiple CC sessions:** The HTTP server handles multiple concurrent sessions. Do not use stdio transport — it spawns separate processes per session.
+
+**Ollama timeout on large sessions:** Hicortex uses streaming mode with 3 retries (30s, 60s, 120s backoff). If first call fails (model loading), retry handles it automatically.

package/dist/cli.js

@@ -26,14 +26,17 @@ switch (command) {
         });
         break;
     }
-    case "init":
+    case "init": {
+        const serverArg = process.argv.indexOf("--server");
+        const serverUrl = serverArg !== -1 ? process.argv[serverArg + 1] : undefined;
         import("./init.js").then(({ runInit }) => {
-            runInit().catch((err) => {
+            runInit({ serverUrl }).catch((err) => {
                 console.error("[hicortex] Init failed:", err);
                 process.exit(1);
             });
         });
         break;
+    }
     case "nightly": {
         const dryRun = process.argv.includes("--dry-run");
         import("./nightly.js").then(({ runNightly }) => {
@@ -66,8 +69,9 @@ switch (command) {
 Usage: hicortex <command> [options]
 
 Commands:
-  server     Start the MCP HTTP/SSE server
-  init       Set up Hicortex for Claude Code
+  server     Start the MCP HTTP/SSE server (server mode)
+  init       Set up Hicortex (server mode, local DB + daemon)
+  init --server <url>  Set up as client (remote server, local distillation)
   nightly    Run nightly distill + consolidate + inject
   status     Show current configuration and stats
   uninstall  Remove CC integration (preserves DB)
@@ -75,10 +79,12 @@ Commands:
 Options:
   server --port <n>   Port (default: 8787)
   server --host <h>   Host (default: 127.0.0.1)
+  nightly --dry-run   Preview without changes
 
 Examples:
   npx @gamaze/hicortex server
   npx @gamaze/hicortex init
+  npx @gamaze/hicortex init --server https://myserver.example.com
   npx @gamaze/hicortex status`);
         process.exit(command ? 1 : 0);
 }

package/dist/consolidate.js

@@ -228,7 +228,12 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
         return `[${project}] [${agent}] ${content}`;
     });
     const memoriesBlock = lines.join("\n\n");
-    const prompt = (0, prompts_js_1.reflection)(memoriesBlock);
+    // Feed recent lessons to prevent duplicates and enable escalation
+    const recentLessons = storage.getLessons(db, 7).slice(0, 10);
+    const recentBlock = recentLessons.length > 0
+        ? recentLessons.map(l => `- ${l.content.slice(0, 150)}`).join("\n")
+        : undefined;
+    const prompt = (0, prompts_js_1.reflection)(memoriesBlock, recentBlock);
     if (dryRun) {
         return { lessons_generated: 0, skipped: false };
     }
@@ -250,10 +255,12 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
             if (!lessonText)
                 continue;
             const project = String(lo.project ?? "global");
+            const lessonType = String(lo.type ?? "principle");
             const severity = String(lo.severity ?? "important");
             const confidence = String(lo.confidence ?? "medium");
             const sourcePattern = String(lo.source_pattern ?? "");
             let content = `## Lesson: ${lessonText}\n\n`;
+            content += `**Type:** ${lessonType}\n`;
             content += `**Severity:** ${severity}\n`;
             content += `**Confidence:** ${confidence}\n`;
             if (sourcePattern)
@@ -307,9 +314,10 @@ 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, "relates_to", similarity);
+                            storage.addLink(db, mem.id, neighbor.id, relationship, similarity);
                             autoLinked++;
                         }
                         catch {
@@ -328,6 +336,29 @@ async function stageLinks(db, memories, embedFn, dryRun) {
     }
     return { auto_linked: autoLinked, failed };
 }
+/**
+ * Classify the relationship between two memories based on type, temporal ordering, and similarity.
+ */
+function classifyRelationship(source, target, similarity) {
+    // Lesson derived from episode(s)
+    if (source.memory_type === "lesson" && target.memory_type === "episode")
+        return "derives";
+    if (target.memory_type === "lesson" && source.memory_type === "episode")
+        return "derives";
+    // Same type + very high similarity + different timestamps → newer updates older
+    if (source.memory_type === target.memory_type &&
+        similarity > 0.8 &&
+        source.created_at !== target.created_at) {
+        return "updates";
+    }
+    // Same project, moderate similarity → extends
+    if (source.project && target.project &&
+        source.project === target.project &&
+        similarity > 0.55 && similarity <= 0.8) {
+        return "extends";
+    }
+    return "relates_to";
+}
 // ---------------------------------------------------------------------------
 // Stage 4: Decay & Prune
 // ---------------------------------------------------------------------------

package/dist/db.js

@@ -103,7 +103,8 @@ CREATE TABLE IF NOT EXISTS memories (
     source_session TEXT,
     project TEXT,
     privacy TEXT DEFAULT 'WORK',
-    memory_type TEXT DEFAULT 'episode'
+    memory_type TEXT DEFAULT 'episode',
+    updated_at TIMESTAMP
 );
 
 CREATE TABLE IF NOT EXISTS memory_links (
@@ -184,6 +185,9 @@ function migrate(db) {
         db.exec("UPDATE memories SET ingested_at = created_at");
         db.exec("CREATE INDEX IF NOT EXISTS idx_memories_ingested ON memories(ingested_at)");
     }
+    if (!colNames.has("updated_at")) {
+        db.exec("ALTER TABLE memories ADD COLUMN updated_at TIMESTAMP");
+    }
 }
 /**
  * Return database statistics.

package/dist/init.d.ts

@@ -14,4 +14,6 @@
  *   - Inject CLAUDE.md learnings block
  *   - Install CC custom commands (/learn, /hicortex-activate)
  */
-export declare function runInit(): Promise<void>;
+export declare function runInit(options?: {
+    serverUrl?: string;
+}): Promise<void>;