@gamaze/hicortex 0.18.1 → 0.18.3

package/dist/recall-index.js

@@ -255,10 +255,15 @@ function handleMemoryGet(db, query) {
     // `citation` is server-rendered so every plugin surfaces the same built-in
     // provenance norm (owner directive 27.07) — see #193.
     const date = (mem.created_at ?? "").slice(0, 10);
+    // Shallow-copy and apply the human-term label to memory_type so the REST
+    // response surfaces the user-facing vocabulary, not the raw DB enum. The
+    // underlying DB row (`mem`) is NOT mutated — the DB IS the raw-enum source
+    // of truth; the label is a presentation concern applied at the boundary.
+    const memory = { ...mem, memory_type: (0, type_labels_js_1.labelForType)(mem.memory_type) };
     return {
         status: 200,
         body: {
-            memory: mem,
+            memory,
             citation: `(memory ${String(mem.id).slice(0, 8)}, ${date}, from ${mem.source_agent ?? "unknown"}, FETCHED)`,
         },
     };
@@ -284,7 +289,7 @@ function formatMemoryGetText(db, query) {
     const date = (mem.created_at ?? "").slice(0, 10);
     // #264 WS2: render the human-term label (Knowledge/Experience/...), not the
     // internal enum, in the citation header shown to the agent/user.
-    const header = `[memory ${mem.id} | ${(0, type_labels_js_1.labelForType)(mem.memory_type ?? "episode")} | ${mem.project ?? "-"} | from ${mem.source_agent ?? "unknown"} | ${date}]\n` +
+    const header = `[memory ${mem.id} | ${(0, type_labels_js_1.labelForType)(mem.memory_type ?? "experience")} | ${mem.project ?? "-"} | from ${mem.source_agent ?? "unknown"} | ${date}]\n` +
         `Cite as ${citation} where this shapes your answer; it may be stale — newer memories supersede older.`;
     return { status: 200, text: `${header}\n\n${mem.content ?? ""}` };
 }

package/dist/retrieval.js

@@ -69,6 +69,7 @@ exports.retrieve = retrieve;
 exports.searchRecent = searchRecent;
 const storage = __importStar(require("./storage.js"));
 const schema_prototypes_js_1 = require("./schema-prototypes.js");
+const type_labels_js_1 = require("./type-labels.js");
 /** Default decay half-life (days) at importance 0.5. #192: was 0.0005/h
  *  (~115-day half-life at base 0.5) — aggressive enough to bury the long tail
  *  in ranking. Long-term remembering is the product; time preference stays,
@@ -450,7 +451,7 @@ function formatResult(memory, score, effStr, connections, provenance) {
         score: Math.round(score * 1e6) / 1e6,
         effective_strength: Math.round(effStr * 1e6) / 1e6,
         access_count: memory.access_count ?? 0,
-        memory_type: memory.memory_type ?? "episode",
+        memory_type: (0, type_labels_js_1.labelForType)(memory.memory_type ?? "experience"),
         project: memory.project ?? null,
         source_agent: memory.source_agent ?? null,
         created_at: memory.created_at ?? "",

package/dist/seed-lesson.js

@@ -63,7 +63,7 @@ async function injectSeedLesson(database, log = console.log) {
         storage.insertMemory(database, exports.SEED_LESSON, embedding, {
             sourceAgent: "hicortex/seed",
             project: "global",
-            memoryType: "lesson",
+            memoryType: "learnings",
             baseStrength: 0.95,
         });
         log("[hicortex] Seed lesson injected: Daily Self-Improvement Protocol");

package/dist/status.d.ts

@@ -10,4 +10,12 @@
  * out as invalid (the hook sends none) rather than silently accepted.
  */
 export declare function statusAgentLine(config: Record<string, unknown>): string;
+/**
+ * Format the memory-type breakdown for `hicortex status`. Each raw DB enum key
+ * is rendered through {@link labelForType} so the printed line uses the human
+ * vocabulary (Knowledge/Experience/Decisions/Learnings), not the raw enum.
+ * Extracted from `runStatus` so the labeling is unit-testable without booting
+ * the full status printer. Unknown keys pass through verbatim (forward-compat).
+ */
+export declare function formatTypeBreakdown(byType: Record<string, number>): string;
 export declare function runStatus(): Promise<void>;

package/dist/status.js

@@ -4,6 +4,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.statusAgentLine = statusAgentLine;
+exports.formatTypeBreakdown = formatTypeBreakdown;
 exports.runStatus = runStatus;
 const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
@@ -14,6 +15,7 @@ const db_js_1 = require("./db.js");
 const features_js_1 = require("./features.js");
 const state_js_1 = require("./state.js");
 const identity_store_js_1 = require("./identity-store.js");
+const type_labels_js_1 = require("./type-labels.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
@@ -36,6 +38,18 @@ function statusAgentLine(config) {
             return "(not set — global identity)";
     }
 }
+/**
+ * Format the memory-type breakdown for `hicortex status`. Each raw DB enum key
+ * is rendered through {@link labelForType} so the printed line uses the human
+ * vocabulary (Knowledge/Experience/Decisions/Learnings), not the raw enum.
+ * Extracted from `runStatus` so the labeling is unit-testable without booting
+ * the full status printer. Unknown keys pass through verbatim (forward-compat).
+ */
+function formatTypeBreakdown(byType) {
+    return Object.entries(byType)
+        .map(([k, v]) => `${(0, type_labels_js_1.labelForType)(k)}=${v}`)
+        .join(", ");
+}
 async function runStatus() {
     console.log("Hicortex Status");
     console.log("─".repeat(40));
@@ -48,7 +62,7 @@ async function runStatus() {
             const { initDb, getStats } = await import("./db.js");
             const db = initDb(dbPath);
             const stats = getStats(db, dbPath);
-            const typeStr = Object.entries(stats.by_type).map(([k, v]) => `${k}=${v}`).join(", ");
+            const typeStr = formatTypeBreakdown(stats.by_type);
             console.log(`Memories:     ${stats.memories} (${typeStr || "none"})`);
             console.log(`Links:        ${stats.links}`);
             console.log(`DB size:      ${(stats.db_size_bytes / 1024).toFixed(1)} KB`);

package/dist/storage.js

@@ -72,7 +72,7 @@ function insertMemory(db, content, embedding, opts = {}) {
         created_at, ingested_at, source_agent, source_agent_id, source_session,
         source_domain, project, privacy, memory_type)
        VALUES (?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(id, content, opts.baseStrength ?? 0.5, ts, ts, ingestedTs, opts.sourceAgent ?? "default", opts.sourceAgentId ?? null, sourceSession, opts.sourceDomain ?? null, opts.project ?? null, opts.privacy ?? null, opts.memoryType ?? "episode");
+        .run(id, content, opts.baseStrength ?? 0.5, ts, ts, ingestedTs, opts.sourceAgent ?? "default", opts.sourceAgentId ?? null, sourceSession, opts.sourceDomain ?? null, opts.project ?? null, opts.privacy ?? null, opts.memoryType ?? "experience");
     if (result.changes > 0) {
         // New row — store its vector.
         db.prepare("INSERT INTO memory_vectors (id, embedding) VALUES (?, ?)").run(id, embedToBlob(embedding));
@@ -469,7 +469,7 @@ function insertMemoriesBatch(db, memories) {
         for (const mem of memories) {
             const id = (0, node_crypto_1.randomUUID)();
             const ts = nowIso();
-            insertMem.run(id, mem.content, mem.baseStrength ?? 0.5, ts, ts, ts, mem.sourceAgent ?? "default", mem.sourceAgentId ?? null, mem.sourceSession ?? null, mem.sourceDomain ?? null, mem.project ?? null, mem.privacy ?? null, mem.memoryType ?? "episode");
+            insertMem.run(id, mem.content, mem.baseStrength ?? 0.5, ts, ts, ts, mem.sourceAgent ?? "default", mem.sourceAgentId ?? null, mem.sourceSession ?? null, mem.sourceDomain ?? null, mem.project ?? null, mem.privacy ?? null, mem.memoryType ?? "experience");
             insertVec.run(id, embedToBlob(mem.embedding));
             count++;
         }
@@ -514,14 +514,14 @@ function getLessons(db, days = 7, project) {
     if (project) {
         const rows = db
             .prepare(`SELECT * FROM memories
-         WHERE memory_type = 'lesson' AND created_at > ? AND project = ?
+         WHERE memory_type = 'learnings' AND created_at > ? AND project = ?
          ORDER BY created_at DESC`)
             .all(cutoff, project);
         return rows.map(rowToMemory);
     }
     const rows = db
         .prepare(`SELECT * FROM memories
-       WHERE memory_type = 'lesson' AND created_at > ?
+       WHERE memory_type = 'learnings' AND created_at > ?
        ORDER BY created_at DESC`)
         .all(cutoff);
     return rows.map(rowToMemory);

package/dist/token-budget.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolve the effective cap: env (HICORTEX_TOKEN_CAP) takes precedence over the
+ * config key. A positive, finite env wins; otherwise the config value (0/absent
+ * = unlimited). Pure — exported for tests.
+ */
+export declare function resolveTokenCap(configCap: unknown): number;
+/**
+ * Initialise at server boot (after stateDir is known). Resolves + caches the cap
+ * and seeds the 80%-warn dedup so a restart mid-period doesn't re-warn.
+ */
+export declare function initTokenBudget(stateDir: string, configCap: unknown): void;
+/** The resolved monthly cap (0 = unlimited / enforcement off). */
+export declare function getTokenCap(): number;
+/**
+ * Pre-call check for /distill: refuse (429) when the tenant is already at/over
+ * the monthly cap. Reuses `shouldThrottleTokens(cap, period, 0)` — lastRunTokens
+ * is 0 because we cannot predict a call's cost before making it, so this refuses
+ * only when already over (a tenant exactly at the cap is refused on the next
+ * call). Reads state.json fresh so the nightly process's writes are reflected.
+ */
+export declare function isTokenBudgetExceeded(stateDir: string): boolean;
+/**
+ * After a successful distill, add the consumed tokens to the monthly counter and
+ * emit the 80% warning once per period. Synchronous read-modify-write via
+ * `updateState` (serializes concurrent in-process /distill; picks up the nightly
+ * process's writes via the fresh read). Accumulates the full breakdown
+ * (prompt/completion/total) so the dashboard's prompt+completion stays
+ * consistent with total (distill + consolidation).
+ */
+export declare function recordDistillUsage(stateDir: string, usage: {
+    prompt: number;
+    completion: number;
+    total: number;
+}): void;

package/dist/token-budget.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTokenCap = resolveTokenCap;
+exports.initTokenBudget = initTokenBudget;
+exports.getTokenCap = getTokenCap;
+exports.isTokenBudgetExceeded = isTokenBudgetExceeded;
+exports.recordDistillUsage = recordDistillUsage;
+/**
+ * Per-tenant monthly token-budget enforcement (#110 Phase 0B item #5).
+ *
+ * Limits LLM token consumption over /distill (the cost-generating path the
+ * nightly consolidation throttle did NOT cover). Mode-agnostic — gates on
+ * `cap > 0`, never on `hostedMode`:
+ *   - Self-hosted: the cap is the operator's own `llmTokensPerMonth` config
+ *     (default 0 = unlimited → never throttles). Protects the operator's wallet
+ *     from a runaway nightly on an expensive model.
+ *   - Hosted: the cap is provider-set via the `HICORTEX_TOKEN_CAP` env, which
+ *     takes PRECEDENCE over config. The tenant process cannot mutate boot-time
+ *     env, so a hosted tenant cannot raise its own cap (the config.json
+ *     self-edit loophole is closed). Protects the provider's wallet.
+ *
+ * Reuses the existing machinery: `shouldThrottleTokens` (consolidate.ts) for the
+ * decision (incl. monthly reset), and `llmTokensThisPeriod` + `updateState`
+ * (state.ts) for the counter + atomic persistence.
+ *
+ * Concurrency: state.json is read fresh for each check and written via
+ * `updateState` (a synchronous read-modify-write; Node's single thread
+ * serializes concurrent /distill calls within the server process, so no
+ * in-process tally is needed). The nightly consolidation is a SEPARATE process
+ * that also writes state.json; a rare cross-process write collision can lose a
+ * small increment — negligible on a multi-million-token monthly budget. A
+ * DB-backed counter (WAL transactions serialize across processes) is the future
+ * hardening if it ever matters.
+ */
+const state_js_1 = require("./state.js");
+const consolidate_js_1 = require("./consolidate.js");
+/** Env override (hosted: provider-set, tenant-immutable at runtime). */
+const TOKEN_CAP_ENV = "HICORTEX_TOKEN_CAP";
+let cap = 0;
+/** periodStart we last emitted the 80% warning at, to dedup within a period. */
+let warnedPeriod = null;
+/**
+ * Resolve the effective cap: env (HICORTEX_TOKEN_CAP) takes precedence over the
+ * config key. A positive, finite env wins; otherwise the config value (0/absent
+ * = unlimited). Pure — exported for tests.
+ */
+function resolveTokenCap(configCap) {
+    const envCap = Number(process.env[TOKEN_CAP_ENV]);
+    if (Number.isFinite(envCap) && envCap > 0)
+        return envCap;
+    const cfg = Number(configCap);
+    return Number.isFinite(cfg) && cfg > 0 ? cfg : 0;
+}
+/**
+ * Initialise at server boot (after stateDir is known). Resolves + caches the cap
+ * and seeds the 80%-warn dedup so a restart mid-period doesn't re-warn.
+ */
+function initTokenBudget(stateDir, configCap) {
+    cap = resolveTokenCap(configCap);
+    if (cap > 0) {
+        const p = (0, state_js_1.loadState)(stateDir).llmTokensThisPeriod;
+        warnedPeriod = p && p.total >= cap * 0.8 ? (p.periodStart ?? null) : null;
+        // Label the source truthfully: only claim env if the env value was actually
+        // used (a malformed env falls back to config, so the label must not lie).
+        const fromEnv = Number(process.env[TOKEN_CAP_ENV]) === cap;
+        console.log(`[hicortex] Token budget: ${cap.toLocaleString()}/month${fromEnv ? " (HICORTEX_TOKEN_CAP)" : ""}`);
+    }
+}
+/** The resolved monthly cap (0 = unlimited / enforcement off). */
+function getTokenCap() {
+    return cap;
+}
+/**
+ * Pre-call check for /distill: refuse (429) when the tenant is already at/over
+ * the monthly cap. Reuses `shouldThrottleTokens(cap, period, 0)` — lastRunTokens
+ * is 0 because we cannot predict a call's cost before making it, so this refuses
+ * only when already over (a tenant exactly at the cap is refused on the next
+ * call). Reads state.json fresh so the nightly process's writes are reflected.
+ */
+function isTokenBudgetExceeded(stateDir) {
+    if (cap <= 0)
+        return false;
+    const period = (0, state_js_1.loadState)(stateDir).llmTokensThisPeriod;
+    return (0, consolidate_js_1.shouldThrottleTokens)(cap, period, 0).throttle;
+}
+/**
+ * After a successful distill, add the consumed tokens to the monthly counter and
+ * emit the 80% warning once per period. Synchronous read-modify-write via
+ * `updateState` (serializes concurrent in-process /distill; picks up the nightly
+ * process's writes via the fresh read). Accumulates the full breakdown
+ * (prompt/completion/total) so the dashboard's prompt+completion stays
+ * consistent with total (distill + consolidation).
+ */
+function recordDistillUsage(stateDir, usage) {
+    if (cap <= 0 || usage.total <= 0)
+        return;
+    let newTotal = 0;
+    let periodStart = "";
+    (0, state_js_1.updateState)((s) => {
+        const prev = s.llmTokensThisPeriod;
+        // Monthly reset (year+month) — matches shouldThrottleTokens's staleness check.
+        const stale = !prev?.periodStart ||
+            new Date(prev.periodStart).getUTCFullYear() !== new Date().getUTCFullYear() ||
+            new Date(prev.periodStart).getUTCMonth() !== new Date().getUTCMonth();
+        if (stale) {
+            s.llmTokensThisPeriod = {
+                prompt: usage.prompt,
+                completion: usage.completion,
+                total: usage.total,
+                periodStart: new Date().toISOString(),
+            };
+        }
+        else {
+            const base = prev;
+            s.llmTokensThisPeriod = {
+                prompt: (base.prompt ?? 0) + usage.prompt,
+                completion: (base.completion ?? 0) + usage.completion,
+                total: (base.total ?? 0) + usage.total,
+                periodStart: base.periodStart,
+            };
+        }
+        newTotal = s.llmTokensThisPeriod.total;
+        periodStart = s.llmTokensThisPeriod.periodStart;
+    }, stateDir);
+    // 80% warning — dedup per period (once per month per threshold crossing).
+    if (periodStart && warnedPeriod !== periodStart && newTotal >= cap * 0.8) {
+        warnedPeriod = periodStart;
+        const pct = Math.round((newTotal / cap) * 100);
+        console.warn(`[hicortex] Token usage at ${pct}% of monthly cap (${newTotal.toLocaleString()}/${cap.toLocaleString()}).`);
+    }
+}

package/dist/type-classify.d.ts

@@ -1,41 +1,41 @@
 /**
- * `hicortex classify-types` — deliberate, resumable episode→fact/decision
- * reclassification pass over the memories corpus (#216).
+ * `hicortex classify-types` — deliberate, resumable experience→knowledge/
+ * decisions reclassification pass over the memories corpus (#216).
  *
  * WHY THIS EXISTS
  * ---------------
  * Before #216 the distiller NEVER set memory_type — every distilled memory
- * defaulted to "episode" (storage.ts insertMemory `?? "episode"`), so the
- * corpus was ~98% episodes. The distiller now classifies each entry at extract
- * time via the [E]/[F]/[D] tag (distiller.ts), but the EXISTING corpus needs a
- * one-shot backfill. This command is that backfill — modelled on
+ * defaulted to "experience" (storage.ts insertMemory `?? "experience"`), so
+ * the corpus was ~98% experiences. The distiller now classifies each entry at
+ * extract time via the [E]/[K]/[D] tag (distiller.ts), but the EXISTING corpus
+ * needs a one-shot backfill. This command is that backfill — modelled on
  * `classify-domains` (resumable cursor, batched, infra-error-safe).
  *
  * WHAT IT DOES
  * ------------
  * Walks memories ordered by rowid in batches (default 200). Default scope =
- * episodes only (`memory_type = 'episode'`); `--all` reclassifies every memory
- * regardless of current type **except lessons** (see below). For each memory,
- * ONE constrained LLM call asks the model to classify the content as
- * episode / fact / decision. The reply is parsed + validated, and
+ * experiences only (`memory_type = 'experience'`); `--all` reclassifies every
+ * memory regardless of current type **except learnings** (see below). For each
+ * memory, ONE constrained LLM call asks the model to classify the content as
+ * experience / knowledge / decisions. The reply is parsed + validated, and
  * `UPDATE memories SET memory_type = ? WHERE id = ?` runs inside a per-batch
  * transaction. The cursor (`typeCursor` in state.json) advances to the last
  * committed rowid after each batch — crash-safe and infra-abort-safe (same
  * discipline as classify-domains).
  *
- * Lessons are NEVER touched here: the reflection stage owns them. The `--all`
- * scope explicitly excludes `memory_type = 'lesson'` — this is the primary
- * defence. (The prompt asks only for episode/fact/decision, so a lesson that
- * DID enter scope would be overwritten to E/F/D — the model never replies
- * "lesson". `parseTypeReply`'s rejection of a "lesson" reply is a backstop, not
- * the main guard.)
+ * Learnings are NEVER touched here: the reflection stage owns them. The
+ * `--all` scope explicitly excludes `memory_type = 'learnings'` — this is the
+ * primary defence. (The prompt asks only for experience/knowledge/decisions,
+ * so a learning that DID enter scope would be overwritten — the model never
+ * replies "learnings". `parseTypeReply`'s rejection of a "learnings" reply is
+ * a backstop, not the main guard.)
  *
  * This command does NOT use the consolidation budget — it is a standalone CLI,
  * not a nightly stage.
  */
 import { LlmClient } from "./llm.js";
 export interface ClassifyTypesOptions {
-    /** Reclassify EVERY memory, not just episodes. */
+    /** Reclassify EVERY memory, not just experiences. */
     all?: boolean;
     /** Memories per batch (default 200). Cursor advances per committed batch. */
     batchSize?: number;
@@ -55,7 +55,7 @@ export interface ClassifyTypesReport {
     scanned: number;
     /** Memories whose memory_type was changed. */
     reclassified: number;
-    /** Episodes confirmed as episode (no change). */
+    /** Experiences confirmed as experience (no change). */
     unchanged: number;
     /** Memories skipped due to an infra error (LLM threw twice). */
     failed: number;
@@ -70,23 +70,26 @@ export interface ClassifyTypesReport {
 }
 /**
  * Build the constrained type-classification prompt for one memory. The model
- * must reply with ONLY the type word (episode/fact/decision) — no prose. The
- * distinction mirrors the distiller's [E]/[F]/[D] tag definitions (prompts.ts),
- * so distill-time and backfill-time classification stay consistent.
+ * must reply with ONLY the type word (experience/knowledge/decisions) — no
+ * prose. The distinction mirrors the distiller's [E]/[K]/[D] tag definitions
+ * (prompts.ts), so distill-time and backfill-time classification stay
+ * consistent. (The stored enum was renamed in #264: episode→experience,
+ * fact→knowledge, decision→decisions; the conceptual definitions are
+ * unchanged.)
  */
 export declare function buildTypeClassifyPrompt(content: string): string;
 /**
  * Parse the model's reply into a validated type. Accepts the bare word
  * (case-insensitive), tolerating surrounding whitespace, a trailing period, a
- * leading "Type:" label, and markdown emphasis. "lesson" is NEVER accepted
- * (the reflection stage owns lessons; a model that emits it is wrong) — returns
- * null so the caller retries.
+ * leading "Type:" label, and markdown emphasis. "learnings" (and the legacy
+ * "lesson") are NEVER accepted (the reflection stage owns learnings; a model
+ * that emits either is wrong) — returns null so the caller retries.
  *
  * Returns null on anything unparseable or out-of-vocabulary so the caller can
  * retry once (matching classify-domains' two-attempt discipline).
  */
 export declare function parseTypeReply(reply: string): {
-    type: "episode" | "fact" | "decision";
+    type: "experience" | "knowledge" | "decisions";
     score: number;
 } | null;
 /**
@@ -95,7 +98,7 @@ export declare function parseTypeReply(reply: string): {
  * (caller leaves the memory untouched and retries via the cursor next run).
  */
 export declare function classifyMemoryType(content: string, llm: LlmClient): Promise<{
-    type: "episode" | "fact" | "decision";
+    type: "experience" | "knowledge" | "decisions";
     score: number;
 } | null>;
 /**

package/dist/type-classify.js

@@ -1,35 +1,35 @@
 "use strict";
 /**
- * `hicortex classify-types` — deliberate, resumable episode→fact/decision
- * reclassification pass over the memories corpus (#216).
+ * `hicortex classify-types` — deliberate, resumable experience→knowledge/
+ * decisions reclassification pass over the memories corpus (#216).
  *
  * WHY THIS EXISTS
  * ---------------
  * Before #216 the distiller NEVER set memory_type — every distilled memory
- * defaulted to "episode" (storage.ts insertMemory `?? "episode"`), so the
- * corpus was ~98% episodes. The distiller now classifies each entry at extract
- * time via the [E]/[F]/[D] tag (distiller.ts), but the EXISTING corpus needs a
- * one-shot backfill. This command is that backfill — modelled on
+ * defaulted to "experience" (storage.ts insertMemory `?? "experience"`), so
+ * the corpus was ~98% experiences. The distiller now classifies each entry at
+ * extract time via the [E]/[K]/[D] tag (distiller.ts), but the EXISTING corpus
+ * needs a one-shot backfill. This command is that backfill — modelled on
  * `classify-domains` (resumable cursor, batched, infra-error-safe).
  *
  * WHAT IT DOES
  * ------------
  * Walks memories ordered by rowid in batches (default 200). Default scope =
- * episodes only (`memory_type = 'episode'`); `--all` reclassifies every memory
- * regardless of current type **except lessons** (see below). For each memory,
- * ONE constrained LLM call asks the model to classify the content as
- * episode / fact / decision. The reply is parsed + validated, and
+ * experiences only (`memory_type = 'experience'`); `--all` reclassifies every
+ * memory regardless of current type **except learnings** (see below). For each
+ * memory, ONE constrained LLM call asks the model to classify the content as
+ * experience / knowledge / decisions. The reply is parsed + validated, and
  * `UPDATE memories SET memory_type = ? WHERE id = ?` runs inside a per-batch
  * transaction. The cursor (`typeCursor` in state.json) advances to the last
  * committed rowid after each batch — crash-safe and infra-abort-safe (same
  * discipline as classify-domains).
  *
- * Lessons are NEVER touched here: the reflection stage owns them. The `--all`
- * scope explicitly excludes `memory_type = 'lesson'` — this is the primary
- * defence. (The prompt asks only for episode/fact/decision, so a lesson that
- * DID enter scope would be overwritten to E/F/D — the model never replies
- * "lesson". `parseTypeReply`'s rejection of a "lesson" reply is a backstop, not
- * the main guard.)
+ * Learnings are NEVER touched here: the reflection stage owns them. The
+ * `--all` scope explicitly excludes `memory_type = 'learnings'` — this is the
+ * primary defence. (The prompt asks only for experience/knowledge/decisions,
+ * so a learning that DID enter scope would be overwritten — the model never
+ * replies "learnings". `parseTypeReply`'s rejection of a "learnings" reply is
+ * a backstop, not the main guard.)
  *
  * This command does NOT use the consolidation budget — it is a standalone CLI,
  * not a nightly stage.
@@ -49,8 +49,8 @@ const type_labels_js_1 = require("./type-labels.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 /** Max chars of memory content fed to the classify prompt. */
 const CLASSIFY_CONTENT_MAX_CHARS = 1500;
-/** Valid distillation-time memory types (NO lesson — reflection owns that). */
-const VALID_TYPES = new Set(["episode", "fact", "decision"]);
+/** Valid distillation-time memory types (NO learnings — reflection owns that). */
+const VALID_TYPES = new Set(["experience", "knowledge", "decisions"]);
 function readConfig(stateDir) {
     try {
         return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(stateDir, "config.json"), "utf-8"));
@@ -61,9 +61,12 @@ function readConfig(stateDir) {
 }
 /**
  * Build the constrained type-classification prompt for one memory. The model
- * must reply with ONLY the type word (episode/fact/decision) — no prose. The
- * distinction mirrors the distiller's [E]/[F]/[D] tag definitions (prompts.ts),
- * so distill-time and backfill-time classification stay consistent.
+ * must reply with ONLY the type word (experience/knowledge/decisions) — no
+ * prose. The distinction mirrors the distiller's [E]/[K]/[D] tag definitions
+ * (prompts.ts), so distill-time and backfill-time classification stay
+ * consistent. (The stored enum was renamed in #264: episode→experience,
+ * fact→knowledge, decision→decisions; the conceptual definitions are
+ * unchanged.)
  */
 function buildTypeClassifyPrompt(content) {
     const truncated = content.length > CLASSIFY_CONTENT_MAX_CHARS
@@ -71,28 +74,31 @@ function buildTypeClassifyPrompt(content) {
         : content;
     return (`You are classifying a single memory by its TYPE and IMPORTANCE.\n\n` +
         `TYPES:\n` +
-        `- episode: a specific event, interaction, or narrative — a one-time ` +
+        `- experience: a specific event, interaction, or narrative — a one-time ` +
         `occurrence ("tried X, failed because Y", a correction, a debugging session).\n` +
-        `- fact: a durable truth that holds across sessions, not tied to a single ` +
-        `moment ("the API is at :8787", "uv is used for packages").\n` +
-        `- decision: a choice made that future work builds on and a later decision ` +
-        `can supersede ("switched from gemma4 to qwen3.5", "adopted the graded-schema ` +
-        `tag model"). Not a fact (it can change) and not an episode (it persists).\n\n` +
+        `- knowledge: a durable truth that holds across sessions, not tied to a ` +
+        `single moment ("the API is at :8787", "uv is used for packages").\n` +
+        `- decisions: a choice made that future work builds on and a later ` +
+        `decision can supersede ("switched from gemma4 to qwen3.5", "adopted the ` +
+        `graded-schema tag model"). Not knowledge (it can change) and not an ` +
+        `experience (it persists).\n\n` +
         `IMPORTANCE (0.0–1.0):\n` +
-        `- 0.8–1.0: load-bearing — a core fact or decision the agent must know.\n` +
+        `- 0.8–1.0: load-bearing — a core piece of knowledge or a decision the ` +
+        `agent must know.\n` +
         `- 0.5–0.8: useful context — relevant to current and future work.\n` +
         `- 0.2–0.5: marginal — situational, likely to fade.\n` +
         `- 0.0–0.2: noise — low value, safe to forget.\n` +
-        `Facts and decisions tend to score higher than episodes (they persist).\n\n` +
+        `Knowledge and decisions tend to score higher than experiences (they ` +
+        `persist).\n\n` +
         `MEMORY:\n${truncated}\n\n` +
-        `Reply with ONLY: type importance (e.g. "fact 0.8"). No prose, no explanation.`);
+        `Reply with ONLY: type importance (e.g. "knowledge 0.8"). No prose, no explanation.`);
 }
 /**
  * Parse the model's reply into a validated type. Accepts the bare word
  * (case-insensitive), tolerating surrounding whitespace, a trailing period, a
- * leading "Type:" label, and markdown emphasis. "lesson" is NEVER accepted
- * (the reflection stage owns lessons; a model that emits it is wrong) — returns
- * null so the caller retries.
+ * leading "Type:" label, and markdown emphasis. "learnings" (and the legacy
+ * "lesson") are NEVER accepted (the reflection stage owns learnings; a model
+ * that emits either is wrong) — returns null so the caller retries.
  *
  * Returns null on anything unparseable or out-of-vocabulary so the caller can
  * retry once (matching classify-domains' two-attempt discipline).
@@ -112,8 +118,8 @@ function parseTypeReply(reply) {
         .replace(/^[*_`"'\s]+/, "")
         .replace(/[*_`"']+$/, "")
         .trim();
-    // Expected format: "type score" (e.g. "fact 0.8"). Parse both.
-    const match = cleaned.toLowerCase().match(/^(episode|fact|decision)\s+([0-9]*\.?[0-9]+)/);
+    // Expected format: "type score" (e.g. "knowledge 0.8"). Parse both.
+    const match = cleaned.toLowerCase().match(/^(experience|knowledge|decisions)\s+([0-9]*\.?[0-9]+)/);
     if (match) {
         const type = match[1];
         let score = parseFloat(match[2]);
@@ -158,7 +164,7 @@ async function classifyMemoryType(content, llm) {
         }
     }
     // Two successful calls, neither parseable → leave the memory's type unchanged.
-    // We do NOT default to episode here: a model that can't decide should not
+    // We do NOT default to experience here: a model that can't decide should not
     // silently overwrite an existing type. Return null so the caller records a
     // failed classification and the cursor still advances past this row.
     return null;
@@ -208,17 +214,18 @@ async function runClassifyTypes(options = {}) {
     try {
         let cursor = options.reset ? 0 : ((0, state_js_1.loadState)(stateDir).typeCursor ?? 0);
         report.cursor = cursor;
-        console.log(`[hicortex] classify-types starting: scope ${all ? "ALL" : "episodes only"}, ` +
+        console.log(`[hicortex] classify-types starting: scope ${all ? "ALL" : "experiences only"}, ` +
             `batch ${batchSize}, cursor ${cursor}${options.reset ? " (reset)" : ""}`);
-        // Scope filter: default = episodes only; --all = everything EXCEPT lessons.
-        // Lessons are owned by the reflection stage — they must never be
-        // reclassified here. (The prompt asks only for episode/fact/decision, so a
-        // lesson row in scope gets overwritten: the model never replies "lesson".
-        // The scope exclusion is therefore the real guard; parseTypeReply's
-        // "lesson" rejection is a backstop, not the primary defence.)
+        // Scope filter: default = experiences only; --all = everything EXCEPT
+        // learnings. Learnings are owned by the reflection stage — they must never
+        // be reclassified here. (The prompt asks only for experience/knowledge/
+        // decisions, so a learning row in scope gets overwritten: the model never
+        // replies "learnings". The scope exclusion is therefore the real guard;
+        // parseTypeReply's "learnings" rejection is a backstop, not the primary
+        // defence.)
         const scopeSql = all
-            ? "rowid > ? AND (memory_type IS NULL OR memory_type != 'lesson')"
-            : "rowid > ? AND memory_type = 'episode'";
+            ? "rowid > ? AND (memory_type IS NULL OR memory_type != 'learnings')"
+            : "rowid > ? AND memory_type = 'experience'";
         const batchStmt = db.prepare(`SELECT rowid AS __rowid, id, content, memory_type FROM memories
        WHERE ${scopeSql} ORDER BY rowid ASC LIMIT ?`);
         // Set true when the classifier returns null (infra error): finish the