@gamaze/hicortex 0.7.1 → 0.10.0

package/dist/lesson-selection.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Domain-aware lesson selection engine — the DEFAULT selector for all installs.
+ *
+ * History: originally shipped as a Pro feature (src/pro/selection.ts), deleted
+ * with the Pro loader in #122, restored into core in #123. Free personal
+ * self-host = the full product; there is no gated variant of this selector.
+ *
+ * Behaviour: score each lesson by four axes, pick the top N, dedup
+ * semantically-adjacent entries by normalized-prefix matching.
+ *
+ * Scoring formula:
+ *   score = w_project * project_match
+ *         + w_recency * recency_score
+ *         + w_strength * base_strength
+ *         + w_access * access_affinity
+ *
+ * where:
+ *   project_match:
+ *     1.0 if lesson.project === ctx.project
+ *     0.5 if lesson.project is in the same knowledge domain (via ctx.moduleIndex)
+ *     0.3 if lesson.project === "global"
+ *     0.0 otherwise
+ *
+ *   recency_score:
+ *     exp(-age_days / half_life_days) in [0, 1]
+ *     half_life_days = 30 — lessons fade to half weight after 30 days
+ *
+ *   base_strength:
+ *     lesson.base_strength from the DB (already in [0, 1])
+ *     represents the importance score from the nightly reflection stage
+ *
+ *   access_affinity:
+ *     min(access_count / 5, 1.0)  — capped at 5 accesses
+ *     lessons that have been retrieved before get a small boost
+ *
+ * Default weights:
+ *   w_project = 0.40  (in-project relevance matters most)
+ *   w_recency = 0.25  (newer lessons preferred)
+ *   w_strength = 0.25 (important lessons preferred)
+ *   w_access = 0.10   (proven-useful lessons preferred)
+ *
+ * After scoring, lessons are sorted high-to-low, then deduplicated via
+ * prefix matching: a lesson is considered a duplicate of an already-selected
+ * lesson if its normalized content is a prefix of the other (or vice versa),
+ * with at least 30 characters in common. This catches lessons that were
+ * rewritten slightly across nightly runs — e.g. "Always validate input" vs
+ * "Always validate input before processing any data". The 30-char floor
+ * prevents false positives on genuinely short, distinct lessons.
+ *
+ * When all lessons score identically (no project/date/strength metadata),
+ * the sort is stable, so input order is preserved — equivalent to the old
+ * slice(0, N) behaviour for metadata-free candidate pools.
+ *
+ * Generic over T so the same function handles:
+ *   - Memory[] from local DB queries (server mode)
+ *   - {content, created_at, base_strength, access_count} HTTP shape (client mode)
+ */
+import type { LessonSelector } from "./extensions.js";
+/**
+ * The domain-aware lesson selector. Registered as the default in extensions.ts.
+ */
+export declare const domainAwareLessonSelector: LessonSelector;

