cogmem 2.7.0__py3-none-any.whl

cogmem/__init__.py

@@ -0,0 +1,7 @@
+"""cogmem — a self-improving, verifiable memory layer for AI coding agents.
+
+The engine package. Installed under the import name ``cogmem`` (setuptools maps
+it from the ``engine/`` directory); modules import each other as ``cogmem.<name>``.
+"""
+
+__version__ = "2.7.0"

cogmem/acquire.py

@@ -0,0 +1,226 @@
+"""
+Cognitive Memory — Acquisition Engine
+
+Reads a session transcript, detects whether it contains behavior-change signal,
+and (only when it does) extracts candidate rules: durable, scope-tagged things
+that should change how the assistant acts in future sessions.
+
+Design goal: learn how the user works so the assistant completes their work more
+accurately and more autonomously. The unit of value is a behavior-change rule
+that can be reliably surfaced when relevant.
+
+Two-step cadence (cost discipline):
+  1. detect  — cheap model decides if the session has any signal at all
+  2. extract — strong model runs ONLY when signal is present
+
+Output: candidate rule files (markdown + YAML frontmatter) under vault/candidates/.
+Candidates are never auto-promoted; consolidation dedups them and queues Layer-A
+rules for human approval. The markdown files are the source of truth; nothing is
+locked into a database.
+
+Usage:
+  python acquire.py <transcript.jsonl>      # explicit path
+  cat hook_payload.json | python acquire.py  # Stop-hook mode (reads transcript_path)
+  python acquire.py <transcript.jsonl> --dry-run   # print, don't write
+"""
+
+import json
+import logging
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from cogmem import config
+from cogmem.common import api_call, parse_json_block
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+log = logging.getLogger("cogmem.acquire")
+
+COGMEM = Path(os.environ.get("COGMEM_HOME", Path.home() / ".claude" / "cogmem"))
+CANDIDATES_DIR = COGMEM / "vault" / "candidates"
+
+DETECT_MODEL = config.model("detect")    # cheap: runs every session
+EXTRACT_MODEL = config.model("extract")  # strong: runs only on signal
+
+# Cap transcript size sent to the model. Most signal lives in user turns
+# (corrections, preferences) and assistant text; we drop thinking/tool noise.
+MAX_TRANSCRIPT_CHARS = 60_000
+
+
+def extract_conversation(transcript_path: Path) -> str:
+    """Flatten a Claude Code transcript to role-tagged text, dropping
+    thinking blocks and tool noise (low signal, high token cost)."""
+    lines = []
+    for raw in transcript_path.read_text(errors="replace").splitlines():
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            obj = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        if obj.get("type") not in ("user", "assistant"):
+            continue
+        msg = obj.get("message") or {}
+        role = msg.get("role")
+        content = msg.get("content")
+        if isinstance(content, str):
+            text = content
+        elif isinstance(content, list):
+            text = "\n".join(
+                b.get("text", "")
+                for b in content
+                if isinstance(b, dict) and b.get("type") == "text"
+            )
+        else:
+            text = ""
+        text = text.strip()
+        if text:
+            lines.append(f"[{role}] {text}")
+    convo = "\n".join(lines)
+    if len(convo) > MAX_TRANSCRIPT_CHARS:
+        # keep the tail: corrections and conclusions cluster at the end
+        convo = convo[-MAX_TRANSCRIPT_CHARS:]
+    return convo
+
+
+DETECT_PROMPT = """You are a signal detector for a coding assistant's memory system.
+Decide whether this session contains BEHAVIOR-CHANGE SIGNAL worth learning: a user
+correction, a stated preference, a repeated or notable mistake, a non-obvious decision,
+or a genuine surprise. Routine sessions with nothing transferable have no signal.
+
+Answer with ONLY one word: YES or NO.
+
+TRANSCRIPT:
+{convo}"""
+
+EXTRACT_PROMPT = """You are the acquisition engine for a coding assistant's memory system.
+Goal: learn how this user works so the assistant completes their work more accurately and
+more autonomously next time.
+
+Extract BEHAVIOR-CHANGE RULES from the session: specific things that should change how the
+assistant acts in future sessions. For each rule provide:
+- layer: "A" or "B". DEFAULT TO "B". A rule is "A" (always-load) ONLY if forgetting it
+  would ship a bug or repeat a costly mistake, AND it must be present from the very start
+  of EVERY relevant session because there is no prompt that would reliably recall it in
+  time. Facts, situational knowledge, one-off context, anything you would only need "when
+  relevant", and anything a recall query could surface in the moment are ALL "B".
+- scope: a project name, a language, or "universal"
+- rule: the imperative rule itself, self-contained
+- evidence: brief paraphrase of what in the session supports it
+
+Be strict. Prefer a few high-value rules over many weak ones. Expect most rules to be "B";
+"A" is rare. Layer A is a tiny, precious budget; reserve it for true must-never-miss guardrails.
+If the session has nothing worth learning, return {{"signal": false, "rules": []}}.
+
+Return ONLY JSON: {{"signal": true/false, "rules": [...]}}.
+
+TRANSCRIPT:
+{convo}"""
+
+
+def slugify(text: str, maxlen: int = 50) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return s[:maxlen].rstrip("-") or "rule"
+
+
+def write_candidate(rule: dict, session_id: str, now: str) -> Path | None:
+    rule_text = (rule.get("rule") or "").strip()
+    if not rule_text:
+        return None
+    layer = rule.get("layer", "B").upper()
+    if layer not in ("A", "B"):
+        layer = "B"
+    scope = (rule.get("scope") or "universal").strip()
+    evidence = (rule.get("evidence") or "").replace('"', "'").strip()
+
+    slug = f"{scope}-{slugify(rule_text)}"
+    path = CANDIDATES_DIR / f"{slug}.md"
+    # avoid clobbering distinct candidates that slugify the same
+    n = 2
+    while path.exists():
+        path = CANDIDATES_DIR / f"{slug}-{n}.md"
+        n += 1
+
+    frontmatter = (
+        "---\n"
+        f"id: {path.stem}\n"
+        f"layer: {layer}\n"
+        f"scope: {scope}\n"
+        "status: candidate\n"
+        f"created: {now}\n"
+        f"source_session: {session_id}\n"
+        f'evidence: "{evidence}"\n'
+        "---\n\n"
+    )
+    path.write_text(frontmatter + rule_text + "\n")
+    return path
+
+
+def acquire(transcript_path: Path, dry_run: bool = False) -> int:
+    if not transcript_path.exists():
+        log.error("Transcript not found: %s", transcript_path)
+        return 0
+    convo = extract_conversation(transcript_path)
+    if len(convo) < 200:
+        log.info("Transcript too short to carry signal; skipping.")
+        return 0
+
+    detect = api_call(DETECT_MODEL, DETECT_PROMPT.format(convo=convo), max_tokens=5)
+    if detect is None:
+        return 0
+    if "yes" not in detect.lower():
+        log.info("No behavior-change signal detected; skipping extraction.")
+        return 0
+    log.info("Signal detected; running extraction.")
+
+    raw = api_call(EXTRACT_MODEL, EXTRACT_PROMPT.format(convo=convo), max_tokens=2000)
+    if raw is None:
+        return 0
+    result = parse_json_block(raw)
+    if not result or not result.get("signal"):
+        log.info("Extractor found no rules.")
+        return 0
+
+    session_id = transcript_path.stem
+    now = datetime.now(timezone.utc).isoformat()
+    rules = result.get("rules", [])
+
+    if dry_run:
+        sys.stdout.write(json.dumps(result, indent=2) + "\n")
+        log.info("[dry-run] would write %d candidate(s).", len(rules))
+        return len(rules)
+
+    CANDIDATES_DIR.mkdir(parents=True, exist_ok=True)
+    written = 0
+    for rule in rules:
+        p = write_candidate(rule, session_id, now)
+        if p:
+            written += 1
+            log.info("  CANDIDATE [%s/%s] %s", rule.get("layer"), rule.get("scope"), p.name)
+    log.info("Wrote %d candidate rule(s) to %s", written, CANDIDATES_DIR)
+    return written
+
+
+def resolve_transcript_arg(arg: str) -> Path | None:
+    """Accept either a transcript path or a Stop-hook JSON payload on stdin."""
+    if arg and arg != "-":
+        return Path(arg)
+    try:
+        payload = json.loads(sys.stdin.read())
+        tp = payload.get("transcript_path")
+        return Path(tp) if tp else None
+    except json.JSONDecodeError:
+        return None
+
+
+if __name__ == "__main__":
+    args = [a for a in sys.argv[1:] if not a.startswith("--")]
+    dry = "--dry-run" in sys.argv
+    path = resolve_transcript_arg(args[0] if args else "-")
+    if path is None:
+        log.error("No transcript path (arg or stdin hook payload required)")
+        sys.exit(1)
+    acquire(path, dry_run=dry)

