@gamaze/hicortex 0.18.1 → 0.18.3

package/dist/type-labels.d.ts

@@ -1,30 +1,61 @@
 /**
- * Human-term labels for the internal `memory_type` enum (#264 WS2).
+ * Human-term labels + normalization for the `memory_type` enum (#264 final).
  *
- * The data model stores four types under unintuitive internal names
- * (`fact` / `episode` / `decision` / `lesson`). Product-facing surfaces show
- * the human terms instead — Knowledge / Experience / Decisions / Learnings —
- * via this single label map. The enum values themselves are NEVER changed:
- * no DB column, query, distiller tag, or storage path is altered. This is a
- * DISPLAY rename only; every user-facing rendering routes through
- * `labelForType`.
+ * The DB column `memories.memory_type` stores the four CANONICAL human terms:
+ *   knowledge / experience / decisions / learnings
+ * These replaced the older raw internal enum (fact/episode/decision/lesson)
+ * via migration v13. Every SQL query, the distiller's type tag mapping, the
+ * type-classify prompt, and the CREATE TABLE default all use the new terms.
+ *
+ * Backward-compat window: the OLD raw values are still accepted on the
+ * request/agent wire (REST `/ingest` + `/update`, MCP tools, OC + Hermes
+ * plugin schemas) and normalized to the new canonical value before any DB
+ * write via {@link normalizeMemoryType}. The label map also still carries
+ * the old keys so a briefly-stale reader (e.g. a snapshot taken mid-migrate)
+ * renders correctly.
  *
  * Mapping (decided 2026-08-11, research/2026-08-11-identity-reframe-brainstorm.md):
- *   fact     → Knowledge
- *   episode  → Experience
- *   decision → Decisions
- *   lesson   → Learnings
+ *   fact     → knowledge
+ *   episode  → experience
+ *   decision → decisions
+ *   lesson   → learnings
  *
  * Unknown / future types fall back to the raw value (never silently remapped).
  */
 /**
- * The four documented memory types mapped to their human-term labels.
- * Kept as a plain record so it can be iterated for coverage assertions.
+ * The four canonical memory types mapped to their human-term labels, PLUS the
+ * legacy raw keys kept during the backward-compat window (old values may appear
+ * briefly in snapshots taken before migration v13, or in-flight requests from
+ * older clients). Kept as a plain record so it can be iterated for coverage
+ * assertions.
  */
 export declare const MEMORY_TYPE_LABELS: Record<string, string>;
 /**
- * Return the human-term label for a `memory_type` enum value. Unknown or
- * future types (including null/undefined) fall back to the raw input so new
- * types are visible rather than silently mislabeled.
+ * Return the human-term label for a `memory_type` value (canonical OR legacy).
+ * Unknown or future types (including null/undefined) fall back to the raw
+ * input so new types are visible rather than silently mislabeled.
  */
 export declare function labelForType(t: string | null | undefined): string;
+/**
+ * Normalize a `memory_type` input (from a request body, MCP tool arg, etc.)
+ * to the canonical value the DB stores (post-v13). Accepts the four legacy
+ * raw enum values (fact/episode/decision/lesson, mapped to the new terms) AND
+ * the four canonical human terms (passthrough). Unknown values pass through
+ * verbatim — the caller validates.
+ */
+export declare function normalizeMemoryType(input: string): string;
+/**
+ * The full accept-set for input validation: the four canonical values plus the
+ * four legacy raw values (kept for backward compat of older clients). Exposed
+ * so every validating surface (REST `/ingest`, `/update`, MCP zod enums, OC
+ * JSON-schema enums, the Hermes plugin) lists the SAME accepted values — no
+ * drift. Compare membership case-insensitively (caller normalizes via
+ * {@link normalizeMemoryType} before the DB write).
+ */
+export declare const ACCEPTED_MEMORY_TYPES: readonly string[];
+/**
+ * True if `input` is one of the accepted memory_type values (canonical OR
+ * legacy raw, any casing). Use this as the validation gate; follow with
+ * {@link normalizeMemoryType} to map the accepted value to the canonical term.
+ */
+export declare function isAcceptedMemoryType(input: string): boolean;