package/dist/lesson-selection.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Domain-aware lesson selection engine — the DEFAULT selector for all installs.
+ *
+ * History: originally shipped as a Pro feature (src/pro/selection.ts), deleted
+ * with the Pro loader in #122, restored into core in #123. Free personal
+ * self-host = the full product; there is no gated variant of this selector.
+ *
+ * Behaviour: score each lesson by four axes, pick the top N, dedup
+ * semantically-adjacent entries by normalized-prefix matching.
+ *
+ * Scoring formula:
+ *   score = w_project * project_match
+ *         + w_recency * recency_score
+ *         + w_strength * base_strength
+ *         + w_access * access_affinity
+ *
+ * where:
+ *   project_match:
+ *     1.0 if lesson.project === ctx.project
+ *     0.5 if lesson.project is in the same knowledge domain (via ctx.moduleIndex)
+ *     0.3 if lesson.project === "global"
+ *     0.0 otherwise
+ *
+ *   recency_score:
+ *     exp(-age_days / half_life_days) in [0, 1]
+ *     half_life_days = 30 — lessons fade to half weight after 30 days
+ *
+ *   base_strength:
+ *     lesson.base_strength from the DB (already in [0, 1])
+ *     represents the importance score from the nightly reflection stage
+ *
+ *   access_affinity:
+ *     min(access_count / 5, 1.0)  — capped at 5 accesses
+ *     lessons that have been retrieved before get a small boost
+ *
+ * Default weights:
+ *   w_project = 0.40  (in-project relevance matters most)
+ *   w_recency = 0.25  (newer lessons preferred)
+ *   w_strength = 0.25 (important lessons preferred)
+ *   w_access = 0.10   (proven-useful lessons preferred)
+ *
+ * After scoring, lessons are sorted high-to-low, then deduplicated via
+ * prefix matching: a lesson is considered a duplicate of an already-selected
+ * lesson if its normalized content is a prefix of the other (or vice versa),
+ * with at least 30 characters in common. This catches lessons that were
+ * rewritten slightly across nightly runs — e.g. "Always validate input" vs
+ * "Always validate input before processing any data". The 30-char floor
+ * prevents false positives on genuinely short, distinct lessons.
+ *
+ * When all lessons score identically (no project/date/strength metadata),
+ * the sort is stable, so input order is preserved — equivalent to the old
+ * slice(0, N) behaviour for metadata-free candidate pools.
+ *
+ * Generic over T so the same function handles:
+ *   - Memory[] from local DB queries (server mode)
+ *   - {content, created_at, base_strength, access_count} HTTP shape (client mode)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.domainAwareLessonSelector = void 0;
+const W_PROJECT = 0.40;
+const W_RECENCY = 0.25;
+const W_STRENGTH = 0.25;
+const W_ACCESS = 0.10;
+const RECENCY_HALF_LIFE_DAYS = 30;
+function parseDate(ts) {
+    if (!ts)
+        return null;
+    const d = new Date(ts);
+    return isNaN(d.getTime()) ? null : d;
+}
+function projectMatch(lesson, targetProject, moduleIndex) {
+    if (!lesson.project)
+        return 0.0;
+    if (targetProject && lesson.project === targetProject)
+        return 1.0;
+    if (lesson.project === "global")
+        return 0.3;
+    // Domain-aware: same domain = 0.5
+    if (targetProject && moduleIndex) {
+        const targetDomain = moduleIndex.domains.find((d) => d.projects.includes(targetProject));
+        if (targetDomain && targetDomain.projects.includes(lesson.project)) {
+            return 0.5;
+        }
+    }
+    return 0.0;
+}
+function recencyScore(lesson, now) {
+    const created = parseDate(lesson.created_at);
+    if (!created)
+        return 0.5; // unknown date → neutral score
+    const ageMs = now.getTime() - created.getTime();
+    const ageDays = ageMs / (1000 * 60 * 60 * 24);
+    if (ageDays < 0)
+        return 1.0; // future-dated, treat as very recent
+    return Math.exp(-ageDays / RECENCY_HALF_LIFE_DAYS);
+}
+function accessAffinity(lesson) {
+    const count = lesson.access_count ?? 0;
+    return Math.min(count / 5, 1.0);
+}
+/**
+ * Normalize a lesson's content to its canonical form for prefix comparison.
+ * Lowercase, collapse whitespace, trim. Full content is preserved so prefix
+ * matching below can handle lessons of different lengths.
+ */
+function dedupKey(lesson) {
+    return lesson.content.toLowerCase().replace(/\s+/g, " ").trim();
+}
+/**
+ * Minimum shared-prefix length for two lessons to be considered duplicates.
+ * Shorter values cause false positives on genuinely distinct short lessons;
+ * longer values miss legitimate duplicates that happen to differ in the
+ * first few dozen characters.
+ */
+const DEDUP_MIN_SHARED_PREFIX = 30;
+function isPrefixDuplicate(candidate, existing) {
+    const shorter = candidate.length < existing.length ? candidate : existing;
+    const longer = candidate.length < existing.length ? existing : candidate;
+    return shorter.length >= DEDUP_MIN_SHARED_PREFIX && longer.startsWith(shorter);
+}
+/**
+ * The domain-aware lesson selector. Registered as the default in extensions.ts.
+ */
+exports.domainAwareLessonSelector = {
+    select(lessons, ctx) {
+        if (lessons.length === 0)
+            return [];
+        const now = new Date();
+        // Score every lesson
+        const scored = lessons.map((lesson) => {
+            const pMatch = projectMatch(lesson, ctx.project, ctx.moduleIndex);
+            const rScore = recencyScore(lesson, now);
+            const sScore = lesson.base_strength ?? 0.5;
+            const aScore = accessAffinity(lesson);
+            const score = W_PROJECT * pMatch +
+                W_RECENCY * rScore +
+                W_STRENGTH * sScore +
+                W_ACCESS * aScore;
+            return { lesson, score };
+        });
+        // Sort high → low (Array.prototype.sort is stable — equal scores keep input order)
+        scored.sort((a, b) => b.score - a.score);
+        // Select top N with prefix-based dedup
+        const selected = [];
+        const selectedKeys = [];
+        for (const { lesson } of scored) {
+            if (selected.length >= ctx.maxLessons)
+                break;
+            const key = dedupKey(lesson);
+            const isDup = selectedKeys.some((existing) => isPrefixDuplicate(key, existing));
+            if (isDup)
+                continue;
+            selectedKeys.push(key);
+            selected.push(lesson);
+        }
+        return selected;
+    },
+};

