@gamaze/hicortex 0.16.0 → 0.16.2

package/dist/types.d.ts

@@ -13,9 +13,23 @@ export interface Memory {
     ingested_at: string;
     source_agent: string;
     source_session: string | null;
+    /**
+     * Stable attribution id of the capturing client (a per-install UUID from
+     * config.json `agentId`). Survives agent/machine renames — unlike
+     * `source_agent` (a readable name). Attribution only; nothing filters on it.
+     * NULL on memories captured before this column existed. (0.16.x)
+     */
+    source_agent_id: string | null;
     project: string | null;
     domain: string | null;
-    privacy: "PUBLIC" | "WORK" | "PERSONAL" | "SENSITIVE";
+    /**
+     * Provenance only (0.16.x): the client-declared topic/domain of the
+     * capturing agent (config.json `sourceDomain`). NOT used for recall filtering
+     * or scoring, and NOT the content-classified primary (that is `domain`
+     * above). NULL when the client declares none. Echoed back on /memory GET.
+     */
+    source_domain: string | null;
+    privacy: ("PUBLIC" | "WORK" | "PERSONAL" | "SENSITIVE") | null;
     memory_type: "episode" | "lesson" | "fact" | "decision";
     updated_at: string | null;
 }
@@ -157,6 +171,15 @@ export interface HicortexConfig {
     serverUrl?: string;
     /** Bearer token for the Hicortex server. Localhost bypasses auth by default. */
     authToken?: string;
+    /**
+     * Stable per-install UUID generated by `init` (see ensureAgentId in init.ts;
+     * never rotated). Attribution identity of the capturing client — stored on
+     * each captured memory as `source_agent_id` (see Memory.source_agent_id) and
+     * sent on every /distill segment. Survives agent/machine renames, unlike the
+     * readable `source_agent` name. Pure attribution; nothing filters or scopes
+     * on it. (0.16.x)
+     */
+    agentId?: string;
     /** @deprecated Use the Hicortex server for distillation and consolidation. */
     llmBaseUrl?: string;
     /** @deprecated Use the Hicortex server for distillation and consolidation. */
@@ -194,6 +217,21 @@ export interface HicortexConfig {
     consolidateHour?: number;
     /** @deprecated The OC plugin no longer opens its own database. */
     dbPath?: string;
+    /**
+     * Client-declared topic/domain of THIS capturing agent (provenance only,
+     * 0.16.x). Sent on captured memories as `source_domain` (see
+     * Memory.source_domain) — NOT used for recall filtering or scoring, and NOT
+     * the content-classified primary (which is the server-derived `domain`
+     * column on each memory, classified against `domains` below).
+     *
+     * DISTINCT from `domains` (plural) directly below: `domains` is the
+     * config-owned VOCABULARY — the server's life-sphere list that memories are
+     * content-classified against; this singular `sourceDomain` is the client
+     * declaring "I am an agent that works on topic X", recorded as provenance on
+     * what it captures. Do not conflate the two. (Renamed from `domain` in
+     * 0.16.x — one char from `domains`, meant something unrelated.)
+     */
+    sourceDomain?: 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
@@ -205,7 +243,7 @@ export interface HicortexConfig {
      * 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
+     * example (custom weakPrimaryFloor) ships as
      * domains.example.json in the package root.
      *
      * NO fallback bucket is needed or special-cased (owner amendment 07.07):
@@ -227,13 +265,6 @@ export interface HicortexConfig {
 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 {
@@ -286,8 +317,14 @@ export interface ModuleIndex {
 export interface InsertMemoryOptions {
     sourceAgent?: string;
     sourceSession?: string | null;
+    /** Stable client UUID (config.json `agentId`). Attribution only. */
+    sourceAgentId?: string | null;
+    /** Client-declared topic/domain of the capturing agent. Provenance only. */
+    sourceDomain?: string | null;
     project?: string | null;
-    privacy?: string;
+    /** 0.16.x: vestigial — stored but never filtered. null (or absent) when the
+     *  caller doesn't declare one; an explicit value is honored as-is. */
+    privacy?: string | null;
     memoryType?: string;
     baseStrength?: number;
     createdAt?: string;
@@ -297,16 +334,3 @@ export interface VectorSearchOptions {
     limit?: number;
     excludeIds?: string[];
 }
-/** Options for FTS search. */
-export interface FtsSearchOptions {
-    limit?: number;
-    privacy?: string[];
-    sourceAgent?: string;
-}
-/** Options for retrieval. */
-export interface RetrievalOptions {
-    limit?: number;
-    project?: string | null;
-    privacy?: string[];
-    sourceAgent?: string;
-}

package/domains.example.json

@@ -33,14 +33,13 @@
   "_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.",
+      "The PRIMARY domain is derived by argmax association weight (LLM tag order breaks ties) — no manual override flag.",
       "`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
+        "description": "Employer, day job, client projects, workstreams"
       },
       {
         "name": "Personal",

package/hermes-plugin/hicortex/README.md

@@ -22,7 +22,7 @@ That's the whole surface. No `sync_turn`, no compaction/session-end capture —
 
 ### Pushed recall index (0.7.0, server ≥ 0.14)
 
-Instead of injecting full memory content every turn, `prefetch` sends the user's message to the server's `POST /recall-index` and injects the returned **index block** verbatim — one line per memory (id, title, date), capped and relevance-gated server-side. The agent fetches full content with `hicortex_get(id)` only when a line is actually relevant; that fetch is what strengthens the memory (exposure ≠ use). All tuning knobs (`recallMaxItems`, `recallMinSimilarity`, `recallReshowTurns`, `recallMinPromptChars`, …) live in the **server** config — the plugin carries none. Dedup is turn-based and server-side per session; the plugin resets it at `initialize` (the Hermes `MemoryProvider` interface exposes no compaction signal, so a mid-session context rebuild cannot trigger a reset — the server's turn-based re-show window covers that gap). Against a pre-0.14 server (404) the plugin falls back to the 0.6.x `GET /search` full-content prefetch, fail-soft, re-probing the endpoint every 10 minutes so a later server upgrade is picked up without a gateway restart. The recall calls carry the profile's configured `privacy_filter`/`default_project` and use a short dedicated timeout (1.5 s) so a slow server can never stall a turn.
+Instead of injecting full memory content every turn, `prefetch` sends the user's message to the server's `POST /recall-index` and injects the returned **index block** verbatim — one line per memory (id, title, date), capped and relevance-gated server-side. The agent fetches full content with `hicortex_get(id)` only when a line is actually relevant; that fetch is what strengthens the memory (exposure ≠ use). All tuning knobs (`recallMaxItems`, `recallMinSimilarity`, `recallReshowTurns`, `recallMinPromptChars`, …) live in the **server** config — the plugin carries none. Dedup is turn-based and server-side per session; the plugin resets it at `initialize` (the Hermes `MemoryProvider` interface exposes no compaction signal, so a mid-session context rebuild cannot trigger a reset — the server's turn-based re-show window covers that gap). Against a pre-0.14 server (404) the plugin falls back to the 0.6.x `GET /search` full-content prefetch, fail-soft, re-probing the endpoint every 10 minutes so a later server upgrade is picked up without a gateway restart. The recall calls carry the profile's configured `default_project` (and `mission_domains`) and use a short dedicated timeout (1.5 s) so a slow server can never stall a turn. (`privacy_filter` is deprecated since 0.7.2 — the server ignores privacy; see [Configuration](#configuration).)
 
 ### Per-agent standing context (0.13)
 
@@ -84,6 +84,8 @@ export HICORTEX_AUTH_TOKEN=hctx-default-token   # or your custom token
 
 Env overrides: `HICORTEX_URL`, `HICORTEX_AUTH_TOKEN`.
 
+> **`privacy_filter` is DEPRECATED** (plugin 0.7.2 / server 0.16.2). The server no longer filters on privacy — the `privacy` column is vestigial (stored, never filtered). The setting is still accepted for backward compatibility but is now a harmless no-op; setting it emits a one-time-per-process warning in the gateway log. For work/personal isolation, run a **separate Hicortex server** per scope rather than relying on in-server privacy filtering.
+
 ## Topology
 
 - **Server host:** runs Hicortex. Set `hicortex_url: http://localhost:8787` (localhost bypasses auth).

package/hermes-plugin/hicortex/config.py

@@ -8,9 +8,15 @@ plugin also works with env-only setup.
 from __future__ import annotations
 
 import json
+import logging
 import os
 from typing import Any, Dict, Optional
 
+logger = logging.getLogger(__name__)
+
+# One-time-per-process guard for the privacy_filter deprecation warning.
+_privacy_filter_deprecation_warned = False
+
 # Declarative config schema — drives `hermes memory setup` (see MemoryProvider
 # .get_config_schema). Field shape per the Hermes MemoryProvider contract:
 # key, label, description, default, required, secret, env_var, choices, url.
@@ -56,8 +62,15 @@ CONFIG_SCHEMA: list[dict[str, Any]] = [
     },
     {
         "key": "privacy_filter",
-        "label": "Privacy filter",
-        "description": "Comma-separated privacy levels to include (e.g. WORK,PERSONAL).",
+        "label": "Privacy filter (DEPRECATED)",
+        "description": (
+            "DEPRECATED since plugin 0.7.2 / server 0.16.2. The server no "
+            "longer filters on privacy — the column is vestigial. This setting "
+            "is now a harmless no-op: it is still accepted for backward "
+            "compat but ignored. For work/personal isolation, run a separate "
+            "Hicortex server per scope. (Historically: comma-separated privacy "
+            "levels to include, e.g. WORK,PERSONAL.)"
+        ),
         "default": "WORK,PERSONAL",
         "required": False,
     },
@@ -94,14 +107,19 @@ def _config_path(hermes_home: Optional[str] = None) -> str:
 
 def load_config() -> Dict[str, Any]:
     """Load merged config: file <- env overrides <- defaults."""
+    global _privacy_filter_deprecation_warned
     path = _config_path()
     cfg: Dict[str, Any] = {}
+    file_set_privacy_filter = False
     if os.path.exists(path):
         try:
             with open(path, encoding="utf-8") as f:
                 cfg = json.load(f) or {}
         except Exception:
             cfg = {}
+        # Detect an EXPLICIT user setting (the default is applied via setdefault
+        # below); only warn when the profile actually configured it.
+        file_set_privacy_filter = "privacy_filter" in cfg
 
     # Env overrides
     if os.environ.get("HICORTEX_URL"):
@@ -113,6 +131,19 @@ def load_config() -> Dict[str, Any]:
     cfg.setdefault("hicortex_url", "http://localhost:8787")
     cfg.setdefault("recall_limit", 5)
     cfg.setdefault("privacy_filter", "WORK,PERSONAL")
+
+    # 0.16.2 deprecation: privacy_filter is a no-op now (server ignores privacy
+    # entirely). Warn once per process if the profile explicitly sets it.
+    if file_set_privacy_filter and not _privacy_filter_deprecation_warned:
+        _privacy_filter_deprecation_warned = True
+        logger.warning(
+            "hicortex: config.json sets 'privacy_filter', which is deprecated "
+            "since plugin 0.7.2 / server 0.16.2 — the server no longer filters "
+            "on privacy (the column is vestigial). It is a harmless no-op now. "
+            "For work/personal isolation, run a separate Hicortex server per "
+            "scope. (This warning fires once per process.)"
+        )
+
     return cfg
 
 

package/hermes-plugin/hicortex/plugin.yaml

@@ -1,5 +1,5 @@
 name: hicortex
-version: 0.7.0
+version: 0.7.2
 description: "Self-learning memory for Hermes agents — every session is distilled into lessons overnight, and your agent wakes up wiser. Pushes a compact per-turn recall index (lazy-loaded with hicortex_get), injects fresh lessons plus a per-agent standing context block, and exposes the full 9-tool memory surface (search, get, recent, ingest, lessons, index, graph, update, delete) via a shared Hicortex server. Stdlib-only."
 pip_dependencies: []
 hooks: []

package/hermes-plugin/hicortex/provider.py

@@ -446,6 +446,11 @@ class HicortexProvider(MemoryProvider):
             lines.append("Lessons:")
             for l in lessons:
                 c = (l.get("content") or "").strip().replace("\n", " ")
+                # Legacy lessons were stored with a "## Lesson:" prefix; new ones are
+                # topic-first (selected by memory_type, not the prefix). Strip it so
+                # Hermes renders the same topic-first line as the CC/OC lessons blocks.
+                if c.startswith("## Lesson: "):
+                    c = c[len("## Lesson: "):]
                 lines.append(f"- {c[:200]}")
         if idx.get("total"):
             lines.append(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "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": {
@@ -39,6 +39,7 @@
     "test:watch": "vitest",
     "eval": "node dist/eval/run-eval.js",
     "eval:recall-sweep": "node dist/eval/recall-sweep.js",
+    "eval:relevance": "node dist/eval/relevance-eval.js",
     "prepack": "npm run build && rm -rf ./hermes-plugin && mkdir -p ./hermes-plugin && cp -r ../../hermes-plugin/hicortex ./hermes-plugin/ && find ./hermes-plugin -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null || true",
     "prepublishOnly": "npm run build && rm -rf ./hermes-plugin && mkdir -p ./hermes-plugin && cp -r ../../hermes-plugin/hicortex ./hermes-plugin/ && find ./hermes-plugin -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null || true"
   },