@gamaze/hicortex 0.5.1 → 0.5.3

package/dist/consolidate.js

@@ -273,14 +273,42 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                     break;
                 }
                 const embedding = await embedFn(content);
-                storage.insertMemory(db, content, embedding, {
-                    sourceAgent: "hicortex/reflection",
-                    project,
-                    memoryType: "lesson",
-                    baseStrength: baseStrength[severity] ?? 0.8,
-                    privacy: "WORK",
+                // Contradiction check: find semantically similar existing lessons.
+                // If a very similar lesson exists, ask the LLM whether the new one
+                // contradicts it. If yes, suppress the new lesson to prevent the
+                // "false coherence" failure mode (wrong lessons reinforcing themselves).
+                const similarLessons = storage.vectorSearch(db, embedding, 3)
+                    .filter((n) => {
+                    const sim = 1.0 - n.distance;
+                    return sim > 0.80 && n.memory_type === "lesson";
                 });
-                generated++;
+                let contradicted = false;
+                if (similarLessons.length > 0 && budget.use("contradiction_check")) {
+                    const existingText = similarLessons[0].content.slice(0, 300);
+                    const newText = content.slice(0, 300);
+                    try {
+                        const verdict = await llm.completeFast(`Two lessons from an AI memory system. Do they CONTRADICT each other (opposite advice on the same topic)?\n\n` +
+                            `EXISTING: ${existingText}\n\nNEW: ${newText}\n\n` +
+                            `Answer ONLY "yes" or "no". If the new lesson updates/refines the existing one (not contradicts), answer "no".`, 16);
+                        if (verdict.toLowerCase().trim().startsWith("yes")) {
+                            contradicted = true;
+                            console.log(`[hicortex] Lesson suppressed (contradicts existing): "${lessonText.slice(0, 80)}"`);
+                        }
+                    }
+                    catch {
+                        // LLM call failed — don't suppress, store the lesson
+                    }
+                }
+                if (!contradicted) {
+                    storage.insertMemory(db, content, embedding, {
+                        sourceAgent: "hicortex/reflection",
+                        project,
+                        memoryType: "lesson",
+                        baseStrength: baseStrength[severity] ?? 0.8,
+                        privacy: "WORK",
+                    });
+                    generated++;
+                }
             }
             catch {
                 // Failed to store lesson

package/dist/distiller.d.ts

@@ -4,6 +4,7 @@
  * not from filesystem scanning.
  */
 import type { LlmClient } from "./llm.js";
+import { type RedactionConfig } from "./redact.js";
 /**
  * Estimate a safe chunk size in chars based on the LLM provider and model.
  * - API providers (Anthropic, OpenAI, claude-cli): no chunking needed (large context windows)
@@ -14,9 +15,13 @@ import type { LlmClient } from "./llm.js";
  */
 export declare function detectChunkSize(provider: string, model: string, baseUrl?: string): Promise<number>;
 /**
- * Convert OpenClaw hook messages to a filtered transcript string.
+ * Convert session messages to a filtered transcript string.
+ * Handles OC hook format, CC JSONL, and Pi JSONL.
+ *
+ * If redactionConfig is provided (or defaults to enabled), secrets and PII
+ * are scrubbed from the final text BEFORE it reaches any LLM or storage.
  */
-export declare function extractConversationText(messages: unknown[]): string;
+export declare function extractConversationText(messages: unknown[], redactionConfig?: RedactionConfig): string;
 /**
  * Send filtered conversation to LLM for knowledge extraction.
  * For large transcripts, chunks into segments to avoid overwhelming small models.

package/dist/distiller.js

@@ -9,6 +9,7 @@ exports.detectChunkSize = detectChunkSize;
 exports.extractConversationText = extractConversationText;
 exports.distillSession = distillSession;
 const prompts_js_1 = require("./prompts.js");
+const redact_js_1 = require("./redact.js");
 const MAX_TRANSCRIPT_CHARS = 80_000;
 const MIN_CONVERSATION_CHARS = 200;
 // Chunk size limits by model parameter count (for local/CPU inference)
@@ -162,9 +163,13 @@ function cleanMessageContent(text) {
     return text.trim();
 }
 /**
- * Convert OpenClaw hook messages to a filtered transcript string.
+ * Convert session messages to a filtered transcript string.
+ * Handles OC hook format, CC JSONL, and Pi JSONL.
+ *
+ * If redactionConfig is provided (or defaults to enabled), secrets and PII
+ * are scrubbed from the final text BEFORE it reaches any LLM or storage.
  */
-function extractConversationText(messages) {
+function extractConversationText(messages, redactionConfig) {
     const parts = [];
     for (const msg of messages) {
         if (typeof msg !== "object" || msg === null)
@@ -196,7 +201,15 @@ function extractConversationText(messages) {
         const role = msgRole === "user" ? "USER" : "ASSISTANT";
         parts.push(`${role}: ${text}`);
     }
-    return parts.join("\n\n");
+    let result = parts.join("\n\n");
+    // Redact secrets and PII before the text reaches any LLM or storage.
+    // This is the last step — after all cleaning/filtering but before return.
+    const { text: redacted, count } = (0, redact_js_1.redact)(result, redactionConfig);
+    if (count > 0) {
+        console.log(`[hicortex] Redacted ${count} secret(s) from transcript`);
+    }
+    result = redacted;
+    return result;
 }
 /**
  * Send filtered conversation to LLM for knowledge extraction.

package/dist/nightly.js

@@ -47,6 +47,11 @@ exports.runNightly = runNightly;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
+let VERSION = "0.0.0";
+try {
+    VERSION = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8")).version;
+}
+catch { }
 const db_js_1 = require("./db.js");
 const llm_js_1 = require("./llm.js");
 const embedder_js_1 = require("./embedder.js");
@@ -59,6 +64,7 @@ const claude_md_js_1 = require("./claude-md.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
+const telemetry_js_1 = require("./telemetry.js");
 const HICORTEX_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
 function readNightlyConfig(stateDir) {
     try {
@@ -315,6 +321,22 @@ async function runNightly(options = {}) {
             }
         }
         console.log(`[hicortex] Nightly pipeline complete.`);
+        // Step 6: Anonymous telemetry (fire-and-forget, opt-out via config)
+        if (!dryRun && (0, telemetry_js_1.isTelemetryEnabled)(savedConfig)) {
+            const agentType = piBatches.length > 0 && ccBatches.length > 0 ? "mixed"
+                : piBatches.length > 0 ? "pi"
+                    : "cc";
+            await (0, telemetry_js_1.sendTelemetry)({
+                id: (0, telemetry_js_1.getTelemetryId)(stateDir),
+                v: VERSION,
+                mode: "server",
+                agent: agentType,
+                mem: storage.countMemories(db),
+                lessons: storage.getLessons(db, 365).length,
+                sessions: batches.length,
+                ok: !hadTransientFailure,
+            });
+        }
     }
     finally {
         db.close();
@@ -508,6 +530,19 @@ async function runClientNightly(config, dryRun) {
         }
     }
     console.log(`[hicortex] Client nightly complete: ${memoriesIngested} memories from ${sessionsSent} sessions → ${serverUrl}`);
+    // Anonymous telemetry (fire-and-forget, opt-out via config)
+    if (!dryRun && (0, telemetry_js_1.isTelemetryEnabled)(config)) {
+        await (0, telemetry_js_1.sendTelemetry)({
+            id: (0, telemetry_js_1.getTelemetryId)(HICORTEX_HOME),
+            v: VERSION,
+            mode: "client",
+            agent: "cc", // client mode is always CC-originated currently
+            mem: memoriesIngested,
+            lessons: 0, // client doesn't know lesson count
+            sessions: batches.length,
+            ok: !hadTransientFailure,
+        });
+    }
 }
 /**
  * Fetch lessons + memory index from server and inject into CLAUDE.md.

package/dist/redact.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pre-ingestion redaction — scrubs secrets and PII from transcript text
+ * BEFORE it reaches the distillation LLM or storage.
+ *
+ * Why this exists:
+ *   - Session transcripts contain tool output: file reads, command output,
+ *     env var dumps. These regularly contain API keys, tokens, and paths.
+ *   - The distillation LLM is often remote (e.g., Ollama on MBP via
+ *     Tailscale). Secrets in the transcript travel over the network.
+ *   - Even if the LLM correctly classifies the memory as SENSITIVE, the
+ *     secret is already stored and searchable via hicortex_search.
+ *   - Redaction runs BEFORE the LLM sees the text, eliminating the risk.
+ *
+ * Default patterns cover common API key formats, bearer tokens, absolute
+ * paths, and generic key=value secrets. Users can add custom patterns via
+ * config.json "redaction.extraPatterns".
+ *
+ * The replacement is always [REDACTED] (or configurable). This preserves
+ * the structure of the text so the LLM can still extract useful knowledge
+ * from the surrounding context.
+ */
+/** Result of a redaction pass. */
+export interface RedactionResult {
+    /** The redacted text. */
+    text: string;
+    /** Number of individual redactions applied. */
+    count: number;
+}
+/** Configuration for redaction, read from config.json. */
+export interface RedactionConfig {
+    /** Master switch. Default: true. */
+    enabled?: boolean;
+    /** Additional regex patterns (strings, compiled to RegExp with 'g' flag). */
+    extraPatterns?: string[];
+    /** Replacement string. Default: "[REDACTED]". */
+    replacement?: string;
+}
+/**
+ * Redact secrets and PII from text.
+ *
+ * @param text The raw transcript text to redact
+ * @param config Optional configuration (extra patterns, replacement string)
+ * @returns The redacted text and count of redactions applied
+ */
+export declare function redact(text: string, config?: RedactionConfig): RedactionResult;

package/dist/redact.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Pre-ingestion redaction — scrubs secrets and PII from transcript text
+ * BEFORE it reaches the distillation LLM or storage.
+ *
+ * Why this exists:
+ *   - Session transcripts contain tool output: file reads, command output,
+ *     env var dumps. These regularly contain API keys, tokens, and paths.
+ *   - The distillation LLM is often remote (e.g., Ollama on MBP via
+ *     Tailscale). Secrets in the transcript travel over the network.
+ *   - Even if the LLM correctly classifies the memory as SENSITIVE, the
+ *     secret is already stored and searchable via hicortex_search.
+ *   - Redaction runs BEFORE the LLM sees the text, eliminating the risk.
+ *
+ * Default patterns cover common API key formats, bearer tokens, absolute
+ * paths, and generic key=value secrets. Users can add custom patterns via
+ * config.json "redaction.extraPatterns".
+ *
+ * The replacement is always [REDACTED] (or configurable). This preserves
+ * the structure of the text so the LLM can still extract useful knowledge
+ * from the surrounding context.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redact = redact;
+/**
+ * Default redaction patterns. Each targets a specific class of secret.
+ * Order matters: more specific patterns should come first to avoid
+ * partial matches by generic patterns.
+ */
+const DEFAULT_PATTERNS = [
+    // Anthropic API keys: sk-ant-api03-...
+    { name: "anthropic_key", pattern: /sk-ant-[a-zA-Z0-9\-_]{20,}/g },
+    // OpenAI API keys: sk-proj-... or sk-...
+    { name: "openai_key", pattern: /sk-(?:proj-)?[a-zA-Z0-9]{20,}/g },
+    // Hicortex license keys: hctx-... (case-insensitive — keys could appear uppercased in logs)
+    { name: "hicortex_key", pattern: /hctx-[a-f0-9]{16}/gi },
+    // GitHub Personal Access Tokens: ghp_...
+    { name: "github_pat", pattern: /ghp_[a-zA-Z0-9]{36}/g },
+    // GitHub OAuth tokens: gho_...
+    { name: "github_oauth", pattern: /gho_[a-zA-Z0-9]{36}/g },
+    // Google API keys: AIza...
+    { name: "google_key", pattern: /AIza[a-zA-Z0-9_\-]{35}/g },
+    // AWS access keys: AKIA...
+    { name: "aws_key", pattern: /AKIA[A-Z0-9]{16}/g },
+    // Stripe live/test keys: sk_live_..., sk_test_...
+    { name: "stripe_key", pattern: /sk_(?:live|test)_[a-zA-Z0-9]{20,}/g },
+    // Bearer tokens in headers (case-insensitive — headers are case-insensitive)
+    { name: "bearer_token", pattern: /[Bb]earer\s+[a-zA-Z0-9._\-]{20,}/g },
+    // Generic secret assignments: password=..., secret_key=..., token: ...
+    // Matches key=value and key: value patterns with common secret key names.
+    // The key name can have underscores/hyphens and optional suffixes (SECRET_KEY, api-key, etc.)
+    // Negative lookahead for [REDACTED] prevents double-counting when a prior pattern
+    // already replaced the value (e.g., bearer_token fires, then generic_secret sees
+    // "token: [REDACTED]" and would otherwise match again).
+    { name: "generic_secret", pattern: /(?:password|secret(?:[_-]?key)?|token|api[_-]?key|private[_-]?key|access[_-]?key)\s*[:=]\s*["']?(?!\[REDACTED\])[^\s"']{8,}["']?/gi },
+    // Absolute macOS paths: /Users/<username>/...
+    // Negative lookbehind avoids matching URL paths like https://api.example.com/Users/list
+    { name: "macos_path", pattern: /(?<![:/])\/Users\/[a-zA-Z0-9._-]+/g },
+    // Absolute Linux home paths: /home/<username>/...
+    // Same lookbehind to avoid URL false positives
+    { name: "linux_path", pattern: /(?<![:/])\/home\/[a-zA-Z0-9._-]+/g },
+];
+/**
+ * Redact secrets and PII from text.
+ *
+ * @param text The raw transcript text to redact
+ * @param config Optional configuration (extra patterns, replacement string)
+ * @returns The redacted text and count of redactions applied
+ */
+function redact(text, config) {
+    if (config?.enabled === false)
+        return { text, count: 0 };
+    const replacement = config?.replacement ?? "[REDACTED]";
+    let count = 0;
+    let result = text;
+    // Apply default patterns
+    for (const { pattern } of DEFAULT_PATTERNS) {
+        // Reset lastIndex for global regexes (they're stateful)
+        pattern.lastIndex = 0;
+        result = result.replace(pattern, () => {
+            count++;
+            return replacement;
+        });
+    }
+    // Apply user-configured extra patterns
+    if (config?.extraPatterns) {
+        for (const patternStr of config.extraPatterns) {
+            try {
+                const re = new RegExp(patternStr, "g");
+                result = result.replace(re, () => {
+                    count++;
+                    return replacement;
+                });
+            }
+            catch {
+                // Invalid regex — skip silently (don't crash the pipeline)
+            }
+        }
+    }
+    return { text: result, count };
+}

package/dist/state.d.ts

@@ -33,6 +33,8 @@ export interface HicortexState {
     lastConsolidated?: string;
     /** Last-known license tier (replaces tier.json + license-validated.txt). */
     tier?: PersistedTier;
+    /** Anonymous telemetry UUID — generated once, never linked to personal info. */
+    telemetryId?: string;
 }
 /**
  * Load the state file. Returns an empty state if the file is missing

package/dist/telemetry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Anonymous telemetry — sends aggregate stats after each nightly run.
+ *
+ * What's sent (8 fields, all aggregate):
+ *   id       — random UUID, generated once on first run, stored in state.json
+ *   v        — package version
+ *   mode     — server or client
+ *   agent    — cc, pi, oc, or mixed (detected from session sources)
+ *   mem      — total memory count
+ *   lessons  — total lesson count
+ *   sessions — sessions distilled this run
+ *   ok       — nightly succeeded (true/false)
+ *
+ * What's NOT sent:
+ *   No personal data, no session content, no file paths, no IPs stored.
+ *
+ * Opt-out:
+ *   Set "telemetry": false in ~/.hicortex/config.json
+ *   OR set HICORTEX_TELEMETRY=off in the environment
+ *
+ * The ping is fire-and-forget with a 5s timeout. If it fails, nothing
+ * happens — the nightly result is unaffected.
+ */
+export interface TelemetryPayload {
+    id: string;
+    v: string;
+    mode: string;
+    agent: string;
+    mem: number;
+    lessons: number;
+    sessions: number;
+    ok: boolean;
+}
+/**
+ * Check if telemetry is enabled. Disabled by:
+ *   - config.telemetry === false
+ *   - HICORTEX_TELEMETRY env var set to "off", "false", or "0"
+ */
+export declare function isTelemetryEnabled(config: Record<string, unknown> | null): boolean;
+/**
+ * Get or create the anonymous telemetry ID.
+ * Generated once, stored in state.json, never linked to any personal info.
+ */
+export declare function getTelemetryId(stateDir: string): string;
+/**
+ * Send anonymous telemetry. Fire-and-forget — failures are silently ignored.
+ */
+export declare function sendTelemetry(payload: TelemetryPayload, serverUrl?: string): Promise<void>;

package/dist/telemetry.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Anonymous telemetry — sends aggregate stats after each nightly run.
+ *
+ * What's sent (8 fields, all aggregate):
+ *   id       — random UUID, generated once on first run, stored in state.json
+ *   v        — package version
+ *   mode     — server or client
+ *   agent    — cc, pi, oc, or mixed (detected from session sources)
+ *   mem      — total memory count
+ *   lessons  — total lesson count
+ *   sessions — sessions distilled this run
+ *   ok       — nightly succeeded (true/false)
+ *
+ * What's NOT sent:
+ *   No personal data, no session content, no file paths, no IPs stored.
+ *
+ * Opt-out:
+ *   Set "telemetry": false in ~/.hicortex/config.json
+ *   OR set HICORTEX_TELEMETRY=off in the environment
+ *
+ * The ping is fire-and-forget with a 5s timeout. If it fails, nothing
+ * happens — the nightly result is unaffected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTelemetryEnabled = isTelemetryEnabled;
+exports.getTelemetryId = getTelemetryId;
+exports.sendTelemetry = sendTelemetry;
+const node_crypto_1 = require("node:crypto");
+const state_js_1 = require("./state.js");
+const TELEMETRY_URL = "https://hicortex.gamaze.com/api/telemetry";
+/**
+ * Check if telemetry is enabled. Disabled by:
+ *   - config.telemetry === false
+ *   - HICORTEX_TELEMETRY env var set to "off", "false", or "0"
+ */
+function isTelemetryEnabled(config) {
+    // Config override
+    if (config?.telemetry === false)
+        return false;
+    // Env var override
+    const env = process.env.HICORTEX_TELEMETRY?.toLowerCase();
+    if (env === "off" || env === "false" || env === "0")
+        return false;
+    return true;
+}
+/**
+ * Get or create the anonymous telemetry ID.
+ * Generated once, stored in state.json, never linked to any personal info.
+ */
+function getTelemetryId(stateDir) {
+    const state = (0, state_js_1.loadState)(stateDir);
+    if (state.telemetryId)
+        return state.telemetryId;
+    const id = (0, node_crypto_1.randomUUID)();
+    (0, state_js_1.updateState)((s) => {
+        s.telemetryId = id;
+        return s;
+    }, stateDir);
+    return id;
+}
+/**
+ * Send anonymous telemetry. Fire-and-forget — failures are silently ignored.
+ */
+async function sendTelemetry(payload, serverUrl = TELEMETRY_URL) {
+    try {
+        await fetch(serverUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(5_000),
+        });
+    }
+    catch {
+        // Silently ignore — telemetry must never affect the nightly result
+    }
+}

package/dist/types.d.ts

@@ -59,6 +59,7 @@ export interface ConsolidationReport {
         };
         reflection?: {
             lessons_generated: number;
+            contradictions_suppressed?: number;
             failed?: boolean;
             skipped?: boolean;
             reason?: string;

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.5.1",
+  "version": "0.5.3",
   "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.5.1",
+  "version": "0.5.3",
   "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": {