package/dist/lessons-context.d.ts

@@ -0,0 +1,17 @@
+/**
+ * lessons-context — query-time lessons fetch for the CC SessionStart hook.
+ *
+ * Replaces file-based injection (injectLessons / injectLessonsFromServer).
+ * Reads ~/.hicortex/config.json to find the server URL, GETs /lessons,
+ * and prints a compact Markdown block to stdout so CC picks it up as
+ * session context.
+ *
+ * Fail-soft by design: ANY failure (missing config, network error, non-2xx,
+ * parse error) results in silent exit-0. A broken hook must never block a
+ * CC session.
+ */
+/**
+ * Fetch lessons from the configured server and return a formatted Markdown
+ * block, or null on any failure (caller should print nothing and exit 0).
+ */
+export declare function fetchLessonsContext(): Promise<string | null>;

package/dist/lessons-context.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * lessons-context — query-time lessons fetch for the CC SessionStart hook.
+ *
+ * Replaces file-based injection (injectLessons / injectLessonsFromServer).
+ * Reads ~/.hicortex/config.json to find the server URL, GETs /lessons,
+ * and prints a compact Markdown block to stdout so CC picks it up as
+ * session context.
+ *
+ * Fail-soft by design: ANY failure (missing config, network error, non-2xx,
+ * parse error) results in silent exit-0. A broken hook must never block a
+ * CC session.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchLessonsContext = fetchLessonsContext;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const features_js_1 = require("./features.js");
+const extensions_js_1 = require("./extensions.js");
+const state_js_1 = require("./state.js");
+const HICORTEX_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
+const DEFAULT_PORT = 8787;
+/**
+ * Fetch lessons from the configured server and return a formatted Markdown
+ * block, or null on any failure (caller should print nothing and exit 0).
+ */
+async function fetchLessonsContext() {
+    let config = {};
+    try {
+        config = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(HICORTEX_HOME, "config.json"), "utf-8"));
+    }
+    catch {
+        // No config file — server not set up yet. Fail soft.
+        return null;
+    }
+    // Determine server URL: client mode uses serverUrl; server mode uses localhost.
+    const serverUrl = config.mode === "client" && typeof config.serverUrl === "string"
+        ? config.serverUrl.replace(/\/+$/, "")
+        : `http://127.0.0.1:${config.port ?? DEFAULT_PORT}`;
+    const authToken = config.authToken;
+    let data;
+    try {
+        const resp = await fetch(`${serverUrl}/lessons`, {
+            headers: authToken ? { "Authorization": `Bearer ${authToken}` } : {},
+            signal: AbortSignal.timeout(3000),
+        });
+        if (!resp.ok)
+            return null;
+        data = await resp.json();
+    }
+    catch {
+        return null;
+    }
+    const maxLessons = (0, features_js_1.lessonsLimit)();
+    const moduleIndex = data.moduleIndex ?? (0, state_js_1.loadState)(HICORTEX_HOME).moduleIndex;
+    // The SessionStart hook runs in the session's working directory, whose last
+    // path component matches the capture-side CC project name convention
+    // (transcript-reader's decodeProjectDirName also takes the last component).
+    // This enables in-project + same-domain lesson boosting on the CC path.
+    const project = (0, node_path_1.basename)(process.cwd()) || null;
+    const selected = await (0, extensions_js_1.getLessonSelector)().select(data.lessons, { maxLessons, moduleIndex, project });
+    const lessonLines = selected.map((l) => {
+        const titleMatch = l.content.match(/## Lesson: (.+)/);
+        const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);
+        const severityMatch = l.content.match(/\*\*Severity:\*\* (\w+)/);
+        const title = titleMatch ? titleMatch[1] : l.content.slice(0, 150);
+        const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
+        return `- ${title}${meta ? ` (${meta})` : ""}`;
+    });
+    const parts = ["## Hicortex Memory", ""];
+    parts.push("You have access to shared long-term memory across all agents and sessions.");
+    parts.push("BEFORE making decisions, search memory: `hicortex_search` for prior decisions on the same topic.");
+    parts.push("Use `hicortex_context` at session start for recent project state.");
+    if (lessonLines.length > 0) {
+        parts.push("", "### Lessons (updated nightly)");
+        parts.push(...lessonLines);
+    }
+    // Memory index
+    const { index } = data;
+    if (moduleIndex && moduleIndex.domains.length > 0) {
+        parts.push("", "### Memory Index");
+        for (const domain of moduleIndex.domains) {
+            const kwStr = domain.keywords.length > 0 ? `: ${domain.keywords.join(", ")}` : "";
+            parts.push(`${domain.name} (${domain.memoryCount} memories, ${domain.lessonCount} lessons)${kwStr}`);
+            parts.push(`  ${domain.projects.join(" | ")}`);
+        }
+        parts.push(`${index.total} memories, ${index.lessonCount} lessons, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
+    }
+    else if (index.projects.length > 0) {
+        parts.push("", "### Memory Index");
+        parts.push(index.projects.map(p => `${p.name}: ${p.count}`).join(" | "));
+        parts.push(`${index.total} memories, ${index.lessonCount} lessons, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
+    }
+    return parts.join("\n");
+}

