@eleboucher/pi-memini 0.6.7 → 0.6.9

package/README.md

@@ -17,8 +17,8 @@ What it wires:
 - **`agent_end`** — once the agent finishes a prompt, stores the completed
   user/assistant turn back into memini (episodic, tagged `pi`, with the session
   id) so it can be recalled later.
-- **Explicit tools** — the same set Claude Code gets from memini's MCP server,
-  registered natively via `pi.registerTool`: `memory_recall`, `memory_list`,
+- **Explicit tools** — modeled on the tool set Claude Code gets from memini's
+  MCP server, registered natively via `pi.registerTool`: `memory_recall`, `memory_list`,
   `memory_remember`, `memory_forget`. The model can call them on demand even
   though the automatic loop already runs.
 
@@ -53,33 +53,68 @@ pi -e ./integrations/pi/plugin/dist/index.js
 All config is via environment variables in the shell that launches Pi (secrets
 stay out of any file):
 
-| Env var                          | Default                 | Purpose                                                                                       |
-| -------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------- |
-| `MEMINI_BASE_URL`                | `http://localhost:8080` | memini REST base URL (alias: `MEMINI_URL`)                                                    |
-| `MEMINI_NAMESPACE`               | cwd basename            | project the memory is scoped to (`X-Memini-Namespace`)                                        |
-| `MEMINI_HOME`                    | unset                   | caller's personal namespace, sent as `X-Memini-Home`; unset = no home leg                     |
-| `MEMINI_RECALL`                  | on                      | `0`/`false` disables recall-before-turn                                                       |
-| `MEMINI_CAPTURE`                 | on                      | `0`/`false` disables capture-after-turn                                                       |
-| `MEMINI_RECALL_LIMIT`            | `3`                     | max memories injected per turn                                                                |
-| `MEMINI_INJECT_RECALL_MAX_TOK`   | `0`                     | hard ceiling on recall-block tokens (`0` = unbounded); the tail is dropped with a footer      |
-| `MEMINI_INJECT_RECALL_MIN_SCORE` | `0`                     | fused-score floor (>=) sent as `min_score` to `/v1/search`                                    |
-| `MEMINI_INJECT_LABELS`           | —                       | comma-separated bullet labels: `tier`, `confidence`, `age`                                    |
-| `MEMINI_TIMEOUT_MS`              | `30000`                 | per-request timeout                                                                           |
-| `MEMINI_FALLBACK`                | on                      | `0`/`false` surfaces errors instead of degrading silently                                     |
-| `MEMINI_API_KEY`                 | —                       | bearer token, if memini needs auth (sent as `Authorization: Bearer …`; alias: `MEMINI_TOKEN`) |
-| `MEMINI_REQUIRE_HTTPS`           | —                       | `1` refuses to send the token over plaintext HTTP                                             |
-
-Unset, the namespace is derived from the working-directory basename and sent as
-the `X-Memini-Namespace` header — set it to share one memory pool with your
+| Env var                          | Default                          | Purpose                                                                                       |
+| -------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------- |
+| `MEMINI_BASE_URL`                | `http://localhost:8080`          | memini REST base URL (alias: `MEMINI_URL`)                                                    |
+| `MEMINI_NAMESPACE`               | git repo name, else cwd basename | project the memory is scoped to (`X-Memini-Namespace`)                                        |
+| `MEMINI_HOME`                    | unset                            | caller's personal namespace, sent as `X-Memini-Home`; unset = no home leg                     |
+| `MEMINI_RECALL`                  | on                               | `0`/`false` disables recall-before-turn                                                       |
+| `MEMINI_CAPTURE`                 | on                               | `0`/`false` disables capture-after-turn                                                       |
+| `MEMINI_RECALL_LIMIT`            | `3`                              | max memories injected per turn                                                                |
+| `MEMINI_INJECT_RECALL_MAX_TOK`   | `0`                              | hard ceiling on recall-block tokens (`0` = unbounded); the tail is dropped with a footer      |
+| `MEMINI_INJECT_RECALL_MIN_SCORE` | `0`                              | fused-score floor (>=) sent as `min_score` to `/v1/search`                                    |
+| `MEMINI_INJECT_LABELS`           | —                                | comma-separated bullet labels: `tier`, `confidence`, `age`                                    |
+| `MEMINI_TIMEOUT_MS`              | `30000`                          | per-request timeout                                                                           |
+| `MEMINI_FALLBACK`                | on                               | `0`/`false` surfaces errors instead of degrading silently                                     |
+| `MEMINI_API_KEY`                 | —                                | bearer token, if memini needs auth (sent as `Authorization: Bearer …`; alias: `MEMINI_TOKEN`) |
+| `MEMINI_REQUIRE_HTTPS`           | —                                | `1` refuses to send the token over plaintext HTTP                                             |
+
+Unset, the namespace is derived from the git repo (remote name, then toplevel
+basename), falling back to the working-directory basename, and sent as the
+`X-Memini-Namespace` header — set it to share one memory pool with your
 other agents (Claude Code, opencode, …).
 