package/dist/type-labels.js

@@ -1,43 +1,114 @@
 "use strict";
 /**
- * Human-term labels for the internal `memory_type` enum (#264 WS2).
+ * Human-term labels + normalization for the `memory_type` enum (#264 final).
  *
- * The data model stores four types under unintuitive internal names
- * (`fact` / `episode` / `decision` / `lesson`). Product-facing surfaces show
- * the human terms instead — Knowledge / Experience / Decisions / Learnings —
- * via this single label map. The enum values themselves are NEVER changed:
- * no DB column, query, distiller tag, or storage path is altered. This is a
- * DISPLAY rename only; every user-facing rendering routes through
- * `labelForType`.
+ * The DB column `memories.memory_type` stores the four CANONICAL human terms:
+ *   knowledge / experience / decisions / learnings
+ * These replaced the older raw internal enum (fact/episode/decision/lesson)
+ * via migration v13. Every SQL query, the distiller's type tag mapping, the
+ * type-classify prompt, and the CREATE TABLE default all use the new terms.
+ *
+ * Backward-compat window: the OLD raw values are still accepted on the
+ * request/agent wire (REST `/ingest` + `/update`, MCP tools, OC + Hermes
+ * plugin schemas) and normalized to the new canonical value before any DB
+ * write via {@link normalizeMemoryType}. The label map also still carries
+ * the old keys so a briefly-stale reader (e.g. a snapshot taken mid-migrate)
+ * renders correctly.
  *
  * Mapping (decided 2026-08-11, research/2026-08-11-identity-reframe-brainstorm.md):
- *   fact     → Knowledge
- *   episode  → Experience
- *   decision → Decisions
- *   lesson   → Learnings
+ *   fact     → knowledge
+ *   episode  → experience
+ *   decision → decisions
+ *   lesson   → learnings
  *
  * Unknown / future types fall back to the raw value (never silently remapped).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MEMORY_TYPE_LABELS = void 0;
+exports.ACCEPTED_MEMORY_TYPES = exports.MEMORY_TYPE_LABELS = void 0;
 exports.labelForType = labelForType;
+exports.normalizeMemoryType = normalizeMemoryType;
+exports.isAcceptedMemoryType = isAcceptedMemoryType;
 /**
- * The four documented memory types mapped to their human-term labels.
- * Kept as a plain record so it can be iterated for coverage assertions.
+ * The four canonical memory types mapped to their human-term labels, PLUS the
+ * legacy raw keys kept during the backward-compat window (old values may appear
+ * briefly in snapshots taken before migration v13, or in-flight requests from
+ * older clients). Kept as a plain record so it can be iterated for coverage
+ * assertions.
  */
 exports.MEMORY_TYPE_LABELS = {
+    // Canonical (post-v13) values.
+    knowledge: "Knowledge",
+    experience: "Experience",
+    decisions: "Decisions",
+    learnings: "Learnings",
+    // Legacy raw enum (kept so stale readers render correctly during the
+    // migration window). Same labels — these are the SAME types, renamed.
     fact: "Knowledge",
     episode: "Experience",
     decision: "Decisions",
     lesson: "Learnings",
 };
 /**
- * Return the human-term label for a `memory_type` enum value. Unknown or
- * future types (including null/undefined) fall back to the raw input so new
- * types are visible rather than silently mislabeled.
+ * Return the human-term label for a `memory_type` value (canonical OR legacy).
+ * Unknown or future types (including null/undefined) fall back to the raw
+ * input so new types are visible rather than silently mislabeled.
  */
 function labelForType(t) {
     if (!t)
         return "—";
     return exports.MEMORY_TYPE_LABELS[t] ?? t;
 }