cogmem/artifacts.py

@@ -0,0 +1,99 @@
+"""
+Cognitive Memory — Artifact Grounding (git history)
+
+Transcripts are a thin slice of the work. The repo records far more: what was
+fixed, what got reverted, the gotchas that show up in commit after commit. This
+mines a project's recent git history into candidate rules, so the system learns
+from what was actually done, not only what was discussed. Output goes into the
+normal candidate pipeline (consolidation dedups against existing knowledge).
+
+Usage:
+  python artifacts.py [repo_path]    # default: current directory
+"""
+
+import logging
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from cogmem.common import VAULT, api_call, parse_json_block, write_note
+from cogmem import config
+from cogmem.acquire import slugify
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+log = logging.getLogger("cogmem.artifacts")
+
+CANDIDATES = VAULT / "candidates"
+MODEL = config.model("artifacts")
+MAX_COMMITS = 150
+
+
+def git_history(repo: Path) -> str | None:
+    try:
+        r = subprocess.run(
+            ["git", "-C", str(repo), "log", f"-n{MAX_COMMITS}", "--no-merges",
+             "--pretty=format:%h %s%n%b%n---"],
+            capture_output=True, text=True, timeout=30,
+        )
+    except (subprocess.SubprocessError, OSError) as e:
+        log.error("git failed: %s", e)
+        return None
+    if r.returncode != 0:
+        log.info("Not a git repo or no history: %s", repo)
+        return None
+    return r.stdout[:24000]
+
+
+PROMPT = """Below are recent git commits (subjects and bodies) from the project "{project}".
+Extract durable lessons that should change how a coding assistant works in THIS repo:
+recurring bug classes, things that had to be reverted (and why), non-obvious gotchas,
+and conventions revealed by fix commits. These are situational (Layer B) rules.
+
+Be strict: only real, recurring or hard-won signal evident in the history, not generic
+advice. Return at most 8 of the strongest. If nothing solid, return {{"rules": []}}.
+
+Return ONLY JSON: {{"rules": [{{"rule": "imperative, self-contained", "evidence": "which commits/pattern"}}]}}
+
+=== COMMITS ===
+{history}"""
+
+
+def ingest(repo: Path) -> int:
+    history = git_history(repo)
+    if not history or len(history) < 200:
+        log.info("No usable history to ingest.")
+        return 0
+    project = repo.name
+    raw = api_call(MODEL, PROMPT.format(project=project, history=history), max_tokens=2500)
+    if raw is None:
+        return 0
+    result = parse_json_block(raw)
+    if not isinstance(result, dict):
+        return 0
+    rules = result.get("rules", [])
+    now = datetime.now(timezone.utc).isoformat()
+    CANDIDATES.mkdir(parents=True, exist_ok=True)
+    written = 0
+    for item in rules:
+        text = (item.get("rule") or "").strip()
+        if not text:
+            continue
+        scope = project.lower()
+        slug = f"{scope}-{slugify(text)}"
+        meta = {
+            "id": slug, "layer": "B", "scope": scope, "status": "candidate",
+            "created": now, "source": f"git:{project}",
+            "evidence": (item.get("evidence") or "").replace('"', "'"),
+        }
+        write_note(CANDIDATES / f"{slug}.md", meta, text)
+        written += 1
+        log.info("  CANDIDATE [%s] %s", scope, slug)
+    log.info("Ingested %d candidate rule(s) from %s history.", written, project)
+    return written
+
+
+if __name__ == "__main__":
+    args = [a for a in sys.argv[1:] if not a.startswith("--")]
+    repo = Path(args[0]) if args else Path.cwd()
+    ingest(repo)

cogmem/cli.py

@@ -0,0 +1,169 @@
+"""
+cogmem — Python CLI entry point (console_scripts: ``cogmem``).
+
+Mirrors the bash ``cogmem`` dispatcher so a ``pip install cogmem`` gets the same
+commands. Most subcommands delegate to a module's ``__main__`` via runpy, reusing
+the exact tested code paths; ``recall``, ``status``, and ``init`` are handled
+directly. ``init`` performs the post-install wiring the clone installer's
+install.sh does: Claude Code hooks, the warm daemon, and the recall index.
+"""
+
+import os
+import runpy
+import sys
+from pathlib import Path
+
+COGMEM_HOME = Path(os.environ.get("COGMEM_HOME", Path.home() / ".claude" / "cogmem"))
+
+USAGE = (
+    "Usage: cogmem [status|doctor|trust|recall|note|guard|review|capture|mcp|"
+    "consolidate|index|verify|init]"
+)
+
+# subcommand -> (module, prefix args prepended to the user's args)
+_DELEGATE = {
+    "doctor": ("cogmem.metrics", ["doctor"]),
+    "trust": ("cogmem.provenance", ["trust"]),
+    "witness": ("cogmem.provenance", ["witness"]),
+    "verify": ("cogmem.provenance", ["verify"]),
+    "receipt": ("cogmem.provenance", ["receipt"]),
+    "statement": ("cogmem.provenance", ["statement"]),
+    "sign-vault": ("cogmem.provenance", ["sign-vault"]),
+    "provenance": ("cogmem.provenance", []),
+    "review": ("cogmem.review", []),
+    "model": ("cogmem.usermodel", []),
+    "progress": ("cogmem.narrative", []),
+    "note": ("cogmem.note", []),
+    "capture": ("cogmem.acquire", []),
+    "guard": ("cogmem.guard", []),
+    "ingest": ("cogmem.artifacts", []),
+    "tune": ("cogmem.tune", []),
+    "eval": ("cogmem.eval", []),
+    "consolidate": ("cogmem.consolidate", []),
+    "index": ("cogmem.index", []),
+    "mcp": ("cogmem.mcp_server", []),
+}
+
+
+def _delegate(module: str, argv: list[str]) -> int:
+    sys.argv = [module.rsplit(".", 1)[-1], *argv]
+    try:
+        runpy.run_module(module, run_name="__main__")
+    except SystemExit as e:  # modules call sys.exit; treat as their return code
+        return int(e.code or 0)
+    return 0
+
+
+def _recall(args: list[str]) -> int:
+    from cogmem import config, recall
+
+    if not args:
+        sys.stdout.write("(no relevant memories)\n")
+        return 0
+    query = args[0]
+    cfg = config.load()
+    try:
+        results = recall.recall(query, k=3, scope=None)
+        results = recall.filter_results(results, cfg["recall_floor"], cfg["recall_gap"])
+    except Exception:  # noqa: BLE001 — daemon down / cold: match the fail-open CLI contract
+        results = []
+    if not results:
+        sys.stdout.write("(no relevant memories)\n")
+        return 0
+    for r in results:
+        sys.stdout.write("- " + r["text"] + "\n")
+    return 0
+
+
+def _status() -> int:
+    from cogmem.common import SOCK_PATH
+
+    _delegate("cogmem.metrics", [])
+    warm = "warm" if _daemon_alive(SOCK_PATH) else "cold (lazy-spawns)"
+    sys.stdout.write(f"Daemon:                   {warm}\n")
+    pending = COGMEM_HOME / "vault" / "pending"
+    n = len(list(pending.glob("*.md"))) if pending.exists() else 0
+    if n:
+        sys.stdout.write(f"-> {n} rule(s) await approval: cogmem review list\n")
+    return 0
+
+
+def _daemon_alive(sock: Path) -> bool:
+    if not sock.exists():
+        return False
+    import socket
+
+    try:
+        c = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        c.settimeout(1.0)
+        c.connect(str(sock))
+        c.sendall(b'{"cmd":"ping"}\n')
+        ok = b"ok" in c.recv(64)
+        c.close()
+        return ok
+    except OSError:
+        return False
+
+
+def _init() -> int:
+    """Post-install wiring, idempotent: record the cogmem interpreter, materialize
+    the hook scripts under COGMEM_HOME, wire them into settings.json, build the
+    recall index. Makes a pip install a full Claude Code integration, not just a CLI."""
+    from importlib import resources
+
+    from cogmem import wire_hooks
+
+    COGMEM_HOME.mkdir(parents=True, exist_ok=True)
+    # The hooks are bash; record the interpreter that can `import cogmem` so they can
+    # invoke `python -m cogmem.<module>` regardless of how cogmem was installed.
+    (COGMEM_HOME / ".cogmem-python").write_text(sys.executable + "\n")
+
+    hooks_dir = COGMEM_HOME / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        packaged = resources.files("cogmem") / "hooks"
+        count = 0
+        for entry in packaged.iterdir():
+            if entry.name.endswith(".sh"):
+                dest = hooks_dir / entry.name
+                dest.write_text(entry.read_text())
+                dest.chmod(0o755)
+                count += 1
+        sys.stdout.write(f"   hooks: materialized {count} script(s) to {hooks_dir}\n")
+    except (FileNotFoundError, ModuleNotFoundError, OSError):
+        sys.stdout.write("   hooks: skipped (no packaged hook scripts found)\n")
+
+    claude_dir = Path(os.environ.get("CLAUDE_DIR", Path.home() / ".claude"))
+    added = wire_hooks.wire(claude_dir / "settings.json", hooks_dir)
+    sys.stdout.write(
+        f"   settings: {added} hook(s) added, {len(wire_hooks.WIRING) - added} already present\n"
+    )
+
+    # Build the recall index if the recall extra is installed; harmless no-op otherwise.
+    try:
+        _delegate("cogmem.index", [])
+    except ModuleNotFoundError:
+        sys.stdout.write("   index: skipped (install the [recall] extra for semantic recall)\n")
+    sys.stdout.write("cogmem initialized. Try:  cogmem status\n")
+    return 0
+
+
+def main() -> int:
+    argv = sys.argv[1:]
+    cmd = argv[0] if argv else "status"
+    rest = argv[1:]
+    if cmd == "status":
+        return _status()
+    if cmd == "recall":
+        return _recall(rest)
+    if cmd == "init":
+        return _init()
+    if cmd in _DELEGATE:
+        module, prefix = _DELEGATE[cmd]
+        return _delegate(module, prefix + rest)
+    sys.stderr.write(USAGE + "\n")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cogmem/common.py

