@gamaze/hicortex 0.13.1 → 0.13.3

package/dist/pi-transcript-reader.d.ts

@@ -16,23 +16,18 @@
  *
  * Directory layout:
  *   ~/.pi/agent/sessions/
- *     --home-agents-Agents-raider--/
+ *     --home-alice-projects-myagent--/
  *       2026-04-10T18-37-44-615Z_<uuid>.jsonl
  *       2026-04-11T07-51-28-282Z_<uuid>.jsonl
  *     --home-agents-Development-MAIC--/
  *       ...
  *
- * The encoded-cwd uses double-dash separators: /home/agents/Agents/raider
- * becomes --home-agents-Agents-raider--. The session header's `cwd` field
+ * The encoded-cwd uses double-dash separators: /home/alice/projects/myagent
+ * becomes --home-alice-projects-myagent--. The session header's `cwd` field
  * is the canonical path; the directory name is a filesystem-safe encoding.
  */
-export interface TranscriptBatch {
-    sessionId: string;
-    projectName: string;
-    date: string;
-    entries: unknown[];
-    sourceAgent?: string;
-}
+import type { TranscriptBatch, CursorMap } from "./transcript-reader.js";
+export type { TranscriptBatch, CursorMap };
 /**
  * Read Pi session transcripts modified after `since`.
  *
@@ -41,5 +36,7 @@ export interface TranscriptBatch {
  *
  * @param since Only return sessions with mtime > this date
  * @param sessionsDir Override the session directory (default: ~/.pi/agent/sessions/)
+ * @param cursors Per-session capture cursors (#189); default empty = whole file
+ * @param keyPrefix Cursor-key namespace ("pi" here; OC passes "oc:<agentId>")
  */
-export declare function readPiTranscripts(since: Date, sessionsDir?: string): TranscriptBatch[];
+export declare function readPiTranscripts(since: Date, sessionsDir?: string, cursors?: CursorMap, keyPrefix?: string): TranscriptBatch[];

package/dist/pi-transcript-reader.js

@@ -17,14 +17,14 @@
  *
  * Directory layout:
  *   ~/.pi/agent/sessions/
- *     --home-agents-Agents-raider--/
+ *     --home-alice-projects-myagent--/
  *       2026-04-10T18-37-44-615Z_<uuid>.jsonl
  *       2026-04-11T07-51-28-282Z_<uuid>.jsonl
  *     --home-agents-Development-MAIC--/
  *       ...
  *
- * The encoded-cwd uses double-dash separators: /home/agents/Agents/raider
- * becomes --home-agents-Agents-raider--. The session header's `cwd` field
+ * The encoded-cwd uses double-dash separators: /home/alice/projects/myagent
+ * becomes --home-alice-projects-myagent--. The session header's `cwd` field
  * is the canonical path; the directory name is a filesystem-safe encoding.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -41,8 +41,10 @@ const DEFAULT_PI_SESSIONS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(),
  *
  * @param since Only return sessions with mtime > this date
  * @param sessionsDir Override the session directory (default: ~/.pi/agent/sessions/)
