@gamaze/hicortex 0.4.6 → 0.5.1

package/README.md

@@ -2,7 +2,7 @@
 
 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 **Claude Code** (primary), **OpenClaw** (in-process plugin), and any MCP-compatible agent.
+Works with **Claude Code**, **Pi**, **OpenClaw**, and any MCP-compatible agent.
 
 **Website:** [hicortex.gamaze.com](https://hicortex.gamaze.com) · **Docs:** [hicortex.gamaze.com/docs](https://hicortex.gamaze.com/docs/)
 
@@ -39,8 +39,8 @@ openclaw gateway restart
 
 | When | What | How |
 |------|------|-----|
-| Agent start | Recent lessons injected into context | CLAUDE.md block / OC hook |
-| Agent end | Conversation captured | CC: nightly transcript scan / OC: hook |
+| Agent start | Recent lessons injected into context | CLAUDE.md / EXPERIENCE.md / OC hook |
+| Agent end | Conversation captured | CC + Pi: nightly transcript scan / OC: hook |
 | Nightly | Distill → score → reflect → link → inject | Automatic pipeline |
 
 ## Agent Tools (MCP)
@@ -159,7 +159,7 @@ Canonical location: `~/.hicortex/hicortex.db`. Existing OC installations at `~/.
 ## Development
 
 ```bash
-cd packages/openclaw-plugin
+cd packages/hicortex
 npm install
 npm run build
 npm test

package/dist/consolidate.d.ts

@@ -24,7 +24,7 @@ export declare function parseJsonLenient<T>(text: string, fallback: T): T;
 /**
  * Run the full consolidation pipeline. Returns a structured report.
  */
-export declare function runConsolidation(db: Database.Database, llm: LlmClient, embedFn: EmbedFn, dryRun?: boolean): Promise<ConsolidationReport>;
+export declare function runConsolidation(db: Database.Database, llm: LlmClient, embedFn: EmbedFn, dryRun?: boolean, skipReflection?: boolean): Promise<ConsolidationReport>;
 /**
  * Calculate milliseconds until the next occurrence of a given hour (local time).
  */

package/dist/consolidate.js

@@ -388,7 +388,7 @@ function stageDecayPrune(db, dryRun) {
 /**
  * Run the full consolidation pipeline. Returns a structured report.
  */
-async function runConsolidation(db, llm, embedFn, dryRun = false) {
+async function runConsolidation(db, llm, embedFn, dryRun = false, skipReflection = false) {
     const start = new Date();
     const report = {
         started_at: start.toISOString(),
@@ -424,7 +424,16 @@ async function runConsolidation(db, llm, embedFn, dryRun = false) {
         // Stage 2: Importance Scoring
         report.stages.importance = await stageImportance(db, scoreMemories, llm, budget, dryRun);
         // Stage 2.5: Reflection
-        report.stages.reflection = await stageReflection(db, precheck.newMemories, llm, budget, embedFn, dryRun);
+        if (skipReflection) {
+            report.stages.reflection = {
+                lessons_generated: 0,
+                skipped: true,
+                reason: "reflect_endpoint_offline",
+            };
+        }
+        else {
+            report.stages.reflection = await stageReflection(db, precheck.newMemories, llm, budget, embedFn, dryRun);
+        }
         // Stage 3: Link Discovery
         report.stages.links = await stageLinks(db, precheck.newMemories, embedFn, dryRun);
         // Stage 4: Decay & Prune

package/dist/distiller.js

@@ -175,16 +175,25 @@ function extractConversationText(messages) {
             continue;
         if (m.isSidechain)
             continue;
-        // Extract content — OpenClaw messages have content at top level;
-        // Python distiller format has message.content
-        const content = m.content ?? m.message?.content;
+        // Extract the message role from whichever format we're dealing with:
+        //   OC hook:  m.role = "user" | "assistant"
+        //   CC JSONL:  m.type = "user" | "assistant"
+        //   Pi JSONL:  m.message.role = "user" | "assistant" | "toolResult"
+        const nestedMsg = m.message;
+        const msgRole = String(m.role ?? nestedMsg?.role ?? m.type ?? "");
+        // Skip tool results — they're noisy (file contents, command output) and
+        // add bulk without much extractable knowledge for distillation.
+        if (msgRole === "toolResult" || msgRole === "tool_result")
+            continue;
+        // Extract content — OC has content at top level; CC/Pi have message.content
+        const content = m.content ?? nestedMsg?.content;
         if (content === undefined || content === null)
             continue;
         let text = extractTextFromContent(content);
         text = cleanMessageContent(text);
         if (text.length < 20)
             continue;
-        const role = m.role === "user" || m.type === "user" ? "USER" : "ASSISTANT";
+        const role = msgRole === "user" ? "USER" : "ASSISTANT";
         parts.push(`${role}: ${text}`);
     }
     return parts.join("\n\n");

package/dist/extensions.d.ts

@@ -123,4 +123,51 @@ export declare function setExtensions(ext: Partial<typeof activeExtensions>): vo
 export declare function getLessonSelector(): LessonSelector;
 /** Get the active PromptStrategy (default unless Pro is loaded). */
 export declare function getPromptStrategy(): PromptStrategy;
+/**
+ * The object passed to a Pro package's `activate()` function at boot.
+ * Pro packages receive this to register their extensions and access OSS
+ * runtime APIs they need.
+ *
+ * Design rationale: Pro code never STATICALLY imports from the OSS client.
+ * All runtime access is through this context object. This has two benefits:
+ *   1. Pro bundles are self-contained — they don't have `require("../...")`
+ *      calls that would break when the tarball is installed to
+ *      ~/.hicortex/pro/ at runtime.
+ *   2. Pro code can only access what the OSS client exposes here, so the
+ *      blast radius of a malicious/buggy Pro release is contained.
+ *
+ * Type-only imports of `LessonSelector`, `PromptStrategy` etc. in Pro code
+ * are fine — they're erased at compile time and produce no runtime imports.
+ */
+export interface ProActivationContext {
+    /** Register a lesson selector implementation. */
+    setSelector(selector: LessonSelector): void;
+    /** Register a prompt strategy implementation. */
+    setPrompts(prompts: PromptStrategy): void;
+    /** The version of the OSS host (from package.json). Pro can use this
+     *  to gate features against host compatibility. */
+    hostVersion: string;
+    /** Log through the OSS logging surface so Pro logs get the [hicortex]
+     *  prefix and unified formatting. */
+    log(message: string): void;
+}
+/**
+ * The shape Pro packages must export as their default export.
+ * See `packages/hicortex/src/pro/index.ts` for the reference impl.
+ */
+export interface ProPackage {
+    /** Called once at OSS boot if a Pro license is valid and the Pro
+     *  tarball has been downloaded + extracted. Should register extensions
+     *  via the context and return. Errors abort Pro activation but do not
+     *  abort the OSS host. */
+    activate(ctx: ProActivationContext): void | Promise<void>;
+}
+/**
+ * Build an activation context for a Pro package. Called from the Pro
+ * loader in features.ts / pro-loader.ts.
+ *
+ * Keep this function small — it's the ONLY surface a Pro package gets.
+ * Expanding it expands the attack surface, so add fields deliberately.
+ */
+export declare function createProActivationContext(hostVersion: string): ProActivationContext;
 export {};

package/dist/extensions.js

@@ -34,6 +34,7 @@ exports.defaultPromptStrategy = exports.defaultLessonSelector = void 0;
 exports.setExtensions = setExtensions;
 exports.getLessonSelector = getLessonSelector;
 exports.getPromptStrategy = getPromptStrategy;
+exports.createProActivationContext = createProActivationContext;
 /**
  * Default LessonSelector — preserves current OSS behaviour exactly.
  * `slice(0, maxLessons)` over the candidate pool, no re-ranking.
@@ -152,3 +153,24 @@ function getLessonSelector() {
 function getPromptStrategy() {
     return activeExtensions.prompts;
 }
+/**
+ * Build an activation context for a Pro package. Called from the Pro
+ * loader in features.ts / pro-loader.ts.
+ *
+ * Keep this function small — it's the ONLY surface a Pro package gets.
+ * Expanding it expands the attack surface, so add fields deliberately.
+ */
+function createProActivationContext(hostVersion) {
+    return {
+        setSelector(selector) {
+            activeExtensions = { ...activeExtensions, selector };
+        },
+        setPrompts(prompts) {
+            activeExtensions = { ...activeExtensions, prompts };
+        },
+        hostVersion,
+        log(message) {
+            console.log(`[hicortex][pro] ${message}`);
+        },
+    };
+}

package/dist/features.d.ts

@@ -22,7 +22,7 @@ import type { LicenseInfo } from "./types.js";
  * After this returns, sync getters (isPro, lessonsLimit, etc.) are deterministic
  * and reflect the user's actual tier — no more "free during validation window".
  */
-export declare function initFeatures(licenseKey: string | undefined, stateDir?: string): Promise<void>;
+export declare function initFeatures(licenseKey: string | undefined, stateDir?: string, hostVersion?: string): Promise<void>;
 /** Are we on a paid tier (Pro, Team, Lifetime)? */
 export declare function isPro(): boolean;
 /** Memory count cap. -1 = unlimited (paid). */

package/dist/features.js

@@ -54,7 +54,7 @@ function persistTier(stateDir, info) {
  * After this returns, sync getters (isPro, lessonsLimit, etc.) are deterministic
  * and reflect the user's actual tier — no more "free during validation window".
  */
-async function initFeatures(licenseKey, stateDir = DEFAULT_STATE_DIR) {
+async function initFeatures(licenseKey, stateDir = DEFAULT_STATE_DIR, hostVersion = "0.0.0") {
     if (initialized)
         return;
     initialized = true;
@@ -66,7 +66,7 @@ async function initFeatures(licenseKey, stateDir = DEFAULT_STATE_DIR) {
     else {
         currentFeatures = FREE_FEATURES;
     }
-    // Step 2: No key → free tier, done
+    // Step 2: No key → free tier, done. Pro loader is only run for paid tiers.
     if (!licenseKey)
         return;
     // Step 3: Validate
@@ -96,6 +96,20 @@ async function initFeatures(licenseKey, stateDir = DEFAULT_STATE_DIR) {
             // Keep persisted features
         });
     }
+    // Step 4: If the current tier is paid, try to load the Pro extension bundle.
+    // This is best-effort — if loading fails (network, missing tarball, bad
+    // extraction, Pro package throws on activate), OSS defaults remain in effect
+    // and the host keeps running. No user-visible crash.
+    if (isPro()) {
+        try {
+            const { loadPro } = await import("./pro-loader.js");
+            await loadPro(licenseKey, stateDir, hostVersion);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[hicortex][pro] Pro loader failed to import: ${msg}`);
+        }
+    }
 }
 // ---------------------------------------------------------------------------
 // Public API — sync getters used everywhere in the codebase

package/dist/nightly.js

@@ -54,6 +54,7 @@ const storage = __importStar(require("./storage.js"));
 const distiller_js_1 = require("./distiller.js");
 const consolidate_js_1 = require("./consolidate.js");
 const transcript_reader_js_1 = require("./transcript-reader.js");
+const pi_transcript_reader_js_1 = require("./pi-transcript-reader.js");
 const claude_md_js_1 = require("./claude-md.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
@@ -171,14 +172,20 @@ async function runNightly(options = {}) {
             ? `${llmConfig.distillProvider}/${llmConfig.distillModel}@${llmConfig.distillBaseUrl}`
             : llmConfig.distillModel ?? "";
         console.log(`[hicortex] LLM: ${llmConfig.provider}/${llmConfig.model}${distillInfo ? `, distill: ${distillInfo}` : ""}`);
-        // Step 1: Read new CC transcripts
+        // Step 1: Read new transcripts (CC + Pi)
         const since = readLastRun();
-        console.log(`[hicortex] Reading CC transcripts since ${since.toISOString()}`);
-        const batches = (0, transcript_reader_js_1.readCcTranscripts)(since);
-        console.log(`[hicortex] Found ${batches.length} new session(s)`);
+        console.log(`[hicortex] Reading transcripts since ${since.toISOString()}`);
+        const ccBatches = (0, transcript_reader_js_1.readCcTranscripts)(since);
+        const piBatches = (0, pi_transcript_reader_js_1.readPiTranscripts)(since);
+        const batches = [...ccBatches, ...piBatches];
+        if (ccBatches.length > 0)
+            console.log(`[hicortex] Found ${ccBatches.length} CC session(s)`);
+        if (piBatches.length > 0)
+            console.log(`[hicortex] Found ${piBatches.length} Pi session(s)`);
+        console.log(`[hicortex] Total: ${batches.length} new session(s)`);
         if (batches.length === 0 && !dryRun) {
             // Still run consolidation — there may be unscored memories from OC
-            console.log(`[hicortex] No new CC transcripts. Running consolidation only.`);
+            console.log(`[hicortex] No new transcripts. Running consolidation only.`);
         }
         // Step 2: Distill each session
         let memoriesIngested = 0;
@@ -263,15 +270,36 @@ async function runNightly(options = {}) {
         console.log(`[hicortex] Distillation complete: ${memoriesIngested} new memories`);
         // Step 3: Consolidation
         if (!dryRun) {
+            // Pre-flight health check for the reflect endpoint.
+            // If reflectBaseUrl points to a remote Ollama and it's down (MBP offline),
+            // skip reflection entirely instead of waiting through 3 retries (~3.5 min).
+            // Scoring + linking + decay still run (they use the local model or don't need LLM).
+            let skipReflection = false;
+            if (llmConfig.reflectBaseUrl && (llmConfig.reflectProvider ?? llmConfig.provider) === "ollama") {
+                const reflectModel = llmConfig.reflectModel ?? llmConfig.model;
+                const health = await (0, llm_js_1.probeOllamaModel)(llmConfig.reflectBaseUrl, reflectModel);
+                if (!health.ok) {
+                    const reason = health.reason === "unreachable"
+                        ? `reflect endpoint unreachable (${llmConfig.reflectBaseUrl})`
+                        : `reflect model not loaded (${reflectModel} missing on ${llmConfig.reflectBaseUrl})`;
+                    console.warn(`[hicortex] ${reason} — skipping reflection, scoring + linking will still run`);
+                    skipReflection = true;
+                }
+            }
             console.log(`[hicortex] Running consolidation...`);
-            const report = await (0, consolidate_js_1.runConsolidation)(db, llm, embedder_js_1.embed, dryRun);
+            const report = await (0, consolidate_js_1.runConsolidation)(db, llm, embedder_js_1.embed, dryRun, skipReflection);
             console.log(`[hicortex] Consolidation ${report.status} in ${report.elapsed_seconds}s` +
                 (report.stages.reflection ? ` (${report.stages.reflection.lessons_generated} lessons)` : ""));
         }
-        // Step 4: Inject lessons into CLAUDE.md
+        // Step 4: Inject lessons into the target file (CLAUDE.md or EXPERIENCE.md
+        // or custom path — configurable via lessonTarget in config.json)
         if (!dryRun) {
-            const injection = await (0, claude_md_js_1.injectLessons)(db, { stateDir });
-            console.log(`[hicortex] CLAUDE.md updated: ${injection.lessonsCount} lessons at ${injection.path}`);
+            const lessonTarget = savedConfig?.lessonTarget;
+            const injection = await (0, claude_md_js_1.injectLessons)(db, {
+                claudeMdPath: lessonTarget,
+                stateDir,
+            });
+            console.log(`[hicortex] Lessons updated: ${injection.lessonsCount} lessons at ${injection.path}`);
         }
         // Step 5: Update last-run timestamp
         // CRITICAL: only advance lastRun if every session was processed without

package/dist/pi-transcript-reader.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pi agent transcript reader.
+ *
+ * Reads session .jsonl files from ~/.pi/agent/sessions/ in the Pi coding
+ * agent's format. Returns the same TranscriptBatch shape as the CC reader
+ * (transcript-reader.ts) so the downstream distillation pipeline is
+ * format-agnostic.
+ *
+ * Pi JSONL format (version 3):
+ *   session              — session header: {id, cwd, timestamp, version}
+ *   model_change         — provider + model switch (skip for distillation)
+ *   thinking_level_change — thinking mode (skip)
+ *   message              — user/assistant/toolResult conversation entries
+ *   custom               — extension events (skip)
+ *   custom_message       — extension messages (skip)
+ *
+ * Directory layout:
+ *   ~/.pi/agent/sessions/
+ *     --home-agents-Agents-raider--/
+ *       2026-04-10T18-37-44-615Z_<uuid>.jsonl
+ *       2026-04-11T07-51-28-282Z_<uuid>.jsonl
+ *     --home-agents-Development-MAIC--/
+ *       ...
+ *
+ * The encoded-cwd uses double-dash separators: /home/agents/Agents/raider
+ * becomes --home-agents-Agents-raider--. The session header's `cwd` field
+ * is the canonical path; the directory name is a filesystem-safe encoding.
+ */
+export interface TranscriptBatch {
+    sessionId: string;
+    projectName: string;
+    date: string;
+    entries: unknown[];
+}
+/**
+ * Read Pi session transcripts modified after `since`.
+ *
+ * Scans the Pi sessions directory for .jsonl files, filters by mtime,
+ * parses each into a TranscriptBatch.
+ *
+ * @param since Only return sessions with mtime > this date
+ * @param sessionsDir Override the session directory (default: ~/.pi/agent/sessions/)
+ */
+export declare function readPiTranscripts(since: Date, sessionsDir?: string): TranscriptBatch[];

package/dist/pi-transcript-reader.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Pi agent transcript reader.
+ *
+ * Reads session .jsonl files from ~/.pi/agent/sessions/ in the Pi coding
+ * agent's format. Returns the same TranscriptBatch shape as the CC reader
+ * (transcript-reader.ts) so the downstream distillation pipeline is
+ * format-agnostic.
+ *
+ * Pi JSONL format (version 3):
+ *   session              — session header: {id, cwd, timestamp, version}
+ *   model_change         — provider + model switch (skip for distillation)
+ *   thinking_level_change — thinking mode (skip)
+ *   message              — user/assistant/toolResult conversation entries
+ *   custom               — extension events (skip)
+ *   custom_message       — extension messages (skip)
+ *
+ * Directory layout:
+ *   ~/.pi/agent/sessions/
+ *     --home-agents-Agents-raider--/
+ *       2026-04-10T18-37-44-615Z_<uuid>.jsonl
+ *       2026-04-11T07-51-28-282Z_<uuid>.jsonl
+ *     --home-agents-Development-MAIC--/
+ *       ...
+ *
+ * The encoded-cwd uses double-dash separators: /home/agents/Agents/raider
+ * becomes --home-agents-Agents-raider--. The session header's `cwd` field
+ * is the canonical path; the directory name is a filesystem-safe encoding.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPiTranscripts = readPiTranscripts;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const DEFAULT_PI_SESSIONS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".pi", "agent", "sessions");
+/**
+ * Read Pi session transcripts modified after `since`.
+ *
+ * Scans the Pi sessions directory for .jsonl files, filters by mtime,
+ * parses each into a TranscriptBatch.
+ *
+ * @param since Only return sessions with mtime > this date
+ * @param sessionsDir Override the session directory (default: ~/.pi/agent/sessions/)
+ */
+function readPiTranscripts(since, sessionsDir = DEFAULT_PI_SESSIONS_DIR) {
+    const batches = [];
+    let projectDirs;
+    try {
+        projectDirs = (0, node_fs_1.readdirSync)(sessionsDir);
+    }
+    catch {
+        // Directory doesn't exist — no Pi sessions. Not an error.
+        return [];
+    }
+    for (const projectDir of projectDirs) {
+        const projectPath = (0, node_path_1.join)(sessionsDir, projectDir);
+        let files;
+        try {
+            const stat = (0, node_fs_1.statSync)(projectPath);
+            if (!stat.isDirectory())
+                continue;
+            files = (0, node_fs_1.readdirSync)(projectPath).filter((f) => f.endsWith(".jsonl"));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            const filePath = (0, node_path_1.join)(projectPath, file);
+            // Filter by modification time
+            try {
+                const stat = (0, node_fs_1.statSync)(filePath);
+                if (stat.mtime <= since)
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            // Parse the JSONL file
+            try {
+                const raw = (0, node_fs_1.readFileSync)(filePath, "utf-8");
+                const lines = raw.split("\n").filter((l) => l.trim());
+                const entries = [];
+                let sessionId = "";
+                let sessionCwd = "";
+                let sessionDate = "";
+                for (const line of lines) {
+                    try {
+                        const entry = JSON.parse(line);
+                        entries.push(entry);
+                        // Extract metadata from the session header
+                        if (entry.type === "session") {
+                            sessionId = entry.id ?? "";
+                            sessionCwd = entry.cwd ?? "";
+                            // Date from the session timestamp or filename
+                            sessionDate =
+                                entry.timestamp?.slice(0, 10) ??
+                                    extractDateFromFilename(file) ??
+                                    "";
+                        }
+                    }
+                    catch {
+                        // Skip malformed lines
+                    }
+                }
+                // Derive project name from the cwd or directory name
+                const projectName = deriveProjectName(sessionCwd, projectDir);
+                // Use filename UUID as fallback session ID
+                if (!sessionId) {
+                    sessionId = extractUuidFromFilename(file) ?? file;
+                }
+                if (!sessionDate) {
+                    sessionDate = extractDateFromFilename(file) ?? "";
+                }
+                if (entries.length > 0) {
+                    batches.push({
+                        sessionId,
+                        projectName,
+                        date: sessionDate,
+                        entries,
+                    });
+                }
+            }
+            catch {
+                // File read or parse failed — skip
+            }
+        }
+    }
+    return batches;
+}
+/**
+ * Extract the last path segment from a cwd as the project name.
+ * /home/agents/Agents/raider → "raider"
+ * Falls back to decoding the directory name if cwd is empty.
+ */
+function deriveProjectName(cwd, encodedDir) {
+    if (cwd) {
+        const segments = cwd.split("/").filter(Boolean);
+        return segments[segments.length - 1] ?? "unknown";
+    }
+    // Decode the Pi directory encoding: --home-agents-Agents-raider-- → raider
+    const decoded = encodedDir.replace(/^--/, "").replace(/--$/, "").split("-");
+    return decoded[decoded.length - 1] ?? "unknown";
+}
+/**
+ * Extract the date (YYYY-MM-DD) from a Pi session filename.
+ * Format: 2026-04-10T18-37-44-615Z_<uuid>.jsonl → "2026-04-10"
+ */
+function extractDateFromFilename(filename) {
+    const match = filename.match(/^(\d{4}-\d{2}-\d{2})T/);
+    return match ? match[1] : null;
+}
+/**
+ * Extract the UUID from a Pi session filename.
+ * Format: 2026-04-10T18-37-44-615Z_f4227d47-e54f-4977-a50c-4de7f6d1fa21.jsonl
+ */
+function extractUuidFromFilename(filename) {
+    const match = filename.match(/_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/);
+    return match ? match[1] : null;
+}

package/dist/pro-loader.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pro extension loader.
+ *
+ * Called from features.ts at boot when a valid paid license is detected.
+ * Responsibilities:
+ *   1. Check ~/.hicortex/pro/installed.json for the currently-installed
+ *      Pro version (if any).
+ *   2. Fetch GET /api/pro/meta from hicortex.gamaze.com to discover the
+ *      latest available version for the caller's license tier.
+ *   3. If the installed version is older (or missing), download the
+ *      tarball, verify the sha256 sidecar, and extract to ~/.hicortex/pro/.
+ *   4. Dynamic-import ~/.hicortex/pro/package/index.js and call activate()
+ *      on its default export with a ProActivationContext.
+ *
+ * Failure modes (all soft — OSS host keeps running with defaults):
+ *   - Network to /api/pro/meta fails → use whatever is already installed
+ *   - No cached Pro and network fails → Pro not activated, OSS defaults apply
+ *   - Downloaded tarball fails sha256 → abort download, keep old version
+ *   - import() of activated module throws → log warning, keep defaults
+ *
+ * The loader is strictly best-effort. It must NEVER crash the OSS host.
+ */
+/**
+ * Entry point called from features.ts at boot.
+ *
+ * @param licenseKey   The Pro license key (hctx-...) from config
+ * @param stateDir     Usually ~/.hicortex/
+ * @param hostVersion  The version of the OSS host (from package.json) — passed
+ *                     to the Pro activate() for compatibility gating
+ * @param serverUrl    Override for the Pro meta/download endpoint (defaults
+ *                     to https://hicortex.gamaze.com). Useful for testing.
+ */
+export declare function loadPro(licenseKey: string, stateDir: string, hostVersion: string, serverUrl?: string): Promise<void>;

package/dist/pro-loader.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * Pro extension loader.
+ *
+ * Called from features.ts at boot when a valid paid license is detected.
+ * Responsibilities:
+ *   1. Check ~/.hicortex/pro/installed.json for the currently-installed
+ *      Pro version (if any).
+ *   2. Fetch GET /api/pro/meta from hicortex.gamaze.com to discover the
+ *      latest available version for the caller's license tier.
+ *   3. If the installed version is older (or missing), download the
+ *      tarball, verify the sha256 sidecar, and extract to ~/.hicortex/pro/.
+ *   4. Dynamic-import ~/.hicortex/pro/package/index.js and call activate()
+ *      on its default export with a ProActivationContext.
+ *
+ * Failure modes (all soft — OSS host keeps running with defaults):
+ *   - Network to /api/pro/meta fails → use whatever is already installed
+ *   - No cached Pro and network fails → Pro not activated, OSS defaults apply
+ *   - Downloaded tarball fails sha256 → abort download, keep old version
+ *   - import() of activated module throws → log warning, keep defaults
+ *
+ * The loader is strictly best-effort. It must NEVER crash the OSS host.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPro = loadPro;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const node_child_process_1 = require("node:child_process");
+const extensions_js_1 = require("./extensions.js");
+const VALIDATE_URL = "https://hicortex.gamaze.com";
+/**
+ * Entry point called from features.ts at boot.
+ *
+ * @param licenseKey   The Pro license key (hctx-...) from config
+ * @param stateDir     Usually ~/.hicortex/
+ * @param hostVersion  The version of the OSS host (from package.json) — passed
+ *                     to the Pro activate() for compatibility gating
+ * @param serverUrl    Override for the Pro meta/download endpoint (defaults
+ *                     to https://hicortex.gamaze.com). Useful for testing.
+ */
+async function loadPro(licenseKey, stateDir, hostVersion, serverUrl = VALIDATE_URL) {
+    const proRoot = (0, node_path_1.join)(stateDir, "pro");
+    try {
+        (0, node_fs_1.mkdirSync)(proRoot, { recursive: true });
+    }
+    catch {
+        // If we can't even create the dir, there's nothing to load
+        return;
+    }
+    // Step 1: read installed state (if any)
+    const installedStatePath = (0, node_path_1.join)(proRoot, "installed.json");
+    const installed = readInstalledState(installedStatePath);
+    // Step 2: try to fetch the latest meta. Network failure is soft.
+    let meta = null;
+    try {
+        meta = await fetchProMeta(serverUrl, licenseKey);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[hicortex][pro] Could not fetch Pro metadata (${msg}) — using cached version if present`);
+    }
+    // Step 3: if meta is newer than installed, download and extract
+    if (meta && (!installed || installed.version !== meta.version)) {
+        try {
+            await downloadAndExtract(serverUrl, licenseKey, meta, proRoot);
+            writeInstalledState(installedStatePath, {
+                version: meta.version,
+                installedAt: new Date().toISOString(),
+                sha256: meta.sha256,
+            });
+            console.log(`[hicortex][pro] Installed Pro v${meta.version}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[hicortex][pro] Pro download failed: ${msg}`);
+        }
+    }
+    // Step 4: activate whatever is installed (if anything)
+    const indexPath = (0, node_path_1.join)(proRoot, "package", "index.js");
+    if (!(0, node_fs_1.existsSync)(indexPath)) {
+        // No Pro installed and meta fetch couldn't install one
+        return;
+    }
+    try {
+        const mod = await import((0, node_url_1.pathToFileURL)(indexPath).href);
+        const pkg = (mod.default ?? mod);
+        if (typeof pkg?.activate !== "function") {
+            console.warn(`[hicortex][pro] Pro package has no activate() function`);
+            return;
+        }
+        const ctx = (0, extensions_js_1.createProActivationContext)(hostVersion);
+        await pkg.activate(ctx);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[hicortex][pro] Pro activation failed: ${msg}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Implementation helpers
+// ---------------------------------------------------------------------------
+function readInstalledState(path) {
+    try {
+        const raw = (0, node_fs_1.readFileSync)(path, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function writeInstalledState(path, state) {
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+        (0, node_fs_1.writeFileSync)(path, JSON.stringify(state, null, 2));
+    }
+    catch {
+        // Non-fatal — we'll just re-download next boot
+    }
+}
+async function fetchProMeta(serverUrl, licenseKey) {
+    const url = `${serverUrl.replace(/\/$/, "")}/api/pro/meta`;
+    const resp = await fetch(url, {
+        headers: { Authorization: `Bearer ${licenseKey}` },
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (resp.status === 401 || resp.status === 403) {
+        throw new Error(`Pro access denied (HTTP ${resp.status}) — check license key`);
+    }
+    if (resp.status === 404) {
+        throw new Error("No Pro release available yet");
+    }
+    if (!resp.ok) {
+        throw new Error(`HTTP ${resp.status}`);
+    }
+    const data = (await resp.json());
+    if (!data.version || !data.url) {
+        throw new Error("Malformed /api/pro/meta response");
+    }
+    return data;
+}
+async function downloadAndExtract(serverUrl, licenseKey, meta, proRoot) {
+    const downloadUrl = `${serverUrl.replace(/\/$/, "")}${meta.url.startsWith("/") ? "" : "/"}${meta.url}`;
+    const resp = await fetch(downloadUrl, {
+        headers: { Authorization: `Bearer ${licenseKey}` },
+        signal: AbortSignal.timeout(60_000),
+    });
+    if (!resp.ok) {
+        throw new Error(`Download failed with HTTP ${resp.status}`);
+    }
+    // Stream to a temp file so we can verify the hash before extracting
+    const tmpPath = (0, node_path_1.join)(proRoot, `.pro-download-${Date.now()}.tgz`);
+    const buf = Buffer.from(await resp.arrayBuffer());
+    (0, node_fs_1.writeFileSync)(tmpPath, buf);
+    // Verify sha256 if the server provided one
+    if (meta.sha256) {
+        const hash = (0, node_crypto_1.createHash)("sha256").update(buf).digest("hex");
+        if (hash !== meta.sha256) {
+            try {
+                (0, node_fs_1.rmSync)(tmpPath);
+            }
+            catch { /* non-fatal */ }
+            throw new Error(`sha256 mismatch: expected ${meta.sha256}, got ${hash}`);
+        }
+    }
+    // Extract to proRoot (overwrites existing package/ directory)
+    const existingPackageDir = (0, node_path_1.join)(proRoot, "package");
+    if ((0, node_fs_1.existsSync)(existingPackageDir)) {
+        try {
+            (0, node_fs_1.rmSync)(existingPackageDir, { recursive: true, force: true });
+        }
+        catch { /* non-fatal */ }
+    }
+    // Use the system tar to extract (cross-platform, no new dependency)
+    const result = (0, node_child_process_1.spawnSync)("tar", ["-xzf", tmpPath, "-C", proRoot], {
+        encoding: "utf-8",
+    });
+    if (result.status !== 0) {
+        throw new Error(`tar extraction failed: ${result.stderr || "unknown error"}`);
+    }
+    // Clean up the temp tarball
+    try {
+        (0, node_fs_1.rmSync)(tmpPath);
+    }
+    catch { /* non-fatal */ }
+}

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.4.6",
+  "version": "0.5.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.4.6",
+  "version": "0.5.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": {
@@ -50,12 +50,12 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/gamaze-labs/hicortex.git",
-    "directory": "packages/openclaw-plugin"
+    "directory": "packages/hicortex"
   },
   "bugs": {
     "url": "https://github.com/gamaze-labs/hicortex/issues"
   },
-  "author": "Mattias Hansson",
+  "author": "Aironic Ventures Ltd.",
   "dependencies": {
     "@huggingface/transformers": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.28.0",