@gamaze/hicortex 0.7.1 → 0.10.1

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

@@ -0,0 +1,20 @@
+/**
+ * OpenClaw transcript reader — reads OC session JSONL files.
+ *
+ * OC persists sessions at ~/.openclaw/agents/<agentId>/sessions/*.jsonl in the
+ * Pi version-3 event format (OpenClaw is Pi-runtime based): event types
+ * `session`, `model_change`, `thinking_level_change`, `message`, `custom`.
+ * The Pi parser handles the format; this wrapper only adapts the directory
+ * layout (one extra `agents/<agentId>` level) and sets OC provenance.
+ *
+ * Known limitation: rotated files (`*.jsonl.reset.<ts>`) are not read — only
+ * live `*.jsonl` files. Server-side session dedup keeps re-reads idempotent.
+ */
+import { type TranscriptBatch } from "./pi-transcript-reader.js";
+/**
+ * Read OpenClaw session transcripts modified after `since`.
+ *
+ * @param since Only return sessions with mtime > this date
+ * @param agentsDir Override the OC agents directory (default: ~/.openclaw/agents/)
+ */
+export declare function readOcTranscripts(since: Date, agentsDir?: string): TranscriptBatch[];

package/dist/oc-transcript-reader.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * OpenClaw transcript reader — reads OC session JSONL files.
+ *
+ * OC persists sessions at ~/.openclaw/agents/<agentId>/sessions/*.jsonl in the
+ * Pi version-3 event format (OpenClaw is Pi-runtime based): event types
+ * `session`, `model_change`, `thinking_level_change`, `message`, `custom`.
+ * The Pi parser handles the format; this wrapper only adapts the directory
+ * layout (one extra `agents/<agentId>` level) and sets OC provenance.
+ *
+ * Known limitation: rotated files (`*.jsonl.reset.<ts>`) are not read — only
+ * live `*.jsonl` files. Server-side session dedup keeps re-reads idempotent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readOcTranscripts = readOcTranscripts;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const pi_transcript_reader_js_1 = require("./pi-transcript-reader.js");
+const DEFAULT_OC_AGENTS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "agents");
+/**
+ * Read OpenClaw session transcripts modified after `since`.
+ *
+ * @param since Only return sessions with mtime > this date
+ * @param agentsDir Override the OC agents directory (default: ~/.openclaw/agents/)
+ */
+function readOcTranscripts(since, agentsDir = DEFAULT_OC_AGENTS_DIR) {
+    let agentIds;
+    try {
+        agentIds = (0, node_fs_1.readdirSync)(agentsDir);
+    }
+    catch {
+        // No OpenClaw install — not an error.
+        return [];
+    }
+    const batches = [];
+    for (const agentId of agentIds) {
+        const agentPath = (0, node_path_1.join)(agentsDir, agentId);
+        try {
+            if (!(0, node_fs_1.statSync)(agentPath).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        // agents/<agentId>/ contains a `sessions/` child with *.jsonl — exactly
+        // the <root>/<projectDir>/*.jsonl shape readPiTranscripts walks.
+        for (const batch of (0, pi_transcript_reader_js_1.readPiTranscripts)(since, agentPath)) {
+            batches.push({
+                ...batch,
+                // The Pi walk labels the project from the cwd or the "sessions" dir
+                // name — the agent id is the meaningful label for OC.
+                projectName: batch.projectName && batch.projectName !== "sessions"
+                    ? batch.projectName
+                    : agentId,
+                sourceAgent: `openclaw/${agentId}`,
+            });
+        }
+    }
+    return batches;
+}

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

@@ -31,6 +31,7 @@ export interface TranscriptBatch {
     projectName: string;
     date: string;
     entries: unknown[];
+    sourceAgent?: string;
 }
 /**
  * Read Pi session transcripts modified after `since`.

package/dist/status.js

@@ -9,6 +9,7 @@ const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
 const node_child_process_1 = require("node:child_process");
 const db_js_1 = require("./db.js");
+const features_js_1 = require("./features.js");
 const HICORTEX_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
@@ -34,15 +35,34 @@ async function runStatus() {
             console.log(`DB error:     ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    // License
+    // Config: license key + auth token
     const configPath = (0, node_path_1.join)(HICORTEX_HOME, "config.json");
     let licenseKey = "";
+    let savedAuthToken = "";
+    let isClientMode = false;
     try {
         const config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
         licenseKey = config.licenseKey ?? "";
+        savedAuthToken = config.authToken ?? "";
+        isClientMode = config.mode === "client";
     }
     catch { /* no config */ }
-    console.log(`License:      ${licenseKey ? "configured" : "free tier (250 memories)"}`);
+    const validated = (0, features_js_1.getValidatedLicense)();
+    if (validated?.valid && validated.tier) {
+        console.log(`License:      ${validated.tier} (licensed)`);
+    }
+    else if (licenseKey) {
+        console.log(`License:      key configured (not yet validated)`);
+    }
+    else {
+        console.log(`License:      noncommercial (no key)`);
+    }
+    if (!isClientMode && savedAuthToken) {
+        console.log(`Auth token:   ${savedAuthToken}  (clients connect with this token)`);
+    }
+    else if (!isClientMode && !savedAuthToken) {
+        console.log(`Auth token:   not configured (run: npx @gamaze/hicortex init)`);
+    }
     console.log();
     // Adapters
     console.log("Adapters:");

package/dist/storage.d.ts

@@ -9,7 +9,13 @@ import type { Memory, MemoryLink, InsertMemoryOptions } from "./types.js";
  */
 export declare function embedToBlob(embedding: Float32Array): Buffer;
 /**
- * Insert a memory and its vector embedding. Returns the generated UUID.
+ * Insert a memory and its vector embedding. Returns the memory's UUID.
+ *
+ * Idempotent on `sourceSession`: if a memory with that source_session already
+ * exists (UNIQUE index from migration v4), the insert is skipped and the
+ * EXISTING memory's id is returned (no vector re-insert). This lets `/ingest`
+ * and `/distill` safely retry a segment without double-inserting. Callers that
+ * omit sourceSession (NULL — nightly distillation, tests) never collide.
  */
 export declare function insertMemory(db: Database.Database, content: string, embedding: Float32Array, opts?: InsertMemoryOptions): string;
 /**

package/dist/storage.js

@@ -43,18 +43,39 @@ function rowToMemory(row) {
 // Single memory CRUD
 // ---------------------------------------------------------------------------
 /**
- * Insert a memory and its vector embedding. Returns the generated UUID.
+ * Insert a memory and its vector embedding. Returns the memory's UUID.
+ *
+ * Idempotent on `sourceSession`: if a memory with that source_session already
+ * exists (UNIQUE index from migration v4), the insert is skipped and the
+ * EXISTING memory's id is returned (no vector re-insert). This lets `/ingest`
+ * and `/distill` safely retry a segment without double-inserting. Callers that
+ * omit sourceSession (NULL — nightly distillation, tests) never collide.
  */
 function insertMemory(db, content, embedding, opts = {}) {
     const id = (0, node_crypto_1.randomUUID)();
     const ts = opts.createdAt ?? nowIso();
     const ingestedTs = nowIso();
-    db.prepare(`INSERT INTO memories
-     (id, content, base_strength, last_accessed, access_count,
-      created_at, ingested_at, source_agent, source_session, project,
-      privacy, memory_type)
-     VALUES (?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?)`).run(id, content, opts.baseStrength ?? 0.5, ts, ts, ingestedTs, opts.sourceAgent ?? "default", opts.sourceSession ?? null, opts.project ?? null, opts.privacy ?? "WORK", opts.memoryType ?? "episode");
-    db.prepare("INSERT INTO memory_vectors (id, embedding) VALUES (?, ?)").run(id, embedToBlob(embedding));
+    const sourceSession = opts.sourceSession ?? null;
+    const result = db
+        .prepare(`INSERT OR IGNORE INTO memories
+       (id, content, base_strength, last_accessed, access_count,
+        created_at, ingested_at, source_agent, source_session, project,
+        privacy, memory_type)
+       VALUES (?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(id, content, opts.baseStrength ?? 0.5, ts, ts, ingestedTs, opts.sourceAgent ?? "default", sourceSession, opts.project ?? null, opts.privacy ?? "WORK", opts.memoryType ?? "episode");
+    if (result.changes > 0) {
+        // New row — store its vector.
+        db.prepare("INSERT INTO memory_vectors (id, embedding) VALUES (?, ?)").run(id, embedToBlob(embedding));
+        return id;
+    }
+    // Collision on UNIQUE source_session — return the existing memory's id.
+    if (sourceSession) {
+        const existing = db
+            .prepare("SELECT id FROM memories WHERE source_session = ?")
+            .get(sourceSession);
+        if (existing)
+            return existing.id;
+    }
     return id;
 }
 /**

package/dist/transcript-reader.d.ts

@@ -12,7 +12,26 @@ export interface TranscriptBatch {
     projectName: string;
     date: string;
     entries: unknown[];
+    /**
+     * Optional source-agent label (e.g. "hermes/lenny"). 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;
 }
+/**
+ * Cheap pre-filter: skip CC session FILES with fewer than this many raw JSONL
+ * lines/entries — they're degenerate (aborted/empty) and not worth parsing.
+ *
+ * This is deliberately NOT the "is there meaningful content" gate. That is the
+ * post-denoise `transcript.length < MIN_CONVERSATION_CHARS` (200) check in
+ * nightly.ts, which measures actual conversation after tool/system noise is
+ * stripped. Raw entry count is a lossy proxy — a dense 2-message exchange can
+ * be very meaningful — so it's used only as a degenerate-file floor here, and
+ * intentionally NOT applied to the Hermes reader (which lets the 200-char
+ * content gate decide, so short dense sessions aren't dropped on count).
+ */
+export declare const MIN_TRANSCRIPT_ENTRIES = 4;
 /**
  * Read all CC transcripts modified since `since`.
  * Returns one batch per session file.

package/dist/transcript-reader.js

@@ -9,10 +9,24 @@
  * and feeds them to the existing distiller pipeline.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_TRANSCRIPT_ENTRIES = void 0;
 exports.readCcTranscripts = readCcTranscripts;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
+/**
+ * Cheap pre-filter: skip CC session FILES with fewer than this many raw JSONL
+ * lines/entries — they're degenerate (aborted/empty) and not worth parsing.
+ *
+ * This is deliberately NOT the "is there meaningful content" gate. That is the
+ * post-denoise `transcript.length < MIN_CONVERSATION_CHARS` (200) check in
+ * nightly.ts, which measures actual conversation after tool/system noise is
+ * stripped. Raw entry count is a lossy proxy — a dense 2-message exchange can
+ * be very meaningful — so it's used only as a degenerate-file floor here, and
+ * intentionally NOT applied to the Hermes reader (which lets the 200-char
+ * content gate decide, so short dense sessions aren't dropped on count).
+ */
+exports.MIN_TRANSCRIPT_ENTRIES = 4;
 const CC_PROJECTS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "projects");
 /**
  * Read all CC transcripts modified since `since`.
@@ -81,8 +95,8 @@ function parseTranscriptFile(filePath, projectName) {
         return null;
     }
     const lines = raw.split("\n").filter((l) => l.trim());
-    if (lines.length < 4)
-        return null; // Too short to be meaningful
+    if (lines.length < exports.MIN_TRANSCRIPT_ENTRIES)
+        return null; // degenerate/empty file
     const entries = [];
     let lastTimestamp = "";
     for (const line of lines) {
@@ -97,7 +111,7 @@ function parseTranscriptFile(filePath, projectName) {
             // Skip malformed lines
         }
     }
-    if (entries.length < 4)
+    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");

package/dist/types.d.ts

@@ -100,11 +100,21 @@ export interface ConsolidationReport {
 /** Plugin configuration from openclaw.plugin.json configSchema. */
 export interface HicortexConfig {
     licenseKey?: string;
+    /** Hicortex server URL. Defaults to http://127.0.0.1:8787 (co-located server). */
+    serverUrl?: string;
+    /** Bearer token for the Hicortex server. Localhost bypasses auth by default. */
+    authToken?: string;
+    /** @deprecated Use the Hicortex server for distillation and consolidation. */
     llmBaseUrl?: string;
+    /** @deprecated Use the Hicortex server for distillation and consolidation. */
     llmApiKey?: string;
+    /** @deprecated Use the Hicortex server for distillation and consolidation. */
     llmModel?: string;
+    /** @deprecated Use the Hicortex server for distillation and consolidation. */
     reflectModel?: string;
+    /** @deprecated Consolidation is owned by the server nightly. */
     consolidateHour?: number;
+    /** @deprecated The OC plugin no longer opens its own database. */
     dbPath?: string;
 }
 /** Response from license validation API. */

package/dist/uninstall.js

@@ -82,7 +82,37 @@ async function runUninstall() {
         }
     }
     console.log("  ✓ Removed /learn and /hicortex-activate commands");
-    // 4. Remove CLAUDE.md block
+    // 4. Remove SessionStart hook (JSON merge — filter out entries containing "lessons-context")
+    try {
+        const raw = (0, node_fs_1.readFileSync)(CC_SETTINGS, "utf-8");
+        const settings = JSON.parse(raw);
+        const hooks = settings.hooks;
+        const sessionStart = hooks && Array.isArray(hooks.SessionStart) ? hooks.SessionStart : null;
+        if (hooks && sessionStart) {
+            const before = sessionStart.length;
+            const filtered = sessionStart.filter((entry) => {
+                if (typeof entry !== "object" || entry === null)
+                    return true;
+                const e = entry;
+                if (Array.isArray(e.hooks)) {
+                    return !e.hooks.some((h) => {
+                        if (typeof h !== "object" || h === null)
+                            return false;
+                        const hook = h;
+                        return typeof hook.command === "string" && hook.command.includes("lessons-context");
+                    });
+                }
+                return true;
+            });
+            if (filtered.length < before) {
+                hooks.SessionStart = filtered;
+                (0, node_fs_1.writeFileSync)(CC_SETTINGS, JSON.stringify(settings, null, 2));
+                console.log("  ✓ Removed SessionStart lessons-context hook");
+            }
+        }
+    }
+    catch { /* no settings file or parse error — nothing to remove */ }
+    // 5. Remove CLAUDE.md block (old static block from pre-0.9.0; may still exist on upgrades)
     if ((0, claude_md_js_1.removeLessonsBlock)(CLAUDE_MD)) {
         console.log("  ✓ Removed Hicortex Learnings block from CLAUDE.md");
     }

package/hermes-plugin/hicortex/README.md

@@ -0,0 +1,77 @@
+# Hicortex memory plugin for Hermes
+
+> **Install:** `hermes plugins install gamaze-labs/hicortex-hermes-plugin` → `hermes memory setup hicortex` → restart your gateway.
+>
+> The [gamaze-labs/hicortex-hermes-plugin](https://github.com/gamaze-labs/hicortex-hermes-plugin) repo is a **generated read-only mirror** of `hermes-plugin/hicortex/` in the main Hicortex repo — do not open PRs there. Requires a running [Hicortex server](https://hicortex.gamaze.com/docs/installation.html) (local or remote) for recall; capture of Hermes sessions is handled by the server machine's nightly job.
+
+Gives [Hermes](https://github.com/nousresearch/hermes-agent) agents self-learning memory backed by a [Hicortex](https://hicortex.gamaze.com/) server: their experience is distilled into lessons overnight, and they wake up wiser. **Recall-only:** the plugin retrieves relevant memories on every turn and injects distilled lessons into the system prompt. It has **no local LLM, no capture, no cron** — it is a thin recall shim.
+
+**Capture happens centrally.** A nightly reader on the Hicortex server distills each agent's own session store (Hermes keeps full history in `~/.hermes/profiles/<agent>/state.db`), so nothing needs to be captured in real time. See `specs/2026-07-01-memory-capture-architecture.md` in the main repo.
+
+## How it works
+
+| Hermes hook | What it does | Hicortex call |
+|---|---|---|
+| `prefetch(query)` | recall relevant memories before each turn | `GET /search` |
+| `queue_prefetch(query)` | background recall for the next turn | `GET /search` |
+| `system_prompt_block()` | inject distilled lessons + memory index | `GET /lessons` |
+| `get_tool_schemas()` | exposes the 8 unified tools + `hicortex_recall_recent` | see tool table below |
+
+That's the whole surface. No `sync_turn`, no compaction/session-end capture — those are intentionally absent.
+
+### Tools (unified 8 + 1 Hermes-specific)
+
+| Tool | REST call | Description |
+|---|---|---|
+| `hicortex_search` | `GET /search` | Semantic search over long-term memory |
+| `hicortex_context` | `GET /context` | Recent context memories by project |
+| `hicortex_ingest` | `POST /ingest` | Store a new memory |
+| `hicortex_lessons` | `GET /lessons` | Get distilled lessons |
+| `hicortex_index` | `GET /index` | Knowledge domain index |
+| `hicortex_graph` | `GET /graph` | Graph queries (neighbors/hubs/path) |
+| `hicortex_update` | `POST /update` | Update a memory (re-embeds on content change) |
+| `hicortex_delete` | `POST /delete` | Permanently delete a memory and its links |
+| `hicortex_recall_recent` | `GET /context` | Hermes-specific alias for context recall |
+
+## Prerequisites
+
+- A reachable Hicortex server (default `http://localhost:8787`). Stand one up with `npx @gamaze/hicortex init`.
+- The server needs the REST `/search`, `/context`, `/lessons` endpoints (Hicortex ≥ 0.7).
+
+## Install
+
+Hermes discovers user-installed providers from `$HERMES_HOME/plugins/<name>/`:
+
+```bash
+cp -r hermes-plugin/hicortex "$HERMES_HOME/plugins/hicortex"
+```
+
+(No `pip install` — the plugin is stdlib-only.)
+
+## Configure & activate
+
+Use Hermes' own tooling — it discovers this plugin automatically and writes `config.yaml` correctly (**never hand-edit `config.yaml` with scripts/regex**):
+
+```bash
+hermes memory setup   # select "hicortex", enter the server URL/token when prompted
+```
+
+Run it once per profile if you use Hermes profiles. Hermes allows **one** external memory provider at a time, so disable Honcho (or any other) first, then restart the gateway.
+
+Config fields (`hicortex_url`, `default_project`, `recall_limit`, `privacy_filter`) can also be written to `$HERMES_HOME/plugins/hicortex/config.json` directly. The auth token is a **secret** — set it via env, not the JSON file:
+
+```bash
+export HICORTEX_AUTH_TOKEN=hctx-default-token   # or your custom token
+```
+
+Env overrides: `HICORTEX_URL`, `HICORTEX_AUTH_TOKEN`.
+
+## Topology
+
+- **Server host:** runs Hicortex. Set `hicortex_url: http://localhost:8787` (localhost bypasses auth).
+- **Other Hermes boxes:** set `hicortex_url` to the server's Tailscale hostname (e.g. `http://memory-server:8787`) and `HICORTEX_AUTH_TOKEN` to the server's token. Each box recalls from the same shared brain.
+
+## Notes
+
+- Localhost requests skip auth; remote requests require the bearer token.
+- Recall failures are non-fatal — the plugin returns empty context and the turn proceeds.

package/hermes-plugin/hicortex/__init__.py

@@ -0,0 +1,17 @@
+"""Hicortex memory provider plugin for Hermes — recall-only.
+
+Recall:   prefetch()          -> GET /search   (relevant memories before each turn)
+          tools               -> hicortex_search / hicortex_recall_recent
+          system_prompt_block -> lessons injected into the system prompt
+
+Capture is NOT the plugin's job. A nightly reader on the Hicortex server
+distills each agent's own session store (Hermes: ~/.hermes/profiles/<agent>/
+state.db) centrally. The plugin has no local LLM, no spool, no timer, and no
+capture path.
+"""
+
+from agent.memory_provider import MemoryProvider  # noqa: F401  (loader scans for this name)
+
+from .provider import HicortexProvider
+
+__all__ = ["HicortexProvider"]

package/hermes-plugin/hicortex/client.py

@@ -0,0 +1,162 @@
+"""Thin HTTP client for the Hicortex memory server.
+
+Stdlib-only (no pip dependencies) so the plugin installs with zero friction.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Optional
+
+
+class HicortexClient:
+    """Stateless HTTP client for the Hicortex REST surface."""
+
+    def __init__(
+        self,
+        base_url: str,
+        auth_token: Optional[str] = None,
+        timeout: float = 5.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        # Omit the token when targeting localhost — the server bypasses auth there.
+        # Match the server's bypass list exactly (mcp-server.ts): IPv4, IPv6,
+        # and IPv4-mapped-IPv6 (which Node reports for v4 clients on a 0.0.0.0 bind).
+        host = urllib.parse.urlparse(self.base_url).hostname or ""
+        self.auth_token = (
+            None
+            if host in ("127.0.0.1", "localhost", "::1", "::ffff:127.0.0.1")
+            else auth_token
+        )
+        self.timeout = timeout
+
+    def _headers(self) -> dict[str, str]:
+        h = {"Content-Type": "application/json", "Accept": "application/json"}
+        if self.auth_token:
+            h["Authorization"] = f"Bearer {self.auth_token}"
+        return h
+
+    def _get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        if params:
+            qs = urllib.parse.urlencode(
+                {k: v for k, v in params.items() if v is not None}
+            )
+            url = f"{url}?{qs}"
+        req = urllib.request.Request(url, headers=self._headers(), method="GET")
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+
+    def _post(self, path: str, body: dict[str, Any]) -> tuple[int, Any]:
+        """POST JSON body; returns (status_code, parsed_response)."""
+        url = f"{self.base_url}{path}"
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(url, data=data, headers=self._headers(), method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return resp.status, json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            body_bytes = e.read()
+            try:
+                parsed = json.loads(body_bytes.decode("utf-8"))
+            except Exception:
+                parsed = {"error": body_bytes.decode("utf-8", errors="replace")}
+            return e.code, parsed
+
+    # -- endpoints ------------------------------------------------------------
+
+    def health(self) -> dict[str, Any]:
+        return self._get("/health")
+
+    def search(
+        self,
+        query: str,
+        limit: int = 5,
+        project: Optional[str] = None,
+        privacy: Optional[str] = None,
+    ) -> list[dict]:
+        return self._get(
+            "/search",
+            {"query": query, "limit": limit, "project": project, "privacy": privacy},
+        ).get("results", [])
+
+    def context(
+        self,
+        project: Optional[str] = None,
+        limit: int = 10,
+        privacy: Optional[str] = None,
+    ) -> list[dict]:
+        return self._get(
+            "/context", {"project": project, "limit": limit, "privacy": privacy}
+        ).get("results", [])
+
+    def lessons(self) -> dict[str, Any]:
+        return self._get("/lessons")
+
+    def index(self) -> dict[str, Any]:
+        return self._get("/index")
+
+    def graph(
+        self,
+        op: str,
+        id: Optional[str] = None,
+        target_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        domain: Optional[str] = None,
+        relationship: Optional[str] = None,
+    ) -> dict[str, Any]:
+        return self._get(
+            "/graph",
+            {
+                "op": op,
+                "id": id,
+                "target_id": target_id,
+                "limit": limit,
+                "domain": domain,
+                "relationship": relationship,
+            },
+        )
+
+    def ingest(
+        self,
+        content: str,
+        source_agent: Optional[str] = None,
+        project: Optional[str] = None,
+        memory_type: str = "episode",
+        privacy: str = "WORK",
+    ) -> tuple[int, dict[str, Any]]:
+        return self._post(
+            "/ingest",
+            {
+                "content": content,
+                "source_agent": source_agent or "hermes/manual",
+                "project": project,
+                "memory_type": memory_type,
+                "privacy": privacy,
+            },
+        )
+
+    def update(
+        self,
+        id: str,
+        content: Optional[str] = None,
+        project: Optional[str] = None,
+        memory_type: Optional[str] = None,
+        privacy: Optional[str] = None,
+    ) -> tuple[int, dict[str, Any]]:
+        body: dict[str, Any] = {"id": id}
+        if content is not None:
+            body["content"] = content
+        if project is not None:
+            body["project"] = project
+        if memory_type is not None:
+            body["memory_type"] = memory_type
+        if privacy is not None:
+            body["privacy"] = privacy
+        return self._post("/update", body)
+
+    def delete(self, id: str) -> tuple[int, dict[str, Any]]:
+        return self._post("/delete", {"id": id})