package/dist/llm.d.ts

@@ -1,19 +1,14 @@
 /**
  * Multi-provider LLM client for consolidation and distillation.
  *
- * Resolution for OC adapter (resolveLlmConfig):
- *   1. Plugin config (llmBaseUrl, llmApiKey, llmModel)
- *   2. ~/.openclaw/openclaw.json agents.defaults.model.primary
- *   3. Environment vars: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY
- *   4. Fallback: Ollama at http://localhost:11434
+ * Resolution (resolveExplicitLlmConfig):
+ *   1. Explicit config-file overrides (llmBaseUrl + llmApiKey + llmModel)
+ *   2. Hicortex-specific env vars (HICORTEX_LLM_BASE_URL + HICORTEX_LLM_API_KEY + HICORTEX_LLM_MODEL)
+ *   Returns null when nothing explicit is set — no silent defaults.
  *
- * Resolution for CC adapter (resolveLlmConfigForCC):
- *   1. Explicit env vars (HICORTEX_LLM_BASE_URL + HICORTEX_LLM_API_KEY + HICORTEX_LLM_MODEL)
- *   2. ANTHROPIC_API_KEY → Claude Haiku (cheap, CC users always have this)
- *   3. OPENAI_API_KEY → gpt-5.4-nano
- *   4. GOOGLE_API_KEY → gemini-2.5-flash
- *   5. Claude CLI fallback (uses subscription, no API key needed)
- *   6. Fallback: Ollama at http://localhost:11434
+ * Explicit backends (handled by call sites before resolveExplicitLlmConfig):
+ *   - llmBackend: "claude-cli" → claudeCliConfig()
+ *   - llmBackend: "ollama"     → explicit ollama LlmConfig
  *
  * Supports any OpenAI-compatible endpoint plus first-class support for
  * OpenAI, Anthropic, Google, Ollama, OpenRouter, and Claude CLI.
@@ -36,25 +31,28 @@ export interface LlmConfig {
     reflectProvider?: string;
 }
 /**
- * Resolve LLM configuration from plugin config, OpenClaw config, env vars, or Ollama fallback.
+ * Resolve LLM configuration from explicit config-file overrides or
+ * Hicortex-specific env vars only. Returns null when nothing explicit is set.
+ *
+ * Call sites (mcp-server, nightly) handle the named backends (claude-cli,
+ * ollama) before reaching this function. Only call this for the "other
+ * provider" / API-key case where no named backend is in config.json.
+ *
+ * NO implicit fallbacks: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY
+ * alone in the environment do NOT configure an LLM — the user must have
+ * chosen a provider via `npx @gamaze/hicortex init`.
  */
