@gamaze/hicortex 0.18.1 → 0.18.2

package/assets/dashboard.html

@@ -238,10 +238,15 @@ let compKey = "by_type";
 
 const $ = (id) => document.getElementById(id);
 
-// #264 WS2: human-term labels for the internal memory_type enum. The data
-// blob carries the RAW enum keys (a stable JSON contract, also relied on by
-// tests); only the rendered label changes. Unknown keys pass through.
+// #264 final: the data blob carries the CANONICAL human-term keys
+// (knowledge/experience/decisions/learnings). Legacy raw keys are also mapped
+// so a snapshot taken mid-migrate renders correctly. Unknown keys pass through.
 const TYPE_LABELS = {
+  knowledge: "Knowledge",
+  experience: "Experience",
+  decisions: "Decisions",
+  learnings: "Learnings",
+  // Legacy raw enum (same types, renamed).
   fact: "Knowledge",
   episode: "Experience",
   decision: "Decisions",

package/assets/viz.html

@@ -389,10 +389,16 @@
   var selDomain = document.getElementById("f-domain");
   var selType = document.getElementById("f-type");
 
-  // #264 WS2: human-term labels for the internal memory_type enum. Node data
-  // carries the RAW enum (the /graph JSON contract filters on it); only the
-  // rendered strings change. Unknown values pass through unchanged.
+  // #264 final: node data carries the CANONICAL human-term values
+  // (knowledge/experience/decisions/learnings). Legacy raw values are also
+  // mapped so a mid-migrate snapshot renders correctly. Unknown values pass
+  // through unchanged.
   var TYPE_LABELS = {
+    knowledge: "Knowledge",
+    experience: "Experience",
+    decisions: "Decisions",
+    learnings: "Learnings",
+    // Legacy raw enum (same types, renamed).
     fact: "Knowledge",
     episode: "Experience",
     decision: "Decisions",

package/dist/consolidate.js

@@ -418,7 +418,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
             const severity = String(lo.severity ?? "important");
             const confidence = String(lo.confidence ?? "medium");
             const sourcePattern = String(lo.source_pattern ?? "");
-            // No `## Lesson:` prefix: memory_type='lesson' carries the type, and the
+            // No `## Lesson:` prefix: memory_type='learnings' carries the type, and the
             // text is the topic-first first line (display reads the first line, not a
             // header parse — see learnings-identity.ts / index.ts).
             let content = `${lessonText}\n\n`;
@@ -443,7 +443,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                 // the accidental 1−L2 scale and required cosine > 0.98 — the check
                 // effectively never fired. See isContradictionCandidate.
                 const similarLessons = storage.vectorSearch(db, embedding, 3)
-                    .filter((n) => isContradictionCandidate(n.distance) && n.memory_type === "lesson");
+                    .filter((n) => isContradictionCandidate(n.distance) && n.memory_type === "learnings");
                 let contradicted = false;
                 if (similarLessons.length > 0 && budget.use("contradiction_check")) {
                     const existingText = similarLessons[0].content.slice(0, 300);
@@ -470,7 +470,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                     storage.insertMemory(db, content, embedding, {
                         sourceAgent: "hicortex/reflection",
                         project,
-                        memoryType: "lesson",
+                        memoryType: "learnings",
                         baseStrength: baseStrength[severity] ?? 0.8,
                     });
                     generated++;
@@ -509,7 +509,7 @@ function rebuildContentModuleIndex(db, domains, stateDir) {
         .all();
     const lessonRows = db
         .prepare(`SELECT domain, COUNT(*) AS cnt FROM memories
-       WHERE domain IS NOT NULL AND memory_type = 'lesson' GROUP BY domain`)
+       WHERE domain IS NOT NULL AND memory_type = 'learnings' GROUP BY domain`)
         .all();
     const memByDomain = new Map(memRows.map((r) => [r.domain, r.cnt]));
     const lessonByDomain = new Map(lessonRows.map((r) => [r.domain, r.cnt]));
@@ -637,7 +637,7 @@ async function stageDomainCuration(db, llm, budget, dryRun, stateDir) {
     }
     const lessonRows = db
         .prepare(`SELECT project, COUNT(*) as cnt FROM memories
-       WHERE project IS NOT NULL AND memory_type = 'lesson'
+       WHERE project IS NOT NULL AND memory_type = 'learnings'
        GROUP BY project`)
         .all();
     const lessonsByProject = new Map(lessonRows.map((r) => [r.project, r.cnt]));
@@ -997,7 +997,7 @@ const SUPERSESSION_BATCH_SIZE = 500;
  * events, not mutable state, so there is nothing to supersede.
  */
 function isSupersedableShape(mem) {
-    return (mem.memory_type === "decision" ||
+    return (mem.memory_type === "decisions" ||
         mem.content.includes("[Decisions Made]") ||
         mem.content.includes("[Corrections & Rejections]") ||
         mem.content.includes("[Facts Learned]") ||
@@ -1117,7 +1117,7 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
     // in lockstep (an inline SQL copy, so drift here silently narrows scope).
     `SELECT rowid AS __rowid, * FROM memories
        WHERE rowid > ?
-         AND (memory_type = 'decision'
+         AND (memory_type = 'decisions'
               OR content LIKE '%[Decisions Made]%'
               OR content LIKE '%[Corrections & Rejections]%'
               OR content LIKE '%[Facts Learned]%'

package/dist/dashboard.js

@@ -53,7 +53,7 @@ function countBy(db, col) {
 function computeDashboardMetrics(db) {
     const mem = db.prepare("SELECT COUNT(*) AS c FROM memories").get().c;
     const lesson = db
-        .prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'lesson'")
+        .prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'learnings'")
         .get().c;
     const link = db.prepare("SELECT COUNT(*) AS c FROM memory_links").get().c;
     const adoptionRow = db
@@ -228,7 +228,7 @@ function backfillSnapshots(db) {
             const dayRows = byDay.get(d);
             for (const r of dayRows) {
                 mem++;
-                if (r.memory_type === "lesson")
+                if (r.memory_type === "learnings")
                     lesson++;
                 byType[r.memory_type] = (byType[r.memory_type] ?? 0) + 1;
                 const domKey = r.domain ?? "(unscoped)";
@@ -380,7 +380,7 @@ function handleDashboardData(db, query, config) {
     const lessonRows = db
         .prepare(`SELECT id, content, created_at
          FROM memories
-        WHERE memory_type = 'lesson' AND created_at BETWEEN ? AND ?
+        WHERE memory_type = 'learnings' AND created_at BETWEEN ? AND ?
         ORDER BY created_at ASC`)
         .all(dayStart, dayEnd);
     // Stage outcomes for the day: dedup merges + supersession links that day.

package/dist/db.js

@@ -105,7 +105,7 @@ CREATE TABLE IF NOT EXISTS memories (
     source_session TEXT,
     project TEXT,
     privacy TEXT DEFAULT 'WORK',
-    memory_type TEXT DEFAULT 'episode',
+    memory_type TEXT DEFAULT 'experience',
     updated_at TIMESTAMP
 );
 
@@ -488,6 +488,29 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 13,
+        name: "memory_type_unified_terminology",
+        up: (db) => {
+            // #264 final step: rename the memory_type COLUMN VALUES from the raw
+            // internal enum (fact/episode/decision/lesson) to the unified human
+            // terms (knowledge/experience/decisions/learnings). The column itself,
+            // its default, and every SQL query/filter were updated in the same
+            // change; this migration converts existing rows in place. Idempotent:
+            // re-running against an already-migrated DB matches 0 rows per clause.
+            // The CREATE TABLE default is now 'experience' (was 'episode'); legacy
+            // rows with the old default value are rewritten here.
+            //
+            // Ordering is irrelevant (each clause keys on a distinct old value) and
+            // no clause can fire on another clause's output (the new values are
+            // disjoint from the old). The transaction wrapper in migrate() makes the
+            // whole migration atomic.
+            db.exec("UPDATE memories SET memory_type = 'knowledge'  WHERE memory_type = 'fact'");
+            db.exec("UPDATE memories SET memory_type = 'experience' WHERE memory_type = 'episode'");
+            db.exec("UPDATE memories SET memory_type = 'decisions'  WHERE memory_type = 'decision'");
+            db.exec("UPDATE memories SET memory_type = 'learnings'  WHERE memory_type = 'lesson'");
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

package/dist/distiller.d.ts

@@ -64,13 +64,13 @@ export declare function distillSession(llm: LlmClient, conversation: string, pro
 export declare function hasMinimalSubstance(entry: string): boolean;
 /**
  * A parsed distillation entry: the stored content (type tag STRIPPED) plus the
- * classified memory_type. `memoryType` is one of "episode" | "fact" |
- * "decision" — the three distillation-time types. "lesson" is deliberately
- * absent: lessons are the reflection stage's product, never distillation's
- * (#216). A missing/unknown tag defaults to "episode" so older distiller
+ * classified memory_type. `memoryType` is one of "experience" | "knowledge" |
+ * "decisions" — the three distillation-time types. "learnings" is deliberately
+ * absent: learnings are the reflection stage's product, never distillation's
+ * (#216). A missing/unknown tag defaults to "experience" so older distiller
  * output (pre-#216, no tag) stays backward-compatible.
  */
 export interface DistilledEntry {
     content: string;
-    memoryType: "episode" | "fact" | "decision";
+    memoryType: "experience" | "knowledge" | "decisions";
 }

package/dist/distiller.js

@@ -267,7 +267,7 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
             for (const entry of entries) {
                 // Deduplicate by normalized content (type tag does not participate —
                 // two chunks extracting the same fact should collapse regardless of
-                // whether one tagged it [F] and the other [E]).
+                // whether one tagged it [K] and the other [E]).
                 const key = entry.content.toLowerCase().replace(/\s+/g, " ").slice(0, 100);
                 if (!seen.has(key)) {
                     seen.add(key);
@@ -325,7 +325,7 @@ async function distillChunk(llm, transcript, projectName, date) {
     // sometimes ignore constraints (cf. the prior max-15-bullet failure). Count
     // entries that still look actor-led or bracket-led so a format regression
     // shows in nightly logs, not months later in the next eval. Non-blocking.
-    // Note: the type tag ([E]/[F]/[D]) is already stripped by the parser, so a
+    // Note: the type tag ([E]/[K]/[D]) is already stripped by the parser, so a
     // leading bracket here means a payload-bracket or a category-first regression.
     const offTopic = parsed.filter((e) => /^\s*(user|ai|the user|assistant)\b/i.test(e.content) || /^\s*\[/.test(e.content)).length;
     if (parsed.length > 0 && offTopic > 0) {
@@ -426,21 +426,31 @@ function hasMinimalSubstance(entry) {
 }
 /**
  * Map a single-letter type tag to the stored memory_type. Unknown/absent →
- * episode (the pre-#216 default). `[L]` is explicitly rejected → episode: the
- * distiller must NEVER emit lessons (that's the reflection stage's job), so a
- * model that emits `[L]` is wrong and we do not propagate it as a lesson.
+ * experience (the pre-#216 default). `[L]` is explicitly rejected →
+ * experience: the distiller must NEVER emit learnings (that's the reflection
+ * stage's job), so a model that emits `[L]` is wrong and we do not propagate
+ * it as a learning.
+ *
+ * The single-letter tags ([E]/[K]/[D]) are unchanged from the raw-enum era —
+ * the model is taught these as "EXPERIENCE/KNOWLEDGE/DECISIONS" concepts in prompts.ts
+ * (ordinary English the model understands), and only the resulting STORED
+ * value changed in #264 (episode→experience, fact→knowledge, decision→
+ * decisions). The tag letters stay stable so neither the prompt nor the
+ * parser needs to change; only this mapping table moves.
  */
 function typeFromTag(letter) {
     switch (letter) {
-        case "F":
+        case "K":
+        case "k":
+        case "F": // legacy tag (was Fact)
         case "f":
-            return "fact";
+            return "knowledge";
         case "D":
         case "d":
-            return "decision";
-        // E, e, L, l (rejected), undefined, or anything else → episode.
+            return "decisions";
+        // E, e, L, l (rejected), undefined, or anything else → experience.
         default:
-            return "episode";
+            return "experience";
     }
 }
 /**
@@ -448,7 +458,7 @@ function typeFromTag(letter) {
  * Each bullet becomes a separate memory. The leading `[E]`/`[F]`/`[D]` type
  * tag is extracted (→ memoryType), stripped from the stored content, and
  * passed to `insertMemory` via the `memoryType` option (#216). Bullets with
- * no tag default to "episode" (backward compatible with pre-#216 distiller
+ * no tag default to "experience" (backward compatible with pre-#216 distiller
  * output that never carried a tag).
  */
 function parseDistilledEntries(markdown) {
@@ -472,15 +482,15 @@ function parseDistilledEntries(markdown) {
             // Extract an optional leading single-letter type tag: "[E]", "[F]",
             // "[D]" (case-insensitive). The tag must be the very first token of the
             // bullet — a bracket that appears later is payload, not a type tag.
-            const tagMatch = body.match(/^\[([EFDefdLl])\]\s*/);
+            const tagMatch = body.match(/^\[([EFDKefdklL])\]\s*/);
             if (tagMatch) {
                 const memoryType = typeFromTag(tagMatch[1].toUpperCase());
                 entries.push({ content: body.slice(tagMatch[0].length), memoryType });
             }
             else {
-                // No tag → episode (pre-#216 distiller output, or a model that
+                // No tag → experience (pre-#216 distiller output, or a model that
                 // skipped the tag). Keep the content verbatim.
-                entries.push({ content: body, memoryType: "episode" });
+                entries.push({ content: body, memoryType: "experience" });
             }
         }
     }

package/dist/eval/recall-sweep.js

@@ -431,7 +431,7 @@ async function buildCorpusDb(dbPath) {
         const vec = await (0, embedder_js_1.embed)(mem.text);
         const id = storage.insertMemory(db, mem.text, vec, {
             sourceAgent: "eval-corpus",
-            memoryType: "episode",
+            memoryType: "experience",
             baseStrength: 0.5, // uniform — strength is NOT a discriminator here
         });
         idToTopic.set(id, mem.topic);
@@ -455,7 +455,7 @@ async function buildScopeDb(dbPath) {
         const vec = await (0, embedder_js_1.embed)(mem.text);
         const id = storage.insertMemory(db, mem.text, vec, {
             sourceAgent: "eval-scope",
-            memoryType: "episode",
+            memoryType: "experience",
             baseStrength: 0.5, // uniform — strength is NOT a discriminator here
             project: mem.project, // #203 scope label
         });

package/dist/eval/reflection-census.js

@@ -11,11 +11,11 @@ exports.runReflectionCensus = runReflectionCensus;
 function runReflectionCensus(db) {
     const lessonsByDate = db
         .prepare(`SELECT date(created_at) AS date, COUNT(*) AS count
-       FROM memories WHERE memory_type = 'lesson'
+       FROM memories WHERE memory_type = 'learnings'
        GROUP BY date ORDER BY date`)
         .all();
-    const totalLessons = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'lesson'").get().c;
-    const totalEpisodes = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'episode'").get().c;
+    const totalLessons = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'learnings'").get().c;
+    const totalEpisodes = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'experience'").get().c;
     return {
         lessonsByDate,
         totalLessons,

package/dist/index.js

@@ -150,7 +150,7 @@ async function fetchOcIdentityBlock(agentId) {
     return (0, learnings_identity_js_1.gateAndRenderIdentity)(data, THIS_HARNESS, { requireAgentEcho: agentId !== null });
 }
 /**
- * Fetch /lessons and build the `## Hicortex Lessons` block, or null on any
+ * Fetch /lessons and build the `## Hicortex Learnings` block, or null on any
  * failure or when no lessons survive selection. Preserves the pre-0.13 lesson
  * output; the caller prepends the `## Identity` block and adds separators.
  */
@@ -177,8 +177,8 @@ async function buildLessonsBlock(project) {
         const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
         return `- ${title}${meta ? ` (${meta})` : ""}`;
     });
-    return (`## Hicortex Lessons (auto-injected from long-term memory)\n` +
-        `These are actionable lessons learned from past sessions:\n\n` +
+    return (`## Hicortex Learnings (auto-injected from long-term memory)\n` +
+        `These are actionable Learnings from past sessions:\n\n` +
         formatted.join("\n"));
 }
 // ---------------------------------------------------------------------------
@@ -354,7 +354,7 @@ exports.default = {
                 const agentId = (0, identity_store_js_1.sanitizeAgentId)(ctx?.agentId ?? "");
                 // Fetch all three concurrently with INDEPENDENT fail-soft: no block
                 // may ever cost another. Order in the injected output: `## Identity`
-                // (standing identity, 0.13) → `## Hicortex Lessons` → the per-turn
+                // (standing identity, 0.13) → `## Hicortex Learnings` → the per-turn
                 // `## Memory recall (auto)` index (#193, closest to the prompt).
                 const [identityBlock, lessonsBlock, recallBlock] = await Promise.all([
                     fetchOcIdentityBlock(agentId).catch(() => null),
@@ -481,7 +481,7 @@ exports.default = {
         }), { name: "hicortex_recent" });
         api.registerTool((_ctx) => ({
             name: "hicortex_ingest",
-            description: "Store a new memory in long-term storage. Use for important facts, decisions, or lessons.",
+            description: "Store a new memory in long-term storage. Use for Knowledge, Decisions, or Learnings.",
             parameters: {
                 type: "object",
                 properties: {
@@ -489,8 +489,8 @@ exports.default = {
                     project: { type: "string", description: "Project this memory belongs to" },
                     memory_type: {
                         type: "string",
-                        enum: ["episode", "lesson", "fact", "decision"],
-                        description: "Type of memory (default: episode)",
+                        enum: ["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"],
+                        description: "Type of memory (default: Experience). Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term).",
                     },
                 },
                 required: ["content"],
@@ -501,7 +501,7 @@ exports.default = {
                         content: args.content,
                         source_agent: `openclaw/${context?.agentId ?? "manual"}`,
                         project: args.project,
-                        memory_type: args.memory_type ?? "episode",
+                        memory_type: args.memory_type ? (0, type_labels_js_1.normalizeMemoryType)(args.memory_type) : "experience",
                     }, 15000);
                     if (!result.ok) {
                         return { error: `Ingest failed: ${result.data?.error ?? `HTTP ${result.status}`}` };
@@ -516,7 +516,7 @@ exports.default = {
         }), { name: "hicortex_ingest" });
         api.registerTool((_ctx) => ({
             name: "hicortex_lessons",
-            description: "Get actionable lessons learned from past sessions. Auto-generated insights about mistakes to avoid.",
+            description: "Get actionable Learnings distilled from past sessions. Auto-generated insights about mistakes to avoid.",
             parameters: {
                 type: "object",
                 properties: {
@@ -530,7 +530,7 @@ exports.default = {
                         return { error: `Lessons fetch failed: ${describeGetFailure(status, "/lessons")}` };
                     const lessons = data.lessons ?? [];
                     if (lessons.length === 0) {
-                        return { content: [{ type: "text", text: "No lessons found." }] };
+                        return { content: [{ type: "text", text: "No Learnings found." }] };
                     }
                     const text = lessons.map((l) => `- ${l.content.slice(0, 500)}`).join("\n");
                     return { content: [{ type: "text", text }] };
@@ -612,8 +612,8 @@ exports.default = {
                     project: { type: "string", description: "New project name" },
                     memory_type: {
                         type: "string",
-                        enum: ["episode", "lesson", "fact", "decision"],
-                        description: "New memory type",
+                        enum: ["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"],
+                        description: "New memory type. Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term).",
                     },
                 },
                 required: ["id"],
@@ -624,7 +624,7 @@ exports.default = {
                         id: args.id,
                         content: args.content,
                         project: args.project,
-                        memory_type: args.memory_type,
+                        memory_type: args.memory_type ? (0, type_labels_js_1.normalizeMemoryType)(args.memory_type) : undefined,
                     }, 15000);
                     if (result.status === 404) {
                         return { error: `Memory not found: ${args.id}` };

package/dist/learnings-identity.js

@@ -117,7 +117,7 @@ async function fetchLessonsBlock(cfg) {
     parts.push("BEFORE making decisions, search memory: `hicortex_search` for prior decisions on the same topic.");
     parts.push("Use `hicortex_recent` at session start for recent project state.");
     if (lessonLines.length > 0) {
-        parts.push("", "### Lessons (updated nightly)");
+        parts.push("", "### Learnings (updated nightly)");
         parts.push(...lessonLines);
     }
     const { index } = data;
@@ -125,16 +125,16 @@ async function fetchLessonsBlock(cfg) {
         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.name} (${domain.memoryCount} memories, ${domain.lessonCount} Learnings)${kwStr}`);
             if (domain.projects.length > 0)
                 parts.push(`  ${domain.projects.join(" | ")}`);
         }
-        parts.push(`${index.total} memories, ${index.lessonCount} lessons, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
+        parts.push(`${index.total} memories, ${index.lessonCount} Learnings, ${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\`.`);
+        parts.push(`${index.total} memories, ${index.lessonCount} Learnings, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
     }
     return parts.join("\n");
 }

package/dist/mcp-server.js

@@ -183,10 +183,10 @@ function createMcpServer() {
         }
     });
     // -- hicortex_ingest --
-    server.tool("hicortex_ingest", "Store a new memory in long-term storage. Use for important facts, decisions, or lessons.", {
+    server.tool("hicortex_ingest", "Store a new memory in long-term storage. Use for Knowledge, Decisions, or Learnings.", {
         content: zod_1.z.string().describe("Memory content to store"),
         project: zod_1.z.string().optional().describe("Project this memory belongs to"),
-        memory_type: zod_1.z.enum(["episode", "lesson", "fact", "decision"]).optional().describe("Type of memory (default: episode)"),
+        memory_type: zod_1.z.enum(["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"]).optional().describe("Type of memory (default: Experience). Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term)."),
     }, async ({ content, project, memory_type }) => {
         if (!db)
             return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
@@ -195,7 +195,8 @@ function createMcpServer() {
             const id = storage.insertMemory(db, content, embedding, {
                 sourceAgent: "claude-code/manual",
                 project,
-                memoryType: memory_type ?? "episode",
+                // Normalize legacy raw enum to the canonical term the DB stores.
+                memoryType: memory_type ? (0, type_labels_js_1.normalizeMemoryType)(memory_type) : "experience",
             });
             return { content: [{ type: "text", text: `Memory stored (id: ${id.slice(0, 8)})` }] };
         }
@@ -208,7 +209,7 @@ function createMcpServer() {
         id: zod_1.z.string().describe("Memory ID (from search results, first 8 chars or full UUID)"),
         content: zod_1.z.string().optional().describe("New content text"),
         project: zod_1.z.string().optional().describe("New project name"),
-        memory_type: zod_1.z.enum(["episode", "lesson", "fact", "decision"]).optional().describe("New memory type"),
+        memory_type: zod_1.z.enum(["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"]).optional().describe("New memory type. Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term)."),
     }, async ({ id, content, project, memory_type }) => {
         if (!db)
             return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
@@ -222,8 +223,9 @@ function createMcpServer() {
                 fields.content = content;
             if (project !== undefined)
                 fields.project = project;
+            // Normalize legacy raw enum to canonical human terms before DB write.
             if (memory_type !== undefined)
-                fields.memory_type = memory_type;
+                fields.memory_type = (0, type_labels_js_1.normalizeMemoryType)(memory_type);
             if (Object.keys(fields).length === 0) {
                 return { content: [{ type: "text", text: "No fields to update" }], isError: true };
             }
@@ -319,7 +321,7 @@ function createMcpServer() {
         const moduleIndex = state.moduleIndex;
         if (moduleIndex && moduleIndex.domains.length > 0) {
             const text = moduleIndex.domains.map((d) => {
-                const head = `**${d.name}** (${d.memoryCount} memories, ${d.lessonCount} lessons)`;
+                const head = `**${d.name}** (${d.memoryCount} memories, ${d.lessonCount} Learnings)`;
                 // Content-based domains carry a description and no projects; legacy
                 // project-grouping domains carry a project list + keywords.
                 if (d.description && d.projects.length === 0) {
@@ -692,11 +694,15 @@ async function startServer(options = {}) {
             res.status(400).json({ error: "Missing or invalid 'content' field" });
             return;
         }
-        const validTypes = ["episode", "lesson", "fact", "decision"];
+        const validTypes = type_labels_js_1.ACCEPTED_MEMORY_TYPES;
         if (memory_type && !validTypes.includes(memory_type)) {
             res.status(400).json({ error: `Invalid memory_type: ${memory_type}` });
             return;
         }
+        // Normalize legacy raw enum (fact/episode/decision/lesson) to the
+        // canonical term the DB stores (knowledge/experience/decisions/learnings).
+        // Canonical values pass through unchanged.
+        const normalizedType = memory_type ? (0, type_labels_js_1.normalizeMemoryType)(memory_type) : memory_type;
         // Dedup by source_session (idempotent — skip if already ingested)
         if (source_session) {
             const existing = db.prepare("SELECT COUNT(*) as cnt FROM memories WHERE source_session = ?").get(source_session);
@@ -714,7 +720,7 @@ async function startServer(options = {}) {
                 sourceDomain: typeof source_domain === "string" ? source_domain : null,
                 sourceSession: source_session ?? undefined,
                 project: project ?? undefined,
-                memoryType: memory_type ?? "episode",
+                memoryType: normalizedType ?? "experience",
                 // 0.16.x: privacy defaults to null (vestigial column). A legacy client
                 // that sends an explicit value is honored; absent → null.
                 privacy: typeof privacy === "string" ? privacy : null,
@@ -1061,9 +1067,9 @@ async function startServer(options = {}) {
                         sourceSession: sourcePrefix ? `${sourcePrefix}#${i}` : undefined,
                         project: project ?? undefined,
                         // #216: the distiller now classifies each entry as
-                        // episode/fact/decision via the [E]/[F]/[D] tag parsed in
+                        // experience/knowledge/decisions via the [E]/[K]/[D] tag parsed in
                         // distiller.ts. Pre-#216 distiller output (no tag) defaults to
-                        // episode in the parser, so this is backward compatible.
+                        // experience in the parser, so this is backward compatible.
                         memoryType,
                         // 0.16.x: privacy defaults to null (vestigial column). A legacy
                         // client that sends an explicit value is honored; absent → null.
@@ -1111,19 +1117,24 @@ async function startServer(options = {}) {
             fields.content = content;
         if (project !== undefined)
             fields.project = project;
-        if (memory_type !== undefined)
-            fields.memory_type = memory_type;
         if (privacy !== undefined)
             fields.privacy = privacy;
-        if (Object.keys(fields).length === 0) {
-            res.status(400).json({ error: "No fields to update" });
-            return;
-        }
-        const validTypes = ["episode", "lesson", "fact", "decision"];
+        // Validate + normalize memory_type BEFORE adding to `fields` so the
+        // empty-fields check below correctly counts a memory_type-only update.
+        const validTypes = type_labels_js_1.ACCEPTED_MEMORY_TYPES;
         if (memory_type !== undefined && !validTypes.includes(memory_type)) {
             res.status(400).json({ error: `Invalid memory_type: ${memory_type}` });
             return;
         }
+        // Normalize legacy raw enum (fact/episode/decision/lesson) to the
+        // canonical term the DB stores (knowledge/experience/decisions/learnings).
+        // Canonical values pass through unchanged.
+        if (memory_type !== undefined)
+            fields.memory_type = (0, type_labels_js_1.normalizeMemoryType)(memory_type);
+        if (Object.keys(fields).length === 0) {
+            res.status(400).json({ error: "No fields to update" });
+            return;
+        }
         try {
             storage.updateMemory(db, fullId, fields);
             // Re-embed when content changes

package/dist/prompts.js

@@ -48,7 +48,7 @@ function reflection(memoriesBlock, recentLessons) {
 Like human learning: we grow fastest when we reinforce what works AND correct what doesn't. A system that only learns from mistakes becomes overly cautious. A system that only learns from successes never improves. The combination multiplies.
 
 GENERALITY BAR (read carefully — the most important rule):
-Every lesson MUST be a generalizable operating principle that transfers across contexts, agents, and projects. It is NOT: an incident report, a changelog entry, a one-event fact, a tool-specific recipe, or a note about a named entity. If a memory is only interesting as "what happened today", it is an EPISODE — do not emit a lesson for it. Abstract away specific tool names, hostnames, and incident details from the lesson text; state the transferable rule.
+Every lesson MUST be a generalizable operating principle that transfers across contexts, agents, and projects. It is NOT: an incident report, a changelog entry, a one-event fact, a tool-specific recipe, or a note about a named entity. If a memory is only interesting as "what happened today", it is an EXPERIENCE — do not emit a lesson for it. Abstract away specific tool names, hostnames, and incident details from the lesson text; state the transferable rule.
 
 Quality over quantity. 1-3 lessons is typical. An empty array [] is the CORRECT response when memories show routine competent work without noteworthy patterns, surprises, or friction. Do not manufacture lessons from nothing.
 
@@ -121,8 +121,8 @@ EXTRACT into this markdown format:
 ### Decisions Made
 - [D] [SUBJECT]: [decision] — [reasoning] (${date})
 
-### Facts Learned
-- [F] [SUBJECT]: [fact] — [context/source] (${date})
+### Knowledge Learned
+- [K] [SUBJECT]: [knowledge] — [context/source] (${date})
 
 ### Problems & Solutions
 - [E] [SUBJECT]: [problem] → [solution that worked] (${date})
@@ -131,7 +131,7 @@ EXTRACT into this markdown format:
 - [D] [SUBJECT]: [what changed], [from → to] (${date})
 
 ### Key Entities & Relationships
-- [F] [entity A] → [relationship] → [entity B] (${date})
+- [K] [entity A] → [relationship] → [entity B] (${date})
 
 ### Corrections & Rejections
 - [E] [SUBJECT]: [what AI proposed] → [why rejected/corrected] → [what user wanted instead] (${date})
@@ -139,18 +139,18 @@ EXTRACT into this markdown format:
    user corrections of AI assumptions, quality complaints like "too verbose")
 
 TYPE TAG (critical — prefix EVERY bullet with exactly one letter + space):
-- [E] EPISODE — a specific event, interaction, or narrative: "tried X, failed
+- [E] EXPERIENCE — a specific event, interaction, or narrative: "tried X, failed
   because Y", a correction, a debugging session, a one-time occurrence. The
   DEFAULT when in doubt.
-- [F] FACT — a durable truth that will hold across sessions: "the API is at
+- [K] KNOWLEDGE — a durable truth that will hold across sessions: "the API is at
   :8787", "uv is used for packages", "config lives in ~/.hicortex/". Not tied
   to a single moment.
-- [D] DECISION — a choice made that future work builds on, and that a later
+- [D] DECISIONS — a choice made that future work builds on, and that 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
+  graded-schema tag model". Not knowledge (it can change) and not experience
   (it persists and constrains).
-- NEVER use [L] (lesson). Lessons are extracted by a SEPARATE reflection stage,
-  not here. If the model emits [L], it is wrong — re-tag as episode/fact/decision.
+- NEVER use [L] (learnings). Learnings are extracted by a SEPARATE reflection stage,
+  not here. If the model emits [L], it is wrong — re-tag as experience/knowledge/decisions.
 The type tag goes BEFORE the subject, never as a section/category bracket.
 
 TOPIC-FIRST RULE (critical — read carefully):
@@ -159,8 +159,8 @@ concrete thing it is about — the system, file, component, decision area, or
 entity. The subject is what a future reader would search for.
 - Write:  "[E] Electrical load calculation: don't bundle unknown loads into one figure — user rejected the estimate"
 - NOT:    "[E] User rejected AI's bundling of unknown loads"
-- Write:  "[F] Nightly capture (Hermes): cron sessions are excluded — source='cron' is skipped before distillation"
-- NOT:    "[F] Discovered that cron sessions are filtered out"
+- Write:  "[K] Nightly capture (Hermes): cron sessions are excluded — source='cron' is skipped before distillation"
+- NOT:    "[K] Discovered that cron sessions are filtered out"
 Reason: each item's first words (after the type tag) become the memory's one-line
 index entry AND dominate its search embedding. An item that opens with a category
 label, a sentiment ("Strong Negative"), or "User rejected…" is unfindable — it