@gamaze/hicortex 0.7.1 → 0.10.1

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

@@ -0,0 +1,27 @@
+/**
+ * Hermes transcript reader — the nightly capture path for Nous Research Hermes.
+ *
+ * Hermes stores conversation in a SQLite state DB, one per profile:
+ *   ~/.hermes/profiles/<profile>/state.db   (per-profile agents: lenny, raider, nano)
+ *   ~/.hermes/state.db                       (global, non-profile setups)
+ *
+ * Schema (relevant columns):
+ *   sessions(id TEXT PK, started_at REAL, ended_at REAL, ...)
+ *   messages(session_id TEXT, role TEXT, content TEXT, tool_name TEXT, timestamp REAL, active INT, ...)
+ *
+ * Compaction is NON-DESTRUCTIVE (compacted-out turns kept with active=0) and
+ * sessions are retained ~90 days — so the full history of any ended session is
+ * readable here nightly. No runtime plugin capture is needed; the Hermes plugin
+ * is recall-only.
+ *
+ * We process only ENDED sessions (ended_at set) that ended since the last run.
+ * A live session is distilled after it ends — this avoids partial-session
+ * distillation and keeps per-session dedup clean (chunks are stored as
+ * `<sessionId>#<chunkIndex>`; see nightly.ts).
+ */
+import type { TranscriptBatch } from "./transcript-reader.js";
+/**
+ * Read Hermes sessions that ended since `since`, across all profiles.
+ * Returns one batch per session, parallel to readCcTranscripts().
+ */
+export declare function readHermesSessions(since: Date, hermesHome?: string): TranscriptBatch[];

