@gamaze/hicortex 0.10.1 → 0.11.1

package/dist/types.d.ts

@@ -72,6 +72,24 @@ export interface ConsolidationReport {
         domain_curation?: {
             curated: boolean;
             domains: number;
+            /** Content-based path only: memories (re)filed this run. */
+            classified?: number;
+            /** Graded-schema pass: domains with a stored prototype after the run. */
+            prototypes?: number;
+            /** Graded-schema pass: memory_tags rows whose weight was recomputed. */
+            weights_recomputed?: number;
+            /** Graded-schema pass: memories whose derived primary changed. */
+            primaries_updated?: number;
+            /**
+             * No-fit path: memories that earned a WEAK primary (argmax prototype
+             * cosine >= weakPrimaryFloor) after the LLM found no fitting domain.
+             */
+            weak_primary?: number;
+            /**
+             * No-fit path: memories below the weak-primary floor — untagged,
+             * base_strength halved (accelerated decay toward prune).
+             */
+            no_association_decayed?: number;
             reason?: string;
         };
         hub_boost?: {
@@ -112,10 +130,65 @@ export interface HicortexConfig {
     llmModel?: string;
     /** @deprecated Use the Hicortex server for distillation and consolidation. */
     reflectModel?: string;
+    /**
+     * Optional dedicated model for memory tag classification (server-side
+     * nightly + `hicortex classify-domains`). When unset, classification uses
+     * the reflect tier exactly as before.
+     */
+    classifyModel?: string;
+    /**
+     * Optional dedicated endpoint for classification. When only classifyModel
+     * is set, it runs on the reflect endpoint (else the base endpoint).
+     */
+    classifyBaseUrl?: string;
+    /** Optional API key for the classify endpoint (defaults to the base apiKey). */
+    classifyApiKey?: string;
+    /** Optional provider for the classify endpoint (defaults to the base provider). */
+    classifyProvider?: string;
     /** @deprecated Consolidation is owned by the server nightly. */
     consolidateHour?: number;
     /** @deprecated The OC plugin no longer opens its own database. */
     dbPath?: string;
+    /**
+     * Optional config-owned domain list — the user's top-level memory spheres
+     * (life areas OR project/topic areas). When present, the nightly multi-tag
+     * classifies each memory by CONTENT against this vocabulary (classify tier,
+     * falling back to the reflect tier) instead of grouping projects into
+     * LLM-invented domains. When ABSENT, the legacy project-grouping
+     * moduleIndex behaviour is unchanged.
+     *
+     * Server-mode `init` scaffolds a generic 5-domain default (Work, Personal,
+     * People, Health, Finance — see GENERIC_DEFAULT_DOMAINS in init.ts) when
+     * this key is absent, and NEVER touches an existing list. A power-user
+     * example (compartment flag, custom weakPrimaryFloor) ships as
+     * domains.example.json in the package root.
+     *
+     * NO fallback bucket is needed or special-cased (owner amendment 07.07):
+     * a genuine no-fit memory gets a WEAK primary from prototype cosines when
+     * possible, else it decays toward pruning (see nofit.ts). A domain named
+     * "Unsorted" — if configured — is just a normal domain.
+     */
+    domains?: DomainDef[];
+    /**
+     * Minimum cosine(memory embedding, best domain prototype) for a no-fit
+     * memory to earn a WEAK primary instead of decaying (see nofit.ts).
+     * Number in (0, 1); default 0.45. Tune from the corpus weight distribution
+     * (the memory_tags.weight histogram of LLM-tagged rows — set the floor
+     * near its lower tail). See domains.example.json for a worked example.
+     */
+    weakPrimaryFloor?: number;
+}
+/** A config-owned life-sphere domain (see HicortexConfig.domains). */
+export interface DomainDef {
+    name: string;
+    description: string;
+    /**
+     * Deliberate compartmentalization (graded-schema spec, 07.07.2026): when
+     * true, this domain becomes the PRIMARY (memories.domain) whenever it is
+     * tagged, overriding the argmax-weight rule. The owner's config flags only
+     * Work — a work/life firewall. Optional; absent = false.
+     */
+    compartment?: boolean;
 }
 /** Response from license validation API. */
 export interface LicenseInfo {
@@ -138,14 +211,31 @@ export interface ModuleDomain {
     memoryCount: number;
     lessonCount: number;
     keywords: string[];
+    /**
+     * One-line description — only populated for content-based (config-owned)
+     * domains. Empty for project-grouping domains.
+     */
+    description?: string;
 }
 /** Auto-generated knowledge routing index, cached in state.json. */
 export interface ModuleIndex {
     domains: ModuleDomain[];
+    /**
+     * Cache-invalidation key.
+     *   - Project-grouping mode: sha256 of the sorted PROJECT name set.
+     *   - Content-based mode: sha256 of the sorted configured DOMAIN name set.
+     * A single field keeps the state shape stable; `mode` disambiguates.
+     */
     projectSetHash: string;
     curatedAt: string;
     totalMemories: number;
     totalLessons: number;
+    /**
+     * How this index was built. Absent = legacy project-grouping (backward
+     * compatible). "content" = per-memory content classification from the
+     * config-owned `domains` list.
+     */
+    mode?: "project" | "content";
 }
 /** Options for inserting a memory. */
 export interface InsertMemoryOptions {

package/dist/viz.d.ts

@@ -0,0 +1,69 @@
+/**
+ * /viz support (#124) — knowledge-graph visualization page.
+ *
+ * Two concerns live here so they can be unit-tested without booting the full
+ * MCP daemon (mcp-server.ts pulls in the embedder + MCP SDK):
+ *
+ * 1. createAuthMiddleware — the bearer-token auth middleware used by the whole
+ *    REST surface. Extracted verbatim from mcp-server.ts, plus ONE change for
+ *    /viz: the page SHELL is exempt like /health (it carries no data or
+ *    secrets — it ships verbatim in the public npm tarball). Browsers cannot
+ *    attach an Authorization header on plain navigation; the page collects
+ *    the token client-side and uses it on its /graph data fetch, which stays
+ *    bearer-only like every other data route.
+ *
+ * 2. readVizHtml — loads the self-contained visualization page from
+ *    assets/viz.html at request time. The asset sits next to src/ and dist/
+ *    (siblings), so `../assets/viz.html` resolves from both the compiled
+ *    output (dist/viz.js) and the TypeScript source (tests/tsx).
+ *
+ * 3. vendorHandler — serves the pinned renderer bundles from assets/vendor/
+ *    (#139: three.js / 3d-force-graph / force-graph, see
+ *    THIRD_PARTY_NOTICES.md). STRICT allowlist of exact filenames — the
+ *    request path is never joined into the filesystem path; the served path
+ *    comes from a fixed lookup table, so traversal is impossible by
+ *    construction. Public like the /viz shell (static public code, no data).
+ */
+import type express from "express";
+/**
+ * Exact filenames servable from assets/vendor/ — nothing else. Pinned bundles
+ * documented in THIRD_PARTY_NOTICES.md. Keep this list in lockstep with the
+ * <script src="/viz/vendor/…"> references in assets/viz.html.
+ */
+export declare const VIZ_VENDOR_FILES: ReadonlySet<string>;
+/**
+ * Bearer token auth — ALWAYS installed, fail-closed. /health, the /viz page
+ * shell, and localhost bypass (OPTIONS is short-circuited by the CORS
+ * middleware before this runs). With no token configured, remote requests are
+ * REJECTED (not open): the default bind is 0.0.0.0, so "no token = no auth"
+ * would expose the whole memory store to the network.
+ */
+export declare function createAuthMiddleware(authToken: string | undefined): 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.
+ */
+export declare function resolveVizHtmlPath(): string;
+/** Read the viz page. Read at request time so a reinstall is picked up live. */
+export declare function readVizHtml(): string;
+/**
+ * Express handler for GET /viz. 503 with the endpoint's usual {error} shape
+ * when the asset cannot be read.
+ */
+export declare function vizHandler(): express.RequestHandler;
+/**
+ * Resolve the on-disk path of an allowlisted vendor bundle, or null when the
+ * requested name is not on the allowlist. The filesystem path is built ONLY
+ * from the allowlist literal (never from request input), so no traversal is
+ * possible by construction.
+ */
+export declare function resolveVizVendorPath(file: string): string | null;
+/**
+ * Express handler for GET /viz/vendor/:file (#139).
+ *
+ * - Not on the allowlist (unknown name, traversal attempts, anything) → 404.
+ * - Allowlisted but missing on disk → 503 (broken install — fail explicitly,
+ *   same contract as vizHandler).
+ * - Long immutable cache: the files only ever change with a package version.
+ */
+export declare function vizVendorHandler(): express.RequestHandler;

package/dist/viz.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * /viz support (#124) — knowledge-graph visualization page.
+ *
+ * Two concerns live here so they can be unit-tested without booting the full
+ * MCP daemon (mcp-server.ts pulls in the embedder + MCP SDK):
+ *
+ * 1. createAuthMiddleware — the bearer-token auth middleware used by the whole
+ *    REST surface. Extracted verbatim from mcp-server.ts, plus ONE change for
+ *    /viz: the page SHELL is exempt like /health (it carries no data or
+ *    secrets — it ships verbatim in the public npm tarball). Browsers cannot
+ *    attach an Authorization header on plain navigation; the page collects
+ *    the token client-side and uses it on its /graph data fetch, which stays
+ *    bearer-only like every other data route.
+ *
+ * 2. readVizHtml — loads the self-contained visualization page from
+ *    assets/viz.html at request time. The asset sits next to src/ and dist/
+ *    (siblings), so `../assets/viz.html` resolves from both the compiled
+ *    output (dist/viz.js) and the TypeScript source (tests/tsx).
+ *
+ * 3. vendorHandler — serves the pinned renderer bundles from assets/vendor/
+ *    (#139: three.js / 3d-force-graph / force-graph, see
+ *    THIRD_PARTY_NOTICES.md). STRICT allowlist of exact filenames — the
+ *    request path is never joined into the filesystem path; the served path
+ *    comes from a fixed lookup table, so traversal is impossible by
+ *    construction. Public like the /viz shell (static public code, no data).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIZ_VENDOR_FILES = void 0;
+exports.createAuthMiddleware = createAuthMiddleware;
+exports.resolveVizHtmlPath = resolveVizHtmlPath;
+exports.readVizHtml = readVizHtml;
+exports.vizHandler = vizHandler;
+exports.resolveVizVendorPath = resolveVizVendorPath;
+exports.vizVendorHandler = vizVendorHandler;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// Vendored renderer assets (#139)
+// ---------------------------------------------------------------------------
+/**
+ * Exact filenames servable from assets/vendor/ — nothing else. Pinned bundles
+ * documented in THIRD_PARTY_NOTICES.md. Keep this list in lockstep with the
+ * <script src="/viz/vendor/…"> references in assets/viz.html.
+ */
+exports.VIZ_VENDOR_FILES = new Set([
+    "three.module.min.js",
+    "three.core.min.js",
+    "3d-force-graph.min.js",
+    "force-graph.min.js",
+]);
+// ---------------------------------------------------------------------------
+// Auth middleware
+// ---------------------------------------------------------------------------
+/**
+ * Bearer token auth — ALWAYS installed, fail-closed. /health, the /viz page
+ * shell, and localhost bypass (OPTIONS is short-circuited by the CORS
+ * middleware before this runs). With no token configured, remote requests are
+ * REJECTED (not open): the default bind is 0.0.0.0, so "no token = no auth"
+ * would expose the whole memory store to the network.
+ */
+function createAuthMiddleware(authToken) {
+    return (req, res, next) => {
+        if (req.path === "/health")
+            return next();
+        // The /viz page SHELL is public like /health — it contains no data and no
+        // secrets (it ships verbatim in the npm tarball). All memory content comes
+        // from /graph, which stays bearer-only; the page collects the token
+        // client-side (URL ?token= handoff or in-page prompt) and sends it as a
+        // normal Authorization header on its data fetches.
+        if (req.method === "GET" && req.path === "/viz")
+            return next();
+        // The pinned renderer bundles the /viz page loads (#139) are public for
+        // the same reason as the shell: static third-party code shipped verbatim
+        // in the npm tarball, zero data. Kept tight: GET only, and ONLY names on
+        // the allowlist. The name is percent-DECODED before the lookup so this
+        // check and vizVendorHandler (which sees Express's decoded req.params)
+        // agree on one canonical form — traversal sequences decode to strings
+        // containing "/" or "..", which are never on the allowlist.
+        if (req.method === "GET" && req.path.startsWith("/viz/vendor/")) {
+            let file = "";
+            try {
+                file = decodeURIComponent(req.path.slice("/viz/vendor/".length));
+            }
+            catch {
+                // malformed percent-encoding — not a vendor file, fall through to auth
+            }
+            if (exports.VIZ_VENDOR_FILES.has(file))
+                return next();
+        }
+        const ip = req.ip ?? req.socket.remoteAddress ?? "";
+        if (ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1")
+            return next();
+        if (authToken && req.headers.authorization === `Bearer ${authToken}`)
+            return next();
+        res.status(401).json({
+            error: authToken
+                ? "Unauthorized"
+                : "No auth token configured on this server — run `npx @gamaze/hicortex init` on the server, then connect with its token.",
+        });
+    };
+}
+// ---------------------------------------------------------------------------
+// Asset loading
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+function resolveVizHtmlPath() {
+    // dist/viz.js  → ../assets/viz.html
+    // src/viz.ts   → ../assets/viz.html (tests / tsx — same sibling layout)
+    const candidates = [(0, node_path_1.join)(__dirname, "..", "assets", "viz.html")];
+    for (const candidate of candidates) {
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    throw new Error(`viz.html asset not found — looked in: ${candidates.join(", ")}. ` +
+        `The package install is incomplete (assets/ missing).`);
+}
+/** Read the viz page. Read at request time so a reinstall is picked up live. */
+function readVizHtml() {
+    return (0, node_fs_1.readFileSync)(resolveVizHtmlPath(), "utf-8");
+}
+/**
+ * Express handler for GET /viz. 503 with the endpoint's usual {error} shape
+ * when the asset cannot be read.
+ */
+function vizHandler() {
+    return (_req, res) => {
+        try {
+            res.type("html").send(readVizHtml());
+        }
+        catch (err) {
+            res.status(503).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+}
+/**
+ * Resolve the on-disk path of an allowlisted vendor bundle, or null when the
+ * requested name is not on the allowlist. The filesystem path is built ONLY
+ * from the allowlist literal (never from request input), so no traversal is
+ * possible by construction.
+ */
+function resolveVizVendorPath(file) {
+    if (!exports.VIZ_VENDOR_FILES.has(file))
+        return null;
+    // dist/viz.js → ../assets/vendor/<file>; src/viz.ts → same sibling layout.
+    return (0, node_path_1.join)(__dirname, "..", "assets", "vendor", file);
+}
+/**
+ * Express handler for GET /viz/vendor/:file (#139).
+ *
+ * - Not on the allowlist (unknown name, traversal attempts, anything) → 404.
+ * - Allowlisted but missing on disk → 503 (broken install — fail explicitly,
+ *   same contract as vizHandler).
+ * - Long immutable cache: the files only ever change with a package version.
+ */
+function vizVendorHandler() {
+    return (req, res) => {
+        const file = typeof req.params.file === "string" ? req.params.file : "";
+        const path = resolveVizVendorPath(file);
+        if (!path) {
+            res.status(404).json({ error: "Not found" });
+            return;
+        }
+        try {
+            const body = (0, node_fs_1.readFileSync)(path);
+            res.setHeader("Content-Type", "application/javascript; charset=utf-8");
+            res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+            res.send(body);
+        }
+        catch (err) {
+            res.status(503).json({
+                error: `Vendor asset ${file} is missing — the package install is incomplete ` +
+                    `(assets/vendor/ missing): ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    };
+}

package/domains.example.json

@@ -0,0 +1,36 @@
+{
+  "_readme": [
+    "Hicortex memory domains — example config.",
+    "Copy the `domains` key (and optionally `weakPrimaryFloor`) into ~/.hicortex/config.json on the SERVER machine.",
+    "Domains are your top-level memory spheres. Each memory gets multiple weighted tags plus a derived primary.",
+    "They can be life areas OR project/topic areas — edit to match how YOU think.",
+    "The `domains` list below is the generic default that `hicortex init` scaffolds automatically.",
+    "There is NO fallback category: memories that fit nothing are handled automatically (weak-primary floor + decay).",
+    "Backfill an existing corpus with: hicortex classify-domains"
+  ],
+  "domains": [
+    { "name": "Work", "description": "Your job and professional life — employer, clients, workstreams" },
+    { "name": "Personal", "description": "Private life — home, hobbies, everyday matters" },
+    { "name": "People", "description": "Relationships — family, friends, social life, network" },
+    { "name": "Health", "description": "Fitness, wellbeing, medical" },
+    { "name": "Finance", "description": "Money — budgeting, spending, investing" }
+  ],
+  "_powerUserExample": {
+    "_readme": [
+      "A narrower life-sphere set for users who want tighter buckets.",
+      "`compartment: true` makes a domain the PRIMARY whenever it is tagged — a deliberate work/life firewall.",
+      "`weakPrimaryFloor` (default 0.45) is the minimum embedding similarity for a no-fit memory to earn a weak primary; tune it from your corpus."
+    ],
+    "domains": [
+      { "name": "Work", "description": "Employer, day job, client projects, workstreams", "compartment": true },
+      { "name": "Personal", "description": "Private life — home, hobbies, everyday matters" },
+      { "name": "People", "description": "Relationships — family, friends, social life, network" },
+      { "name": "Health", "description": "Fitness, wellbeing, medical" },
+      { "name": "Finance", "description": "Money — budgeting, spending, investing" },
+      { "name": "Boating", "description": "Boats — maintenance, gear, trips, harbour life" },
+      { "name": "Property", "description": "House and land — renovation, upkeep, garden" },
+      { "name": "Vehicles", "description": "Cars and other vehicles — service, repairs, purchases" }
+    ],
+    "weakPrimaryFloor": 0.5
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.10.1",
-  "description": "Self-learning memory for AI agents \u2014 experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
+  "version": "0.11.1",
+  "description": "Self-learning memory for AI agents — experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {
     "hicortex": "dist/cli.js"
@@ -25,10 +25,13 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist/",
+    "assets/",
     "skills/",
     "hermes-plugin/",
     "openclaw.plugin.json",
-    "README.md"
+    "domains.example.json",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc",