@gamaze/hicortex 0.12.1 → 0.13.0

package/README.md

@@ -129,6 +129,20 @@ Beyond auto-distilled memories and lessons, Hicortex holds a **hand-edited conte
 - **Delivery:** injected into the harnesses listed in `contextClients` (default `["cc"]` — Claude Code only in v1; `"all"` or any subset of `cc`/`hermes`/`oc`).
 - **Deletion** is filesystem-only — remove the file on the server (as the daemon user).
 
+### Per-agent context (0.13)
+
+One server serves a fleet of distinct-persona agents. Each agent can have its **own** context, resolved server-side into one of three modes:
+
+- **`override`** (default when an `agents/<id>/` dir exists) — the agent's sections win **per section name**, falling back to the global set for any section it doesn't define.
+- **`global`** — the shared global set (the 0.12 behavior).
+- **`off`** — inject nothing for that agent.
+
+- **Agent id:** Hermes and OC scope per profile/agent automatically. **CC is global by default** — it sends no `?agent=`, so all your CC machines share one global context (one user = one identity across machines). `agentName` is an explicit opt-in: set it with `init --agent-name <name>` and CC will send `?agent=<config.agentName>`; clear it with `init --agent-name ""` to return to global. The id is on the same strict allowlist as section names (it becomes a path). Shown by `hicortex status` (or `(not set — global context)` when unset).
+- **Storage:** per-agent sections live at `~/.hicortex/context/agents/<id>/*.md`; the global reader never descends into `agents/`.
+- **Config:** `contextAgents` maps agent id → mode; a dropped-in `agents/<id>/` dir alone means `override` with no config. Editing `contextAgents` needs a daemon restart; dropping in a dir takes effect immediately.
+- **Edit:** the web editor's scope selector (`Global` | `<agent>`; inherited sections shown dimmed), or `hicortex context show|edit --agent <id>`.
+- **Backward compatible:** no `?agent=` and no `contextAgents`/`agents/` dir → every agent gets the global set.
+
 ## CLI Commands
 
 ```bash
@@ -141,6 +155,9 @@ npx @gamaze/hicortex nightly --dry-run         # Preview without changes
 npx @gamaze/hicortex classify-domains          # Backfill domain tags over the corpus (see Memory Domains & Tags)
 npx @gamaze/hicortex context show [name]       # Print the standing context layer (see Context Layer)
 npx @gamaze/hicortex context edit <name>       # Edit a context section in $EDITOR
+npx @gamaze/hicortex context show --agent <id> # Show a specific agent's resolved context (0.13)
+npx @gamaze/hicortex init --agent-name <name>  # Opt in to a per-agent context id (default: unset — shared global context)
+npx @gamaze/hicortex init --agent-name ""      # Clear it back to global context
 npx @gamaze/hicortex status                    # Show config, DB stats
 npx @gamaze/hicortex uninstall                 # Remove CC integration (keeps DB)
 ```