+/**
+ * Map BOTH legacy raw enum values AND canonical human terms TO the canonical
+ * value stored in the DB (post-v13). Used to normalize request input
+ * (`/ingest`, `/update`, MCP tools) so the wire/agent surface accepts the old
+ * vocabulary while the storage layer always sees the canonical term.
+ * Unknown inputs pass through untouched so the caller's own validation can
+ * reject them with a precise error (this helper never silently remaps).
+ *
+ * Lookup is case-insensitive on the input (the human terms are documented in
+ * Titlecase but agents/users send any casing); the four canonical values and
+ * the four legacy raw values are all lowercase in the DB.
+ */
+const TO_CANONICAL = {
+    // Legacy raw → canonical.
+    fact: "knowledge",
+    episode: "experience",
+    decision: "decisions",
+    lesson: "learnings",
+    // Canonical passthrough (also covered case-insensitively).
+    knowledge: "knowledge",
+    experience: "experience",
+    decisions: "decisions",
+    learnings: "learnings",
+};
+/**
+ * Normalize a `memory_type` input (from a request body, MCP tool arg, etc.)
+ * to the canonical value the DB stores (post-v13). Accepts the four legacy
+ * raw enum values (fact/episode/decision/lesson, mapped to the new terms) AND
+ * the four canonical human terms (passthrough). Unknown values pass through
+ * verbatim — the caller validates.
+ */
+function normalizeMemoryType(input) {
+    return TO_CANONICAL[input.toLowerCase()] ?? input;
+}
+/**
+ * The full accept-set for input validation: the four canonical values plus the
+ * four legacy raw values (kept for backward compat of older clients). Exposed
+ * so every validating surface (REST `/ingest`, `/update`, MCP zod enums, OC
+ * JSON-schema enums, the Hermes plugin) lists the SAME accepted values — no
+ * drift. Compare membership case-insensitively (caller normalizes via
+ * {@link normalizeMemoryType} before the DB write).
+ */
+exports.ACCEPTED_MEMORY_TYPES = Object.freeze([
+    "knowledge", "experience", "decisions", "learnings",
+    "fact", "episode", "decision", "lesson",
+]);
+/**
+ * True if `input` is one of the accepted memory_type values (canonical OR
+ * legacy raw, any casing). Use this as the validation gate; follow with
+ * {@link normalizeMemoryType} to map the accepted value to the canonical term.
+ */
+function isAcceptedMemoryType(input) {
+    return exports.ACCEPTED_MEMORY_TYPES.includes(input.toLowerCase());
+}

package/dist/types.d.ts

@@ -30,7 +30,7 @@ export interface Memory {
      */
     source_domain: string | null;
     privacy: ("PUBLIC" | "WORK" | "PERSONAL" | "SENSITIVE") | null;
-    memory_type: "episode" | "lesson" | "fact" | "decision";
+    memory_type: "experience" | "learnings" | "knowledge" | "decisions";
     updated_at: string | null;
 }
 /** A link between two memories. */
@@ -412,6 +412,15 @@ export interface HicortexConfig {
      * so these were not surfacing in the top-k anyway).
      */
     memorySoftCap?: number;