+### Commands
+
+| Command            | What it does                                                                    |
+| ------------------ | ------------------------------------------------------------------------------- |
+| `memini:status`    | Effective settings, the resolved namespace **and where it came from**, warnings |
+| `memini:namespace` | Show, set, or clear the namespace override for this project                     |
+
+`memini:status` exists because a list of values is not enough to debug a namespace
+problem. It shows provenance (`<- env` vs `(default)`), so a `MEMINI_NAMESPACE`
+exported once from a shell profile — which pins _every_ repo on the machine to one
+namespace — shows up as a warning rather than as a mystery. Secrets are redacted.
+
+### The namespace override
+
+```
+memini:namespace              # show the namespace and where it came from
+memini:namespace acme/api     # override it for this project
+memini:namespace --clear      # back to automatic resolution
+```
+
+Precedence is **override > `MEMINI_NAMESPACE` > config file > git > cwd**. The
+override deliberately beats the environment: a globally exported
+`MEMINI_NAMESPACE` is exactly the problem an override exists to solve, so if the
+environment won, the command would silently do nothing on the machines that need
+it.
+
+The override is stored in `~/.config/memini/overrides.json` and shared with every
+other memini client, so one set in Claude Code applies here too, and `memini
+doctor` reports the same value. See
+[env-vars](../../docs/reference/env-vars.md#the-overrides-file) for the format.
+
+Unlike the Claude Code plugin, setting an override here takes effect immediately —
+the namespace is re-read per request, so there is no reconnect to wait for.
+
 ### Build & test
 
 ```sh
 cd integrations/pi/plugin
 npm install
-npm run build      # tsc -> dist/index.js
-npm test           # pure-helper unit tests (tsx --test)
+npm run build      # esbuild bundle -> dist/index.js
+npm test           # bundle test (node --test) + pure-helper unit tests (tsx --test)
 ```
 
 ## Alternative: MCP wire

package/dist/index.js

@@ -158,11 +158,245 @@ function resolveNamespace(opts) {
   return { namespace, segments, source, home, homeSource };
 }
 
+// ../../../packages/memini-client/src/redact.ts
+var SENSITIVE = /(^|_)(KEY|TOKEN|SECRET|PASSWORD|PASS|BEARER|DSN|CREDENTIALS?)$/i;
+function isSensitive(name) {
+  return SENSITIVE.test(name);
+}
+function redactValue(value) {
+  if (!value) return "";
+  if (value.length <= 12) return "***";
+  return `${value.slice(0, 3)}\u2026${value.slice(-4)}`;
+}
+
+// ../../../packages/memini-client/src/namespace-validate.ts
+var MAX_NAMESPACE_BYTES = 256;
+function normalizeNamespace(ns) {
+  let out = String(ns ?? "").trim();
+  out = out.replace(/^\/+|\/+$/g, "");
+  while (out.includes("//")) out = out.replace(/\/\/+/g, "/");
+  return out;
+}
+function validateNamespace(ns) {
+  if (!ns) return "namespace is empty";
+  if (Buffer.byteLength(ns, "utf8") > MAX_NAMESPACE_BYTES) {
+    return `namespace exceeds ${MAX_NAMESPACE_BYTES} bytes`;
+  }
+  if (/[\r\n]/.test(ns)) return "namespace contains a newline";
+  if (/[\x00-\x1F\x7F]/.test(ns)) return "namespace contains a control character";
+  if (/[^\x20-\x7E]/.test(ns)) return "namespace contains a non-ASCII character";
+  return null;
+}
+
+// ../../../packages/memini-client/src/override.ts
+import { execSync as execSync2 } from "node:child_process";
+import { homedir as homedir2 } from "node:os";
+import fs2 from "node:fs";
+import path2 from "node:path";
+var OVERRIDES_VERSION = 1;
+var EMPTY = { version: OVERRIDES_VERSION, overrides: {} };
+function defaultOverridesPath(env = process.env) {
+  const xdg = env["XDG_CONFIG_HOME"];
+  const base = xdg && xdg.trim() ? xdg : path2.join(homedir2(), ".config");
+  return path2.join(base, "memini", "overrides.json");
+}
+function overrideKey(cwd) {
+  const dir = cwd && cwd.trim() ? cwd : process.cwd();
+  try {
+    const top = execSync2("git rev-parse --show-toplevel", {
+      cwd: dir,
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 500
+    }).toString().trim();
+    if (top) return path2.resolve(top);
+  } catch {
+  }
+  return path2.resolve(dir);
+}
+function readOverrides(opts = {}) {
+  const p = opts.overridesPath || defaultOverridesPath(opts.env);
+  try {
+    const parsed = JSON.parse(fs2.readFileSync(p, "utf8"));
+    if (!parsed || typeof parsed !== "object" || typeof parsed.overrides !== "object") {
+      return { ...EMPTY, overrides: {} };
+    }
+    return {
+      version: typeof parsed.version === "number" ? parsed.version : OVERRIDES_VERSION,
+      overrides: parsed.overrides || {}
+    };
+  } catch {
+    return { ...EMPTY, overrides: {} };
+  }
+}
+function readOverride(cwd, opts = {}) {
+  const file = readOverrides(opts);
+  const keys = Object.keys(file.overrides);
+  if (keys.length === 0) return void 0;
+  const entry = file.overrides[overrideKey(cwd)];
+  if (!entry || typeof entry.namespace !== "string" || !entry.namespace.trim()) return void 0;
+  return entry;
+}
+function writeOverride(cwd, namespace, opts = {}) {
+  const ns = normalizeNamespace(namespace);
+  const bad = validateNamespace(ns);
+  if (bad) throw new Error(`invalid namespace ${JSON.stringify(namespace)}: ${bad}`);
+  const p = opts.overridesPath || defaultOverridesPath(opts.env);
+  const file = readOverrides(opts);
+  const entry = {
+    namespace: ns,
+    setAt: (opts.now ? opts.now() : /* @__PURE__ */ new Date()).toISOString()
+  };
+  file.version = OVERRIDES_VERSION;
+  file.overrides[overrideKey(cwd)] = entry;
+  fs2.mkdirSync(path2.dirname(p), { recursive: true });
+  fs2.writeFileSync(p, JSON.stringify(file, null, 2) + "\n");
+  return entry;
+}
+function clearOverride(cwd, opts = {}) {
+  const p = opts.overridesPath || defaultOverridesPath(opts.env);
+  const file = readOverrides(opts);
+  const key = overrideKey(cwd);
+  if (!(key in file.overrides)) return false;
+  delete file.overrides[key];
+  try {
+    fs2.mkdirSync(path2.dirname(p), { recursive: true });
+    fs2.writeFileSync(p, JSON.stringify(file, null, 2) + "\n");
+  } catch {
+    return false;
+  }
+  return true;
+}
+
+// ../../../packages/memini-client/src/session.ts
+var SESSION_CWD_TTL_MS = 6 * 60 * 60 * 1e3;
+
+// ../../../packages/memini-client/src/settings.ts
+var CLIENT_KNOBS = [
+  // Connection
+  { name: "MEMINI_BASE_URL", kind: "string", default: "http://localhost:8080", usedBy: "hooks + MCP", description: "memini base URL (alias: MEMINI_URL)" },
+  { name: "MEMINI_MCP_URL", kind: "string", default: "${MEMINI_BASE_URL}/mcp", usedBy: "MCP", description: "MCP endpoint; derived from the base URL unless set" },
+  { name: "MEMINI_API_KEY", kind: "string", default: "", usedBy: "hooks + MCP", description: "bearer token sent to the server (alias: MEMINI_TOKEN)" },
+  { name: "MEMINI_REQUIRE_HTTPS", kind: "bool", default: "0", usedBy: "hooks + MCP", description: "refuse to send a bearer token over plaintext HTTP" },
+  // Namespace
+  { name: "MEMINI_NAMESPACE", kind: "string", default: "(auto: git/cwd)", usedBy: "hooks + MCP", description: "pin the namespace; overrides git and directory detection" },
+  { name: "MEMINI_NAMESPACE_SCOPE", kind: "string", default: "repo", usedBy: "hooks", description: "owner-repo derives owner-repo slugs from the git remote" },
+  { name: "MEMINI_AGENT", kind: "string", default: "", usedBy: "hooks + MCP", description: "nest the namespace under a per-agent segment" },
+  { name: "MEMINI_HOME", kind: "string", default: "", usedBy: "hooks + MCP", description: 'personal namespace; required for visibility:"personal" writes' },
+  // Capture
+  { name: "MEMINI_CAPTURE_TURNS", kind: "bool", default: "on", usedBy: "hooks", description: "capture each user\u2192assistant turn as episodic memory" },
+  { name: "MEMINI_SESSION_DIGEST", kind: "bool", default: "on", usedBy: "hooks", description: "record session digests (files edited, commands run); 0 to keep memory to durable facts only" },
+  { name: "MEMINI_INLINE_EXTRACT", kind: "bool", default: "on", usedBy: "hooks", description: "inject the memory-save directive at SessionStart" },
+  { name: "MEMINI_AUTO_SAVE", kind: "bool", default: "on", usedBy: "hooks", description: "periodic auto-save nudge on Stop" },
+  { name: "MEMINI_AUTO_SAVE_INTERVAL", kind: "int", default: "10", usedBy: "hooks", description: "user messages between auto-save nudges" },
+  // Injection budgets
+  { name: "MEMINI_INJECT_BRIEFING_PINNED", kind: "int", default: "5", usedBy: "hooks", description: "max pinned memories at SessionStart (0 disables)" },
+  { name: "MEMINI_INJECT_BRIEFING_FACTS", kind: "int", default: "5", usedBy: "hooks", description: "max durable facts at SessionStart (0 disables)" },
+  { name: "MEMINI_INJECT_BRIEFING_PROCEDURES", kind: "int", default: "5", usedBy: "hooks", description: "max procedural how-tos at SessionStart (0 disables)" },
+  { name: "MEMINI_INJECT_BRIEFING_RECENT", kind: "int", default: "3", usedBy: "hooks", description: "max recent episodic entries at SessionStart (0 disables)" },
+  { name: "MEMINI_INJECT_BRIEFING_MAX_TOK", kind: "int", default: "uncapped", usedBy: "hooks", description: "token ceiling on the SessionStart briefing" },
+  { name: "MEMINI_INJECT_PRETOOL_ITEMS", kind: "int", default: "3", usedBy: "hooks", description: "max hits surfaced per file on PreToolUse" },
+  { name: "MEMINI_INJECT_PRETOOL_MAX_TOK", kind: "int", default: "uncapped", usedBy: "hooks", description: "token ceiling per file on PreToolUse" },
+  { name: "MEMINI_INJECT_PRETOOL_MIN_SCORE", kind: "float", default: "0", usedBy: "hooks", description: "relevance floor for PreToolUse hits" },
+  { name: "MEMINI_INJECT_PRETOOL_TOOLS", kind: "list", default: "Read|Write|Edit|Glob|Grep", usedBy: "hooks", description: "tool allowlist for PreToolUse recall" },
+  { name: "MEMINI_INJECT_LABELS", kind: "list", default: "", usedBy: "hooks", description: "annotate injected bullets: tier, confidence, age, reason" },
+  // Diagnostics
+  { name: "MEMINI_DEBUG", kind: "bool", default: "0", usedBy: "hooks + MCP", description: "verbose hook logging to stderr" }
+];
+function describeKnob(spec, env) {
+  const raw = env[spec.name];
+  const set = raw != null && raw !== "";
+  const sensitive = isSensitive(spec.name);
+  let value;
+  if (set) {
+    value = sensitive ? redactValue(raw) : raw;
+  } else {
+    value = spec.default === "" ? "(unset)" : spec.default;
+  }
+  return {
+    name: spec.name,
+    value,
+    source: set ? "env" : "default",
+    isDefault: !set,
+    sensitive,
+    usedBy: spec.usedBy,
+    description: spec.description
+  };
+}
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+function isPlaintextToNonLoopback(baseUrl) {
+  try {
+    const u = new URL(baseUrl);
+    return u.protocol === "http:" && !LOOPBACK.has(u.hostname.replace(/^\[|\]$/g, "").toLowerCase());
+  } catch {
+    return false;
+  }
+}
+function describeSettings(opts) {
+  const env = opts.env || process.env;
+  const cwd = opts.cwd;
+  const override = readOverride(cwd, { env, overridesPath: opts.overridesPath });
+  const withoutOverride = opts.resolve(env, { ignoreOverride: true });
+  const envSansPin = { ...env };
+  delete envSansPin["MEMINI_NAMESPACE"];
+  const derived = opts.resolve(envSansPin, { ignoreOverride: true });
+  const effective = override ? override.namespace : withoutOverride.namespace;
+  const source = override ? "override" : withoutOverride.source;
+  const home = (env["MEMINI_HOME"] || "").trim() || void 0;
+  const settings = CLIENT_KNOBS.map((k) => describeKnob(k, env));
+  const warnings = [];
+  if (override) {
+    warnings.push({
+      level: "note",
+      code: "override-active",
+      message: `namespace is overridden to "${override.namespace}" for this project (set ${override.setAt}); without it this project would use "${withoutOverride.namespace}".`,
+      fix: "Run the namespace command with --clear to return to automatic resolution."
+    });
+  }
+  const pin = (env["MEMINI_NAMESPACE"] || "").trim();
+  if (pin && !override && derived.namespace && derived.namespace !== pin) {
+    warnings.push({
+      level: "warn",
+      code: "global-namespace-pin",
+      message: `MEMINI_NAMESPACE is set to "${pin}", which pins EVERY project on this machine to one namespace. This project would otherwise resolve to "${derived.namespace}". If this variable is exported from a shell rc (or a fish universal variable), every repo you work in is sharing one memory pool.`,
+      fix: `Unset MEMINI_NAMESPACE and let each repo resolve on its own, or set a per-project override instead.`
+    });
+  }
+  if (!home) {
+    warnings.push({
+      level: "warn",
+      code: "home-unset",
+      message: 'MEMINI_HOME is unset: there is no personal namespace, so visibility:"personal" writes will error and no personal leg merges into recall.',
+      fix: "Export MEMINI_HOME=personal/<you>."
+    });
+  }
+  const baseUrl = env["MEMINI_BASE_URL"] || env["MEMINI_URL"] || "http://localhost:8080";
+  const token = env["MEMINI_API_KEY"] || env["MEMINI_TOKEN"] || "";
+  if (token && isPlaintextToNonLoopback(baseUrl)) {
+    warnings.push({
+      level: "warn",
+      code: "plaintext-bearer",
+      message: `a bearer token is configured for plaintext HTTP to ${baseUrl}; the token and your memory payloads can be observed on the network.`,
+      fix: "Use HTTPS, or tunnel over SSH. Set MEMINI_REQUIRE_HTTPS=1 to make this an error."
+    });
+  }
+  return {
+    cwd,
+    namespace: { effective, source, override, withoutOverride, derived, home },
+    settings,
+    paths: {
+      overrides: opts.overridesPath || defaultOverridesPath(env),
+      cache: opts.cacheDir
+    },
+    warnings
+  };
+}
+
 // src/index.ts
 var DEFAULT_BASE_URL = "http://localhost:8080";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_RECALL_LIMIT = 3;
 var DEFAULT_NAMESPACE = "pi";
+var STATUS_TIMEOUT_MS = 4e3;
 var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
 function envBool(value, fallback) {
   if (value === void 0 || value === null || value === "") return fallback;
@@ -200,22 +434,33 @@ function deriveNamespace(cwd) {
   const base = cwd.replace(/[\\/]+$/, "").split(/[\\/]/).pop() || "";
   return sanitizeNamespace(base);
 }
-function resolveConfig(env, cwd) {
+function resolverSource(source) {
+  return source === "git" ? "git-remote" : source;
+}
+function resolveProjectNamespace(env, cwd, opts = {}) {
   const e = env || {};
+  if (!opts.ignoreOverride && cwd) {
+    const override = readOverride(cwd, { env: e });
+    if (override) return { namespace: override.namespace, source: "override" };
+  }
   const nsEnv = (e.MEMINI_NAMESPACE || "").trim();
-  let namespace;
   if (nsEnv) {
-    namespace = nsEnv;
-  } else if (cwd) {
-    const { namespace: resolvedNs } = resolveNamespace({
+    return { namespace: nsEnv, source: "env" };
+  }
+  if (cwd) {
+    const { namespace: resolvedNs, source } = resolveNamespace({
       cwd,
       env: e,
       integration: "pi"
     });
-    namespace = sanitizeNamespacePath(resolvedNs) || DEFAULT_NAMESPACE;
-  } else {
-    namespace = DEFAULT_NAMESPACE;
+    const sanitized = sanitizeNamespacePath(resolvedNs);
+    if (sanitized) return { namespace: sanitized, source: resolverSource(source) };
   }
+  return { namespace: DEFAULT_NAMESPACE, source: "default" };
+}
+function resolveConfig(env, cwd) {
+  const e = env || {};
+  const { namespace } = resolveProjectNamespace(e, cwd);
   const recall_limit = (() => {
     const n = Number(e.MEMINI_RECALL_LIMIT);
     return Number.isFinite(n) && n >= 0 ? n : DEFAULT_RECALL_LIMIT;
@@ -223,7 +468,7 @@ function resolveConfig(env, cwd) {
   const homeEnv = (e.MEMINI_HOME || "").trim();
   return {
     base_url: e.MEMINI_BASE_URL || e.MEMINI_URL || DEFAULT_BASE_URL,
-    // namespace is already resolved above (raw-trimmed on the env path,
+    // namespace is already resolved above (verbatim on the override/env paths,
     // per-segment sanitized on the resolver path); re-sanitizing here would
     // flatten tenant separators.
     namespace: namespace || DEFAULT_NAMESPACE,
@@ -328,10 +573,10 @@ function createClient(cfg, warn) {
     if (cfg.home) h["X-Memini-Home"] = cfg.home;
     return h;
   }
-  async function request(method, path2, body) {
+  async function request(method, path3, body) {
     guard(baseUrl, secret);
     try {
-      const res = await fetch(`${baseUrl}${path2}`, {
+      const res = await fetch(`${baseUrl}${path3}`, {
         method,
         headers: headers(body ? { "Content-Type": "application/json" } : void 0),
         body: body ? JSON.stringify(body) : void 0,
@@ -339,11 +584,11 @@ function createClient(cfg, warn) {
       });
       if (!res.ok) {
         if (cfg.fallback_on_error) {
-          warn(`memini ${method} ${path2} failed: ${res.status}`);
+          warn(`memini ${method} ${path3} failed: ${res.status}`);
           return null;
         }
         const text = await res.text().catch(() => "");
-        throw new Error(`memini ${method} ${path2} failed: ${res.status} ${text}`);
+        throw new Error(`memini ${method} ${path3} failed: ${res.status} ${text}`);
       }
       return await res.json().catch(() => ({ ok: true }));
     } catch (error) {
@@ -352,10 +597,31 @@ function createClient(cfg, warn) {
       return null;
     }
   }
+  async function requestResult(method, path3, body) {
+    try {
+      guard(baseUrl, secret);
+      const res = await fetch(`${baseUrl}${path3}`, {
+        method,
+        headers: headers(body ? { "Content-Type": "application/json" } : void 0),
+        body: body ? JSON.stringify(body) : void 0,
+        signal: AbortSignal.timeout(cfg.timeout_ms)
+      });
+      if (!res.ok) {
+        const detail = (await res.text().catch(() => "")).trim();
+        warn(`memini ${method} ${path3} failed: ${res.status} ${detail}`);
+        return { ok: false, error: detail || `HTTP ${res.status}` };
+      }
+      return { ok: true, data: await res.json().catch(() => ({})) };
+    } catch (error) {
+      warn(`memini: ${String(error)}`);
+      return { ok: false, error: String(error) };
+    }
+  }
   return {
-    postJson: (path2, payload) => request("POST", path2, payload),
-    getJson: (path2) => request("GET", path2),
-    deleteJson: (path2) => request("DELETE", path2)
+    postJson: (path3, payload) => request("POST", path3, payload),
+    getJson: (path3) => request("GET", path3),
+    deleteJson: (path3) => request("DELETE", path3),
+    postJsonResult: (path3, payload) => requestResult("POST", path3, payload)
   };
 }
 function meminiListPath(args) {
@@ -394,8 +660,223 @@ function buildTurnContent(userText, assistantText) {
 
 ${String(assistantText).slice(0, 3e3)}`;
 }
-var TOOL_NAMES = ["memory_recall", "memory_list", "memory_remember", "memory_forget"];
+async function statusGet(cfg, namespace, path3, warn, quiet = false) {
+  const baseUrl = String(cfg.base_url).replace(/\/+$/, "");
+  const secret = process.env.MEMINI_API_KEY || process.env.MEMINI_TOKEN;
+  const headers = { "X-Memini-Namespace": namespace };
+  if (secret) headers.Authorization = `Bearer ${secret}`;
+  if (cfg.home) headers["X-Memini-Home"] = cfg.home;
+  try {
+    const res = await fetch(`${baseUrl}${path3}`, {
+      method: "GET",
+      headers,
+      signal: AbortSignal.timeout(STATUS_TIMEOUT_MS)
+    });
+    if (!res.ok) {
+      if (!quiet) warn(`GET ${path3} -> ${res.status}`);
+      return null;
+    }
+    return await res.json();
+  } catch (error) {
+    if (!quiet) warn(`GET ${path3} failed: ${String(error)}`);
+    return null;
+  }
+}
+async function fetchServer(cfg, namespace, warn) {
+  const started = Date.now();
+  const readSet = await statusGet(cfg, namespace, "/v1/namespaces/read-set", warn);
+  const out = {
+    reachable: readSet != null,
+    latencyMs: Date.now() - started,
+    readSet
+  };
+  const health = await statusGet(cfg, namespace, "/healthz?verbose=1", warn, true);
+  if (health) {
+    out.version = health.version;
+    out.status = health.status;
+    out.deps = health.deps;
+  } else {
+    out.healthExposed = false;
+  }
+  return out;
+}
+var pad = (s, n) => String(s).padEnd(n);
+function renderStatus(settings, cfg, server) {
+  const ns = settings.namespace;
+  const L = [];
+  L.push(`memini \u2014 effective settings (pi)`);
+  L.push(`cwd: ${settings.cwd}`);
+  L.push("");
+  L.push(`NAMESPACE`);
+  L.push(`  ${pad("effective", 28)} ${pad(ns.effective, 34)} <- ${ns.source}`);
+  if (ns.override) {
+    L.push(
+      `  ${pad("without the override", 28)} ${pad(ns.withoutOverride.namespace, 34)} <- ${ns.withoutOverride.source}`
+    );
+  }
+  if (ns.derived.namespace !== ns.effective) {
+    L.push(`  ${pad("git/cwd would give", 28)} ${pad(ns.derived.namespace, 34)} <- ${ns.derived.source}`);
+  }
+  L.push(`  ${pad("home (personal)", 28)} ${ns.home || "(unset)"}`);
+  L.push("");
+  const groups = [
+    ["CONNECTION", ["MEMINI_BASE_URL", "MEMINI_API_KEY", "MEMINI_REQUIRE_HTTPS"]],
+    ["NAMESPACE INPUTS", ["MEMINI_NAMESPACE", "MEMINI_NAMESPACE_SCOPE", "MEMINI_AGENT", "MEMINI_HOME"]]
+  ];
+  for (const [group, names] of groups) {
+    const rows = (settings.settings || []).filter((s) => names.includes(s.name));
+    if (!rows.length) continue;
+    L.push(group);
+    for (const r of rows) {
+      const origin = r.source === "env" ? `<- env` : `(default)`;
+      L.push(`  ${pad(r.name.replace(/^MEMINI_/, "").toLowerCase(), 28)} ${pad(r.value, 34)} ${origin}`);
+    }
+    L.push("");
+  }
+  const secret = process.env.MEMINI_API_KEY || process.env.MEMINI_TOKEN || "";
+  L.push(`EXTENSION`);
+  L.push(`  ${pad("recall", 28)} ${cfg.recall ? "on" : "off"}`);
+  L.push(`  ${pad("capture", 28)} ${cfg.capture ? "on" : "off"}`);
+  L.push(`  ${pad("recall_limit", 28)} ${cfg.recall_limit}`);
+  L.push(`  ${pad("timeout_ms", 28)} ${cfg.timeout_ms}`);
+  L.push(`  ${pad("bearer", 28)} ${secret ? redactValue(secret) : "(none)"}`);
+  L.push("");
+  L.push(`SERVER`);
+  if (!server.reachable) {
+    L.push(`  ${pad("reachable", 28)} NO \u2014 could not reach ${cfg.base_url}`);
+  } else {
+    const ver = server.version ? `, ${server.version}` : "";
+    L.push(`  ${pad("reachable", 28)} yes (${server.latencyMs}ms${ver})`);
+    const d = server.deps || {};
+    if (d.store) L.push(`  ${pad("store", 28)} ${d.store.ok ? "ok" : `FAILING \u2014 ${d.store.last_error || "?"}`}`);
+    if (d.embedder) {
+      L.push(`  ${pad("embedder", 28)} ${d.embedder.ok ? "ok" : `FAILING \u2014 ${d.embedder.last_error || "?"}`}`);
+    }
+    if (server.healthExposed === false) {
+      L.push(`  ${pad("dependency detail", 28)} unavailable (/healthz not routed \u2014 normal behind an ingress)`);
+    }
+  }
+  L.push("");
+  if (server.readSet?.entries?.length) {
+    L.push(`READ SET for "${ns.effective}" \u2014 where a plain recall looks`);
+    L.push(`  ${pad("NAMESPACE", 34)} ${pad("ORIGIN", 12)} TIERS`);
+    for (const e of server.readSet.entries) {
+      const tiers = Array.isArray(e.tiers) && e.tiers.length ? e.tiers.join(",") : "all";
+      L.push(`  ${pad(e.namespace, 34)} ${pad(e.origin, 12)} ${tiers}`);
+    }
+    L.push("");
+  }
+  L.push(`PATHS`);
+  L.push(`  ${pad("overrides", 28)} ${settings.paths.overrides}`);
+  L.push("");
+  if (settings.warnings.length) {
+    L.push(`WARNINGS`);
+    for (const w of settings.warnings) {
+      L.push(`  [${w.level === "warn" ? "!" : "i"}] ${w.code}: ${w.message}`);
+      if (w.fix) L.push(`      fix: ${w.fix}`);
+    }
+  } else {
+    L.push(`No problems detected.`);
+  }
+  return L.join("\n");
+}
+function registerMeminiCommands(pi, cfg, warn) {
+  const show = (content) => {
+    pi.sendMessage({ customType: "memini-status", content, display: true });
+  };
+  pi.registerCommand("memini:status", {
+    description: "Show memini's effective settings: namespace + provenance, connection, server read set",
+    handler: async (_args, ctx) => {
+      try {
+        const cwd = ctx.cwd || process.cwd();
+        const settings = describeSettings({
+          cwd,
+          env: process.env,
+          // Hand describeSettings THIS harness's resolver, so what it reports is
+          // what the extension actually does. The opts pass-through carries
+          // ignoreOverride, which is how the counterfactual lines see past an
+          // override (it lives in a file, so no env-doctoring would remove it).
+          resolve: (env, o) => resolveProjectNamespace(env, cwd, o)
+        });
+        const server = await fetchServer(cfg, settings.namespace.effective, warn);
+        show(renderStatus(settings, cfg, server));
+      } catch (error) {
+        ctx.ui.notify(`memini: status failed: ${String(error)}`, "error");
+      }
+    }
+  });
+  pi.registerCommand("memini:namespace", {
+    description: "Show, set, or --clear the memini namespace override for this project",
+    handler: async (args, ctx) => {
+      try {
+        const cwd = ctx.cwd || process.cwd();
+        const arg = String(args || "").trim();
+        const before = resolveProjectNamespace(process.env, cwd);
+        if (!arg) {
+          const current = readOverride(cwd, { env: process.env });
+          const out = [
+            `namespace: ${before.namespace}  (source: ${before.source})`,
+            `project:   ${overrideKey(cwd)}`,
+            ``
+          ];
+          if (current) {
+            out.push(`An override is active (set ${current.setAt}).`);
+            out.push(`Clear it with:  /memini:namespace --clear`);
+          } else {
+            out.push(`No override \u2014 resolving automatically.`);
+            out.push(`Set one with:  /memini:namespace <namespace>`);
+          }
+          out.push(`Overrides file: ${defaultOverridesPath(process.env)}`);
+          show(out.join("\n"));
+          return;
+        }
+        if (arg === "--clear" || arg === "clear") {
+          const removed = clearOverride(cwd, { env: process.env });
+          if (!removed) {
+            show(`No override was set for ${overrideKey(cwd)} \u2014 nothing to clear.`);
+            return;
+          }
+          const after2 = resolveProjectNamespace(process.env, cwd);
+          cfg.namespace = after2.namespace;
+          show(
+            [
+              `namespace override cleared: ${before.namespace} -> ${after2.namespace}  (source: ${after2.source})`,
+              ``,
+              `Recall and capture use the new namespace from the next turn.`
+            ].join("\n")
+          );
+          return;
+        }
+        const ns = normalizeNamespace(arg);
+        const bad = validateNamespace(ns);
+        if (bad) {
+          ctx.ui.notify(`memini: invalid namespace ${JSON.stringify(arg)}: ${bad}`, "error");
+          return;
+        }
+        writeOverride(cwd, ns, { env: process.env });
+        const after = resolveProjectNamespace(process.env, cwd);
+        cfg.namespace = after.namespace;
+        show(
+          [
+            `namespace override set: ${before.namespace} -> ${after.namespace}`,
+            `project: ${overrideKey(cwd)}`,
+            ``,
+            `The override wins over MEMINI_NAMESPACE. Recall and capture use it from the next turn.`
+          ].join("\n")
+        );
+      } catch (error) {
+        ctx.ui.notify(`memini: namespace failed: ${String(error)}`, "error");
+      }
+    }
+  });
+}
+var TOOL_NAMES = ["memory_recall", "memory_briefing", "memory_list", "memory_remember", "memory_forget"];
 var VALID_TIERS = ["working", "episodic", "semantic", "procedural"];
+var VALID_SCOPES = ["project", "full", "everywhere"];
+function briefingPath(args) {
+  const scope = String(args?.scope || "").trim();
+  return VALID_SCOPES.includes(scope) ? `/v1/namespaces/briefing?scope=${encodeURIComponent(scope)}` : "/v1/namespaces/briefing";
+}
 function sessionIdOf(ctx) {
   try {
     return String(ctx?.sessionManager?.getSessionId?.() ?? "");
@@ -419,6 +900,11 @@ function meminiExtension(pi) {
   };
   const cfg = resolveConfig(process.env, process.cwd());
   const client = createClient(cfg, warn);
+  try {
+    if (typeof pi.registerCommand === "function") registerMeminiCommands(pi, cfg, warn);
+  } catch (error) {
+    warn(`command registration skipped: ${String(error)}`);
+  }
   const pendingUser = /* @__PURE__ */ new Map();
   const captured = /* @__PURE__ */ new Set();
   const injectedBySession = /* @__PURE__ */ new Map();
@@ -506,31 +992,70 @@ function meminiExtension(pi) {
       description: 'Match memories whose top-level metadata contains each key=value pair, e.g. {"category":"bug_fixes"}.'
     })
   );
+  const Scope = Type.Optional(
+    Type.String({
+      enum: VALID_SCOPES,
+      description: "How wide to read: 'project' = just this project's own memories; 'full' (default) = project plus inherited context (ancestors, your personal namespace, links); 'everywhere' = full plus nested sub-projects."
+    })
+  );
   pi.registerTool({
     name: "memory_recall",
     label: "Recall memory",
-    description: `Recall relevant memories from long-term memory (memini) via hybrid (semantic + keyword) search. Call before starting work that may have history: editing an unfamiliar file, debugging a recurring issue, or when asked what's known about something. Empty results mean nothing is known \u2014 proceed from first principles, never invent a remembered fact. A degraded:"keyword_only" field in the result means semantic search was unavailable and results came from keyword matching alone \u2014 treat as incomplete, not exhaustive.`,
+    description: `Search prior context in long-term memory (memini) via hybrid (semantic + keyword) retrieval, ranked by relevance, recency, and corroboration. Call BEFORE starting work that may have history: editing an unfamiliar file, debugging a recurring issue, making a non-obvious decision, or when asked what's known about something. Prefer a short descriptive query ('JWT auth setup'). scope picks how wide to read: 'project' (just this project), 'full' (default: project plus inherited ancestor/personal/link context), or 'everywhere' (full plus nested sub-projects). Each result's namespace/from fields are provenance, not a choice \u2014 an absent 'from' means this project's own memory, otherwise it names the ancestor or personal namespace the memory came from; read them to learn where knowledge lives, never construct a namespace path. Empty results mean nothing is known \u2014 proceed from first principles, never invent a remembered fact. A degraded:"keyword_only" field in the result means semantic search was unavailable and results came from keyword matching alone \u2014 treat as incomplete, not exhaustive.`,
     parameters: Type.Object({
       query: Type.String({ description: "What to search for" }),
       limit: Type.Optional(Type.Number({ description: "Max results (default 3)" })),
       tags: Tags,
-      metadata: Metadata
+      metadata: Metadata,
+      scope: Scope
     }),
     async execute(_toolCallId, params) {
       const body = { query: params.query, limit: params.limit || DEFAULT_RECALL_LIMIT };
       if (params.tags?.length) body.tags = params.tags;
       if (params.metadata && Object.keys(params.metadata).length) body.metadata = params.metadata;
+      if (VALID_SCOPES.includes(params.scope)) body.scope = params.scope;
       const res = await client.postJson("/v1/search", body);
-      const results = (res?.results || []).map((r) => ({
-        id: r?.memory?.id || "",
-        content: r?.memory?.content || "",
-        summary: r?.memory?.summary || "",
-        tier: r?.memory?.tier || "",
-        score: typeof r?.score === "number" ? r.score : 0
-      }));
+      const results = (res?.results || []).map((r) => {
+        const mem = r?.memory || {};
+        const out = {
+          id: mem.id || "",
+          content: mem.content || "",
+          summary: mem.summary || "",
+          tier: mem.tier || "",
+          score: typeof r?.score === "number" ? r.score : 0
+        };
+        if (mem.namespace) out.namespace = mem.namespace;
+        if (r?.from) out.from = r.from;
+        return out;
+      });
       return text(res?.degraded ? { results, degraded: res.degraded, note: res.note } : { results });
     }
   });
+  pi.registerTool({
+    name: "memory_briefing",
+    label: "Session briefing",
+    description: "Layered session-start briefing for this project from long-term memory (memini) \u2014 pinned context, durable facts, how-to procedures, and recent activity \u2014 in one query-less call. Call it when a session opens to orient yourself; prefer it over broad recall queries at session start. The scope_header line ('Scope: acme/phoenix/api \u2190 acme/phoenix(3) \u2190 acme(4) \u2190 personal(2)') spells out the ancestor chain you inherit from \u2014 read it instead of guessing namespace paths, and name one of those ancestors as memory_remember's visibility to share a fact up that chain. scope='everywhere' also briefs nested sub-projects.",
+    parameters: Type.Object({ scope: Scope }),
+    async execute(_toolCallId, params) {
+      const res = await client.getJson(briefingPath(params));
+      if (!res) return text({ briefing: null, error: "memini unavailable" });
+      const section = (items) => (items || []).map((b) => {
+        const mem = b?.memory || {};
+        const out = { id: mem.id || "", content: mem.content || "", tier: mem.tier || "" };
+        if (mem.namespace) out.namespace = mem.namespace;
+        if (b?.from) out.from = b.from;
+        return out;
+      });
+      return text({
+        namespace: res.namespace || "",
+        scope_header: res.scope_header || "",
+        pinned: section(res.pinned),
+        facts: section(res.facts),
+        procedures: section(res.procedures),
+        recent: section(res.recent)
+      });
+    }
+  });
   pi.registerTool({
     name: "memory_list",
     label: "List memory",
@@ -560,7 +1085,7 @@ function meminiExtension(pi) {
   pi.registerTool({
     name: "memory_remember",
     label: "Remember",
-    description: "Store a durable fact, decision, or preference in long-term memory (memini). Call proactively when the user says 'remember this', after an architectural decision (capture the why), or after discovering a non-obvious bug or convention. Keep memories atomic \u2014 one self-contained fact per call. Don't store what's already in project docs or trivially recoverable from code. To correct an existing memory, pass its id \u2014 the write updates it in place.",
+    description: "Store a durable fact, decision, or preference in long-term memory (memini). Call proactively when the user says 'remember this', after an architectural decision (capture the why), or after discovering a non-obvious bug or convention. Keep memories atomic \u2014 one self-contained fact per call. Don't store what's already in project docs or trivially recoverable from code. To correct an existing memory, pass its id \u2014 the write updates it in place. visibility decides who should know: 'project' (default) keeps it here; 'personal' follows the user everywhere; or name an ancestor from the memory_briefing Scope line to share it up that chain. reinforced=true in the result means the fact was ALREADY KNOWN: no new memory was created, the existing one was strengthened, and `id` names that pre-existing memory rather than anything you just wrote \u2014 do not report it to the user as a new save.",
     parameters: Type.Object({
       content: Type.String({ description: "The fact to remember \u2014 atomic and self-contained." }),
       id: Type.Optional(
@@ -582,6 +1107,11 @@ function meminiExtension(pi) {
         Type.String({
           description: "Optional topic bucket stored as metadata.category (e.g. bug_fixes, architecture_decisions) for browsing by subject later."
         })
+      ),
+      visibility: Type.Optional(
+        Type.String({
+          description: "Who should remember this: 'project' (default, this project only), 'personal' (about the user, follows them everywhere), or an ancestor namespace name read off the memory_briefing Scope line (e.g. the team or org level) to share it up that chain. On a durable write an unrecognized name errors listing the valid options. Episodic/working writes always stay in the project regardless."
+        })
       )
     }),
     async execute(_toolCallId, params) {
@@ -590,8 +1120,13 @@ function meminiExtension(pi) {
       if (params.tier && VALID_TIERS.includes(params.tier)) body.tier = params.tier;
       if (params.tags?.length) body.tags = params.tags;
       if (params.category) body.metadata = { category: params.category };
-      const res = await client.postJson("/v1/memories", body);
-      return text({ id: res?.id || null, success: res != null });
+      const visibility = String(params.visibility || "").trim();
+      if (visibility) body.visibility = visibility;
+      const res = await client.postJsonResult("/v1/memories", body);
+      if (!res.ok) return text({ id: null, success: false, error: res.error });
+      const out = { id: res.data?.id || null, success: true };
+      if (res.data?.reinforced) out.reinforced = true;
+      return text(out);
     }
   });
   pi.registerTool({
@@ -611,6 +1146,7 @@ function meminiExtension(pi) {
 }
 export {
   approxTokens,
+  briefingPath,
   buildTurnContent,
   createPlaintextBearerAuthGuard,
   meminiExtension as default,
@@ -623,7 +1159,10 @@ export {
   intEnv,
   labelsEnv,
   meminiListPath,
+  registerMeminiCommands,
+  renderStatus,
   resolveConfig,
+  resolveProjectNamespace,
   sanitizeNamespace,
   sanitizeNamespacePath,
   truncate

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@eleboucher/pi-memini",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "Shared cross-session memory for the Pi coding agent, backed by a memini service.",
   "files": [
     "dist"
   ],
   "type": "module",
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --external:typebox --external:@earendil-works/pi-coding-agent --alias:@memini/namespace-resolver=../../../packages/namespace-resolver/src/index.ts --outfile=dist/index.js",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --external:typebox --external:@earendil-works/pi-coding-agent --alias:@memini/namespace-resolver=../../../packages/namespace-resolver/src/index.ts --alias:@memini/client=../../../packages/memini-client/src/index.ts --outfile=dist/index.js",
     "test": "node --test test/bundle.test.mjs && npx tsx --test test/helpers.test.ts",
     "typecheck": "tsc -p tsconfig.test.json"
   },