-export declare function resolveLlmConfig(pluginConfig?: {
+export declare function resolveExplicitLlmConfig(overrides?: {
     llmBaseUrl?: string;
     llmApiKey?: string;
     llmModel?: string;
     reflectModel?: string;
-}): LlmConfig;
+}): LlmConfig | null;
 /**
- * Resolve LLM configuration for Claude Code (no OC config file).
- * Uses env vars only — CC users always have ANTHROPIC_API_KEY.
- * Defaults to Haiku for distillation/scoring (~$0.50/mo).
+ * @deprecated Use resolveExplicitLlmConfig. This alias exists only to ease
+ * the transition for any lingering call sites — remove after 0.10.0 ships.
  */
-export declare function resolveLlmConfigForCC(overrides?: {
-    llmBaseUrl?: string;
-    llmApiKey?: string;
-    llmModel?: string;
-    reflectModel?: string;
-}): LlmConfig;
+export declare const resolveLlmConfigForCC: typeof resolveExplicitLlmConfig;
 /**
  * Find the claude CLI binary. Returns the full path or null.
  */
@@ -78,7 +76,7 @@ export declare function probeOllama(baseUrl?: string): Promise<string | null>;
  *   - `ok: false, reason: "unreachable"` — network failure or non-2xx.
  *   - `ok: false, reason: "model_missing"` — endpoint is up but the
  *     model isn't listed (the exact case that caused data loss when
- *     mhac-pro's Ollama didn't have the distill model loaded).
+ *     a remote Ollama box didn't have the distill model loaded).
  *
  * Matches on exact name OR name prefix ("qwen3.5:35b" matches "qwen3.5:35b-a3b").
  */
@@ -89,11 +87,26 @@ export declare function probeOllamaModel(baseUrl: string, modelName: string): Pr
     reason: "unreachable" | "model_missing";
 }>;
 /**
- * For batch operations (nightly pipeline), prefer Ollama when available.
- * Claude CLI has strict rate limits that kill batch distillation.
- * Falls back to the provided config if Ollama is unreachable.
+ * Resolve the distillation endpoint before a /distill request.
+ *
+ * @param config  LlmConfig (mutated in "local" mode when fallback is used)
+ * @param mode
+ *   "strict" (default) — when a separate distillBaseUrl is configured and its
+ *     Ollama probe fails, return "abort" immediately WITHOUT mutating config.
+ *     The session is not distilled now; the nightly watermark is not advanced,
+ *     so the session is re-shipped on the next run (harness stores retain raw
+ *     for 30–90 days — the retry IS the queue). Prefer this to producing
+ *     low-quality memories from a weak fallback model.
+ *   "local" — legacy 0.9.0 behaviour: fall back to the base endpoint (local
+ *     Ollama or API provider) when the remote is down. Mutates config IN PLACE
+ *     to repoint distill* at the fallback.
+ *
+ * Returns:
+ *   "ok"       — remote distill endpoint healthy, or no separate endpoint set
+ *   "fellback" — ("local" mode only) remote down; distill redirected to base
+ *   "abort"    — remote down and fallback not allowed (strict) or both down (local)
  */
-export declare function preferOllamaForBatch(resolved: LlmConfig, ollamaBaseUrl?: string): Promise<LlmConfig>;
+export declare function resolveDistillFallback(config: LlmConfig, mode?: "strict" | "local"): Promise<"ok" | "fellback" | "abort">;
 export declare class RateLimitError extends Error {
     retryAfterMs: number;
     constructor(retryAfterMs: number);