+ * @param cursors Per-session capture cursors (#189); default empty = whole file
+ * @param keyPrefix Cursor-key namespace ("pi" here; OC passes "oc:<agentId>")
  */
-function readPiTranscripts(since, sessionsDir = DEFAULT_PI_SESSIONS_DIR) {
+function readPiTranscripts(since, sessionsDir = DEFAULT_PI_SESSIONS_DIR, cursors = {}, keyPrefix = "pi") {
     const batches = [];
     let projectDirs;
     try {
@@ -80,6 +82,7 @@ function readPiTranscripts(since, sessionsDir = DEFAULT_PI_SESSIONS_DIR) {
                 const raw = (0, node_fs_1.readFileSync)(filePath, "utf-8");
                 const lines = raw.split("\n").filter((l) => l.trim());
                 const entries = [];
+                const timestamps = [];
                 let sessionId = "";
                 let sessionCwd = "";
                 let sessionDate = "";
@@ -87,6 +90,7 @@ function readPiTranscripts(since, sessionsDir = DEFAULT_PI_SESSIONS_DIR) {
                     try {
                         const entry = JSON.parse(line);
                         entries.push(entry);
+                        timestamps.push(typeof entry.timestamp === "string" ? entry.timestamp : "");
                         // Extract metadata from the session header
                         if (entry.type === "session") {
                             sessionId = entry.id ?? "";
@@ -111,14 +115,38 @@ function readPiTranscripts(since, sessionsDir = DEFAULT_PI_SESSIONS_DIR) {
                 if (!sessionDate) {
                     sessionDate = extractDateFromFilename(file) ?? "";
                 }
-                if (entries.length > 0) {
-                    batches.push({
-                        sessionId,
-                        projectName,
-                        date: sessionDate,
-                        entries,
-                    });
+                if (entries.length === 0)
+                    continue;
+                // Incremental slice (#189): append-only JSONL v3, same discipline as CC.
+                const cursorKey = `${keyPrefix}:${sessionId}`;
+                const pos = cursors[cursorKey] ?? { cursor: 0, gen: 0 };
+                let start = pos.cursor;
+                let gen = pos.gen;
+                if (start > entries.length) {
+                    // shrink guard (truncation/rotation) — reset + bump generation (fix 8)
+                    start = 0;
+                    gen = pos.gen + 1;
+                }
+                const delta = entries.slice(start);
+                if (delta.length === 0)
+                    continue; // cursor already covers the file
+                const entryCursors = delta.map((_, i) => start + i + 1);
+                // Prefer the last timestamped entry in the delta for per-night dating.
+                let deltaDate = "";
+                for (let i = start; i < entries.length; i++) {
+                    if (timestamps[i])
+                        deltaDate = timestamps[i].slice(0, 10);
                 }
+                batches.push({
+                    sessionId,
+                    projectName,
+                    date: deltaDate || sessionDate || new Date().toISOString().slice(0, 10),
+                    entries: delta,
+                    cursorKey,
+                    startCursor: start,
+                    generation: gen,
+                    entryCursors,
+                });
             }
             catch {
                 // File read or parse failed — skip
@@ -129,7 +157,7 @@ function readPiTranscripts(since, sessionsDir = DEFAULT_PI_SESSIONS_DIR) {
 }
 /**
  * Extract the last path segment from a cwd as the project name.
- * /home/agents/Agents/raider → "raider"
+ * /home/alice/projects/myagent → "myagent"
  * Falls back to decoding the directory name if cwd is empty.
  */
 function deriveProjectName(cwd, encodedDir) {
@@ -137,7 +165,7 @@ function deriveProjectName(cwd, encodedDir) {
         const segments = cwd.split("/").filter(Boolean);
         return segments[segments.length - 1] ?? "unknown";
     }
-    // Decode the Pi directory encoding: --home-agents-Agents-raider-- → raider
+    // Decode the Pi directory encoding: --home-alice-projects-myagent-- → myagent
     const decoded = encodedDir.replace(/^--/, "").replace(/--$/, "").split("-");
     return decoded[decoded.length - 1] ?? "unknown";
 }

package/dist/transcript-reader.d.ts

@@ -7,17 +7,38 @@
  * The reader scans for new sessions since the last nightly run
  * and feeds them to the existing distiller pipeline.
  */
+import type { CursorMap } from "./capture-cursors.js";
+export type { CursorMap };
 export interface TranscriptBatch {
     sessionId: string;
     projectName: string;
     date: string;
     entries: unknown[];
     /**
-     * Optional source-agent label (e.g. "hermes/lenny"). When set, the nightly
+     * Optional source-agent label (e.g. "hermes/alice"). When set, the nightly
      * pipeline uses it verbatim for provenance instead of the default
      * `claude-code/<project>`. Lets per-harness readers stamp their own origin.
      */
     sourceAgent?: string;
+    /**
+     * Per-session cursor key (`<prefix>:<sessionId>`) — the capture-cursors.json
+     * key whose value gates and advances this session's incremental capture (#189).
+     */
+    cursorKey: string;
+    /** Cursor value the delta starts from (entries already captured before this run). */
+    startCursor: number;
+    /**
+     * Shrink-guard generation for this session — woven into segment ids so
+     * post-reset segments can't collide with pre-reset ids on the content-blind
+     * server dedup. Advanced back to the store with the cursor.
+     */
+    generation: number;
+    /**
+     * End-cursor value for each delta entry (length === entries.length). The
+     * packer uses these to land segment boundaries on exact entry boundaries.
+     * JSONL: startCursor + i + 1. Hermes: the row's messages.id.
+     */
+    entryCursors: number[];
 }
 /**
  * Cheap pre-filter: skip CC session FILES with fewer than this many raw JSONL
@@ -36,4 +57,4 @@ export declare const MIN_TRANSCRIPT_ENTRIES = 4;
  * Read all CC transcripts modified since `since`.
  * Returns one batch per session file.
  */
-export declare function readCcTranscripts(since: Date, projectsDir?: string): TranscriptBatch[];
+export declare function readCcTranscripts(since: Date, projectsDir?: string, cursors?: CursorMap): TranscriptBatch[];

package/dist/transcript-reader.js

@@ -32,7 +32,7 @@ const CC_PROJECTS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude
  * Read all CC transcripts modified since `since`.
  * Returns one batch per session file.
  */
-function readCcTranscripts(since, projectsDir = CC_PROJECTS_DIR) {
+function readCcTranscripts(since, projectsDir = CC_PROJECTS_DIR, cursors = {}) {
     const batches = [];
     let projectDirs;
     try {
@@ -74,7 +74,10 @@ function readCcTranscripts(since, projectsDir = CC_PROJECTS_DIR) {
             // Skip files not modified since last run
             if (fileStat.mtime <= since)
                 continue;
-            const batch = parseTranscriptFile(filePath, projectName);
+            const sessionId = (0, node_path_1.basename)(filePath, ".jsonl");
+            const key = `cc:${sessionId}`;
+            const pos = cursors[key] ?? { cursor: 0, gen: 0 };
+            const batch = parseTranscriptFile(filePath, projectName, key, pos.cursor, pos.gen);
             if (batch) {
                 batches.push(batch);
             }
@@ -83,10 +86,15 @@ function readCcTranscripts(since, projectsDir = CC_PROJECTS_DIR) {
     return batches;
 }
 /**
- * Parse a single .jsonl transcript file into a batch.
- * Returns null if the file has too few meaningful entries.
+ * Parse a single .jsonl transcript file into a delta batch.
+ *
+ * Returns null if the file has too few meaningful entries (whole-file gate) or
+ * the cursor already covers everything (nothing new since last capture, #189).
+ *
+ * @param cursorKey capture-cursors.json key for this session
+ * @param startCursor entries already captured (delta = entries.slice(startCursor))
  */
-function parseTranscriptFile(filePath, projectName) {
+function parseTranscriptFile(filePath, projectName, cursorKey, startCursor, generation) {
     let raw;
     try {
         raw = (0, node_fs_1.readFileSync)(filePath, "utf-8");
@@ -98,40 +106,65 @@ function parseTranscriptFile(filePath, projectName) {
     if (lines.length < exports.MIN_TRANSCRIPT_ENTRIES)
         return null; // degenerate/empty file
     const entries = [];
-    let lastTimestamp = "";
+    const timestamps = [];
     for (const line of lines) {
         try {
             const entry = JSON.parse(line);
             entries.push(entry);
-            if (entry.timestamp) {
-                lastTimestamp = entry.timestamp;
-            }
+            timestamps.push(typeof entry.timestamp === "string" ? entry.timestamp : "");
         }
         catch {
-            // Skip malformed lines
+            // Skip malformed lines — a permanently-malformed line is skipped
+            // identically every run, and a partial trailing write fails JSON.parse
+            // now and parses (at the same index) once fully flushed.
         }
     }
+    // Whole-file degeneracy gate stays on the full parse, not the delta.
     if (entries.length < exports.MIN_TRANSCRIPT_ENTRIES)
         return null;
-    // Extract session ID from filename (UUID.jsonl)
-    const sessionId = (0, node_path_1.basename)(filePath, ".jsonl");
+    // Shrink guard: a truncated/rotated file with fewer entries than the stored
+    // cursor → reset to 0 AND bump the generation. The generation is woven into
+    // the segment id downstream so the fresh file's segments can never collide
+    // with the pre-reset ids on the server's content-blind dedup (fix 8).
+    let start = startCursor;
+    let gen = generation;
+    if (start > entries.length) {
+        start = 0;
+        gen = generation + 1;
+    }
+    const delta = entries.slice(start);
+    if (delta.length === 0)
+        return null; // cursor already covers the whole file
+    // Per-entry end cursors: entry i (0-based in the delta) ends at start+i+1.
+    const entryCursors = delta.map((_, i) => start + i + 1);
+    // Date from the LAST timestamped entry in the delta (per-night created_at for
+    // multi-day sessions), falling back to today.
+    let lastTimestamp = "";
+    for (let i = start; i < entries.length; i++) {
+        if (timestamps[i])
+            lastTimestamp = timestamps[i];
+    }
     return {
-        sessionId,
+        sessionId: (0, node_path_1.basename)(filePath, ".jsonl"),
         projectName,
         date: lastTimestamp
             ? lastTimestamp.slice(0, 10)
             : new Date().toISOString().slice(0, 10),
-        entries,
+        entries: delta,
+        cursorKey,
+        startCursor: start,
+        generation: gen,
+        entryCursors,
     };
 }
 /**
  * Decode CC project directory name to a human-readable project name.
- * CC uses path-based hashing: "-Users-mattias-Development-Tools-hicortex"
+ * CC uses path-based hashing: "-Users-alice-Development-Tools-hicortex"
  * becomes "hicortex" (last path component).
  */
 function decodeProjectDirName(dirName) {
     // CC encodes paths by replacing / with -
-    // e.g. "-Users-mattias-Development-Tools-hicortex"
+    // e.g. "-Users-alice-Development-Tools-hicortex"
     const parts = dirName.split("-").filter(Boolean);
     if (parts.length === 0)
         return dirName;

package/domains.example.json

@@ -9,11 +9,26 @@
     "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" }
+    {
+      "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": [
@@ -22,14 +37,39 @@
       "`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" }
+      {
+        "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": "Photography",
+        "description": "Camera gear, shoots, editing workflow, photo projects"
+      },
+      {
+        "name": "Home",
+        "description": "House, renovation projects, maintenance, garden"
+      },
+      {
+        "name": "Travel",
+        "description": "Trips, destinations, bookings, travel plans"
+      }
     ],
     "weakPrimaryFloor": 0.5
   }

package/hermes-plugin/hicortex/provider.py

@@ -33,8 +33,8 @@ _INJECT_CONTENT_CAP = 500
 
 # Agent ids are joined into a filesystem path server-side, so they share the
 # section-name allowlist. \Z (NOT $) anchors the END OF STRING: Python's $ also
-# matches just before a trailing "\n", so "nano\n" would pass and go out as
-# agent=nano%0A → a 400 the fail-soft path silently swallows.
+# matches just before a trailing "\n", so "alice\n" would pass and go out as
+# agent=alice%0A → a 400 the fail-soft path silently swallows.
 _AGENT_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*\Z")
 
 
@@ -48,7 +48,7 @@ def _sanitize_agent_id(raw: Optional[str]) -> Optional[str]:
     EXACTLY so a profile resolves to the SAME id on both harnesses (a mismatch
     would make one honor the persona firewall and the other leak global context
     into an ``off``/``override`` persona): lowercase → collapse invalid runs to
-    "-" → strip leading -/_ → truncate 64 → validate. "Lenny" → "lenny";
+    "-" → strip leading -/_ → truncate 64 → validate. "Alice" → "alice";
     "MacBook-Pro.local" → "macbook-pro-local"; all-symbols → None."""
     if not isinstance(raw, str):
         return None
@@ -73,7 +73,7 @@ def _resolve_agent_name(cfg: Dict[str, Any]) -> Optional[str]:
       2. ``HERMES_PROFILE`` env;
       3. parse ``HERMES_HOME`` when it ends ``profiles/<name>``;
       4. None → bare fetch → the global set.
-    Each source is stripped then SANITIZED (not rejected) so "Lenny" → "lenny"
+    Each source is stripped then SANITIZED (not rejected) so "Alice" → "alice"
     matches the TS contract; a source that sanitizes to None yields None (bare
     fetch), never a fall-through to another identity."""
     configured = (cfg.get("agent_name") or "").strip()

package/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "serverUrl": {
         "type": "string",
         "default": "http://127.0.0.1:8787",
-        "description": "Hicortex server URL. Defaults to localhost (co-located server). For multi-machine setups, point this at the remote server (e.g. http://bedrock:8787 or a Tailscale HTTPS URL)."
+        "description": "Hicortex server URL. Defaults to localhost (co-located server). For multi-machine setups, point this at the remote server (e.g. http://your-server:8787 or an HTTPS URL)."
       },
       "authToken": {
         "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "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.",
   "main": "dist/index.js",
   "bin": {