@@ -0,0 +1,115 @@
+"""Shared helpers for the cogmem engine: API access and frontmatter I/O.
+
+The markdown files are the source of truth. Frontmatter is a small, fixed set of
+scalar fields, so a minimal parser is used rather than pulling in a YAML dependency.
+"""
+
+import json
+import logging
+import os
+import urllib.request
+import urllib.error
+from pathlib import Path
+
+log = logging.getLogger("cogmem")
+
+COGMEM = Path(os.environ.get("COGMEM_HOME", Path.home() / ".claude" / "cogmem"))
+VAULT = COGMEM / "vault"
+CLAUDE_DIR = Path.home() / ".claude"
+
+# Derived runtime artifacts live under COGMEM_HOME, NOT next to the code: a pip
+# install runs from site-packages (read-only, shared across COGMEM_HOMEs), so the
+# recall socket and semantic index must sit in the user's home to stay writable and
+# per-install isolated.
+SOCK_PATH = COGMEM / "recall.sock"
+INDEX_DB = COGMEM / "index.db"
+
+API_URL = "https://api.anthropic.com/v1/messages"
+
+
+def api_call(model: str, prompt: str, max_tokens: int) -> str | None:
+    key = os.environ.get("ANTHROPIC_API_KEY")
+    if not key:
+        log.error("ANTHROPIC_API_KEY not set")
+        return None
+    body = json.dumps(
+        {
+            "model": model,
+            "max_tokens": max_tokens,
+            "messages": [{"role": "user", "content": prompt}],
+        }
+    ).encode()
+    req = urllib.request.Request(
+        API_URL,
+        data=body,
+        headers={
+            "x-api-key": key,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=90) as resp:
+            return json.loads(resp.read())["content"][0]["text"]
+    except urllib.error.HTTPError as e:
+        log.error("API HTTP %s: %s", e.code, e.read()[:200])
+    except Exception as e:  # noqa: BLE001 — callers run inside hooks; never crash a session
+        log.error("API call failed: %s", e)
+    return None
+
+
+def parse_json_block(text: str) -> object | None:
+    text = text.strip()
+    if text.startswith("```"):
+        text = text.split("\n", 1)[1].rsplit("```", 1)[0].strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        log.warning("Could not parse model output: %s", text[:200])
+        return None
+
+
+def read_note(path: Path) -> tuple[dict, str]:
+    """Return (frontmatter_dict, body) for a markdown note. Tolerant of files
+    without frontmatter (returns empty dict + full text as body)."""
+    text = path.read_text(errors="replace")
+    if not text.startswith("---\n"):
+        return {}, text.strip()
+    _, fm, body = text.split("---\n", 2)
+    meta: dict = {}
+    for line in fm.splitlines():
+        if ":" not in line:
+            continue
+        k, v = line.split(":", 1)
+        v = v.strip()
+        if len(v) >= 2 and v[0] == v[-1] and v[0] in "\"'":
+            v = v[1:-1]
+        meta[k.strip()] = v
+    return meta, body.strip()
+
+
+def validate_note(meta: dict, body: str) -> list[str]:
+    """Return a list of problems with a note (empty list = valid). Used to keep
+    malformed model output out of the vault."""
+    errors = []
+    if not meta.get("id"):
+        errors.append("missing id")
+    layer = meta.get("layer")
+    if layer and str(layer).upper() not in ("A", "B"):
+        errors.append(f"invalid layer: {layer}")
+    if not body or not body.strip():
+        errors.append("empty body")
+    return errors
+
+
+def write_note(path: Path, meta: dict, body: str) -> None:
+    lines = ["---"]
+    for k, v in meta.items():
+        v = str(v)
+        if any(c in v for c in ':"#') or v == "":
+            v = '"' + v.replace('"', "'") + '"'
+        lines.append(f"{k}: {v}")
+    lines.append("---\n")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines) + "\n" + body.strip() + "\n")

