@eleboucher/pi-memini 0.6.12 → 0.7.2

package/dist/index.js

@@ -1,168 +1,8 @@
 // src/index.ts
 import { Type } from "typebox";
-
-// ../../../packages/namespace-resolver/src/index.ts
-import { execSync } from "node:child_process";
-import { basename } from "node:path";
-import { homedir } from "node:os";
-import fs from "node:fs";
-import path from "node:path";
-var DEFAULT_TEMPLATE = "{tenant}/{project}/{agent}";
-function defaultConfigPath() {
-  const xdg = process.env["XDG_CONFIG_HOME"];
-  const base = xdg && xdg.trim() ? xdg : path.join(homedir(), ".config");
-  return path.join(base, "memini", "config.json");
-}
-function readConfig(configPath) {
-  const p = configPath || defaultConfigPath();
-  try {
-    const raw = fs.readFileSync(p, "utf8");
-    const parsed = JSON.parse(raw);
-    return {
-      tenantRoots: Array.isArray(parsed.tenantRoots) ? parsed.tenantRoots : [],
-      template: typeof parsed.template === "string" ? parsed.template : DEFAULT_TEMPLATE,
-      overrides: parsed.overrides && typeof parsed.overrides === "object" ? parsed.overrides : {},
-      found: true
-    };
-  } catch {
-    return { tenantRoots: [], template: DEFAULT_TEMPLATE, overrides: {}, found: false };
-  }
-}
-function gitOut(args, dir) {
-  try {
-    return execSync(`git ${args}`, {
-      cwd: dir,
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 500
-    }).toString().trim();
-  } catch {
-    return "";
-  }
-}
-function repoNameFromRemote(url) {
-  if (typeof url !== "string" || !url) return null;
-  const cleaned = url.trim().replace(/\/+$/, "").replace(/\.git$/i, "");
-  if (!cleaned) return null;
-  const scpMatch = cleaned.match(/^[^/:]+:[^/]/);
-  const p = scpMatch ? cleaned.slice(scpMatch[0].indexOf(":") + 1) : cleaned;
-  const segs = p.split("/").filter(Boolean);
-  return segs.length ? segs[segs.length - 1] : null;
-}
-function repoSlugFromRemote(url) {
-  if (typeof url !== "string" || !url) return null;
-  const cleaned = url.trim().replace(/\/+$/, "").replace(/\.git$/i, "");
-  if (!cleaned) return null;
-  const scpMatch = cleaned.match(/^[^/:]+:[^/]/);
-  const p = scpMatch ? cleaned.slice(scpMatch[0].indexOf(":") + 1) : cleaned;
-  const segs = p.split("/").filter(Boolean);
-  if (!segs.length) return null;
-  if (segs.length === 1) return segs[0];
-  const owner = segs[segs.length - 2].replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-  const repo = segs[segs.length - 1];
-  return owner ? `${owner}-${repo}` : repo;
-}
-function expandTilde(p) {
-  if (p === "~") return homedir();
-  if (p.startsWith("~/")) return path.join(homedir(), p.slice(2));
-  return p;
-}
-function sanitizeSegment(s) {
-  return s.replace(/[^A-Za-z0-9._/-]+/g, "-").replace(/^-+|-+$/g, "");
-}
-function resolveTenant(cwd, config) {
-  const resolvedCwd = path.resolve(cwd);
-  for (const root of config.tenantRoots) {
-    if (!root || typeof root !== "object") continue;
-    if (typeof root.path !== "string" || !root.path) continue;
-    const rootPath = path.resolve(expandTilde(root.path));
-    if (resolvedCwd === rootPath || resolvedCwd.startsWith(rootPath + path.sep)) {
-      const t = sanitizeSegment(String(root.tenant || ""));
-      if (t) return t;
-    }
-  }
-  return void 0;
-}
-function resolveProject(cwd, gitRemoteUrl, env) {
-  const ownerRepo = (env?.["MEMINI_NAMESPACE_SCOPE"] || "").trim() === "owner-repo";
-  let remote = gitRemoteUrl;
-  if (!remote) {
-    remote = gitOut("remote get-url origin", cwd);
-  }
-  if (remote) {
-    const name = ownerRepo ? repoSlugFromRemote(remote) : repoNameFromRemote(remote);
-    if (name) return sanitizeSegment(name);
-  }
-  const toplevel = gitOut("rev-parse --show-toplevel", cwd);
-  if (toplevel) return sanitizeSegment(basename(toplevel));
-  const b = basename(cwd);
-  return sanitizeSegment(b) || "default";
-}
-function resolveAgent(opts) {
-  const agent = (opts.agentId || opts.env?.["MEMINI_AGENT"] || "").trim();
-  if (!agent) return void 0;
-  return sanitizeSegment(agent);
-}
-function resolveHome(env) {
-  const home = (env["MEMINI_HOME"] || "").trim();
-  return home || void 0;
-}
-function applyTemplate(template, segments) {
-  const all = {
-    tenant: segments.tenant,
-    project: segments.project,
-    agent: segments.agent,
-    namespace: segments.namespace
-  };
-  let result = template.replace(/\{(tenant|project|agent|namespace)\}/g, (_, key) => {
-    return all[key] ?? "";
-  });
-  result = result.replace(/\/{2,}/g, "/");
-  result = result.replace(/^\/+|\/+$/g, "");
-  return result;
-}
-function resolveNamespace(opts) {
-  const env = opts.env || process.env;
-  const cwd = opts.cwd && opts.cwd.trim() ? opts.cwd : process.cwd();
-  const home = resolveHome(env);
-  const homeSource = home ? "env" : void 0;
-  const nsEnv = (env["MEMINI_NAMESPACE"] || "").trim();
-  if (nsEnv) {
-    return { namespace: nsEnv, segments: {}, source: "env", home, homeSource };
-  }
-  const config = readConfig(opts.configPath);
-  if (!config.found) {
-    const project2 = sanitizeSegment(basename(cwd));
-    return {
-      namespace: project2,
-      segments: project2 ? { project: project2 } : {},
-      source: "cwd",
-      home,
-      homeSource
-    };
-  }
-  const tenant = resolveTenant(cwd, config);
-  const project = resolveProject(cwd, opts.gitRemoteUrl, env);
-  const agent = resolveAgent(opts);
-  const override = opts.integration ? config.overrides[opts.integration] : void 0;
-  const baseNamespace = override?.namespace;
-  const segments = { tenant, project, agent, namespace: baseNamespace };
-  const template = override?.template || config.template;
-  let namespace = applyTemplate(template, segments);
-  if (!namespace) {
-    namespace = project || "default";
-  }
-  let source = "default";
-  if (tenant) source = "config";
-  else if (opts.gitRemoteUrl || gitOut("remote get-url origin", cwd)) source = "git";
-  else source = "cwd";
-  return { namespace, segments, source, home, homeSource };
-}
+import { readFileSync } from "node:fs";
 
 // ../../../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 "***";
@@ -188,216 +28,262 @@ function validateNamespace(ns) {
   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");
+// ../../../packages/memini-client/src/session.ts
+var SESSION_CWD_TTL_MS = 6 * 60 * 60 * 1e3;
+
+// ../../../packages/memini-client/src/settings.ts
+var BEHAVIOR_KNOBS = [
+  { envName: "MEMINI_CAPTURE_TURNS", wireKey: "capture_turns", kind: "bool", default: true },
+  { envName: "MEMINI_SESSION_DIGEST", wireKey: "session_digest", kind: "bool", default: true },
+  { envName: "MEMINI_INLINE_EXTRACT", wireKey: "inline_extract", kind: "bool", default: true },
+  { envName: "MEMINI_AUTO_SAVE", wireKey: "auto_save", kind: "bool", default: true },
+  { envName: "MEMINI_AUTO_SAVE_INTERVAL", wireKey: "auto_save_interval", kind: "int", default: 10 },
+  { envName: "MEMINI_AUTO_SAVE_MIN_EVENTS", wireKey: "auto_save_min_events", kind: "int", default: 3 },
+  { envName: "MEMINI_INJECT_BRIEFING_PINNED", wireKey: "inject_briefing_pinned", kind: "int", default: 5 },
+  { envName: "MEMINI_INJECT_BRIEFING_FACTS", wireKey: "inject_briefing_facts", kind: "int", default: 5 },
+  { envName: "MEMINI_INJECT_BRIEFING_PROCEDURES", wireKey: "inject_briefing_procedures", kind: "int", default: 5 },
+  { envName: "MEMINI_INJECT_BRIEFING_RECENT", wireKey: "inject_briefing_recent", kind: "int", default: 3 },
+  { envName: "MEMINI_INJECT_BRIEFING_MAX_TOK", wireKey: "inject_briefing_max_tok", kind: "int", default: 0 },
+  { envName: "MEMINI_INJECT_PRETOOL_ITEMS", wireKey: "inject_pretool_items", kind: "int", default: 3 },
+  { envName: "MEMINI_INJECT_PRETOOL_MAX_TOK", wireKey: "inject_pretool_max_tok", kind: "int", default: 0 },
+  { envName: "MEMINI_INJECT_PRETOOL_MIN_SCORE", wireKey: "inject_pretool_min_score", kind: "float", default: 0 },
+  {
+    envName: "MEMINI_INJECT_PRETOOL_TOOLS",
+    wireKey: "inject_pretool_tools",
+    kind: "list",
+    default: ["Read", "Write", "Edit", "Glob", "Grep"]
+  },
+  { envName: "MEMINI_INJECT_DEDUPE", wireKey: "inject_dedupe", kind: "bool", default: true },
+  { envName: "MEMINI_INJECT_LABELS", wireKey: "inject_labels", kind: "list", default: [] },
+  { envName: "MEMINI_RECALL", wireKey: "recall", kind: "bool", default: true },
+  { envName: "MEMINI_CAPTURE", wireKey: "capture", kind: "bool", default: true },
+  { envName: "MEMINI_RECALL_LIMIT", wireKey: "recall_limit", kind: "int", default: 3 },
+  { envName: "MEMINI_INJECT_RECALL_MAX_TOK", wireKey: "inject_recall_max_tok", kind: "int", default: 0 },
+  { envName: "MEMINI_INJECT_RECALL_MIN_SCORE", wireKey: "inject_recall_min_score", kind: "float", default: 0 },
+  { envName: "MEMINI_MIN_CAPTURE_CHARS", wireKey: "min_capture_chars", kind: "int", default: 0 }
+];
+function parseIntKnob(raw, fallback) {
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
 }
-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 parseFloatKnob(raw, fallback) {
+  const n = Number.parseFloat(raw);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
 }
-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: {} };
+function parseListKnob(raw) {
+  return raw.split(/[|,]/).map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+function effectiveSetting(knob2, server, env = process.env) {
+  const raw = env[knob2.envName];
+  if (raw != null && raw !== "") {
+    let value;
+    switch (knob2.kind) {
+      case "bool":
+        value = !/^(0|false|no|off)$/i.test(raw.trim());
+        break;
+      case "int":
+        value = parseIntKnob(raw, knob2.default);
+        break;
+      case "float":
+        value = parseFloatKnob(raw, knob2.default);
+        break;
+      case "list":
+        value = parseListKnob(raw);
+        break;
     }
-    return {
-      version: typeof parsed.version === "number" ? parsed.version : OVERRIDES_VERSION,
-      overrides: parsed.overrides || {}
-    };
-  } catch {
-    return { ...EMPTY, overrides: {} };
+    return { value, source: "env-override" };
+  }
+  if (server && Object.prototype.hasOwnProperty.call(server, knob2.wireKey)) {
+    return { value: server[knob2.wireKey], source: "server" };
   }
+  return { value: knob2.default, source: "default" };
 }
-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;
+
+// ../../../packages/memini-client/src/bootstrap.ts
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+function envEnabled(raw, defaultOn) {
+  if (raw == null || raw === "") return defaultOn;
+  return !/^(0|false|no|off)$/i.test(raw.trim());
 }
-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()
+function readBootstrap(env = process.env) {
+  return {
+    baseUrl: env["MEMINI_BASE_URL"] || "http://localhost:8080",
+    apiKey: env["MEMINI_API_KEY"] || "",
+    requireHttps: envEnabled(env["MEMINI_REQUIRE_HTTPS"], false),
+    debug: envEnabled(env["MEMINI_DEBUG"], false),
+    agent: env["MEMINI_AGENT"] || "",
+    namespaceEnv: (env["MEMINI_NAMESPACE"] || "").trim(),
+    namespacePrefixEnv: (env["MEMINI_NAMESPACE_PREFIX"] || "").trim(),
+    homeEnv: (env["MEMINI_HOME"] || "").trim()
   };
-  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];
+function isPlaintextBearerUnsafe(baseUrl, secret) {
+  if (!secret) return false;
   try {
-    fs2.mkdirSync(path2.dirname(p), { recursive: true });
-    fs2.writeFileSync(p, JSON.stringify(file, null, 2) + "\n");
+    const u = new URL(baseUrl);
+    return u.protocol === "http:" && !LOOPBACK_HOSTS.has(u.hostname.replace(/^\[|\]$/g, "").toLowerCase());
   } catch {
     return false;
   }
-  return true;
+}
+function assertBearerTransportSafe(baseUrl, secret, env = process.env) {
+  if (!isPlaintextBearerUnsafe(baseUrl, secret)) return;
+  if (!envEnabled(env["MEMINI_REQUIRE_HTTPS"], false)) return;
+  throw new Error(
+    `memini: a bearer token is configured for plaintext HTTP to ${baseUrl}. The token and memory payloads can be observed on the network; use HTTPS or an SSH tunnel.`
+  );
 }
 
-// ../../../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;
+// ../../../packages/memini-client/src/facts.ts
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+function gitOut(args, dir) {
+  try {
+    const out = execFileSync("git", args, {
+      cwd: dir,
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 500
+    }).toString().trim();
+    return out || void 0;
+  } catch {
+    return void 0;
   }
-  return {
-    name: spec.name,
-    value,
-    source: set ? "env" : "default",
-    isDefault: !set,
-    sensitive,
-    usedBy: spec.usedBy,
-    description: spec.description
+}
+function gatherFacts(cwd, env = process.env) {
+  const dir = cwd && cwd.trim() ? cwd : process.cwd();
+  const facts = {
+    cwd_basename: path.basename(dir)
   };
+  const remote = gitOut(["remote", "get-url", "origin"], dir);
+  if (remote) facts.remote_url = remote;
+  const toplevel = gitOut(["rev-parse", "--show-toplevel"], dir);
+  if (toplevel) {
+    facts.toplevel_path = toplevel;
+    facts.toplevel_basename = path.basename(toplevel);
+  }
+  const agent = env["MEMINI_AGENT"];
+  if (agent) facts.agent = agent;
+  const ns = (env["MEMINI_NAMESPACE"] || "").trim();
+  if (ns) facts.env_namespace = ns;
+  const prefix = (env["MEMINI_NAMESPACE_PREFIX"] || "").trim();
+  if (prefix) facts.env_namespace_prefix = prefix;
+  return facts;
 }
-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;
+
+// ../../../packages/memini-client/src/resolve.ts
+function remotePathSegments(url) {
+  if (typeof url !== "string" || !url) return [];
+  const cleaned = url.trim().replace(/\/+$/, "").replace(/\.git$/i, "");
+  if (!cleaned) return [];
+  const scpMatch = cleaned.match(/^[^/:]+:[^/]/);
+  const p = scpMatch ? cleaned.slice(scpMatch[0].indexOf(":") + 1) : cleaned;
+  return p.split("/").filter(Boolean);
+}
+function repoNameFromRemote(url) {
+  const segs = remotePathSegments(url);
+  return segs.length ? segs[segs.length - 1] : void 0;
+}
+function repoSlugFromRemote(url) {
+  const segs = remotePathSegments(url);
+  if (!segs.length) return void 0;
+  if (segs.length === 1) return segs[0];
+  const owner = segs[segs.length - 2].replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  const repo = segs[segs.length - 1];
+  return owner ? `${owner}-${repo}` : repo;
+}
+function withAgent(ns, agent) {
+  const trimmed = (agent || "").trim();
+  if (!trimmed) return ns;
+  const seg = trimmed.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return seg ? `${ns}/${seg}` : ns;
+}
+function deriveLocalNamespace(f, scope = "repo") {
+  if (f.declared_namespace) {
+    return { namespace: f.declared_namespace, source: "declared" };
+  }
+  let base;
+  let source = "default";
+  if (f.remote_url) {
+    const name = scope === "owner_repo" ? repoSlugFromRemote(f.remote_url) : repoNameFromRemote(f.remote_url);
+    if (name) {
+      base = name;
+      source = "remote";
+    }
+  }
+  if (!base && f.toplevel_basename) {
+    base = f.toplevel_basename;
+    source = "toplevel";
+  }
+  if (!base && f.cwd_basename) {
+    base = f.cwd_basename;
+    source = "cwd";
+  }
+  if (!base) {
+    return { namespace: "default", source: "default" };
   }
+  return { namespace: withAgent(base, f.agent), source };
 }
-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."
-    });
+function resolveNamespace(boot, facts, hs) {
+  if (hs) {
+    return { namespace: hs.namespace, source: `server:${hs.namespace_source}`, degraded: false };
   }
-  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 (boot.namespaceEnv) {
+    return { namespace: boot.namespaceEnv, source: "env", degraded: true };
   }
-  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 { namespace, source } = deriveLocalNamespace(facts);
+  const prefix = boot.namespacePrefixEnv;
+  if (prefix && (source === "remote" || source === "toplevel" || source === "cwd")) {
+    return { namespace: `${prefix}/${namespace}`, source: `local-${source}`, degraded: true };
   }
-  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 { namespace, source: `local-${source}`, degraded: true };
+}
+
+// ../../../packages/memini-client/src/handshake.ts
+var HANDSHAKE_TTL_MS = 10 * 60 * 1e3;
+async function performHandshake(boot, facts, opts = {}) {
+  assertBearerTransportSafe(boot.baseUrl, boot.apiKey, {
+    MEMINI_REQUIRE_HTTPS: boot.requireHttps ? "1" : "0"
+  });
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 2500);
+  try {
+    const headers = { "Content-Type": "application/json" };
+    if (boot.apiKey) headers["Authorization"] = `Bearer ${boot.apiKey}`;
+    if (boot.homeEnv) headers["X-Memini-Home"] = boot.homeEnv;
+    const body = JSON.stringify({
+      project: facts,
+      client: { name: opts.clientName, version: opts.clientVersion }
+    });
+    const res = await fetch(`${boot.baseUrl}/v1/handshake`, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal
     });
+    if (!res.ok) return void 0;
+    return await res.json();
+  } catch {
+    return void 0;
+  } finally {
+    clearTimeout(timer);
   }
-  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"]);
+var HANDSHAKE_TIMEOUT_MS = 2500;
+var CLIENT_NAME = "pi-memini";
+function readPluginVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var CLIENT_VERSION = readPluginVersion();
 function envBool(value, fallback) {
   if (value === void 0 || value === null || value === "") return fallback;
   return !/^(0|false|no|off)$/i.test(String(value).trim());
@@ -423,65 +309,74 @@ function labelsEnv(name = "MEMINI_INJECT_LABELS") {
     raw.split(/[|,]/).map((s) => s.trim().toLowerCase()).filter(Boolean)
   );
 }
-function sanitizeNamespace(s) {
-  return String(s).trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-}
-function sanitizeNamespacePath(s) {
-  return String(s).split("/").map(sanitizeNamespace).filter(Boolean).join("/");
-}
-function deriveNamespace(cwd) {
-  if (typeof cwd !== "string" || !cwd.trim()) return "";
-  const base = cwd.replace(/[\\/]+$/, "").split(/[\\/]/).pop() || "";
-  return sanitizeNamespace(base);
-}
-function resolverSource(source) {
-  return source === "git" ? "git-remote" : source;
+function memoizeAsync(fn, ttlMs, now = Date.now) {
+  let cached = null;
+  return {
+    async get() {
+      const t = now();
+      if (!cached || t >= cached.expiresAt) {
+        const value = await fn();
+        cached = { value, expiresAt: t + ttlMs };
+      }
+      return cached.value;
+    },
+    invalidate() {
+      cached = null;
+    }
+  };
 }
-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();
-  if (nsEnv) {
-    return { namespace: nsEnv, source: "env" };
-  }
-  if (cwd) {
-    const { namespace: resolvedNs, source } = resolveNamespace({
-      cwd,
-      env: e,
-      integration: "pi"
+async function attemptHandshake(boot, facts, fallbackOnError) {
+  try {
+    return await performHandshake(boot, facts, {
+      timeoutMs: HANDSHAKE_TIMEOUT_MS,
+      clientName: CLIENT_NAME,
+      clientVersion: CLIENT_VERSION
     });
-    const sanitized = sanitizeNamespacePath(resolvedNs);
-    if (sanitized) return { namespace: sanitized, source: resolverSource(source) };
+  } catch (error) {
+    if (!fallbackOnError) throw error;
+    return void 0;
   }
-  return { namespace: DEFAULT_NAMESPACE, source: "default" };
 }
-function resolveConfig(env, cwd) {
+function createSessionContext(cwd, env = process.env, now = Date.now) {
+  const e = env;
+  const boot = readBootstrap(e);
+  const facts = gatherFacts(cwd, e);
+  const fallbackOnError = envBool(e.MEMINI_FALLBACK, true);
+  const memo = memoizeAsync(() => attemptHandshake(boot, facts, fallbackOnError), HANDSHAKE_TTL_MS, now);
+  return { boot, facts, memo };
+}
+function resolveStaticConfig(env = process.env) {
   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;
-  })();
   const homeEnv = (e.MEMINI_HOME || "").trim();
   return {
-    base_url: e.MEMINI_BASE_URL || e.MEMINI_URL || DEFAULT_BASE_URL,
-    // 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,
     home: homeEnv || void 0,
-    recall: envBool(e.MEMINI_RECALL, true),
-    capture: envBool(e.MEMINI_CAPTURE, true),
-    recall_limit,
-    recall_max_tokens: intEnv("MEMINI_INJECT_RECALL_MAX_TOK", 0),
-    recall_min_score: floatEnv("MEMINI_INJECT_RECALL_MIN_SCORE", 0),
     timeout_ms: Number(e.MEMINI_TIMEOUT_MS || DEFAULT_TIMEOUT_MS),
     fallback_on_error: envBool(e.MEMINI_FALLBACK, true)
   };
 }
+function knob(wireKey) {
+  const k = BEHAVIOR_KNOBS.find((b) => b.wireKey === wireKey);
+  if (!k) throw new Error(`pi-memini: unknown behavior knob "${wireKey}"`);
+  return k;
+}
+function resolveLiveConfig(boot, facts, hs, env = process.env) {
+  const resolved = resolveNamespace(boot, facts, hs);
+  const server = hs?.settings;
+  return {
+    namespace: resolved.namespace,
+    namespace_source: resolved.source,
+    degraded: resolved.degraded,
+    recall: effectiveSetting(knob("recall"), server, env).value,
+    capture: effectiveSetting(knob("capture"), server, env).value,
+    recall_limit: effectiveSetting(knob("recall_limit"), server, env).value,
+    recall_max_tokens: effectiveSetting(knob("inject_recall_max_tok"), server, env).value,
+    recall_min_score: effectiveSetting(knob("inject_recall_min_score"), server, env).value
+  };
+}
+async function sessionLive(ctx, env = process.env) {
+  const hs = await ctx.memo.get();
+  return resolveLiveConfig(ctx.boot, ctx.facts, hs, env);
+}
 function approxTokens(text) {
   if (!text) return 0;
   const words = String(text).trim().split(/\s+/).filter(Boolean).length;
@@ -535,25 +430,13 @@ function formatResults(results, limit, labels) {
     return `[${tagParts.join(" \xB7 ")}] ${text}`;
   }).filter((x) => Boolean(x));
 }
-function normalizedHostname(hostname) {
-  return hostname.replace(/^\[|\]$/g, "").toLowerCase();
-}
-function usesPlaintextBearerAuth(baseUrl, secret) {
-  if (!secret) return false;
-  try {
-    const parsed = new URL(baseUrl);
-    return parsed.protocol === "http:" && !LOOPBACK_HOSTS.has(normalizedHostname(parsed.hostname));
-  } catch {
-    return false;
-  }
-}
 function plaintextBearerAuthMessage(baseUrl) {
   return `memini: MEMINI_API_KEY is configured for plaintext HTTP to ${baseUrl}. Bearer tokens and memory payloads can be observed on the network; use HTTPS or an SSH tunnel.`;
 }
 function createPlaintextBearerAuthGuard(warn, env) {
   let warned = false;
   return function guardPlaintextBearerAuth(baseUrl, secret) {
-    if (!usesPlaintextBearerAuth(baseUrl, secret)) return;
+    if (!isPlaintextBearerUnsafe(baseUrl, secret || "")) return;
     const message = plaintextBearerAuthMessage(baseUrl);
     if ((env || process.env).MEMINI_REQUIRE_HTTPS === "1") throw new Error(message);
     if (!warned) {
@@ -562,53 +445,53 @@ function createPlaintextBearerAuthGuard(warn, env) {
     }
   };
 }
-function createClient(cfg, warn) {
-  const baseUrl = String(cfg.base_url).replace(/\/+$/, "");
-  const secret = process.env.MEMINI_API_KEY || process.env.MEMINI_TOKEN;
+function createClient(staticCfg, boot, warn) {
+  const baseUrl = String(boot.baseUrl).replace(/\/+$/, "");
+  const secret = boot.apiKey;
   const guard = createPlaintextBearerAuthGuard(warn);
-  if (process.env.MEMINI_REQUIRE_HTTPS === "1") guard(baseUrl, secret);
-  function headers(extra) {
-    const h = { "X-Memini-Namespace": cfg.namespace, ...extra || {} };
+  if (boot.requireHttps) guard(baseUrl, secret);
+  function headers(namespace, extra) {
+    const h = { "X-Memini-Namespace": namespace, ...extra || {} };
     if (secret) h.Authorization = `Bearer ${secret}`;
-    if (cfg.home) h["X-Memini-Home"] = cfg.home;
+    if (staticCfg.home) h["X-Memini-Home"] = staticCfg.home;
     return h;
   }
-  async function request(method, path3, body) {
+  async function request(method, path2, namespace, body) {
     guard(baseUrl, secret);
     try {
-      const res = await fetch(`${baseUrl}${path3}`, {
+      const res = await fetch(`${baseUrl}${path2}`, {
         method,
-        headers: headers(body ? { "Content-Type": "application/json" } : void 0),
+        headers: headers(namespace, body ? { "Content-Type": "application/json" } : void 0),
         body: body ? JSON.stringify(body) : void 0,
-        signal: AbortSignal.timeout(cfg.timeout_ms)
+        signal: AbortSignal.timeout(staticCfg.timeout_ms)
       });
       if (!res.ok) {
-        if (cfg.fallback_on_error) {
-          warn(`memini ${method} ${path3} failed: ${res.status}`);
+        if (staticCfg.fallback_on_error) {
+          warn(`memini ${method} ${path2} failed: ${res.status}`);
           return null;
         }
         const text = await res.text().catch(() => "");
-        throw new Error(`memini ${method} ${path3} failed: ${res.status} ${text}`);
+        throw new Error(`memini ${method} ${path2} failed: ${res.status} ${text}`);
       }
       return await res.json().catch(() => ({ ok: true }));
     } catch (error) {
-      if (!cfg.fallback_on_error) throw error;
+      if (!staticCfg.fallback_on_error) throw error;
       warn(`memini: ${String(error)}`);
       return null;
     }
   }
-  async function requestResult(method, path3, body) {
+  async function requestResult(method, path2, namespace, body) {
     try {
       guard(baseUrl, secret);
-      const res = await fetch(`${baseUrl}${path3}`, {
+      const res = await fetch(`${baseUrl}${path2}`, {
         method,
-        headers: headers(body ? { "Content-Type": "application/json" } : void 0),
+        headers: headers(namespace, body ? { "Content-Type": "application/json" } : void 0),
         body: body ? JSON.stringify(body) : void 0,
-        signal: AbortSignal.timeout(cfg.timeout_ms)
+        signal: AbortSignal.timeout(staticCfg.timeout_ms)
       });
       if (!res.ok) {
         const detail = (await res.text().catch(() => "")).trim();
-        warn(`memini ${method} ${path3} failed: ${res.status} ${detail}`);
+        warn(`memini ${method} ${path2} failed: ${res.status} ${detail}`);
         return { ok: false, error: detail || `HTTP ${res.status}` };
       }
       return { ok: true, data: await res.json().catch(() => ({})) };
@@ -618,10 +501,10 @@ function createClient(cfg, warn) {
     }
   }
   return {
-    postJson: (path3, payload) => request("POST", path3, payload),
-    getJson: (path3) => request("GET", path3),
-    deleteJson: (path3) => request("DELETE", path3),
-    postJsonResult: (path3, payload) => requestResult("POST", path3, payload)
+    postJson: (path2, payload, namespace) => request("POST", path2, namespace, payload),
+    getJson: (path2, namespace) => request("GET", path2, namespace),
+    deleteJson: (path2, namespace) => request("DELETE", path2, namespace),
+    postJsonResult: (path2, payload, namespace) => requestResult("POST", path2, namespace, payload)
   };
 }
 function meminiListPath(args) {
@@ -660,37 +543,69 @@ function buildTurnContent(userText, assistantText) {
 
 ${String(assistantText).slice(0, 3e3)}`;
 }
-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;
+function pinKeyFacts(facts) {
+  const out = {};
+  if (facts.remote_url) out.remote_url = facts.remote_url;
+  if (facts.toplevel_path) out.toplevel_path = facts.toplevel_path;
+  return out;
+}
+async function pinsRequest(boot, method, body) {
+  assertBearerTransportSafe(boot.baseUrl, boot.apiKey);
+  const headers = { "Content-Type": "application/json" };
+  if (boot.apiKey) headers.Authorization = `Bearer ${boot.apiKey}`;
+  if (boot.homeEnv) headers["X-Memini-Home"] = boot.homeEnv;
+  const res = await fetch(`${boot.baseUrl}/v1/pins`, {
+    method,
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(5e3)
+  });
+  let parsed = null;
+  try {
+    parsed = await res.json();
+  } catch {
+  }
+  return { ok: res.ok, status: res.status, body: parsed };
+}
+function pinErrorMessage(res) {
+  return res.body?.error || res.body?.message || `HTTP ${res.status}`;
+}
+function offlineMessage(boot, error) {
+  const detail = String(error?.message || error);
+  return `${detail}
+
+Could not reach the memini server at ${boot.baseUrl}. Pins live on the server, so setting one needs it reachable. For an offline, machine-local override instead, export MEMINI_NAMESPACE=<namespace>.`;
+}
+async function statusGet(boot, namespace, path2, warn, quiet = false) {
+  const baseUrl = String(boot.baseUrl).replace(/\/+$/, "");
   const headers = { "X-Memini-Namespace": namespace };
-  if (secret) headers.Authorization = `Bearer ${secret}`;
-  if (cfg.home) headers["X-Memini-Home"] = cfg.home;
+  if (boot.apiKey) headers.Authorization = `Bearer ${boot.apiKey}`;
+  if (boot.homeEnv) headers["X-Memini-Home"] = boot.homeEnv;
   try {
-    const res = await fetch(`${baseUrl}${path3}`, {
+    const res = await fetch(`${baseUrl}${path2}`, {
       method: "GET",
       headers,
       signal: AbortSignal.timeout(STATUS_TIMEOUT_MS)
     });
     if (!res.ok) {
-      if (!quiet) warn(`GET ${path3} -> ${res.status}`);
+      if (!quiet) warn(`GET ${path2} -> ${res.status}`);
       return null;
     }
     return await res.json();
   } catch (error) {
-    if (!quiet) warn(`GET ${path3} failed: ${String(error)}`);
+    if (!quiet) warn(`GET ${path2} failed: ${String(error)}`);
     return null;
   }
 }
-async function fetchServer(cfg, namespace, warn) {
+async function fetchServer(boot, namespace, warn) {
   const started = Date.now();
-  const readSet = await statusGet(cfg, namespace, "/v1/namespaces/read-set", warn);
+  const readSet = await statusGet(boot, namespace, "/v1/namespaces/readset", warn);
   const out = {
     reachable: readSet != null,
     latencyMs: Date.now() - started,
     readSet
   };
-  const health = await statusGet(cfg, namespace, "/healthz?verbose=1", warn, true);
+  const health = await statusGet(boot, namespace, "/healthz?verbose=1", warn, true);
   if (health) {
     out.version = health.version;
     out.status = health.status;
@@ -701,49 +616,75 @@ async function fetchServer(cfg, namespace, warn) {
   return out;
 }
 var pad = (s, n) => String(s).padEnd(n);
-function renderStatus(settings, cfg, server) {
-  const ns = settings.namespace;
+function buildWarnings(ctx, live, hs) {
+  const warnings = [];
+  if (live.degraded) {
+    warnings.push({
+      level: "warn",
+      code: "degraded-mode",
+      message: `could not reach the memini server at ${ctx.boot.baseUrl}: the namespace is local-derived and every setting is a built-in default, not what the server would return.`,
+      fix: "Check MEMINI_BASE_URL and that the server is running; recall and capture are both failing until it is reachable."
+    });
+  }
+  if (ctx.boot.namespaceEnv && hs?.namespace_source !== "pin") {
+    warnings.push({
+      level: "warn",
+      code: "global-namespace-pin",
+      message: `MEMINI_NAMESPACE is set to "${ctx.boot.namespaceEnv}", which pins EVERY project on this machine to one namespace (unless this repo has a stronger server-side pin). If it is exported from a shell rc (or a fish universal variable), every repo you work in is sharing one memory pool.`,
+      fix: "Set a pin instead: /memini:namespace <ns> (a pin beats the environment)."
+    });
+  }
+  if (!ctx.boot.homeEnv) {
+    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>."
+    });
+  }
+  if (isPlaintextBearerUnsafe(ctx.boot.baseUrl, ctx.boot.apiKey)) {
+    warnings.push({
+      level: "warn",
+      code: "plaintext-bearer",
+      message: `a bearer token is configured for plaintext HTTP to ${ctx.boot.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 warnings;
+}
+function renderStatus(ctx, staticCfg, live, hs, server) {
   const L = [];
   L.push(`memini \u2014 effective settings (pi)`);
-  L.push(`cwd: ${settings.cwd}`);
+  L.push(`cwd: ${ctx.facts.toplevel_path || process.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("effective", 28)} ${pad(live.namespace, 34)} <- ${live.namespace_source}`);
+  if (live.degraded) {
+    const local = deriveLocalNamespace(ctx.facts);
+    if (local.namespace !== live.namespace) {
+      L.push(`  ${pad("git/cwd would give", 28)} ${pad(local.namespace, 34)} <- local-${local.source}`);
+    }
   }
-  L.push(`  ${pad("home (personal)", 28)} ${ns.home || "(unset)"}`);
+  L.push(`  ${pad("home (personal)", 28)} ${ctx.boot.homeEnv || "(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("");
+  L.push(`SETTINGS`);
+  const wireKeys = ["recall", "capture", "recall_limit", "inject_recall_max_tok", "inject_recall_min_score"];
+  for (const wireKey of wireKeys) {
+    const k = knob(wireKey);
+    const { value, source } = effectiveSetting(k, hs?.settings, process.env);
+    const origin = source === "env-override" ? "<- env" : source === "server" ? "<- server" : "(default)";
+    L.push(`  ${pad(k.envName.replace(/^MEMINI_/, "").toLowerCase(), 28)} ${pad(String(value), 22)} ${origin}`);
   }
-  const secret = process.env.MEMINI_API_KEY || process.env.MEMINI_TOKEN || "";
+  L.push("");
+  const secret = ctx.boot.apiKey;
   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("base_url", 28)} ${ctx.boot.baseUrl}`);
+  L.push(`  ${pad("timeout_ms", 28)} ${staticCfg.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}`);
+    L.push(`  ${pad("reachable", 28)} NO \u2014 could not reach ${ctx.boot.baseUrl}`);
   } else {
     const ver = server.version ? `, ${server.version}` : "";
     L.push(`  ${pad("reachable", 28)} yes (${server.latencyMs}ms${ver})`);
@@ -758,7 +699,7 @@ function renderStatus(settings, cfg, server) {
   }
   L.push("");
   if (server.readSet?.entries?.length) {
-    L.push(`READ SET for "${ns.effective}" \u2014 where a plain recall looks`);
+    L.push(`READ SET for "${live.namespace}" \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";
@@ -766,12 +707,10 @@ function renderStatus(settings, cfg, server) {
     }
     L.push("");
   }
-  L.push(`PATHS`);
-  L.push(`  ${pad("overrides", 28)} ${settings.paths.overrides}`);
-  L.push("");
-  if (settings.warnings.length) {
+  const warnings = buildWarnings(ctx, live, hs);
+  if (warnings.length) {
     L.push(`WARNINGS`);
-    for (const w of settings.warnings) {
+    for (const w of warnings) {
       L.push(`  [${w.level === "warn" ? "!" : "i"}] ${w.code}: ${w.message}`);
       if (w.fix) L.push(`      fix: ${w.fix}`);
     }
@@ -780,69 +719,94 @@ function renderStatus(settings, cfg, server) {
   }
   return L.join("\n");
 }
-function registerMeminiCommands(pi, cfg, warn) {
+function registerMeminiCommands(pi, ctx, staticCfg, 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) => {
+    handler: async (_args, cmdCtx) => {
       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));
+        const hs = await ctx.memo.get();
+        const live = resolveLiveConfig(ctx.boot, ctx.facts, hs, process.env);
+        const server = await fetchServer(ctx.boot, live.namespace, warn);
+        show(renderStatus(ctx, staticCfg, live, hs, server));
       } catch (error) {
-        ctx.ui.notify(`memini: status failed: ${String(error)}`, "error");
+        cmdCtx.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) => {
+    description: "Show, set, or --clear the memini namespace pin for this project (server-side)",
+    handler: async (args, cmdCtx) => {
       try {
-        const cwd = ctx.cwd || process.cwd();
         const arg = String(args || "").trim();
-        const before = resolveProjectNamespace(process.env, cwd);
+        const { boot, facts } = ctx;
         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>`);
+          const hs = await ctx.memo.get();
+          const live = resolveLiveConfig(boot, facts, hs, process.env);
+          const out = [];
+          if (!hs) {
+            out.push(`namespace: ${live.namespace}  (${live.namespace_source} \u2014 server unreachable)`);
+            out.push("");
+            out.push(`Could not reach ${boot.baseUrl}, so this is a local guess, not the server's authority.`);
+            out.push(`A pin (if any) can only be read from the server.`);
+            show(out.join("\n"));
+            return;
+          }
+          out.push(`namespace: ${hs.namespace}  (source: ${hs.namespace_source})`);
+          if (hs.namespace_source === "pin" && hs.pin) {
+            out.push(`pin:       key ${hs.pin.key}`);
+            if (hs.pin.created_by) out.push(`           set by ${hs.pin.created_by}`);
+            if (hs.pin.updated_at) out.push(`           updated ${hs.pin.updated_at}`);
+            if (hs.pin.note) out.push(`           note: ${hs.pin.note}`);
+            if (boot.namespaceEnv) {
+              out.push("");
+              out.push(`MEMINI_NAMESPACE is set to "${boot.namespaceEnv}", but the pin wins \u2014 a pin`);
+              out.push(`beats the environment on purpose.`);
+            }
+          } else if (hs.namespace_source === "env") {
+            out.push("");
+            out.push(`This comes from MEMINI_NAMESPACE, which pins EVERY project on this machine to`);
+            out.push(`one namespace. To scope just this project, set a pin: /memini:namespace <ns>`);
+            out.push(`(a pin beats the environment).`);
           }
-          out.push(`Overrides file: ${defaultOverridesPath(process.env)}`);
+          out.push("");
+          out.push(`Set a pin with:    /memini:namespace <namespace>`);
+          out.push(`Clear it with:     /memini:namespace --clear`);
           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.`);
+          const keyFacts2 = pinKeyFacts(facts);
+          if (!keyFacts2.remote_url && !keyFacts2.toplevel_path) {
+            cmdCtx.ui.notify(
+              `memini: this project has no git remote or toplevel, so it cannot have a pin to clear.`,
+              "error"
+            );
             return;
           }
-          const after2 = resolveProjectNamespace(process.env, cwd);
-          cfg.namespace = after2.namespace;
+          let res2;
+          try {
+            res2 = await pinsRequest(boot, "DELETE", keyFacts2);
+          } catch (error) {
+            cmdCtx.ui.notify(`memini: ${offlineMessage(boot, error)}`, "error");
+            return;
+          }
+          if (res2.status === 404) {
+            show(`No pin was set for this project \u2014 nothing to clear.`);
+            return;
+          }
+          if (!res2.ok) {
+            cmdCtx.ui.notify(`memini: could not clear the pin: ${pinErrorMessage(res2)}`, "error");
+            return;
+          }
+          ctx.memo.invalidate();
           show(
             [
-              `namespace override cleared: ${before.namespace} -> ${after2.namespace}  (source: ${after2.source})`,
+              `namespace pin cleared \u2014 this project resolves automatically again.`,
               ``,
-              `Recall and capture use the new namespace from the next turn.`
+              `Recall and capture use the new resolution from the next turn.`
             ].join("\n")
           );
           return;
@@ -850,22 +814,42 @@ function registerMeminiCommands(pi, cfg, warn) {
         const ns = normalizeNamespace(arg);
         const bad = validateNamespace(ns);
         if (bad) {
-          ctx.ui.notify(`memini: invalid namespace ${JSON.stringify(arg)}: ${bad}`, "error");
+          cmdCtx.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;
+        const keyFacts = pinKeyFacts(facts);
+        if (!keyFacts.remote_url && !keyFacts.toplevel_path) {
+          cmdCtx.ui.notify(
+            `memini: this project has no git remote or toplevel to pin a namespace to. A pin is keyed by the project's git identity; run inside a git repository, or export MEMINI_NAMESPACE=${ns} for a machine-local override.`,
+            "error"
+          );
+          return;
+        }
+        let res;
+        try {
+          res = await pinsRequest(boot, "PUT", { namespace: ns, ...keyFacts });
+        } catch (error) {
+          cmdCtx.ui.notify(`memini: ${offlineMessage(boot, error)}`, "error");
+          return;
+        }
+        if (!res.ok) {
+          cmdCtx.ui.notify(`memini: could not set the pin: ${pinErrorMessage(res)}`, "error");
+          return;
+        }
+        ctx.memo.invalidate();
+        const entry = res.body || {};
         show(
           [
-            `namespace override set: ${before.namespace} -> ${after.namespace}`,
-            `project: ${overrideKey(cwd)}`,
+            `namespace pinned: ${entry.namespace || ns}`,
+            `project key:      ${entry.key || keyFacts.remote_url || keyFacts.toplevel_path}`,
             ``,
-            `The override wins over MEMINI_NAMESPACE. Recall and capture use it from the next turn.`
+            `Recall and capture use it from the next turn. The pin lives on the memini server, so it`,
+            `follows you across machines and every client resolves the same namespace. It beats`,
+            `MEMINI_NAMESPACE.`
           ].join("\n")
         );
       } catch (error) {
-        ctx.ui.notify(`memini: namespace failed: ${String(error)}`, "error");
+        cmdCtx.ui.notify(`memini: namespace failed: ${String(error)}`, "error");
       }
     }
   });
@@ -898,10 +882,11 @@ function meminiExtension(pi) {
     } catch {
     }
   };
-  const cfg = resolveConfig(process.env, process.cwd());
-  const client = createClient(cfg, warn);
+  const sessionCtx = createSessionContext(process.cwd(), process.env);
+  const staticCfg = resolveStaticConfig(process.env);
+  const client = createClient(staticCfg, sessionCtx.boot, warn);
   try {
-    if (typeof pi.registerCommand === "function") registerMeminiCommands(pi, cfg, warn);
+    if (typeof pi.registerCommand === "function") registerMeminiCommands(pi, sessionCtx, staticCfg, warn);
   } catch (error) {
     warn(`command registration skipped: ${String(error)}`);
   }
@@ -966,22 +951,23 @@ function meminiExtension(pi) {
     const sid = sessionIdOf(ctx);
     const query = String(event?.prompt || "").trim();
     if (query && sid) rememberPendingUser(sid, query);
-    if (!cfg.recall || !query) return;
-    const body = { query, limit: cfg.recall_limit };
+    const live = await sessionLive(sessionCtx);
+    if (!live.recall || !query) return;
+    const body = { query, limit: live.recall_limit };
     if (sid) body.exclude_metadata = { session_id: sid };
-    if (cfg.recall_min_score > 0) body.min_score = cfg.recall_min_score;
+    if (live.recall_min_score > 0) body.min_score = live.recall_min_score;
     const excludeIds = sid ? [...injectedBySession.get(sid) ?? []] : [];
     const result = await searchExcluding(body, excludeIds);
-    const floor = cfg.recall_min_score > 0 ? cfg.recall_min_score : 0;
+    const floor = live.recall_min_score > 0 ? live.recall_min_score : 0;
     let rawHits = Array.isArray(result?.results) ? result.results : [];
     if (sid) {
       const seen = injectedBySession.get(sid);
       if (seen?.size) rawHits = rawHits.filter((r) => !seen.has(r?.memory?.id));
     }
     const filtered = floor > 0 ? rawHits.filter((r) => (typeof r?.score === "number" ? r.score : 0) >= floor) : rawHits;
-    const hits = formatResults(filtered, cfg.recall_limit, labelsEnv());
+    const hits = formatResults(filtered, live.recall_limit, labelsEnv());
     if (hits.length === 0) return;
-    const fit = fitByTokens(hits, cfg.recall_max_tokens);
+    const fit = fitByTokens(hits, live.recall_max_tokens);
     if (fit.items.length === 0) return;
     if (sid) {
       rememberInjected(sid, filtered.map((r) => r?.memory?.id).filter(Boolean));
@@ -1005,7 +991,8 @@ function meminiExtension(pi) {
     };
   });
   pi.on("agent_end", async (event, ctx) => {
-    if (!cfg.capture) return;
+    const live = await sessionLive(sessionCtx);
+    if (!live.capture) return;
     const sid = sessionIdOf(ctx);
     const userText = sid && pendingUser.get(sid) || "";
     const assistantText = extractLastAssistantText(event?.messages);
@@ -1014,11 +1001,15 @@ function meminiExtension(pi) {
     if (dedupKey && captured.has(dedupKey)) return;
     const metadata = { source: "pi", format: "turn" };
     if (sid) metadata.session_id = sid;
-    const stored = await client.postJson("/v1/memories", {
-      content: buildTurnContent(userText, assistantText),
-      tags: ["pi"],
-      metadata
-    });
+    const stored = await client.postJson(
+      "/v1/memories",
+      {
+        content: buildTurnContent(userText, assistantText),
+        tags: ["pi"],
+        metadata
+      },
+      live.namespace
+    );
     if (stored !== null) {
       if (dedupKey) rememberCaptured(dedupKey);
       if (sid) pendingUser.delete(sid);
@@ -1051,11 +1042,12 @@ function meminiExtension(pi) {
       scope: Scope
     }),
     async execute(_toolCallId, params) {
+      const live = await sessionLive(sessionCtx);
       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 res = await client.postJson("/v1/search", body, live.namespace);
       const results = (res?.results || []).map((r) => {
         const mem = r?.memory || {};
         const out = {
@@ -1078,7 +1070,8 @@ function meminiExtension(pi) {
     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));
+      const live = await sessionLive(sessionCtx);
+      const res = await client.getJson(briefingPath(params), live.namespace);
       if (!res) return text({ briefing: null, error: "memini unavailable" });
       const section = (items) => (items || []).map((b) => {
         const mem = b?.memory || {};
@@ -1110,8 +1103,9 @@ function meminiExtension(pi) {
       limit: Type.Optional(Type.Number({ description: "Max results (0 = all, default 20)" }))
     }),
     async execute(_toolCallId, params) {
+      const live = await sessionLive(sessionCtx);
       const args = { ...params, limit: params.limit ?? 20 };
-      const res = await client.getJson(meminiListPath(args));
+      const res = await client.getJson(meminiListPath(args), live.namespace);
       const memories = (res?.memories || []).map((m) => ({
         id: m.id || "",
         content: m.content || "",
@@ -1126,7 +1120,8 @@ 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. 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.",
+    // Save-policy invariants are canonical in internal/api/mcp/mcp.go serverInstructions.
+    description: "Store a fact, decision, preference, or event for later recall. Do not wait to be asked \u2014 call this the moment you learn: a decision and why it was made, a bug's root cause, a project convention, a stated user preference, a correction from the user (a correction IS a durable preference), an environment or tool quirk, or a non-obvious command/workflow. When the user says 'remember this', 'note that', 'don't forget', 'going forward...', or corrects you, call this tool FIRST, then acknowledge \u2014 and on an explicit request save unconditionally, even if it seems trivial or already stored; secrets and credentials are the one exception. Keep memories atomic \u2014 one self-contained fact per call; search works better on small records. Do NOT store secrets or credentials, transient session state, task progress, or facts already in project docs/CLAUDE.md or trivially recoverable from code. To correct an existing memory, pass its id \u2014 the write updates it in place. If a stored memory proves wrong or outdated, fix it immediately: re-save the corrected fact with the existing id, or delete it with memory_forget if it should not exist \u2014 never leave a known-incorrect memory 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(
@@ -1156,6 +1151,7 @@ function meminiExtension(pi) {
       )
     }),
     async execute(_toolCallId, params) {
+      const live = await sessionLive(sessionCtx);
       const body = { content: params.content };
       if (params.id) body.id = params.id;
       if (params.tier && VALID_TIERS.includes(params.tier)) body.tier = params.tier;
@@ -1163,7 +1159,7 @@ function meminiExtension(pi) {
       if (params.category) body.metadata = { category: params.category };
       const visibility = String(params.visibility || "").trim();
       if (visibility) body.visibility = visibility;
-      const res = await client.postJsonResult("/v1/memories", body);
+      const res = await client.postJsonResult("/v1/memories", body, live.namespace);
       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;
@@ -1178,8 +1174,9 @@ function meminiExtension(pi) {
       id: Type.String({ description: "The id of the memory to forget (from memory_recall / memory_list)." })
     }),
     async execute(_toolCallId, params) {
+      const live = await sessionLive(sessionCtx);
       if (!params.id) return text({ forgotten: false, error: "id is required" });
-      const res = await client.deleteJson(`/v1/memories/${encodeURIComponent(params.id)}`);
+      const res = await client.deleteJson(`/v1/memories/${encodeURIComponent(params.id)}`, live.namespace);
       return text({ forgotten: res != null });
     }
   });
@@ -1189,9 +1186,10 @@ export {
   approxTokens,
   briefingPath,
   buildTurnContent,
+  buildWarnings,
   createPlaintextBearerAuthGuard,
+  createSessionContext,
   meminiExtension as default,
-  deriveNamespace,
   extractLastAssistantText,
   extractMessageText,
   fitByTokens,
@@ -1200,11 +1198,12 @@ export {
   intEnv,
   labelsEnv,
   meminiListPath,
+  memoizeAsync,
+  pinKeyFacts,
   registerMeminiCommands,
   renderStatus,
-  resolveConfig,
-  resolveProjectNamespace,
-  sanitizeNamespace,
-  sanitizeNamespacePath,
+  resolveLiveConfig,
+  resolveStaticConfig,
+  sessionLive,
   truncate
 };