+    /**
+     * Hosted-service mode (issue #110, #271 — spec 2026-07-27 §1-§2). When true,
+     * the server enforces hosted-tenant constraints at boot: it refuses to start
+     * if `HICORTEX_DB_PATH` is set (path-override attacks) or if the localhost
+     * auth-bypass marker file is present (hosted must be fail-closed — no bypass).
+     * Absent/false (the self-hosted default) → the assertions never fire and
+     * behaviour is unchanged. Read at server boot via readStrictBoolean.
+     */
+    hostedMode?: boolean;
     /**
      * Monthly fair-use ceiling on consolidation LLM token consumption (#246).
      * Default `0` = unlimited (the self-hosted default — no cap, never throttled).

package/dist/viz.d.ts

@@ -45,8 +45,16 @@ export declare const VIZ_VENDOR_FILES: ReadonlySet<string>;
  * always evaluated (no short-circuit), so a caller cannot learn WHICH token
  * matched from the response timing. Absent/empty `authTokenPrevious` behaves
  * exactly as the single-token middleware always has.
+ *
+ * `allowLocalhostBypass` (0.18, #110 §2/#271): when false (or omitted), the
+ * localhost bypass is DISABLED — localhost connections need the bearer token
+ * like any other (fail-closed). When true, localhost loopback (127.0.0.1,
+ * ::1, ::ffff:127.0.0.1) bypasses auth as before. The marker file
+ * `~/.hicortex/.allow-localhost-bypass` (written by self-hosted init) gates
+ * this — a hosted tenant dir is fail-closed by default. mcp-server.ts captures
+ * the marker state once at boot and passes it in (no per-request stat).
  */
-export declare function createAuthMiddleware(authToken: string | undefined, authTokenPrevious?: string): express.RequestHandler;
+export declare function createAuthMiddleware(authToken: string | undefined, authTokenPrevious?: string, allowLocalhostBypass?: boolean): express.RequestHandler;
 /**
  * Resolve the on-disk path of the viz page. Throws (fail explicitly) when the
  * asset is missing — a broken install should surface, not degrade silently.

package/dist/viz.js

@@ -92,9 +92,18 @@ function safeBearerMatch(headerValue, expectedToken) {
  * always evaluated (no short-circuit), so a caller cannot learn WHICH token
  * matched from the response timing. Absent/empty `authTokenPrevious` behaves
  * exactly as the single-token middleware always has.
+ *
+ * `allowLocalhostBypass` (0.18, #110 §2/#271): when false (or omitted), the
+ * localhost bypass is DISABLED — localhost connections need the bearer token
+ * like any other (fail-closed). When true, localhost loopback (127.0.0.1,
+ * ::1, ::ffff:127.0.0.1) bypasses auth as before. The marker file
+ * `~/.hicortex/.allow-localhost-bypass` (written by self-hosted init) gates
+ * this — a hosted tenant dir is fail-closed by default. mcp-server.ts captures
+ * the marker state once at boot and passes it in (no per-request stat).
  */