cogmem/config.py

@@ -0,0 +1,67 @@
+"""
+Cognitive Memory — tunable config
+
+Thresholds that self-regulation adjusts live, kept in config.json so the recall
+path reads current values without code edits and `cogmem tune` can rewrite them.
+"""
+
+import json
+from pathlib import Path
+
+CONFIG = Path(__file__).resolve().parent / "config.json"
+
+# LLM ids per pipeline role and the local recall models, in one place so upgrades
+# don't need code edits and a config.json can override any of them.
+_MODELS = {
+    "detect": "claude-haiku-4-5-20251001",  # cheap signal check, every session
+    "extract": "claude-sonnet-4-6",  # rule extraction, only on signal
+    "judge": "claude-haiku-4-5-20251001",  # feedback verdicts
+    "consolidate": "claude-sonnet-4-6",  # dedup classification
+    "selfmodel": "claude-sonnet-4-6",
+    "projectstate": "claude-sonnet-4-6",
+    "usermodel": "claude-sonnet-4-6",
+    "narrative": "claude-sonnet-4-6",
+    "artifacts": "claude-sonnet-4-6",
+    "eval_gen": "claude-haiku-4-5-20251001",
+}
+_EMBED_MODEL = "BAAI/bge-small-en-v1.5"
+_RERANK_MODEL = "Xenova/ms-marco-MiniLM-L-6-v2"
+
+DEFAULTS = {
+    "recall_floor": 0.62,
+    "recall_gap": 6.0,
+    "provenance_enforce": False,
+    "keychain": False,
+    "witness_did": None,
+    "user_name": "the user",
+    "models": _MODELS,
+    "embed_model": _EMBED_MODEL,
+    "rerank_model": _RERANK_MODEL,
+}
+
+
+def load() -> dict:
+    if CONFIG.exists():
+        try:
+            return {**DEFAULTS, **json.loads(CONFIG.read_text())}
+        except (json.JSONDecodeError, OSError):
+            return dict(DEFAULTS)
+    return dict(DEFAULTS)
+
+
+def model(role: str) -> str:
+    """LLM id for a pipeline role; a partial "models" map in config.json overrides
+    individual roles, falling back to the built-in default for any role it omits."""
+    return load().get("models", {}).get(role, _MODELS[role])
+
+
+def embed_model() -> str:
+    return load().get("embed_model", _EMBED_MODEL)
+
+
+def rerank_model() -> str:
+    return load().get("rerank_model", _RERANK_MODEL)
+
+
+def save(cfg: dict) -> None:
+    CONFIG.write_text(json.dumps(cfg, indent=2))