@gamaze/hicortex 0.4.2 → 0.4.4

package/dist/features.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Centralized feature gating — single source of truth for tier-dependent values.
+ *
+ * Why this exists:
+ *   - getFeatures() in license.ts was sync but validateLicense was async, creating
+ *     a race where Pro users got free-tier features during the validation window.
+ *   - License checks were scattered across 8+ call sites with subtly different
+ *     handling (e.g., consolidate.ts:308 had a dynamic import in a hot loop to
+ *     dodge a circular import).
+ *
+ * All feature decisions now flow through this module. Call initFeatures() once at
+ * process boot before serving any requests; sync getters become deterministic.
+ */
+import type { LicenseInfo } from "./types.js";
+/**
+ * Initialize the feature cache. Call ONCE at process boot before any feature
+ * gating queries. Race fix:
+ *   1. Synchronously load persisted tier from disk (instant, deterministic)
+ *   2. If no persisted tier and we have a key, AWAIT first validation
+ *   3. If persisted tier exists, kick off background re-validation
+ *
+ * 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>;
+/** Are we on a paid tier (Pro, Team, Lifetime)? */
+export declare function isPro(): boolean;
+/** Memory count cap. -1 = unlimited (paid). */
+export declare function maxMemoriesAllowed(): number;
+/** Has the memory cap been hit? Pass current count from caller. */
+export declare function memoryCapReached(currentCount: number): boolean;
+/** Number of lessons to inject into CLAUDE.md / before_agent_start. */
+export declare function lessonsLimit(): number;
+/** Is remote /ingest allowed? Free + Team yes, Pro (single-machine) no. */
+export declare function remoteIngestAllowed(): boolean;
+/** Direct read of the underlying features (for callers that need the full record). */
+export declare function getCurrentFeatures(): LicenseInfo["features"];

package/dist/features.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Centralized feature gating — single source of truth for tier-dependent values.
+ *
+ * Why this exists:
+ *   - getFeatures() in license.ts was sync but validateLicense was async, creating
+ *     a race where Pro users got free-tier features during the validation window.
+ *   - License checks were scattered across 8+ call sites with subtly different
+ *     handling (e.g., consolidate.ts:308 had a dynamic import in a hot loop to
+ *     dodge a circular import).
+ *
+ * All feature decisions now flow through this module. Call initFeatures() once at
+ * process boot before serving any requests; sync getters become deterministic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initFeatures = initFeatures;
+exports.isPro = isPro;
+exports.maxMemoriesAllowed = maxMemoriesAllowed;
+exports.memoryCapReached = memoryCapReached;
+exports.lessonsLimit = lessonsLimit;
+exports.remoteIngestAllowed = remoteIngestAllowed;
+exports.getCurrentFeatures = getCurrentFeatures;
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const license_js_1 = require("./license.js");
+const state_js_1 = require("./state.js");
+const DEFAULT_STATE_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
+const FREE_FEATURES = {
+    reflection: true,
+    vectorSearch: true,
+    maxMemories: 250,
+    crossAgent: true,
+    remoteIngest: true,
+};
+let currentFeatures = FREE_FEATURES;
+let initialized = false;
+function persistTier(stateDir, info) {
+    (0, state_js_1.updateState)((s) => {
+        s.tier = {
+            tier: info.tier,
+            validatedAt: new Date().toISOString(),
+            features: info.features,
+        };
+        return s;
+    }, stateDir);
+}
+/**
+ * Initialize the feature cache. Call ONCE at process boot before any feature
+ * gating queries. Race fix:
+ *   1. Synchronously load persisted tier from disk (instant, deterministic)
+ *   2. If no persisted tier and we have a key, AWAIT first validation
+ *   3. If persisted tier exists, kick off background re-validation
+ *
+ * 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) {
+    if (initialized)
+        return;
+    initialized = true;
+    // Step 1: Load persisted tier from state.json (instant)
+    const persisted = (0, state_js_1.loadState)(stateDir).tier;
+    if (persisted) {
+        currentFeatures = persisted.features;
+    }
+    else {
+        currentFeatures = FREE_FEATURES;
+    }
+    // Step 2: No key → free tier, done
+    if (!licenseKey)
+        return;
+    // Step 3: Validate
+    if (!persisted) {
+        // First-time: AWAIT validation so the very first request sees the right tier
+        try {
+            const info = await (0, license_js_1.validateLicense)(licenseKey, stateDir);
+            currentFeatures = info.features;
+            if (info.valid) {
+                persistTier(stateDir, info);
+            }
+        }
+        catch {
+            // Validation failed (network, etc.) — stay on free
+        }
+    }
+    else {
+        // Already have a persisted tier; re-validate in background
+        (0, license_js_1.validateLicense)(licenseKey, stateDir)
+            .then((info) => {
+            currentFeatures = info.features;
+            if (info.valid) {
+                persistTier(stateDir, info);
+            }
+        })
+            .catch(() => {
+            // Keep persisted features
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API — sync getters used everywhere in the codebase
+// ---------------------------------------------------------------------------
+/** Are we on a paid tier (Pro, Team, Lifetime)? */
+function isPro() {
+    return currentFeatures.maxMemories === -1;
+}
+/** Memory count cap. -1 = unlimited (paid). */
+function maxMemoriesAllowed() {
+    return currentFeatures.maxMemories;
+}
+/** Has the memory cap been hit? Pass current count from caller. */
+function memoryCapReached(currentCount) {
+    const max = maxMemoriesAllowed();
+    return max > 0 && currentCount >= max;
+}
+/** Number of lessons to inject into CLAUDE.md / before_agent_start. */
+function lessonsLimit() {
+    return isPro() ? 20 : 10;
+}
+/** Is remote /ingest allowed? Free + Team yes, Pro (single-machine) no. */
+function remoteIngestAllowed() {
+    return currentFeatures.remoteIngest !== false;
+}
+/** Direct read of the underlying features (for callers that need the full record). */
+function getCurrentFeatures() {
+    return currentFeatures;
+}