-function createAuthMiddleware(authToken, authTokenPrevious) {
+function createAuthMiddleware(authToken, authTokenPrevious, allowLocalhostBypass) {
     const previous = authTokenPrevious && authTokenPrevious.length > 0 ? authTokenPrevious : undefined;
+    const bypassEnabled = allowLocalhostBypass === true;
     return (req, res, next) => {
         if (req.path === "/health")
             return next();
@@ -142,7 +151,7 @@ function createAuthMiddleware(authToken, authTokenPrevious) {
                 return next();
         }
         const ip = req.ip ?? req.socket.remoteAddress ?? "";
-        if (ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1")
+        if (bypassEnabled && (ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1"))
             return next();
         // Constant-time bearer check (#254). When authTokenPrevious is set, BOTH
         // tokens are compared every request (no short-circuit) so timing cannot

package/hermes-plugin/hicortex/client.py

@@ -169,7 +169,7 @@ class HicortexClient:
         content: str,
         source_agent: Optional[str] = None,
         project: Optional[str] = None,
-        memory_type: str = "episode",
+        memory_type: str = "experience",
         privacy: str = "WORK",
     ) -> tuple[int, dict[str, Any]]:
         return self._post(

package/hermes-plugin/hicortex/provider.py

@@ -132,7 +132,7 @@ def _order_section_names(names: Iterable[str]) -> List[str]:
 
 
 def _render_context_block(sections: Dict[str, Any]) -> str:
-    """Render the ``## Context`` block, or "" when every section is blank."""
+    """Render the ``## Identity`` block, or "" when every section is blank."""
     body_parts: List[str] = []
     for name in _order_section_names(sections.keys()):
         body = sections.get(name)
@@ -141,7 +141,7 @@ def _render_context_block(sections: Dict[str, Any]) -> str:
         body_parts.extend([f"### {_title_case_section(name)}", "", body.strip()])
     if not body_parts:
         return ""
-    return "\n".join(["## Context", "", *body_parts])
+    return "\n".join(["## Identity", "", *body_parts])
 
 
 class HicortexProvider(MemoryProvider):
@@ -397,7 +397,7 @@ class HicortexProvider(MemoryProvider):
         return "\n\n".join(b for b in blocks if b)
 
     def _context_block(self, client: HicortexClient) -> str:
-        """Fetch the standing context layer and render a ``## Context`` block,
+        """Fetch the standing context layer and render a ``## Identity`` block,
         or "" when nothing should be injected. Gates (ALL): "hermes" in the
         server-resolved ``clients``; when an agent id was SENT, the response
         echoes ``agent`` (old-server guard — a pre-0.13 server ignores ?agent=
@@ -444,7 +444,7 @@ class HicortexProvider(MemoryProvider):
             "the recall index), and `hicortex_recent` for recent memories by project.",
         ]
         if lessons:
-            lines.append("Lessons:")
+            lines.append("Learnings:")
             for l in lessons:
                 c = (l.get("content") or "").strip().replace("\n", " ")
                 # Legacy lessons were stored with a "## Lesson:" prefix; new ones are
@@ -455,7 +455,7 @@ class HicortexProvider(MemoryProvider):
                 lines.append(f"- {c[:200]}")
         if idx.get("total"):
             lines.append(
-                f"({idx.get('total')} memories, {idx.get('lessonCount')} lessons "
+                f"({idx.get('total')} memories, {idx.get('lessonCount')} learnings "
                 f"across {idx.get('sourceCount')} agents)"
             )
         return "\n".join(lines)
@@ -523,7 +523,7 @@ class HicortexProvider(MemoryProvider):
                 "name": "hicortex_ingest",
                 "description": (
                     "Store a new memory in long-term storage. "
-                    "Use for important facts, decisions, or lessons."
+                    "Use for Knowledge, Decisions, or Learnings."
                 ),
                 "parameters": {
                     "type": "object",
@@ -532,8 +532,8 @@ class HicortexProvider(MemoryProvider):
                         "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 server-side).",
                         },
                     },
                     "required": ["content"],
@@ -542,7 +542,7 @@ class HicortexProvider(MemoryProvider):
             {
                 "name": "hicortex_lessons",
                 "description": (
-                    "Get actionable lessons learned from past sessions. "
+                    "Get actionable Learnings distilled from past sessions. "
                     "Auto-generated insights about mistakes to avoid."
                 ),
                 "parameters": {
@@ -603,8 +603,8 @@ class HicortexProvider(MemoryProvider):
                         "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 server-side).",
                         },
                     },
                     "required": ["id"],
@@ -677,7 +677,7 @@ class HicortexProvider(MemoryProvider):
                     content=content,
                     source_agent="hermes/manual",
                     project=args.get("project") or self._project,
-                    memory_type=args.get("memory_type", "episode"),
+                    memory_type=args.get("memory_type", "experience"),
                 )
                 if status not in (200, 201):
                     return json.dumps({"error": resp.get("error", f"HTTP {status}")})
@@ -688,7 +688,7 @@ class HicortexProvider(MemoryProvider):
                 data = client.lessons()
                 lessons = (data.get("lessons") or [])
                 if not lessons:
-                    return json.dumps({"message": "No lessons found."})
+                    return json.dumps({"message": "No Learnings found."})
                 return json.dumps([{"content": l.get("content", "")[:500]} for l in lessons])
 
             elif tool_name == "hicortex_index":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "description": "Persistent agent identity for AI agents — a hand-edited identity layer, nightly-distilled experience, and lessons injected every session, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {