@gamaze/hicortex 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -10,7 +10,7 @@
  *
  * 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
+ *   - Tools               → HTTP proxies to /search, /recent, /ingest, /lessons
  *
  * CAPTURE IS NOT THIS PLUGIN'S JOB. OpenClaw persists sessions at
  * ~/.openclaw/agents/<agentId>/sessions/*.jsonl in the Pi v3 format; the

package/dist/index.js

@@ -11,7 +11,7 @@
  *
  * 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
+ *   - Tools               → HTTP proxies to /search, /recent, /ingest, /lessons
  *
  * CAPTURE IS NOT THIS PLUGIN'S JOB. OpenClaw persists sessions at
  * ~/.openclaw/agents/<agentId>/sessions/*.jsonl in the Pi v3 format; the
@@ -50,13 +50,30 @@ async function serverGet(path, timeoutMs) {
             signal: AbortSignal.timeout(timeoutMs),
         });
         if (!resp.ok)
-            return null;
-        return await resp.json();
+            return { data: null, status: resp.status };
+        return { data: await resp.json(), status: resp.status };
     }
     catch {
-        return null;
+        return { data: null, status: null };
     }
 }
+/**
+ * Human-readable GET failure. Distinguishes a down server from an HTTP error —
+ * in particular a 404, so plugin/server version skew reads as a version
+ * problem, not a network one. The /context→/recent rename hint (0.12) is
+ * added only for /recent, where it is the overwhelmingly likely cause.
+ */
+function describeGetFailure(status, endpoint) {
+    if (status === null)
+        return "server unreachable";
+    if (status === 404) {
+        const renameHint = endpoint.startsWith("/recent")
+            ? " (0.12 renamed /context to /recent)"
+            : "";
+        return `HTTP 404 — ${endpoint} not found on the server; likely plugin/server version skew${renameHint}. Upgrade the server first.`;
+    }
+    return `server returned HTTP ${status}`;
+}
 async function serverPost(path, body, timeoutMs) {
     try {
         const resp = await fetch(`${serverUrl}${path}`, {
@@ -145,7 +162,7 @@ exports.default = {
         api.on("before_agent_start", async (_event, ctx) => {
             try {
                 // One fetch — build context and check cap from the same response.
-                const data = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
+                const { data } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
                 if (!data || !data.lessons || data.lessons.length === 0)
                     return {};
                 const maxLessons = (0, features_js_1.lessonsLimit)();
@@ -199,9 +216,9 @@ exports.default = {
                         params.set("limit", String(args.limit));
                     if (args.project)
                         params.set("project", args.project);
-                    const data = await serverGet(`/search?${params}`, 10000);
+                    const { data, status } = await serverGet(`/search?${params}`, 10000);
                     if (!data)
-                        return { error: "Search failed: server unreachable" };
+                        return { error: `Search failed: ${describeGetFailure(status, "/search")}` };
                     return formatToolResults(data.results ?? []);
                 }
                 catch (err) {
@@ -210,8 +227,8 @@ exports.default = {
             },
         }), { name: "hicortex_search" });
         api.registerTool((_ctx) => ({
-            name: "hicortex_context",
-            description: "Get recent context memories, optionally filtered by project. Useful to recall what happened recently.",
+            name: "hicortex_recent",
+            description: "Get recent memories, optionally filtered by project. Queryless recall of the latest memories by project, ranked by importance. Useful to catch up on what happened recently.",
             parameters: {
                 type: "object",
                 properties: {
@@ -227,16 +244,16 @@ exports.default = {
                     if (args?.limit)
                         params.set("limit", String(args.limit));
                     const qs = params.toString();
-                    const data = await serverGet(`/context${qs ? `?${qs}` : ""}`, 10000);
+                    const { data, status } = await serverGet(`/recent${qs ? `?${qs}` : ""}`, 10000);
                     if (!data)
-                        return { error: "Context search failed: server unreachable" };
+                        return { error: `Recent recall failed: ${describeGetFailure(status, "/recent")}` };
                     return formatToolResults(data.results ?? []);
                 }
                 catch (err) {
-                    return { error: `Context search failed: ${err instanceof Error ? err.message : String(err)}` };
+                    return { error: `Recent recall failed: ${err instanceof Error ? err.message : String(err)}` };
                 }
             },
-        }), { name: "hicortex_context" });
+        }), { name: "hicortex_recent" });
         api.registerTool((_ctx) => ({
             name: "hicortex_ingest",
             description: "Store a new memory in long-term storage. Use for important facts, decisions, or lessons.",
@@ -284,9 +301,9 @@ exports.default = {
             },
             async execute(_callId, args, _ctx) {
                 try {
-                    const data = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
+                    const { data, status } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
                     if (!data)
-                        return { error: "Lessons fetch failed: server unreachable" };
+                        return { error: `Lessons fetch failed: ${describeGetFailure(status, "/lessons")}` };
                     const lessons = data.lessons ?? [];
                     if (lessons.length === 0) {
                         return { content: [{ type: "text", text: "No lessons found." }] };
@@ -308,9 +325,9 @@ exports.default = {
             },
             async execute(_callId, _args, _ctx) {
                 try {
-                    const data = await serverGet("/index", 10000);
+                    const { data, status } = await serverGet("/index", 10000);
                     if (!data)
-                        return { error: "Index fetch failed: server unreachable" };
+                        return { error: `Index fetch failed: ${describeGetFailure(status, "/index")}` };
                     return { content: [{ type: "text", text: JSON.stringify(data) }] };
                 }
                 catch (err) {
@@ -350,9 +367,9 @@ exports.default = {
                         params.set("domain", args.domain);
                     if (args.relationship)
                         params.set("relationship", args.relationship);
-                    const data = await serverGet(`/graph?${params}`, 10000);
+                    const { data, status } = await serverGet(`/graph?${params}`, 10000);
                     if (!data)
-                        return { error: "Graph query failed: server unreachable" };
+                        return { error: `Graph query failed: ${describeGetFailure(status, "/graph")}` };
                     return { content: [{ type: "text", text: JSON.stringify(data) }] };
                 }
                 catch (err) {
@@ -432,7 +449,7 @@ exports.default = {
 // ---------------------------------------------------------------------------
 const HICORTEX_TOOLS = [
     "hicortex_search",
-    "hicortex_context",
+    "hicortex_recent",
     "hicortex_ingest",
     "hicortex_lessons",
     "hicortex_index",

package/dist/init.js

@@ -188,7 +188,7 @@ function installCcCommands() {
 name: learn
 description: Save an explicit learning/insight to Hicortex long-term memory. Immediate storage, no nightly wait. Use when you discover something worth remembering across sessions.
 argument-hint: <learning to save>
-allowed-tools: mcp__hicortex__hicortex_ingest, mcp__hicortex__hicortex_search, mcp__hicortex__hicortex_context, mcp__hicortex__hicortex_lessons
+allowed-tools: mcp__hicortex__hicortex_ingest, mcp__hicortex__hicortex_search, mcp__hicortex__hicortex_recent, mcp__hicortex__hicortex_lessons
 ---
 
 # Save Learning to Hicortex
@@ -234,7 +234,7 @@ Becomes a call to hicortex_ingest with:
 name: hicortex-activate
 description: Register a Hicortex commercial license key. Personal and noncommercial use is free; commercial use requires a per-seat license from hicortex.gamaze.com.
 argument-hint: <license-key>
-allowed-tools: Bash(mkdir:*), Bash(echo:*), Bash(launchctl:*), Bash(systemctl:*), Bash(curl:*), mcp__hicortex__hicortex_ingest, mcp__hicortex__hicortex_search, mcp__hicortex__hicortex_context, mcp__hicortex__hicortex_lessons
+allowed-tools: Bash(mkdir:*), Bash(echo:*), Bash(launchctl:*), Bash(systemctl:*), Bash(curl:*), mcp__hicortex__hicortex_ingest, mcp__hicortex__hicortex_search, mcp__hicortex__hicortex_recent, mcp__hicortex__hicortex_lessons
 ---
 
 # Register Hicortex Commercial License
@@ -640,7 +640,7 @@ async function persistLlmConfig() {
     await options[selectedIdx].save();
     const selectedLabel = options[selectedIdx].label;
     if (selectedLabel.startsWith("Skip")) {
-        console.log("  No LLM configured — server will run recall-only (search/lessons/context work).\n" +
+        console.log("  No LLM configured — server will run recall-only (search/lessons/recent work).\n" +
             "  To enable capture and consolidation later, run: npx @gamaze/hicortex init");
     }
     else {
@@ -1282,10 +1282,12 @@ function installNightlyCron(hour) {
     const hh = String(hour).padStart(2, "0");
     // PATH must start with the binary's own directory (see installLaunchd for rationale).
     const binDir = (0, node_path_1.dirname)(binaryArgs[0]);
+    // One canonical nightly log path across platforms — status output, docs,
+    // and support instructions all reference this single location.
+    const logPath = (0, node_path_1.join)(HICORTEX_HOME, "nightly.log");
     if (os === "darwin") {
         const plistDir = (0, node_path_1.join)((0, node_os_1.homedir)(), "Library", "LaunchAgents");
         const plistPath = (0, node_path_1.join)(plistDir, "com.gamaze.hicortex-nightly.plist");
-        const logPath = (0, node_path_1.join)(HICORTEX_HOME, "nightly.log");
         // Never overwrite an existing schedule — users tune these (multi-slot
         // capture windows, quiet hours). Fresh installs only.
         if ((0, node_fs_1.existsSync)(plistPath)) {
@@ -1341,18 +1343,18 @@ ${programArgs}
         const configDir = (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "systemd", "user");
         const servicePath = (0, node_path_1.join)(configDir, "hicortex-nightly.service");
         const timerPath = (0, node_path_1.join)(configDir, "hicortex-nightly.timer");
-        // Never overwrite an existing schedule — users tune these. Fresh installs only.
-        if ((0, node_fs_1.existsSync)(timerPath)) {
-            console.log(`  ✓ Nightly timer already installed — leaving existing schedule as-is`);
-            return;
-        }
         const execStart = [...binaryArgs, "nightly"].join(" ");
+        // File logging, not journal: oneshot runs on machines with a volatile
+        // journal (e.g. Raspberry Pi defaults) otherwise fail without a trace.
+        // Same log path as the macOS plist. append: needs systemd ≥ 240 (2018).
         const service = `[Unit]
 Description=Hicortex Nightly (distill + POST)
 
 [Service]
 Type=oneshot
 ExecStart=${execStart}
+StandardOutput=append:${logPath}
+StandardError=append:${logPath}
 Environment=PATH=${binDir}:/usr/local/bin:/usr/bin:/bin
 Environment=HOME=${(0, node_os_1.homedir)()}
 WorkingDirectory=${(0, node_os_1.homedir)()}`;
@@ -1366,7 +1368,18 @@ Persistent=true
 [Install]
 WantedBy=timers.target`;
         (0, node_fs_1.mkdirSync)(configDir, { recursive: true });
+        // The .service file is ours — always refresh it so fixes (like file
+        // logging) reach existing installs. The .timer holds the user-tuned
+        // schedule and is never overwritten.
         (0, node_fs_1.writeFileSync)(servicePath, service);
+        if ((0, node_fs_1.existsSync)(timerPath)) {
+            try {
+                (0, node_child_process_1.execSync)("systemctl --user daemon-reload", { stdio: "pipe" });
+            }
+            catch { /* fine */ }
+            console.log(`  ✓ Nightly service refreshed — existing timer schedule kept as-is`);
+            return;
+        }
         (0, node_fs_1.writeFileSync)(timerPath, timer);
         try {
             (0, node_child_process_1.execSync)("systemctl --user daemon-reload", { stdio: "pipe" });

package/dist/lessons-context.d.ts

@@ -1,17 +1,30 @@
 /**
- * lessons-context — query-time lessons fetch for the CC SessionStart hook.
+ * lessons-context — query-time context injection for the CC SessionStart hook.
  *
  * Replaces file-based injection (injectLessons / injectLessonsFromServer).
- * Reads ~/.hicortex/config.json to find the server URL, GETs /lessons,
- * and prints a compact Markdown block to stdout so CC picks it up as
- * session context.
+ * Reads ~/.hicortex/config.json to find the server URL, then fetches TWO
+ * endpoints concurrently and prints a compact Markdown block to stdout so CC
+ * picks it up as session context:
+ *
+ *   GET /context  → the standing context layer (user info + rules; 0.12).
+ *                   Injected as a `## Context` block ONLY when this harness
+ *                   ("cc") is in the server-resolved `clients` list (self-gate).
+ *   GET /lessons  → episodic memory lessons + memory index, rendered as the
+ *                   existing `## Hicortex Memory` block.
+ *
+ * The two fetches run in Promise.all, each with its OWN 3 s timeout and
+ * INDEPENDENT fail-soft: a /context failure must never cost the lessons block,
+ * and vice versa. Sequential fetches would double worst-case SessionStart
+ * latency (~6 s) — see spec §7.
  *
  * Fail-soft by design: ANY failure (missing config, network error, non-2xx,
  * parse error) results in silent exit-0. A broken hook must never block a
- * CC session.
+ * CC session, and a broken /context fetch must never blank the whole output.
  */
 /**
- * Fetch lessons from the configured server and return a formatted Markdown
- * block, or null on any failure (caller should print nothing and exit 0).
+ * Fetch context + lessons concurrently and return the combined Markdown block,
+ * or null when neither yields anything (nothing to inject; caller prints
+ * nothing and exits 0). The `## Context` block is prepended before the existing
+ * `## Hicortex Memory` block.
  */
 export declare function fetchLessonsContext(): Promise<string | null>;

package/dist/lessons-context.js

@@ -1,15 +1,26 @@
 "use strict";
 /**
- * lessons-context — query-time lessons fetch for the CC SessionStart hook.
+ * lessons-context — query-time context injection for the CC SessionStart hook.
  *
  * Replaces file-based injection (injectLessons / injectLessonsFromServer).
- * Reads ~/.hicortex/config.json to find the server URL, GETs /lessons,
- * and prints a compact Markdown block to stdout so CC picks it up as
- * session context.
+ * Reads ~/.hicortex/config.json to find the server URL, then fetches TWO
+ * endpoints concurrently and prints a compact Markdown block to stdout so CC
+ * picks it up as session context:
+ *
+ *   GET /context  → the standing context layer (user info + rules; 0.12).
+ *                   Injected as a `## Context` block ONLY when this harness
+ *                   ("cc") is in the server-resolved `clients` list (self-gate).
+ *   GET /lessons  → episodic memory lessons + memory index, rendered as the
+ *                   existing `## Hicortex Memory` block.
+ *
+ * The two fetches run in Promise.all, each with its OWN 3 s timeout and
+ * INDEPENDENT fail-soft: a /context failure must never cost the lessons block,
+ * and vice versa. Sequential fetches would double worst-case SessionStart
+ * latency (~6 s) — see spec §7.
  *
  * Fail-soft by design: ANY failure (missing config, network error, non-2xx,
  * parse error) results in silent exit-0. A broken hook must never block a
- * CC session.
+ * CC session, and a broken /context fetch must never blank the whole output.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchLessonsContext = fetchLessonsContext;
@@ -19,41 +30,53 @@ const node_os_1 = require("node:os");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
-const HICORTEX_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
 const DEFAULT_PORT = 8787;
+/** Harness name this hook injects for — used to self-gate on GET /context `clients`. */
+const THIS_HARNESS = "cc";
 /**
- * Fetch lessons from the configured server and return a formatted Markdown
- * block, or null on any failure (caller should print nothing and exit 0).
+ * Resolve the Hicortex home. Honors HICORTEX_HOME (matches the HICORTEX_DB_PATH
+ * env convention in db.ts) so headless/scratch installs can point elsewhere;
+ * defaults to ~/.hicortex. Resolved per-call so tests and env changes apply.
  */
-async function fetchLessonsContext() {
-    let config = {};
+function hicortexHome() {
+    return process.env.HICORTEX_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
+}
+/**
+ * Read ~/.hicortex/config.json and resolve the server URL + auth token, or
+ * null when there is no usable config (server not set up yet — fail soft).
+ */
+function resolveConfig() {
+    const home = hicortexHome();
+    let config;
     try {
-        config = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(HICORTEX_HOME, "config.json"), "utf-8"));
+        config = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(home, "config.json"), "utf-8"));
     }
     catch {
-        // No config file — server not set up yet. Fail soft.
         return null;
     }
-    // Determine server URL: client mode uses serverUrl; server mode uses localhost.
+    // Client mode uses serverUrl; server mode uses localhost.
     const serverUrl = config.mode === "client" && typeof config.serverUrl === "string"
         ? config.serverUrl.replace(/\/+$/, "")
         : `http://127.0.0.1:${config.port ?? DEFAULT_PORT}`;
-    const authToken = config.authToken;
-    let data;
-    try {
-        const resp = await fetch(`${serverUrl}/lessons`, {
-            headers: authToken ? { "Authorization": `Bearer ${authToken}` } : {},
-            signal: AbortSignal.timeout(3000),
-        });
-        if (!resp.ok)
-            return null;
-        data = await resp.json();
-    }
-    catch {
+    return { serverUrl, authToken: config.authToken, home };
+}
+function authHeaders(authToken) {
+    return authToken ? { "Authorization": `Bearer ${authToken}` } : {};
+}
+/**
+ * Fetch /lessons and build the `## Hicortex Memory` block, or null on any
+ * failure (missing/non-2xx/parse). Preserves the pre-0.12 behavior exactly.
+ */
+async function fetchLessonsBlock(cfg) {
+    const resp = await fetch(`${cfg.serverUrl}/lessons`, {
+        headers: authHeaders(cfg.authToken),
+        signal: AbortSignal.timeout(3000),
+    });
+    if (!resp.ok)
         return null;
-    }
+    const data = await resp.json();
     const maxLessons = (0, features_js_1.lessonsLimit)();
-    const moduleIndex = data.moduleIndex ?? (0, state_js_1.loadState)(HICORTEX_HOME).moduleIndex;
+    const moduleIndex = data.moduleIndex ?? (0, state_js_1.loadState)(cfg.home).moduleIndex;
     // The SessionStart hook runs in the session's working directory, whose last
     // path component matches the capture-side CC project name convention
     // (transcript-reader's decodeProjectDirName also takes the last component).
@@ -71,12 +94,11 @@ async function fetchLessonsContext() {
     const parts = ["## Hicortex Memory", ""];
     parts.push("You have access to shared long-term memory across all agents and sessions.");
     parts.push("BEFORE making decisions, search memory: `hicortex_search` for prior decisions on the same topic.");
-    parts.push("Use `hicortex_context` at session start for recent project state.");
+    parts.push("Use `hicortex_recent` at session start for recent project state.");
     if (lessonLines.length > 0) {
         parts.push("", "### Lessons (updated nightly)");
         parts.push(...lessonLines);
     }
-    // Memory index
     const { index } = data;
     if (moduleIndex && moduleIndex.domains.length > 0) {
         parts.push("", "### Memory Index");
@@ -95,3 +117,79 @@ async function fetchLessonsContext() {
     }
     return parts.join("\n");
 }
+/**
+ * Title-case a section name for its heading: split on `-`/`_`, capitalize each
+ * word ("user" → "User", "my_notes" → "My Notes").
+ */
+function titleCaseSection(name) {
+    return name
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/**
+ * Stable section ordering: `user` first, then `rules` (the seeded primary
+ * sections, spec §8), then every other section alphabetically. Server-side
+ * enumeration order (readdirSync) is FS-dependent, so we sort here for a
+ * deterministic injection block.
+ */
+function orderSectionNames(names) {
+    const primaries = ["user", "rules"].filter((p) => names.includes(p));
+    const rest = names.filter((n) => n !== "user" && n !== "rules").sort();
+    return [...primaries, ...rest];
+}
+/**
+ * Fetch /context and build the `## Context` block, or null when nothing should
+ * be injected: non-2xx, this harness not in `clients`, no sections, or all
+ * sections empty. Throws propagate to the caller's fail-soft catch.
+ */
+async function fetchContextBlock(cfg) {
+    const resp = await fetch(`${cfg.serverUrl}/context`, {
+        headers: authHeaders(cfg.authToken),
+        signal: AbortSignal.timeout(3000),
+    });
+    if (!resp.ok)
+        return null;
+    const data = await resp.json();
+    // Self-gate: only inject when this harness is in the server-resolved list.
+    const clients = Array.isArray(data.clients) ? data.clients : [];
+    if (!clients.includes(THIS_HARNESS))
+        return null;
+    const sections = data.sections;
+    if (!sections || typeof sections !== "object" || Array.isArray(sections))
+        return null;
+    const names = orderSectionNames(Object.keys(sections));
+    const bodyParts = [];
+    for (const name of names) {
+        const body = sections[name];
+        if (typeof body !== "string" || body.trim() === "")
+            continue;
+        bodyParts.push(`### ${titleCaseSection(name)}`, "", body.trim());
+    }
+    if (bodyParts.length === 0)
+        return null;
+    return ["## Context", "", ...bodyParts].join("\n");
+}
+/**
+ * Fetch context + lessons concurrently and return the combined Markdown block,
+ * or null when neither yields anything (nothing to inject; caller prints
+ * nothing and exits 0). The `## Context` block is prepended before the existing
+ * `## Hicortex Memory` block.
+ */
+async function fetchLessonsContext() {
+    const cfg = resolveConfig();
+    if (!cfg)
+        return null;
+    // Independent fail-soft: each branch degrades to null without affecting the
+    // other. Promise.all runs them concurrently — each carries its own 3 s
+    // timeout, so worst-case latency stays ~3 s, not ~6 s (spec §7).
+    const [contextBlock, lessonsBlock] = await Promise.all([
+        fetchContextBlock(cfg).catch(() => null),
+        fetchLessonsBlock(cfg).catch(() => null),
+    ]);
+    const blocks = [contextBlock, lessonsBlock].filter((b) => b !== null && b !== "");
+    if (blocks.length === 0)
+        return null;
+    return blocks.join("\n\n");
+}

package/dist/mcp-server.js

@@ -50,6 +50,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startServer = startServer;
 const express_1 = __importDefault(require("express"));
+const node_path_1 = require("node:path");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const sse_js_1 = require("@modelcontextprotocol/sdk/server/sse.js");
 const zod_1 = require("zod");
@@ -61,6 +62,7 @@ const embedder_js_1 = require("./embedder.js");
 const storage = __importStar(require("./storage.js"));
 const graph_js_1 = require("./graph.js");
 const viz_js_1 = require("./viz.js");
+const context_store_js_1 = require("./context-store.js");
 const retrieval = __importStar(require("./retrieval.js"));
 const seed_lesson_js_1 = require("./seed-lesson.js");
 const distiller_js_1 = require("./distiller.js");
@@ -76,6 +78,9 @@ let llmConfig = null;
 // immediate abort ("strict", default) or a fallback to the base model ("local").
 let distillFallbackMode = "strict";
 let stateDir = "";
+// Resolved contextClients list (spec §2) — the harness names allowed to inject
+// the standing context layer. Echoed by GET /context so each hook self-gates.
+let contextClients = ["cc"];
 // Cache detectChunkSize results keyed by "<provider>/<model>@<baseUrl>" so we
 // probe each endpoint once per server boot rather than once per /distill request.
 const chunkSizeCache = new Map();
@@ -109,8 +114,8 @@ function createMcpServer() {
             return { content: [{ type: "text", text: `Search failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
         }
     });
-    // -- hicortex_context --
-    server.tool("hicortex_context", "Get recent context memories, optionally filtered by project. Useful to recall what happened recently.", {
+    // -- hicortex_recent --
+    server.tool("hicortex_recent", "Get recent memories, optionally filtered by project. Queryless recall of the latest memories by project, ranked by importance. Useful to catch up on what happened recently.", {
         project: zod_1.z.string().optional().describe("Filter by project name"),
         limit: zod_1.z.coerce.number().optional().describe("Max results (default 10)"),
     }, async ({ project, limit }) => {
@@ -121,7 +126,7 @@ function createMcpServer() {
             return { content: [{ type: "text", text: formatResults(results) }] };
         }
         catch (err) {
-            return { content: [{ type: "text", text: `Context search failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+            return { content: [{ type: "text", text: `Recent recall failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
         }
     });
     // -- hicortex_ingest --
@@ -387,7 +392,7 @@ async function startServer(options = {}) {
         console.warn("╔══════════════════════════════════════════════════════════════╗");
         console.warn("║  NO LLM CONFIGURED — running in recall-only mode            ║");
         console.warn("║                                                              ║");
-        console.warn("║  search / lessons / context: ENABLED                        ║");
+        console.warn("║  search / lessons / recent: ENABLED                         ║");
         console.warn("║  /distill (capture) and consolidation: DISABLED             ║");
         console.warn("║                                                              ║");
         console.warn("║  To enable capture, run:                                    ║");
@@ -422,6 +427,15 @@ async function startServer(options = {}) {
         console.warn("[hicortex] WARNING: no authToken configured — remote connections will be rejected " +
             "(localhost still works). Run `npx @gamaze/hicortex init` to generate a token.");
     }
+    // Context layer (0.12): resolve which harnesses may inject the standing
+    // context. Warn once per boot on unknown names so typos (e.g. "herms")
+    // surface instead of silently dropping.
+    const resolvedClients = (0, context_store_js_1.resolveContextClients)(savedConfig?.contextClients);
+    contextClients = resolvedClients.clients;
+    if (resolvedClients.dropped.length > 0) {
+        console.warn(`[hicortex] Ignoring unknown contextClients: ${resolvedClients.dropped.join(", ")} ` +
+            `(known: cc, hermes, oc)`);
+    }
     // Express app
     const app = (0, express_1.default)();
     // Raise the body limit — whole-session denoised transcripts exceed the 100 kB default.
@@ -431,7 +445,7 @@ async function startServer(options = {}) {
         const origin = req.headers.origin;
         if (origin) {
             res.setHeader("Access-Control-Allow-Origin", origin);
-            res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+            res.setHeader("Access-Control-Allow-Methods", "GET, PUT, POST, OPTIONS");
             res.setHeader("Access-Control-Allow-Headers", "Content-Type, Accept, Authorization");
             res.setHeader("Access-Control-Allow-Credentials", "true");
             res.setHeader("Vary", "Origin");
@@ -567,8 +581,8 @@ async function startServer(options = {}) {
             res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
         }
     });
-    // REST /context — recent context memories, optionally filtered by project.
-    app.get("/context", (req, res) => {
+    // REST /recent — recent memories, optionally filtered by project.
+    app.get("/recent", (req, res) => {
         if (!db) {
             res.status(503).json({ error: "Server not initialized" });
             return;
@@ -586,6 +600,44 @@ async function startServer(options = {}) {
             res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
         }
     });
+    // -------------------------------------------------------------------------
+    // REST /context — standing context layer (0.12, spec 2026-07-12).
+    //
+    // GET  → { sections, updated_at, clients } read from <hicortex-home>/context/.
+    // PUT  → partial upsert of named sections (allowlisted names, atomic).
+    //
+    // This is NOT recall. The recall endpoint that previously held this name is
+    // now /recent (§Naming). Stale-client tripwire: old recall callers always
+    // send project/limit/privacy query params; context-layer callers never do —
+    // so those params on GET /context return a loud, self-explaining 400 instead
+    // of silently degrading recall to an empty {sections} response.
+    //
+    // Auth is the standard model (bearer; localhost bypass) via the shared
+    // middleware — no special-casing here.
+    // -------------------------------------------------------------------------
+    // Thin adapters: all logic (tripwire, validation, allowlist, atomicity,
+    // symlink safety, size warn) lives in the pure handlers in context-store.ts,
+    // which the tests exercise directly — no mirror-app drift.
+    app.get("/context", (req, res) => {
+        try {
+            const r = (0, context_store_js_1.handleContextGet)((0, node_path_1.join)(stateDir, "context"), contextClients, req.query);
+            res.status(r.status).json(r.body);
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    app.put("/context", (req, res) => {
+        try {
+            const r = (0, context_store_js_1.handleContextPut)((0, node_path_1.join)(stateDir, "context"), req.body);
+            if (r.warn)
+                console.warn(`[hicortex] ${r.warn}`);
+            res.status(r.status).json(r.body);
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
     // REST /distill — canonical capture endpoint (0.9.0+).
     // Every machine (including the server itself) POSTs denoised session text here.
     // The server distills, embeds, stores. Body limit: 25 MB (raised at app init).
@@ -822,7 +874,9 @@ async function startServer(options = {}) {
             return;
         }
         const rawLimit = req.query.limit ? Number(req.query.limit) : undefined;
-        const resultLimit = rawLimit && Number.isFinite(rawLimit) ? rawLimit : 10;
+        // Floor + minimum 1: negative/fractional values would otherwise reach SQL
+        // LIMIT (negative = unlimited in SQLite; fractional = binding error).
+        const resultLimit = rawLimit && Number.isFinite(rawLimit) && rawLimit >= 1 ? Math.floor(rawLimit) : 10;
         const filterDomain = typeof req.query.domain === "string" && req.query.domain ? req.query.domain : undefined;
         const filterRelationship = typeof req.query.relationship === "string" && req.query.relationship ? req.query.relationship : undefined;
         try {
@@ -878,8 +932,9 @@ async function startServer(options = {}) {
                     }
                     minStrength = v;
                 }
-                // Export has its own default (500) — the shared resultLimit default of
-                // 10 is for neighbors/hubs. exportGraph clamps to the hard max (2000).
+                // Export has its own default (EXPORT_DEFAULT_LIMIT) — the shared
+                // resultLimit default of 10 is for neighbors/hubs. exportGraph clamps
+                // to EXPORT_MAX_LIMIT.
                 const exportLimit = rawLimit && Number.isFinite(rawLimit) ? rawLimit : graph_js_1.EXPORT_DEFAULT_LIMIT;
                 res.json((0, graph_js_1.exportGraph)(db, {
                     domain: filterDomain,
@@ -913,6 +968,16 @@ async function startServer(options = {}) {
     // (static third-party code from the npm tarball, no data) — the exemption
     // lives in createAuthMiddleware next to the /viz one.
     app.get("/viz/vendor/:file", (0, viz_js_1.vizVendorHandler)());
+    // GET /context/ui — standing-context editor page (0.12, spec 2026-07-12 §5).
+    //
+    // The PRIMARY edit surface for the context layer. Self-contained HTML (inline
+    // CSS/JS, zero external requests) served from assets/context.html; builds one
+    // tab per section from GET /context and saves via PUT /context. The page
+    // SHELL is public (exempted in createAuthMiddleware, like /viz — it carries
+    // no data); the GET/PUT /context data calls stay bearer-only (localhost
+    // bypass). The page collects the token client-side: ?token= URL param
+    // (stripped on load) or an in-page prompt on 401, persisted in localStorage.
+    app.get("/context/ui", (0, viz_js_1.contextUiHandler)());
     // SSE endpoint — each connection gets its own McpServer + transport
     app.get("/sse", async (req, res) => {
         const transport = new sse_js_1.SSEServerTransport("/messages", res);