package/dist/hermes-transcript-reader.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Hermes transcript reader — the nightly capture path for Nous Research Hermes.
+ *
+ * Hermes stores conversation in a SQLite state DB, one per profile:
+ *   ~/.hermes/profiles/<profile>/state.db   (per-profile agents: lenny, raider, nano)
+ *   ~/.hermes/state.db                       (global, non-profile setups)
+ *
+ * Schema (relevant columns):
+ *   sessions(id TEXT PK, started_at REAL, ended_at REAL, ...)
+ *   messages(session_id TEXT, role TEXT, content TEXT, tool_name TEXT, timestamp REAL, active INT, ...)
+ *
+ * Compaction is NON-DESTRUCTIVE (compacted-out turns kept with active=0) and
+ * sessions are retained ~90 days — so the full history of any ended session is
+ * readable here nightly. No runtime plugin capture is needed; the Hermes plugin
+ * is recall-only.
+ *
+ * We process only ENDED sessions (ended_at set) that ended since the last run.
+ * A live session is distilled after it ends — this avoids partial-session
+ * distillation and keeps per-session dedup clean (chunks are stored as
+ * `<sessionId>#<chunkIndex>`; see nightly.ts).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readHermesSessions = readHermesSessions;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const HERMES_HOME = process.env.HERMES_HOME || (0, node_path_1.join)((0, node_os_1.homedir)(), ".hermes");
+/**
+ * Session `source` values that are NOT primary conversations and must not be
+ * captured — capturing them would pollute long-term memory with automated,
+ * non-conversational runs. `cron` is Hermes' scheduled-task source (garmin
+ * syncs, daily scans, self-reflection loops). This mirrors the MemoryProvider
+ * contract's own guidance to skip non-primary `agent_context` (e.g. "cron").
+ * Everything else (cli, discord, telegram, slack, …) is a real conversation.
+ */
+const NON_PRIMARY_SOURCES = new Set(["cron"]);
+/**
+ * Message roles that are metadata/noise, not conversation — mapped so the
+ * distiller's extractConversationText drops them (it skips "tool_result").
+ */
+const NOISE_ROLES = new Set(["tool", "session_meta"]);
+/**
+ * Read Hermes sessions that ended since `since`, across all profiles.
+ * Returns one batch per session, parallel to readCcTranscripts().
+ */
+function readHermesSessions(since, hermesHome = HERMES_HOME) {
+    const batches = [];
+    const sinceEpoch = since.getTime() / 1000; // Hermes timestamps are unix seconds (REAL)
+    for (const { profile, dbPath } of discoverProfileDbs(hermesHome)) {
+        let db;
+        try {
+            db = new better_sqlite3_1.default(dbPath, { readonly: true, fileMustExist: true });
+        }
+        catch {
+            continue; // locked / unreadable / wrong owner — skip, retry next run
+        }
+        try {
+            const sessions = db
+                .prepare("SELECT id, ended_at, source FROM sessions WHERE ended_at IS NOT NULL AND ended_at > ? ORDER BY ended_at")
+                .all(sinceEpoch);
+            const msgStmt = db.prepare("SELECT role, content, tool_name, timestamp FROM messages WHERE session_id = ? ORDER BY timestamp, id");
+            for (const s of sessions) {
+                // Skip automated (non-primary) sessions — cron runs are not
+                // conversations and would pollute memory. Checked before pulling
+                // messages so we don't even read them.
+                if (NON_PRIMARY_SOURCES.has(s.source))
+                    continue;
+                const rows = msgStmt.all(s.id);
+                // Skip only genuinely empty sessions. Do NOT gate on message count —
+                // a short 2-message exchange can carry a real decision. Meaningful-
+                // content is gated downstream by the post-denoise 200-char check in
+                // nightly.ts, so short-but-dense sessions aren't dropped here.
+                if (rows.length === 0)
+                    continue;
+                // Map Hermes rows to the shape extractConversationText() understands
+                // (it reads m.role + m.content). Metadata/noise roles (tool results,
+                // session_meta) are relabelled "tool_result" so the distiller drops them.
+                const entries = rows.map((r) => ({
+                    role: NOISE_ROLES.has(r.role) ? "tool_result" : r.role,
+                    content: r.content ?? "",
+                }));
+                const endTs = s.ended_at ?? rows[rows.length - 1].timestamp;
+                batches.push({
+                    sessionId: s.id,
+                    projectName: profile,
+                    sourceAgent: `hermes/${profile}`,
+                    date: new Date(endTs * 1000).toISOString().slice(0, 10),
+                    entries,
+                });
+            }
+        }
+        catch {
+            // Query failed (schema drift on a Hermes upgrade) — skip this DB, don't crash the run.
+        }
+        finally {
+            db.close();
+        }
+    }
+    return batches;
+}
+/**
+ * Find every Hermes state DB: one per profile, plus the global DB for
+ * non-profile installs. The profile name becomes the provenance label.
+ */
+function discoverProfileDbs(hermesHome) {
+    const out = [];
+    const profilesDir = (0, node_path_1.join)(hermesHome, "profiles");
+    try {
+        for (const entry of (0, node_fs_1.readdirSync)(profilesDir)) {
+            if (entry.startsWith(".") || entry.startsWith("_"))
+                continue;
+            const dbPath = (0, node_path_1.join)(profilesDir, entry, "state.db");
+            try {
+                if ((0, node_fs_1.statSync)(dbPath).isFile())
+                    out.push({ profile: entry, dbPath });
+            }
+            catch {
+                // no state.db for this profile
+            }
+        }
+    }
+    catch {
+        // no profiles dir
+    }
+    const globalDb = (0, node_path_1.join)(hermesHome, "state.db");
+    if ((0, node_fs_1.existsSync)(globalDb))
+        out.push({ profile: "default", dbPath: globalDb });
+    return out;
+}

package/dist/index.d.ts

@@ -1,9 +1,21 @@
 /**
- * Hicortex OpenClaw Plugin — Long-term Memory That Learns.
+ * Hicortex OpenClaw Plugin — Long-term Memory That Learns. (0.10.0)
  *
- * Pure in-process plugin: no sidecar, no HTTP. Uses better-sqlite3 + sqlite-vec
- * for storage, @huggingface/transformers for embeddings, and multi-provider LLM
- * for distillation and consolidation.
+ * Thin-client model: the plugin requires a Hicortex server (co-located at
+ * http://127.0.0.1:8787 by default, or a remote URL via `serverUrl` config).
+ * No local database, no local LLM, no embedder, no consolidation scheduler.
+ *
+ * Install once: `openclaw plugins install @gamaze/hicortex`
+ * Run server:   `npx @gamaze/hicortex init`
+ *
+ * Responsibilities (recall-only adapter, like the Hermes plugin):
+ *   - before_agent_start  → GET /lessons (fail-soft, 3s timeout) → inject context
+ *   - Tools               → HTTP proxies to /search, /context, /ingest, /lessons
+ *
+ * CAPTURE IS NOT THIS PLUGIN'S JOB. OpenClaw persists sessions at
+ * ~/.openclaw/agents/<agentId>/sessions/*.jsonl in the Pi v3 format; the
+ * machine's Hicortex nightly reads them via oc-transcript-reader.ts —
+ * canonical nightly-from-logs, same as CC JSONL and Hermes state.db.
  */
 declare const _default: {
     id: string;