@eleboucher/pi-memini 0.6.12 → 0.7.1

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,261 @@ 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_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 +308,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 +429,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 +444,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 +500,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 +542,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 +615,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 +698,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 +706,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 +718,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 +813,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 +881,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 +950,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 +990,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 +1000,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 +1041,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 +1069,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 +1102,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 || "",
@@ -1156,6 +1149,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 +1157,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 +1172,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 +1184,10 @@ export {
   approxTokens,
   briefingPath,
   buildTurnContent,
+  buildWarnings,
   createPlaintextBearerAuthGuard,
+  createSessionContext,
   meminiExtension as default,
-  deriveNamespace,
   extractLastAssistantText,
   extractMessageText,
   fitByTokens,
@@ -1200,11 +1196,12 @@ export {
   intEnv,
   labelsEnv,
   meminiListPath,
+  memoizeAsync,
+  pinKeyFacts,
   registerMeminiCommands,
   renderStatus,
-  resolveConfig,
-  resolveProjectNamespace,
-  sanitizeNamespace,
-  sanitizeNamespacePath,
+  resolveLiveConfig,
+  resolveStaticConfig,
+  sessionLive,
   truncate
 };