package/dist/index.js

@@ -42,7 +42,9 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_path_1 = require("node:path");
 const db_js_1 = require("./db.js");
-const license_js_1 = require("./license.js");
+const features_js_1 = require("./features.js");
+const extensions_js_1 = require("./extensions.js");
+const state_js_1 = require("./state.js");
 const llm_js_1 = require("./llm.js");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
@@ -87,8 +89,10 @@ exports.default = {
                 llm = new llm_js_1.LlmClient(llmConfig);
                 log(`[hicortex] LLM: ${llmConfig.provider}/${llmConfig.model} ` +
                     `(reflect: ${llmConfig.reflectModel})`);
-                // License check (non-blocking)
-                (0, license_js_1.validateLicense)(config.licenseKey, stateDir).catch((err) => log(`[hicortex] License validation failed: ${err}`));
+                // One-time migration of legacy state files (no-op if state.json exists)
+                (0, state_js_1.migrateLegacyState)(stateDir);
+                // License: init feature cache (sync after this returns)
+                await (0, features_js_1.initFeatures)(config.licenseKey, stateDir);
                 // Schedule nightly consolidation
                 const consolidateHour = config.consolidateHour ?? 2;
                 cancelConsolidation = (0, consolidate_js_1.scheduleConsolidation)(db, llm, embedder_js_1.embed, consolidateHour);
@@ -123,9 +127,13 @@ exports.default = {
                 const lessons = storage.getLessons(db, 7, ctx.project);
                 if (lessons.length === 0)
                     return {};
-                const maxFeatures = (0, license_js_1.getFeatures)(stateDir);
-                const maxLessons = maxFeatures.maxMemories === -1 ? 20 : 10;
-                const formatted = lessons.slice(0, maxLessons).map((l) => {
+                const maxLessons = (0, features_js_1.lessonsLimit)();
+                const selected = await (0, extensions_js_1.getLessonSelector)().select(lessons, {
+                    maxLessons,
+                    project: ctx.project,
+                    agentId: ctx.agentId,
+                });
+                const formatted = selected.map((l) => {
                     // Extract just the lesson text from the structured content
                     const match = l.content.match(/## Lesson: (.+)/);
                     return match ? `- ${match[1]}` : `- ${l.content.slice(0, 200)}`;
@@ -136,9 +144,9 @@ exports.default = {
                     "\n";
                 // Daily friendly reminder when at memory cap
                 const memCount = storage.countMemories(db);
-                if (maxFeatures.maxMemories > 0 && memCount >= maxFeatures.maxMemories) {
+                if ((0, features_js_1.memoryCapReached)(memCount)) {
                     context +=
-                        `\n---\nHicortex free tier: ${maxFeatures.maxMemories} memories stored. ` +
+                        `\n---\nHicortex free tier: ${(0, features_js_1.maxMemoriesAllowed)()} memories stored. ` +
                             `New memories can no longer be saved, and your agent has stopped learning and self-improving from new sessions. ` +
                             `Existing memories, lessons, and search still work. ` +
                             `Upgrade for unlimited usage: https://hicortex.gamaze.com/ ` +
@@ -169,10 +177,8 @@ exports.default = {
                 if (entries.length === 0)
                     return;
                 // Check license cap
-                const features = (0, license_js_1.getFeatures)(stateDir);
-                if (features.maxMemories > 0 &&
-                    storage.countMemories(db) >= features.maxMemories) {
-                    console.warn(`[hicortex] Free tier limit reached (${features.maxMemories} memories). ` +
+                if ((0, features_js_1.memoryCapReached)(storage.countMemories(db))) {
+                    console.warn(`[hicortex] Free tier limit reached (${(0, features_js_1.maxMemoriesAllowed)()} memories). ` +
                         `Search and lessons still work, but new memories won't be saved. ` +
                         `Upgrade for unlimited usage: https://hicortex.gamaze.com/`);
                     return;
@@ -299,12 +305,11 @@ exports.default = {
             async execute(_callId, args, context) {
                 if (!db)
                     return { error: "Hicortex not initialized" };
-                const features = (0, license_js_1.getFeatures)(stateDir);
-                if (features.maxMemories > 0 && storage.countMemories(db) >= features.maxMemories) {
+                if ((0, features_js_1.memoryCapReached)(storage.countMemories(db))) {
                     return {
                         content: [{
                                 type: "text",
-                                text: `Free tier limit reached (${features.maxMemories} memories). ` +
+                                text: `Free tier limit reached (${(0, features_js_1.maxMemoriesAllowed)()} memories). ` +
                                     `Your existing memories and lessons still work — search and recall are unaffected. ` +
                                     `New memories won't be saved until you upgrade.\n\n` +
                                     `Upgrade for unlimited usage: https://hicortex.gamaze.com/`
@@ -529,26 +534,6 @@ function persistProviderConfig(llmConfig, log) {
         // Non-fatal — config works in memory even if we can't persist
     }
 }
-/**
- * Track when the memory cap was first hit. Returns days since cap was reached.
- * Stores timestamp in stateDir/cap-hit.txt on first detection.
- */
-function getDaysSinceCapHit(dir) {
-    const capFile = (0, node_path_1.join)(dir, "cap-hit.txt");
-    try {
-        const ts = (0, node_fs_1.readFileSync)(capFile, "utf-8").trim();
-        const hitDate = new Date(ts);
-        return Math.floor((Date.now() - hitDate.getTime()) / (1000 * 60 * 60 * 24));
-    }
-    catch {
-        // First time hitting cap — record it
-        try {
-            (0, node_fs_1.writeFileSync)(capFile, new Date().toISOString());
-        }
-        catch { /* non-fatal */ }
-        return 0;
-    }
-}
 const HICORTEX_TOOLS = [
     "hicortex_search",
     "hicortex_context",

package/dist/license.d.ts

@@ -1,5 +1,15 @@
+/**
+ * License API client.
+ *
+ * This module is a thin wrapper over the validation HTTP endpoint at
+ * https://hicortex.gamaze.com/api/validate. Persistence and feature gating
+ * live in features.ts + state.ts; this file does NOT touch disk.
+ *
+ * Offline grace: when the API is unreachable, we fall back to the cached
+ * tier in state.json (written by features.ts on the last successful
+ * validation). If the cached tier was validated within OFFLINE_GRACE_DAYS,
+ * we treat it as still valid.
+ */
 import type { LicenseInfo } from "./types.js";
-/** Validate a license key against the Hicortex API */
+/** Validate a license key against the Hicortex API. */
 export declare function validateLicense(key: string | undefined, stateDir: string): Promise<LicenseInfo>;
-/** Get current features, using cache or free tier defaults */
-export declare function getFeatures(stateDir: string): LicenseInfo["features"];

package/dist/license.js

@@ -1,13 +1,23 @@
 "use strict";
+/**
+ * License API client.
+ *
+ * This module is a thin wrapper over the validation HTTP endpoint at
+ * https://hicortex.gamaze.com/api/validate. Persistence and feature gating
+ * live in features.ts + state.ts; this file does NOT touch disk.
+ *
+ * Offline grace: when the API is unreachable, we fall back to the cached
+ * tier in state.json (written by features.ts on the last successful
+ * validation). If the cached tier was validated within OFFLINE_GRACE_DAYS,
+ * we treat it as still valid.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateLicense = validateLicense;
-exports.getFeatures = getFeatures;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
+const state_js_1 = require("./state.js");
 const VALIDATE_URL = "https://hicortex.gamaze.com/api/validate";
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const OFFLINE_GRACE_DAYS = 7;
-// In-memory cache
+// In-memory cache for the current process
 let cachedLicense = null;
 let cacheTimestamp = 0;
 const FREE_LICENSE = {
@@ -21,12 +31,12 @@ const FREE_LICENSE = {
         remoteIngest: true,
     },
 };
-/** Validate a license key against the Hicortex API */
+/** Validate a license key against the Hicortex API. */
 async function validateLicense(key, stateDir) {
     // No key = free tier
     if (!key)
         return FREE_LICENSE;
-    // Check in-memory cache
+    // Check in-memory cache (24h TTL)
     if (cachedLicense && Date.now() - cacheTimestamp < CACHE_TTL_MS) {
         return cachedLicense;
     }
@@ -41,57 +51,36 @@ async function validateLicense(key, stateDir) {
             throw new Error(`HTTP ${resp.status}`);
         }
         const data = (await resp.json());
-        // Cache result
         cachedLicense = data;
         cacheTimestamp = Date.now();
-        // Persist last successful validation timestamp for offline grace
-        if (data.valid) {
-            persistValidationTimestamp(stateDir);
-        }
         return data;
     }
     catch {
-        // Network failure — check offline grace period
-        return offlineFallback(key, stateDir);
-    }
-}
-/** Get current features, using cache or free tier defaults */
-function getFeatures(stateDir) {
-    if (cachedLicense)
-        return cachedLicense.features;
-    return FREE_LICENSE.features;
-}
-function persistValidationTimestamp(stateDir) {
-    try {
-        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(stateDir, "license-validated.txt"), new Date().toISOString());
-    }
-    catch {
-        // Non-critical
+        // Network failure — check offline grace period via state.tier
+        return offlineFallback(stateDir);
     }
 }
-function offlineFallback(key, stateDir) {
-    const tsPath = (0, node_path_1.join)(stateDir, "license-validated.txt");
-    if (!(0, node_fs_1.existsSync)(tsPath))
+/**
+ * Offline fallback: if state.tier was validated within the grace period,
+ * return its cached features as if validation succeeded. Otherwise, free tier.
+ */
+function offlineFallback(stateDir) {
+    const persisted = (0, state_js_1.loadState)(stateDir).tier;
+    if (!persisted)
         return FREE_LICENSE;
     try {
-        const lastValidated = new Date((0, node_fs_1.readFileSync)(tsPath, "utf-8").trim());
+        const lastValidated = new Date(persisted.validatedAt);
         const daysSince = (Date.now() - lastValidated.getTime()) / (1000 * 60 * 60 * 24);
         if (daysSince <= OFFLINE_GRACE_DAYS) {
-            // Within grace period — assume last known state was valid
-            return cachedLicense ?? {
+            return {
                 valid: true,
-                tier: "pro",
-                features: {
-                    reflection: true,
-                    vectorSearch: true,
-                    maxMemories: -1,
-                    crossAgent: true,
-                },
+                tier: persisted.tier,
+                features: persisted.features,
             };
         }
     }
     catch {
-        // Corrupted file
+        // Corrupted timestamp — fall through
     }
     return FREE_LICENSE;
 }

package/dist/mcp-server.js

@@ -55,7 +55,8 @@ const sse_js_1 = require("@modelcontextprotocol/sdk/server/sse.js");
 const zod_1 = require("zod");
 const db_js_1 = require("./db.js");
 const llm_js_1 = require("./llm.js");
-const license_js_1 = require("./license.js");
+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 retrieval = __importStar(require("./retrieval.js"));
@@ -121,12 +122,11 @@ function createMcpServer() {
     }, async ({ content, project, memory_type }) => {
         if (!db)
             return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
-        const features = (0, license_js_1.getFeatures)(stateDir);
-        if (features.maxMemories > 0 && storage.countMemories(db) >= features.maxMemories) {
+        if ((0, features_js_1.memoryCapReached)(storage.countMemories(db))) {
             return {
                 content: [{
                         type: "text",
-                        text: `Free tier limit reached (${features.maxMemories} memories). ` +
+                        text: `Free tier limit reached (${(0, features_js_1.maxMemoriesAllowed)()} memories). ` +
                             `Your existing memories and lessons still work — search and recall are unaffected. ` +
                             `New memories won't be saved until you upgrade.\n\n` +
                             `Upgrade for unlimited usage: https://hicortex.gamaze.com/`
@@ -296,11 +296,13 @@ async function startServer(options = {}) {
         ? `${llmConfig.reflectProvider}/${llmConfig.reflectModel}@${llmConfig.reflectBaseUrl}`
         : llmConfig.reflectModel;
     console.log(`[hicortex] LLM fast: ${llmConfig.provider}/${llmConfig.model}${distillInfo ? `, distill: ${distillInfo}` : ""}, reflect: ${reflectInfo}`);
-    // License: read from options, config file, or env var
+    // One-time migration of legacy state files (no-op if state.json exists)
+    (0, state_js_1.migrateLegacyState)(stateDir);
+    // License: read from options, config file, or env var, init feature cache
     const licenseKey = options.licenseKey
         ?? savedConfig?.licenseKey
         ?? process.env.HICORTEX_LICENSE_KEY;
-    (0, license_js_1.validateLicense)(licenseKey, stateDir).catch((err) => console.log(`[hicortex] License validation failed: ${err}`));
+    await (0, features_js_1.initFeatures)(licenseKey, stateDir);
     if (licenseKey) {
         console.log(`[hicortex] License key configured`);
     }
@@ -368,6 +370,40 @@ async function startServer(options = {}) {
             llm: `${llmConfig.provider}/${llmConfig.model}`,
         });
     });
+    // REST /lessons — return lessons + memory index for client CLAUDE.md injection
+    app.get("/lessons", (_req, res) => {
+        if (!db) {
+            res.status(503).json({ error: "Server not initialized" });
+            return;
+        }
+        try {
+            const lessons = storage.getLessons(db, 30);
+            const totalCount = storage.countMemories(db);
+            // Project index
+            const projects = db
+                .prepare("SELECT project, COUNT(*) as cnt FROM memories WHERE project IS NOT NULL GROUP BY project ORDER BY cnt DESC LIMIT 10")
+                .all();
+            const sourceCount = db.prepare("SELECT COUNT(DISTINCT source_agent) as cnt FROM memories").get().cnt;
+            const lessonCount = lessons.length;
+            res.json({
+                lessons: lessons.map(l => ({
+                    content: l.content,
+                    created_at: l.created_at,
+                    base_strength: l.base_strength,
+                    access_count: l.access_count,
+                })),
+                index: {
+                    total: totalCount,
+                    lessonCount,
+                    sourceCount,
+                    projects: projects.map(p => ({ name: p.project, count: p.cnt })),
+                },
+            });
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
     // REST /ingest — accept pre-distilled memories from remote clients
     app.post("/ingest", async (req, res) => {
         if (!db) {
@@ -377,15 +413,12 @@ async function startServer(options = {}) {
         // Pro license blocks remote ingest (upgrade to Team for multi-client)
         const ip = req.ip ?? req.socket.remoteAddress ?? "";
         const isLocal = ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1";
-        if (!isLocal) {
-            const features = (0, license_js_1.getFeatures)(stateDir);
-            if (features.remoteIngest === false) {
-                res.status(403).json({
-                    error: "Pro license is single-machine. Upgrade to Team for multi-client remote ingestion.",
-                    upgrade: "https://hicortex.gamaze.com/",
-                });
-                return;
-            }
+        if (!isLocal && !(0, features_js_1.remoteIngestAllowed)()) {
+            res.status(403).json({
+                error: "Pro license is single-machine. Upgrade to Team for multi-client remote ingestion.",
+                upgrade: "https://hicortex.gamaze.com/",
+            });
+            return;
         }
         const { content, source_agent, project, memory_type, privacy, source_session, session_date } = req.body ?? {};
         if (!content || typeof content !== "string") {
@@ -406,9 +439,8 @@ async function startServer(options = {}) {
             }
         }
         // License check
-        const features = (0, license_js_1.getFeatures)(stateDir);
-        if (features.maxMemories > 0 && storage.countMemories(db) >= features.maxMemories) {
-            res.status(429).json({ error: "Memory limit reached", limit: features.maxMemories });
+        if ((0, features_js_1.memoryCapReached)(storage.countMemories(db))) {
+            res.status(429).json({ error: "Memory limit reached", limit: (0, features_js_1.maxMemoriesAllowed)() });
             return;
         }
         try {

package/dist/nightly-status.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Nightly pipeline status — lightweight check without running the pipeline.
+ *
+ * Shows:
+ *   - Last run timestamp + age
+ *   - Timer/schedule status (systemd/launchd)
+ *   - DB memory count
+ *   - Distillation source breakdown
+ *   - Staleness warnings
+ */
+export declare function showNightlyStatus(): Promise<void>;