@@ -186,6 +203,8 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `weakPrimaryFloor` | Minimum similarity for a no-fit memory to keep a weak domain association (default: 0.45) |
 | `moduleIndexTokenBudget` | Max tokens for domain index in lessons context (default: 500) |
 | `contextClients` | Which harnesses inject the [context layer](#context-layer) at session start (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc`) |
+| `contextAgents` | Per-agent context modes (0.13): `{ "<id>": "override" \| "global" \| "off" }`. Absent + no `agents/<id>/` dir → every agent gets the global set. Boot-time (restart to apply) — see [Per-agent context](#per-agent-context-013) |
+| `agentName` | This install's per-agent context id sent as `?agent=`. **Unset by default** (CC shares the global context — no `?agent=` sent). Explicit opt-in via `init --agent-name <name>`; `init --agent-name ""` clears it. An empty/whitespace value equals unset |
 | `nightlyHour` | Local hour (0–23) for the nightly job installed by `init` (defaults: client 2, server 3). Applied on fresh installs; existing schedules are never overwritten |
 | `telemetry` | Anonymous usage telemetry, `false` to opt out |
 
@@ -199,7 +218,7 @@ Full docs: [hicortex.gamaze.com/docs/configuration.html](https://hicortex.gamaze
 | `/distill` | POST | Yes | Canonical capture endpoint (0.9.0+). Accepts denoised session text (`text` string or `messages` array), distills server-side, stores. Used by both server-mode and client-mode nightly jobs. |
 | `/search` | GET | Yes | Semantic memory search |
 | `/recent` | GET | Yes | Recent memories, queryless recall (renamed from `/context` in 0.12) |
-| `/context` | GET / PUT | Yes | Standing [context layer](#context-layer): read all sections / partial-upsert named sections. Recall-style query params on GET → 400 (use `/recent`) |
+| `/context` | GET / PUT | Yes | Standing [context layer](#context-layer): read all sections / partial-upsert named sections. `?agent=<id>` selects a [per-agent scope](#per-agent-context-013) (server resolves override/global/off + merge); invalid id → 400. Recall-style query params on GET → 400 (use `/recent`) |
 | `/context/ui` | GET | No* | Web editor for the context layer (shell served without auth, like `/viz`; data via `/context`) |
 | `/lessons` | GET | Yes | Lessons + memory index (used by CC SessionStart hook) |
 | `/ingest` | POST | Yes | Legacy: accept a single pre-distilled memory from older clients |

package/assets/context.html

@@ -77,6 +77,13 @@
   header h1 { font-size: 15px; font-weight: 600; white-space: nowrap; }
   header .meta { color: var(--text-dim); font-size: 12px; white-space: nowrap; }
   header .spacer { flex: 1; }
+  header select, header #newagent {
+    background: var(--bg); color: var(--text);
+    border: 1px solid var(--panel-border); border-radius: 5px;
+    padding: 4px 6px; font: inherit; font-size: 12px;
+  }
+  header #newagent { width: 120px; }
+  header .btn.small { padding: 4px 10px; font-size: 12px; }
 
   main { flex: 1; display: flex; flex-direction: column; padding: 14px 18px; gap: 12px; min-height: 0; }
 
@@ -95,7 +102,9 @@
     color: var(--text); background: var(--tab-active);
     border-color: var(--panel-border); border-bottom: 1px solid var(--tab-active);
   }
+  .tab.inherited { opacity: 0.6; font-style: italic; }
   .tab .dirty { color: var(--accent); margin-left: 5px; }
+  .tab .inh { color: var(--text-dim); margin-left: 5px; font-size: 11px; }
 
   #addwrap { margin-left: auto; display: flex; gap: 6px; align-items: center; }
   #addname {
@@ -161,8 +170,13 @@
 <body>
 <header>
   <h1>Hicortex — context</h1>
+  <label class="meta" for="scope">scope</label>
+  <select id="scope" title="Which agent's context to edit"></select>
+  <input type="text" id="newagent" placeholder="new-agent-id" autocomplete="off" spellcheck="false">
+  <button class="btn secondary small" id="addagent">Add agent</button>
   <span class="meta" id="clients"></span>
   <div class="spacer"></div>
+  <span class="meta" id="mode"></span>
   <span class="meta" id="updated"></span>
 </header>
 
@@ -255,6 +269,10 @@
   var msgEl = document.getElementById("msg");
   var clientsEl = document.getElementById("clients");
   var updatedEl = document.getElementById("updated");
+  var modeEl = document.getElementById("mode");
+  var scopeSel = document.getElementById("scope");
+  var newAgentInput = document.getElementById("newagent");
+  var addAgentBtn = document.getElementById("addagent");
   var overlay = document.getElementById("overlay");
   var tokenInput = document.getElementById("token-input");
   var tokenErr = document.getElementById("token-err");
@@ -267,6 +285,20 @@
   var active = null;        // active section name
   var afterAuth = null;     // action to retry after a successful token prompt
 
+  // Per-agent scope (0.13). scope = null → the global set; otherwise an agent
+  // id, and edits target PUT /context?agent=<id>. `agents` is the id -> mode
+  // map from the bare (global) GET; `origins` is the id -> "global"|"agent"
+  // provenance from an agent-scope GET (used to dim inherited tabs).
+  var scope = null;
+  var agents = {};
+  var origins = {};
+
+  // ?agent= query for the active scope. Written so the literal fetch("/context"
+  // survives the self-containment test; the server does the resolution.
+  function scopeQS() {
+    return scope ? "?agent=" + encodeURIComponent(scope) : "";
+  }
+
   function setMsg(text, cls) {
     msgEl.textContent = text || "";
     msgEl.className = cls || "dim";
@@ -288,9 +320,18 @@
 
     order.forEach(function (name) {
       var b = document.createElement("button");
-      b.className = "tab" + (name === active ? " active" : "");
+      // In an agent scope, a section still coming from the global set is
+      // inherited — dim it and mark it. Saving it PUTs to the agent (override).
+      var inherited = scope && origins[name] === "global";
+      b.className = "tab" + (name === active ? " active" : "") + (inherited ? " inherited" : "");
       b.type = "button";
       b.appendChild(document.createTextNode(name));
+      if (inherited) {
+        var inh = document.createElement("span");
+        inh.className = "inh";
+        inh.textContent = "(inherited)";
+        b.appendChild(inh);
+      }
       if (isDirty(name)) {
         var dot = document.createElement("span");
         dot.className = "dirty";
@@ -316,13 +357,33 @@
     area.focus();
   }
 
-  function updateMeta(clients, updatedAt) {
+  function updateMeta(clients, updatedAt, mode) {
     if (Array.isArray(clients)) {
       clientsEl.textContent = clients.length ? "clients: " + clients.join(", ") : "clients: none";
     }
     if (updatedAt !== undefined) {
       updatedEl.textContent = updatedAt ? "updated " + updatedAt : "";
     }
+    if (mode !== undefined) {
+      modeEl.textContent = mode ? "mode: " + mode : "";
+    }
+  }
+
+  // Rebuild the scope <select> from the known agents map. Options are added via
+  // textContent only (never innerHTML); the current scope stays selected.
+  function populateScopeOptions() {
+    while (scopeSel.firstChild) scopeSel.removeChild(scopeSel.firstChild);
+    var globalOpt = document.createElement("option");
+    globalOpt.value = "";
+    globalOpt.textContent = "Global";
+    scopeSel.appendChild(globalOpt);
+    Object.keys(agents).sort().forEach(function (id) {
+      var o = document.createElement("option");
+      o.value = id;
+      o.textContent = id + " (" + agents[id] + ")";
+      scopeSel.appendChild(o);
+    });
+    scopeSel.value = scope || "";
   }
 
   // =========================================================================
@@ -330,7 +391,7 @@
   // =========================================================================
   function load() {
     setMsg("Loading…", "dim");
-    fetch("/context", { headers: authHeaders() })
+    fetch("/context" + scopeQS(), { headers: authHeaders() })
       .then(function (resp) {
         if (resp.status === 401) { afterAuth = load; showTokenPrompt(); throw new Error("unauthorized"); }
         if (!resp.ok) {
@@ -342,6 +403,11 @@
       })
       .then(function (data) {
         overlay.classList.remove("open");
+        // The bare (global) response carries the `agents` map; an agent-scope
+        // response carries `origins`. Retain the last-known agents list when the
+        // current response omits it so the selector stays populated.
+        if (scope === null && data.agents && typeof data.agents === "object") agents = data.agents;
+        origins = (data.origins && typeof data.origins === "object") ? data.origins : {};
         var incoming = data.sections || {};
         var names = Object.keys(incoming).sort();
         sections = {};
@@ -353,7 +419,8 @@
         // Keep the active tab if it still exists, else pick the first.
         if (!active || order.indexOf(active) < 0) active = order.length ? order[0] : null;
         if (active) area.value = sections[active].draft;
-        updateMeta(data.clients, data.updated_at || null);
+        updateMeta(data.clients, data.updated_at || null, data.mode || "");
+        populateScopeOptions();
         renderTabs();
         setMsg(order.length ? "" : "", "dim");
       })
@@ -382,7 +449,7 @@
 
     saveBtn.disabled = true;
     setMsg("Saving…", "dim");
-    fetch("/context", {
+    fetch("/context" + scopeQS(), {
       method: "PUT",
       headers: authHeaders({ "Content-Type": "application/json" }),
       body: JSON.stringify(payload),
@@ -402,7 +469,13 @@
         overlay.classList.remove("open");
         var s = sections[name];
         if (s) { s.saved = value; s.isNew = false; }
-        updateMeta(undefined, body.updated_at || null);
+        // In an agent scope the just-saved section is now an override (no longer
+        // inherited); a first save also registers the agent in the selector.
+        if (scope) {
+          origins[name] = "agent";
+          if (!agents[scope]) { agents[scope] = body.mode || "override"; populateScopeOptions(); }
+        }
+        updateMeta(undefined, body.updated_at || null, body.mode);
         setMsg("Saved" + (body.updated_at ? " · " + body.updated_at : ""), "ok");
         renderTabs();
       })
@@ -436,6 +509,39 @@
     setMsg("New section “" + name + "” — edit and Save to create it.", "dim");
   }
 
+  // =========================================================================
+  // Scope switching — reload the selected agent's (or the global) context.
+  // Warns before discarding unsaved edits in the current scope.
+  // =========================================================================
+  function anyDirty() {
+    return order.some(function (n) { return isDirty(n); });
+  }
+
+  function switchScope(next) {
+    if (anyDirty() && !window.confirm("Discard unsaved changes and switch scope?")) {
+      scopeSel.value = scope || "";
+      return;
+    }
+    scope = next || null;
+    active = null; // let load() pick the first tab in the new scope
+    load();
+  }
+
+  function addAgent() {
+    var id = newAgentInput.value.trim();
+    if (!validName(id)) {
+      setMsg("Invalid agent id — lowercase letters, digits, - or _ (max 64, no leading - or _).", "err");
+      newAgentInput.focus();
+      return;
+    }
+    newAgentInput.value = "";
+    // The agent dir is created server-side on the first Save; until then the
+    // scope resolves to the inherited global set. Register it locally so the
+    // selector shows it immediately.
+    if (!agents[id]) agents[id] = "override";
+    switchScope(id);
+  }
+
   // =========================================================================
   // Token prompt (remote only — localhost bypasses auth)
   // =========================================================================
@@ -466,6 +572,9 @@
   saveBtn.addEventListener("click", save);
   addBtn.addEventListener("click", addSection);
   addName.addEventListener("keydown", function (e) { if (e.key === "Enter") addSection(); });
+  scopeSel.addEventListener("change", function () { switchScope(scopeSel.value); });
+  addAgentBtn.addEventListener("click", addAgent);
+  newAgentInput.addEventListener("keydown", function (e) { if (e.key === "Enter") addAgent(); });
   area.addEventListener("input", function () {
     if (active && sections[active]) sections[active].draft = area.value;
     renderTabs();

package/dist/cli-args.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tiny, dependency-free argv helpers for cli.ts. Kept in their own module so
+ * cli.ts can import them statically without pulling in a heavy command module
+ * (its command handlers stay lazily `import()`-ed).
+ */
+/** Thrown when a value-flag is present but missing its value. */
+export declare class MissingFlagValueError extends Error {
+}
+/**
+ * Read a required value for `flag` from `argv`. Returns undefined when the flag
+ * is absent; throws MissingFlagValueError when it is present without a value
+ * (end of args) OR the next token is itself a flag (starts with "-"). The
+ * latter guard stops `--agent-name --server <url>` from silently swallowing
+ * `--server` as the agent name — a typo must be loud.
+ */
+export declare function readValueFlag(argv: string[], flag: string): string | undefined;

package/dist/cli-args.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Tiny, dependency-free argv helpers for cli.ts. Kept in their own module so
+ * cli.ts can import them statically without pulling in a heavy command module
+ * (its command handlers stay lazily `import()`-ed).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingFlagValueError = void 0;
+exports.readValueFlag = readValueFlag;
+/** Thrown when a value-flag is present but missing its value. */
+class MissingFlagValueError extends Error {
+}
+exports.MissingFlagValueError = MissingFlagValueError;
+/**
+ * Read a required value for `flag` from `argv`. Returns undefined when the flag
+ * is absent; throws MissingFlagValueError when it is present without a value
+ * (end of args) OR the next token is itself a flag (starts with "-"). The
+ * latter guard stops `--agent-name --server <url>` from silently swallowing
+ * `--server` as the agent name — a typo must be loud.
+ */
+function readValueFlag(argv, flag) {
+    const i = argv.indexOf(flag);
+    if (i === -1)
+        return undefined;
+    const val = argv[i + 1];
+    if (val === undefined || val.startsWith("-")) {
+        throw new MissingFlagValueError(`${flag} requires a value`);
+    }
+    return val;
+}

package/dist/cli.js

@@ -14,6 +14,7 @@
  *   uninstall  Clean removal of CC integration
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+const cli_args_js_1 = require("./cli-args.js");
 const command = process.argv[2];
 switch (command) {
     case "server": {
@@ -32,8 +33,16 @@ switch (command) {
     case "init": {
         const serverArg = process.argv.indexOf("--server");
         const serverUrl = serverArg !== -1 ? process.argv[serverArg + 1] : undefined;
+        let agentName;
+        try {
+            agentName = (0, cli_args_js_1.readValueFlag)(process.argv, "--agent-name");
+        }
+        catch {
+            console.error("[hicortex] init: --agent-name requires a value, e.g. --agent-name lenovo");
+            process.exit(1);
+        }
         import("./init.js").then(({ runInit }) => {
-            runInit({ serverUrl }).catch((err) => {
+            runInit({ serverUrl, agentName }).catch((err) => {
                 console.error("[hicortex] Init failed:", err);
                 process.exit(1);
             });
@@ -170,6 +179,8 @@ Commands:
                   Scaffolds 5 editable default memory domains (Work, Personal,
                   People, Health, Finance) in ~/.hicortex/config.json
   init --server <url>  Set up as client (remote server)
+  init --agent-name <name>  Opt in to a per-agent context id (default: unset — shared global context)
+                            Pass --agent-name "" to clear it back to global
   nightly         Run nightly denoise + capture + consolidate
   relink          Resumable link-discovery pass over the ENTIRE corpus (server mode)
   classify-domains  Backfill content-based domain tags over the corpus (server mode, needs config.domains)
@@ -192,6 +203,7 @@ Options:
   classify-domains --reset  Restart from the beginning (ignore saved cursor)
   context show [name]       Print all context sections, or just <name> (raw, pipeable)
   context edit <name>       Edit a section in $EDITOR; PUT only if changed
+  context … --agent <id>    Target a per-agent scope instead of the global set
 
 Examples:
   npx @gamaze/hicortex server

package/dist/context-cli.d.ts

@@ -33,11 +33,14 @@ export interface ContextGetResponse {
     sections: Record<string, string>;
     updated_at: string | null;
     clients: string[];
+    /** Present only for an agent-scoped read (0.13). */
+    agent?: string;
+    mode?: string;
 }
 /** GET /context. Throws ContextCliError with a clear message on any failure. */
-export declare function getContext(target: ContextServerTarget): Promise<ContextGetResponse>;
+export declare function getContext(target: ContextServerTarget, agent?: string): Promise<ContextGetResponse>;
 /** PUT one section. Throws ContextCliError with a clear message on any failure. */
-export declare function putSection(target: ContextServerTarget, name: string, content: string): Promise<void>;
+export declare function putSection(target: ContextServerTarget, name: string, content: string, agent?: string): Promise<void>;
 /** Readable rendering of every section + the resolved clients line (show, no name). */
 export declare function formatAllSections(data: ContextGetResponse): string;
 /** Raw markdown for one section (show <name>), or null if it does not exist. */
@@ -53,6 +56,14 @@ export type EditorSpawn = (file: string) => boolean;
  * current content → $EDITOR on a temp file → PUT only if changed. Temp file is
  * always cleaned up. `spawn` is injectable for tests.
  */
-export declare function runEdit(name: string, spawn?: EditorSpawn): Promise<void>;
+export declare function runEdit(name: string, spawn?: EditorSpawn, agent?: string): Promise<void>;
+/**
+ * Split out a `--agent <id>` flag (anywhere in argv) from the positional args.
+ * The flag omitted → the global scope.
+ */
+export declare function extractAgentFlag(args: string[]): {
+    agent?: string;
+    rest: string[];
+};
 /** Dispatch for `hicortex context <sub>`. Throws ContextCliError on bad usage/failure. */
 export declare function runContextCommand(args: string[]): Promise<void>;

package/dist/context-cli.js

@@ -24,6 +24,7 @@ exports.putSection = putSection;
 exports.formatAllSections = formatAllSections;
 exports.formatOneSection = formatOneSection;
 exports.runEdit = runEdit;
+exports.extractAgentFlag = extractAgentFlag;
 exports.runContextCommand = runContextCommand;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -61,6 +62,10 @@ function loadConfig() {
 function sectionChanged(before, after) {
     return before !== after;
 }
+/** Append `?agent=<id>` to a /context URL when an agent scope is targeted. */
+function contextUrl(baseUrl, agent) {
+    return `${baseUrl}/context${agent ? `?agent=${encodeURIComponent(agent)}` : ""}`;
+}
 function authHeaders(token) {
     return token ? { Authorization: `Bearer ${token}` } : {};
 }
@@ -89,10 +94,10 @@ async function readBodyError(resp) {
     }
 }
 /** GET /context. Throws ContextCliError with a clear message on any failure. */
-async function getContext(target) {
+async function getContext(target, agent) {
     let resp;
     try {
-        resp = await fetch(`${target.baseUrl}/context`, {
+        resp = await fetch(contextUrl(target.baseUrl, agent), {
             headers: authHeaders(target.authToken),
             signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         });
@@ -103,13 +108,20 @@ async function getContext(target) {
     if (!resp.ok) {
         throw new ContextCliError(`GET /context failed — ${describeFailure(resp.status, await readBodyError(resp))}`);
     }
-    return (await resp.json());
+    const data = (await resp.json());
+    // Old-server echo guard: a pre-0.13 server ignores ?agent= and answers 200
+    // with the GLOBAL set. Editing off that (then PUTting) would clobber shared
+    // context. Refuse unless the server echoes the agent it was asked for.
+    if (agent && data.agent !== agent) {
+        throw new ContextCliError(`server did not echo agent '${agent}' — it likely predates per-agent context (needs 0.13+)`);
+    }
+    return data;
 }
 /** PUT one section. Throws ContextCliError with a clear message on any failure. */
-async function putSection(target, name, content) {
+async function putSection(target, name, content, agent) {
     let resp;
     try {
-        resp = await fetch(`${target.baseUrl}/context`, {
+        resp = await fetch(contextUrl(target.baseUrl, agent), {
             method: "PUT",
             headers: { "Content-Type": "application/json", ...authHeaders(target.authToken) },
             body: JSON.stringify({ sections: { [name]: content } }),
@@ -122,6 +134,17 @@ async function putSection(target, name, content) {
     if (!resp.ok) {
         throw new ContextCliError(`PUT /context failed — ${describeFailure(resp.status, await readBodyError(resp))}`);
     }
+    // Old-server echo guard on the WRITE too: a pre-0.13 server silently accepts
+    // the PUT as a GLOBAL write and returns 200 without echoing `agent`. Treat a
+    // missing echo as a failed agent write (the global section may have been
+    // clobbered — surface it loudly rather than reporting a false success).
+    if (agent) {
+        const body = (await resp.json().catch(() => ({})));
+        if (body.agent !== agent) {
+            throw new ContextCliError(`PUT /context?agent=${agent} — server did not echo the agent; it likely predates per-agent ` +
+                `context (needs 0.13+). It may have written to the GLOBAL scope — verify the server version.`);
+        }
+    }
 }
 // ---------------------------------------------------------------------------
 // Pure formatters (tested directly; no I/O)
@@ -140,6 +163,8 @@ function formatAllSections(data) {
         }
     }
     parts.push(`clients: ${data.clients.join(", ") || "(none)"}`);
+    if (data.agent)
+        parts.push(`agent: ${data.agent}${data.mode ? ` (mode: ${data.mode})` : ""}`);
     return parts.join("\n");
 }
 /** Raw markdown for one section (show <name>), or null if it does not exist. */
@@ -176,8 +201,8 @@ const defaultSpawn = (file) => {
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
-async function runShow(name) {
-    const data = await getContext(resolveContextTarget(loadConfig()));
+async function runShow(name, agent) {
+    const data = await getContext(resolveContextTarget(loadConfig()), agent);
     if (name) {
         const body = formatOneSection(data, name);
         if (body === null) {
@@ -195,12 +220,12 @@ async function runShow(name) {
  * current content → $EDITOR on a temp file → PUT only if changed. Temp file is
  * always cleaned up. `spawn` is injectable for tests.
  */
-async function runEdit(name, spawn = defaultSpawn) {
+async function runEdit(name, spawn = defaultSpawn, agent) {
     if (!(0, context_store_js_1.isValidSectionName)(name)) {
         throw new ContextCliError(`Invalid section name '${name}'. Must match ^[a-z0-9][a-z0-9_-]*$ (max ${context_store_js_1.SECTION_NAME_MAX} chars).`);
     }
     const target = resolveContextTarget(loadConfig());
-    const data = await getContext(target);
+    const data = await getContext(target, agent);
     const before = data.sections[name] ?? "";
     const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "hicortex-ctx-"));
     const file = (0, node_path_1.join)(dir, `${name}.md`);
@@ -215,26 +240,55 @@ async function runEdit(name, spawn = defaultSpawn) {
             process.stdout.write("no changes\n");
             return;
         }
-        await putSection(target, name, after);
-        process.stdout.write(`Saved section '${name}'.\n`);
+        await putSection(target, name, after, agent);
+        // Saving to an agent scope creates/extends that agent's override.
+        process.stdout.write(`Saved section '${name}'${agent ? ` for agent '${agent}' (override)` : ""}.\n`);
     }
     finally {
         (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
     }
 }
+/**
+ * Split out a `--agent <id>` flag (anywhere in argv) from the positional args.
+ * The flag omitted → the global scope.
+ */
+function extractAgentFlag(args) {
+    const rest = [];
+    let agent;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--agent") {
+            const val = args[i + 1];
+            // A missing value (end of args) or the next token being another flag is a
+            // typo — never let it silently fall through to the global scope.
+            if (val === undefined || val.startsWith("-")) {
+                throw new ContextCliError("--agent requires a value, e.g. --agent lenny");
+            }
+            agent = val;
+            i++;
+            continue;
+        }
+        rest.push(args[i]);
+    }
+    return { agent, rest };
+}
 /** Dispatch for `hicortex context <sub>`. Throws ContextCliError on bad usage/failure. */
 async function runContextCommand(args) {
-    const sub = args[0];
+    const { agent, rest } = extractAgentFlag(args);
+    // Fast-fail on a bad agent id before any HTTP call (the server enforces too).
+    if (agent !== undefined && !(0, context_store_js_1.isValidAgentId)(agent)) {
+        throw new ContextCliError(`Invalid agent id '${agent}'. Must match ^[a-z0-9][a-z0-9_-]*$ (max ${context_store_js_1.SECTION_NAME_MAX} chars).`);
+    }
+    const sub = rest[0];
     switch (sub) {
         case "show":
-            await runShow(args[1]);
+            await runShow(rest[1], agent);
             return;
         case "edit":
-            if (!args[1])
-                throw new ContextCliError("Usage: hicortex context edit <name>");
-            await runEdit(args[1]);
+            if (!rest[1])
+                throw new ContextCliError("Usage: hicortex context edit <name> [--agent <id>]");
+            await runEdit(rest[1], undefined, agent);
             return;
         default:
-            throw new ContextCliError("Usage: hicortex context <show [name] | edit <name>>");
+            throw new ContextCliError("Usage: hicortex context <show [name] | edit <name>> [--agent <id>]");
     }
 }