leos-agent 7.0.0 → 10.2.0

package/scripts/memory.py

@@ -1,744 +0,0 @@
-#!/usr/bin/env python3
-"""memory: durable, cross-harness facts for leos-agent.
-
-Same CODE/DATA split as state.py: this file ships inside a plugin cache that an
-update can wipe, so the store is always resolved from the environment, never
-from __file__. The canonical store is the only writable copy of a memory:
-
-  ${LEOS_AGENT_LOCAL_PATH:-$HOME/.leos-agent-local}/memory/
-    global/<slug>.md              one fact per file
-    repo/<repo-slug>/<slug>.md    one fact per file, scoped to a repo/project
-    MEMORY.md                     generated index, human and model readable
-    index.json                    generated index, machine readable
-    .trash/                       forgotten facts, never auto-pruned
-
-The .md files are the sole source of truth. MEMORY.md, index.json, and every
-projected block are derived and rebuilt from scratch on each mutation, which is
-what makes concurrent writers safe: nothing is ever merged into a derived file.
-
-Harness-native memory surfaces receive a one-way PROJECTION of the GLOBAL facts
-only. Every per-user surface (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ...) is
-loaded in every repo, so projecting repo-scoped facts there would leak one
-project's memories into unrelated sessions. Repo facts reach the model through
-the session-start context block instead, which knows the working directory.
-Do not "fix" this by projecting repo facts.
-
-  memory.py write  <scope> <type> <title> [--repo KEY]   body on stdin
-  memory.py list   [<scope>] [--repo KEY]
-  memory.py read   <ref>
-  memory.py forget <ref>
-  memory.py reindex
-  memory.py project
-  memory.py context [--repo KEY | --cwd DIR]
-  memory.py session [--cwd DIR]
-  memory.py key    [<dir>]
-  memory.py path   [<ref>]
-
-A <ref> is the store-relative path without .md: "global/<slug>" or
-"repo/<repo-slug>/<slug>". Mutating verbs are serialized with the same flock
-mechanism state.py uses; list/read/context/key/path are lock-free because every
-write is atomic, so a reader sees the old file or the new one, never a torn one.
-context and session always exit 0 and print nothing on failure: they run inside
-session bootstraps that must degrade to "no memory", never take the policy down.
-
-Set LEOS_AGENT_NO_PROJECT=1 to disable writing to native surfaces entirely.
-Exit codes: 0 ok, non-zero on error (except context/session, which never fail).
-"""
-import datetime
-import contextlib
-import hashlib
-import json
-import os
-import re
-import shutil
-import subprocess
-import sys
-import tempfile
-import unicodedata
-
-# state.py is a sibling. Running memory.py as a script puts scripts/ on sys.path
-# automatically, but hooks/session-start.py imports this module (its own
-# sys.path[0] is hooks/) and the tests load it with spec_from_file_location,
-# which adds nothing. Fixing the path here keeps all three entry points working.
-_HERE = os.path.dirname(os.path.abspath(__file__))
-if _HERE not in sys.path:
-    sys.path.insert(0, _HERE)
-import state  # noqa: E402
-
-# The closed type enum. This is the primary anti-noise gate: a fact that fits
-# none of these is not a memory. Keep in sync with skills/memory/SKILL.md.
-TYPES = ("preference", "convention", "environment", "decision", "person")
-
-SETUP_STATE = "setup"
-MEMORY_CONTEXT_LIMIT = 4000
-MAX_BODY = 1200
-MAX_TITLE = 80
-MAX_DESCRIPTION = 160
-MAX_FACTS_PER_SCOPE = 500
-
-BEGIN = "<!-- BEGIN leos-agent memory (generated by scripts/memory.py; edits are overwritten) -->"
-END = "<!-- END leos-agent memory -->"
-
-FRONTMATTER_KEYS = ("title", "type", "description", "scope", "repo", "created", "updated")
-
-
-# --------------------------------------------------------------------------
-# paths
-# --------------------------------------------------------------------------
-
-def memory_root():
-    return os.path.join(state._data_root(), "memory")
-
-
-def _lock_path():
-    return os.path.join(memory_root(), "index.json")
-
-
-def fact_slug(title):
-    s = unicodedata.normalize("NFKD", title).encode("ascii", "ignore").decode("ascii")
-    s = re.sub(r"[^A-Za-z0-9]+", "-", s).strip("-").lower()[:48].strip("-")
-    return s or "fact"
-
-
-def repo_slug(key):
-    """Directory name for a repo key.
-
-    The hash is taken over the ORIGINAL key, before lowercasing and character
-    substitution, so "owner/repo", "owner-repo" and "Owner/Repo" land in three
-    different directories. The readable half is lowercased so the directory
-    name itself is byte-identical on case-sensitive ext4 and case-insensitive
-    APFS — without that split the two platforms disagree about collisions.
-    """
-    readable = re.sub(r"[^A-Za-z0-9._-]+", "-", key).strip("-.").lower()[:60].strip("-.")
-    digest = hashlib.sha256(key.encode("utf-8")).hexdigest()[:8]
-    return f"{readable or 'project'}--{digest}"
-
-
-def _git(cwd, *args):
-    try:
-        done = subprocess.run(
-            ["git", "-C", cwd, *args],
-            capture_output=True, text=True, timeout=2,
-        )
-    except Exception:
-        return None
-    out = done.stdout.strip()
-    return out if done.returncode == 0 and out else None
-
-
-def repo_key(cwd=None):
-    """state.py's key convention, implemented once: owner/repo, else abs path."""
-    cwd = cwd or os.getcwd()
-    url = _git(cwd, "remote", "get-url", "origin")
-    if url:
-        m = re.search(r"[:/]([^/:]+)/([^/]+?)(?:\.git)?/?$", url)
-        if m:
-            return f"{m.group(1)}/{m.group(2)}"
-    return _git(cwd, "rev-parse", "--show-toplevel") or os.path.abspath(cwd)
-
-
-def ref_path(ref):
-    root = memory_root()
-    parts = [p for p in ref.split("/") if p]
-    if ".." in parts or os.path.isabs(ref) or len(parts) not in (2, 3):
-        sys.exit(f"memory: {ref!r} is not a valid memory ref")
-    if parts[0] not in ("global", "repo"):
-        sys.exit(f"memory: {ref!r} must start with 'global/' or 'repo/'")
-    return os.path.join(root, *parts) + ".md"
-
-
-# --------------------------------------------------------------------------
-# fact files
-# --------------------------------------------------------------------------
-
-def _private_dir(path):
-    """Create a canonical Leo-owned directory with private permissions."""
-    os.makedirs(path, mode=0o700, exist_ok=True)
-    os.chmod(path, 0o700)
-    return path
-
-
-def _memory_dirs(scope=None, repo=None):
-    root = _private_dir(memory_root())
-    if scope == "global":
-        return _private_dir(os.path.join(root, "global"))
-    if scope == "repo":
-        repo_root = _private_dir(os.path.join(root, "repo"))
-        return _private_dir(os.path.join(repo_root, repo_slug(repo)))
-    return root
-
-
-@contextlib.contextmanager
-def _memory_lock():
-    """The one lock boundary for every memory read-modify-write operation."""
-    _memory_dirs()
-    with state._locked(_lock_path()):
-        yield
-
-
-def _atomic_text(path, text, mode=0o600):
-    """Markdown twin of state.atomic_write, which json-dumps its argument."""
-    os.makedirs(os.path.dirname(path), exist_ok=True)
-    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path), suffix=".tmp")
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as fh:
-            fh.write(text)
-        os.chmod(tmp, mode)  # mkstemp is 0600; callers choose the final contract.
-        os.replace(tmp, path)
-    except BaseException:
-        try:
-            os.unlink(tmp)
-        except OSError:
-            pass
-        raise
-
-
-def render_fact(meta, body):
-    lines = ["---"]
-    for key in FRONTMATTER_KEYS:
-        value = meta.get(key)
-        if value is None:
-            continue
-        # JSON-quoted scalars are valid YAML and parse with json.loads, which
-        # keeps colons, quotes and em-dashes safe without a YAML dependency.
-        lines.append(f"{key}: {json.dumps(value, ensure_ascii=False)}")
-    lines.append("---")
-    lines.append("")
-    lines.append(body.strip())
-    return "\n".join(lines) + "\n"
-
-
-def parse_fact(path):
-    """Return (meta, body) or None when the file is not a readable fact."""
-    try:
-        with open(path, encoding="utf-8", errors="replace") as fh:
-            text = fh.read()
-    except OSError:
-        return None
-    lines = text.splitlines()
-    if not lines or lines[0].strip() != "---":
-        return None
-    meta = {}
-    for index, line in enumerate(lines[1:], 1):
-        if line.strip() == "---":
-            body = "\n".join(lines[index + 1:]).strip()
-            if "title" not in meta or "type" not in meta:
-                return None
-            return meta, body
-        key, _, raw = line.partition(":")
-        key = key.strip()
-        if key not in FRONTMATTER_KEYS:
-            continue
-        raw = raw.strip()
-        try:
-            meta[key] = json.loads(raw)
-        except json.JSONDecodeError:
-            meta[key] = raw.strip('"')
-    return None
-
-
-def _now():
-    return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-
-def _scope_dir(scope, repo=None):
-    if scope == "global":
-        return os.path.join(memory_root(), "global")
-    return os.path.join(memory_root(), "repo", repo_slug(repo))
-
-
-def _iter_facts():
-    """Yield (ref, meta, body) for every readable fact, plus unreadable refs."""
-    root = memory_root()
-    unreadable = []
-    facts = []
-    for scope_rel in ("global",) + tuple(
-        os.path.join("repo", d)
-        for d in sorted(_listdir(os.path.join(root, "repo")))
-    ):
-        directory = os.path.join(root, scope_rel)
-        for name in sorted(_listdir(directory)):
-            if not name.endswith(".md"):
-                continue
-            ref = f"{scope_rel}/{name[:-3]}"
-            parsed = parse_fact(os.path.join(directory, name))
-            if parsed is None:
-                unreadable.append(ref)
-                continue
-            facts.append((ref, parsed[0], parsed[1]))
-    return facts, unreadable
-
-
-def _listdir(path):
-    try:
-        return [n for n in os.listdir(path) if not n.startswith(".")]
-    except OSError:
-        return []
-
-
-# --------------------------------------------------------------------------
-# index
-# --------------------------------------------------------------------------
-
-def _reindex_unlocked():
-    facts, unreadable = _iter_facts()
-    entries = []
-    repos = {}
-    for ref, meta, _ in facts:
-        entries.append({
-            "ref": ref,
-            "title": meta.get("title", ref),
-            "type": meta.get("type", "convention"),
-            "description": meta.get("description", ""),
-            "scope": meta.get("scope", "global"),
-            "repo": meta.get("repo"),
-            "updated": meta.get("updated", ""),
-        })
-        if meta.get("scope") == "repo" and meta.get("repo"):
-            repos[repo_slug(meta["repo"])] = meta["repo"]
-    index = {
-        "version": 1,
-        "generated": _now(),
-        "facts": entries,
-        "repos": repos,
-        "unreadable": unreadable,
-    }
-    _atomic_text(os.path.join(memory_root(), "index.json"),
-                 json.dumps(index, indent=1, sort_keys=True) + "\n")
-    _atomic_text(os.path.join(memory_root(), "MEMORY.md"), _render_memory_md(index))
-    return index
-
-
-def reindex():
-    with _memory_lock():
-        return _reindex_unlocked()
-
-
-def _load_index():
-    """Never state.load(): it sys.exit()s on corruption, breaking fail-open."""
-    try:
-        with open(os.path.join(memory_root(), "index.json"), encoding="utf-8") as fh:
-            data = json.load(fh)
-        if isinstance(data, dict) and isinstance(data.get("facts"), list):
-            return data
-    except Exception:
-        return None
-    return None
-
-
-def _entry_line(entry):
-    line = f"- [{entry['title']}]({entry['ref']}.md) — {entry['type']}: {entry['description']}"
-    return line[:MAX_DESCRIPTION + 120]
-
-
-def _render_memory_md(index):
-    out = [
-        "<!-- Generated by scripts/memory.py; do not edit. Facts live in the .md files. -->",
-        "# Memory index",
-        "",
-    ]
-    globals_ = [e for e in index["facts"] if e["scope"] == "global"]
-    if globals_:
-        out += ["## Global", ""] + [_entry_line(e) for e in globals_] + [""]
-    by_repo = {}
-    for entry in index["facts"]:
-        if entry["scope"] == "repo":
-            by_repo.setdefault(entry.get("repo") or "unknown", []).append(entry)
-    for repo in sorted(by_repo):
-        out += [f"## {repo}", ""] + [_entry_line(e) for e in by_repo[repo]] + [""]
-    return "\n".join(out).rstrip("\n") + "\n"
-
-
-def render_context(index, repo=None, limit=MEMORY_CONTEXT_LIMIT):
-    """The block shared by projection and session injection."""
-    if index is None or not index.get("facts"):
-        return ""
-    globals_ = [e for e in index["facts"] if e["scope"] == "global"]
-    mine = [e for e in index["facts"] if e["scope"] == "repo" and e.get("repo") == repo] if repo else []
-    if not globals_ and not mine:
-        return ""
-    head = [
-        "# Memory (leos-agent)",
-        "Facts already learned. Each line is a pointer, not the fact — read the "
-        "file before relying on one, and prefer what you can observe right now.",
-        f"Store: {memory_root()}",
-    ]
-    # Both tail lines are appended after the entry loop, so their worst-case
-    # length is reserved up front — otherwise the block overshoots the limit by
-    # exactly the tail it was about to add.
-    unreadable = len(index.get("unreadable") or ())
-    reserve = len(f"- …and {len(globals_) + len(mine)} more (see MEMORY.md in the store).") + 1
-    if unreadable:
-        reserve += len(
-            f"- ({unreadable} memory files could not be read — run memory.py reindex)."
-        ) + 1
-
-    out = list(head)
-    dropped = 0
-    for title, entries in (("## Global", globals_), (f"## {repo}", mine)):
-        if not entries:
-            continue
-        section = ["", title, ""]
-        for entry in entries:
-            line = _entry_line(entry)
-            if len("\n".join(out + section + [line])) + reserve > limit:
-                dropped += 1
-                continue
-            section.append(line)
-        if len(section) > 3:
-            out += section
-    if dropped:
-        out.append(f"- …and {dropped} more (see MEMORY.md in the store).")
-    if unreadable:
-        out.append(
-            f"- ({unreadable} memory files could not be read — run memory.py reindex)."
-        )
-    return "\n".join(out).rstrip("\n") + "\n"
-
-
-# --------------------------------------------------------------------------
-# projection
-# --------------------------------------------------------------------------
-
-def hermes_home():
-    return os.environ.get("HERMES_HOME") or os.path.join(os.path.expanduser("~"), ".hermes")
-
-
-def hermes_enabled():
-    """Hermes projection is opt-in, through leo:setup.
-
-    Its only user-owned global file is SOUL.md, the agent's own identity
-    prompt and the opening section of every system prompt on that machine —
-    a blast radius the other four targets do not have. `hermes plugins
-    install` has no install-time hook (register() runs at session start), so
-    there is no moment during installation at which consent could be implied.
-    """
-    try:
-        data = state.load(state.state_file(SETUP_STATE))
-        return bool((data.get("hermes") or {}).get("projectMemory"))
-    except SystemExit:
-        # state.load() exits hard on a corrupt file. Projection must degrade
-        # to "not enabled" rather than take the whole session down with it.
-        return False
-    except Exception:
-        return False
-
-
-def projection_targets():
-    """(harness, gate_dir, file, owned, require_file) — gate_dir must exist.
-
-    Never mkdir a harness config directory: its absence means the harness is
-    not installed, and creating ~/.cursor for a non-Cursor user is exactly the
-    surprise this must not cause.
-
-    require_file extends that rule one step for Hermes: SOUL.md must already
-    exist too. Hermes falls back to a built-in persona when the file is
-    absent, so creating it would silently replace the user's agent identity —
-    the same class of surprise, one level down.
-    """
-    claude = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.join(os.path.expanduser("~"), ".claude")
-    codex = os.environ.get("CODEX_HOME") or os.path.join(os.path.expanduser("~"), ".codex")
-    xdg = os.environ.get("XDG_CONFIG_HOME") or os.path.join(os.path.expanduser("~"), ".config")
-    opencode = os.path.join(xdg, "opencode")
-    cursor = os.path.join(os.path.expanduser("~"), ".cursor")
-    targets = [
-        ("claude", claude, os.path.join(claude, "CLAUDE.md"), False, False),
-        ("codex", codex, os.path.join(codex, "AGENTS.md"), False, False),
-        ("opencode", opencode, os.path.join(opencode, "AGENTS.md"), False, False),
-        ("cursor", os.path.join(cursor, "rules"),
-         os.path.join(cursor, "rules", "leos-agent-memory.mdc"), True, False),
-    ]
-    if hermes_enabled():
-        home = hermes_home()
-        targets.append(("hermes", home, os.path.join(home, "SOUL.md"), False, True))
-    return targets
-
-
-def _backup_once(path):
-    """One copy of the user's original, before Leo's first ever write to it."""
-    backup = path + ".leo-backup"
-    if os.path.exists(path) and not os.path.exists(backup):
-        shutil.copy2(path, backup)
-
-
-def splice(existing, block):
-    """Return the new file text, or None when the markers are unbalanced.
-
-    Content outside the markers is preserved byte-for-byte. An unbalanced or
-    duplicated marker pair means something else edited the file: leave it
-    completely alone rather than guessing where the managed region ends.
-    """
-    begins = existing.count(BEGIN)
-    ends = existing.count(END)
-    if begins > 1 or ends > 1 or begins != ends:
-        return None
-    if begins == 0:
-        if not existing.strip():
-            return block
-        return existing.rstrip("\n") + "\n\n" + block
-    start = existing.index(BEGIN)
-    stop = existing.index(END) + len(END)
-    if stop < start:
-        return None
-    if not block:
-        head = existing[:start].rstrip("\n")
-        tail = existing[stop:].lstrip("\n")
-        joined = (head + ("\n\n" if head and tail else "") + tail).rstrip("\n")
-        return joined + "\n" if joined else ""
-    return existing[:start] + block.rstrip("\n") + existing[stop:]
-
-
-def _wrap(body):
-    return f"{BEGIN}\n{body.rstrip()}\n{END}\n" if body else ""
-
-
-def _hermes_absent(targets):
-    """Hermes always appears in the report, enabled or not — a harness that is
-    silently missing from the list reads as one that was projected."""
-    if any(t[0] == "hermes" for t in targets):
-        return []
-    return [{"harness": "hermes", "path": None, "status": "skipped:opt-in-required"}]
-
-
-def _project_unlocked(index=None):
-    if os.environ.get("LEOS_AGENT_NO_PROJECT") == "1":
-        targets = projection_targets()
-        return [{"harness": h, "path": f, "status": "skipped:disabled"}
-                for h, _, f, _, _ in targets] + [
-            {"harness": t["harness"], "path": None, "status": "skipped:disabled"}
-            for t in _hermes_absent(targets)]
-    if index is None:
-        index = _load_index() or _reindex_unlocked()
-    # GLOBAL facts only — see the module docstring.
-    body = render_context({"facts": [e for e in index["facts"] if e["scope"] == "global"],
-                           "unreadable": index.get("unreadable", [])})
-    block = _wrap(body)
-    results = []
-    targets = projection_targets()
-    for harness, gate, path, owned, require_file in targets:
-        results.append({"harness": harness, "path": path,
-                        "status": _project_one(gate, path, owned, block, require_file)})
-    results.extend(_hermes_absent(targets))
-    return results
-
-
-def project(index=None):
-    with _memory_lock():
-        return _project_unlocked(index)
-
-
-def _project_one(gate, path, owned, block, require_file=False):
-    try:
-        if not os.path.isdir(gate):
-            return "skipped:no-dir"
-        if require_file and not os.path.exists(path):
-            # Hermes only. Creating SOUL.md would displace the built-in
-            # persona the harness uses when it is absent.
-            return "skipped:no-soul"
-        target = os.path.realpath(path) if os.path.islink(path) else path
-        existing = ""
-        # New generated projections are private. If the user already owns the
-        # target, retain its existing mode exactly instead of tightening it
-        # behind their back.
-        mode = 0o600
-        if os.path.exists(target):
-            if not owned:
-                mode = os.stat(target).st_mode & 0o777
-            with open(target, encoding="utf-8", errors="replace") as fh:
-                existing = fh.read()
-        if owned:
-            if not block:
-                if os.path.exists(target):
-                    os.unlink(target)
-                    return "removed"
-                return "unchanged"
-            new = ("---\ndescription: Leo's Agent projected memory (generated)\n"
-                   "alwaysApply: true\n---\n" + block)
-        else:
-            new = splice(existing, block)
-            if new is None:
-                return "error: unbalanced markers"
-        if new == existing:
-            return "unchanged"
-        if existing:
-            _backup_once(target)
-        if not new.strip():
-            os.unlink(target)
-            return "removed"
-        _atomic_text(target, new, mode)
-        return "written"
-    except OSError as exc:
-        return f"error: {exc.strerror or exc}"
-
-
-# --------------------------------------------------------------------------
-# verbs
-# --------------------------------------------------------------------------
-
-def write_fact(scope, type_, title, body, repo=None):
-    if scope not in ("global", "repo"):
-        sys.exit("memory: scope must be 'global' or 'repo'")
-    if type_ not in TYPES:
-        sys.exit(f"memory: type must be one of {', '.join(TYPES)}")
-    if scope == "repo" and not repo:
-        sys.exit("memory: --repo KEY is required for a repo-scoped memory")
-    title = title.strip()
-    if not title or len(title) > MAX_TITLE:
-        sys.exit(f"memory: title must be 1..{MAX_TITLE} characters")
-    body = body.strip()
-    if not body:
-        sys.exit("memory: body is empty — pass the fact on stdin")
-    if len(body) > MAX_BODY:
-        sys.exit(f"memory: body is {len(body)} chars (max {MAX_BODY}) — shorten it or split it in two")
-
-    directory = _scope_dir(scope, repo)
-    slug = fact_slug(title)
-    with _memory_lock():
-        _memory_dirs(scope, repo)
-        path, action, created = _resolve_slot(directory, slug, type_, title)
-        if action == "created" and len(_listdir(directory)) >= MAX_FACTS_PER_SCOPE:
-            sys.exit(f"memory: this scope is full ({MAX_FACTS_PER_SCOPE} facts) — consolidate or forget first")
-        now = _now()
-        meta = {
-            "title": title,
-            "type": type_,
-            "description": body.splitlines()[0].strip()[:MAX_DESCRIPTION],
-            "scope": scope,
-            "created": created or now,
-            "updated": now,
-        }
-        if scope == "repo":
-            meta["repo"] = repo
-        _atomic_text(path, render_fact(meta, body))
-        index = _reindex_unlocked()
-        projection = _project_unlocked(index)
-    rel = os.path.relpath(path, memory_root())[:-3]
-    return {"action": action, "ref": rel, "path": path,
-            "description": meta["description"], "projection": projection}
-
-
-def _resolve_slot(directory, slug, type_, title):
-    """Only an exact title-and-type identity updates; collisions get -N."""
-    candidate = os.path.join(directory, f"{slug}.md")
-    parsed = parse_fact(candidate) if os.path.exists(candidate) else None
-    if not os.path.exists(candidate):
-        return candidate, "created", None
-    if (parsed and parsed[0].get("type") == type_
-            and parsed[0].get("title") == title):
-        return candidate, "updated", parsed[0].get("created")
-    suffix = 2
-    while os.path.exists(os.path.join(directory, f"{slug}-{suffix}.md")):
-        existing = parse_fact(os.path.join(directory, f"{slug}-{suffix}.md"))
-        if (existing and existing[0].get("type") == type_
-                and existing[0].get("title") == title):
-            return (os.path.join(directory, f"{slug}-{suffix}.md"), "updated",
-                    existing[0].get("created"))
-        suffix += 1
-    return os.path.join(directory, f"{slug}-{suffix}.md"), "created", None
-
-
-def forget(ref):
-    path = ref_path(ref)
-    if not os.path.exists(path):
-        sys.exit(f"memory: no such memory {ref!r}")
-    stamp = datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%d%H%M%S")
-    trash = os.path.join(memory_root(), ".trash", os.path.dirname(ref))
-    with _memory_lock():
-        trash_root = _private_dir(os.path.join(memory_root(), ".trash"))
-        current = trash_root
-        for part in os.path.dirname(ref).split("/"):
-            current = _private_dir(os.path.join(current, part))
-        # Move, never unlink: automatic capture plus hard delete on the model's
-        # own judgment is a data-loss path, and the trash costs nothing.
-        destination = os.path.join(trash, f"{os.path.basename(ref)}.{stamp}.md")
-        shutil.move(path, destination)
-        index = _reindex_unlocked()
-        projection = _project_unlocked(index)
-    return {"forgotten": ref, "path": destination, "projection": projection}
-
-
-def session(cwd=None):
-    """One call for the bootstraps: refresh, project, return the block."""
-    with _memory_lock():
-        index = _reindex_unlocked()
-        _project_unlocked(index)
-        return render_context(index, repo=repo_key(cwd))
-
-
-FLAGS = ("--repo", "--cwd")
-
-
-def _split_args(argv):
-    """Positional args and flags. A flag consumes its value, so a title is
-    never silently joined with the repo key that followed --repo."""
-    positional, flags, index = [], {}, 0
-    while index < len(argv):
-        token = argv[index]
-        if token in FLAGS:
-            flags[token] = argv[index + 1] if index + 1 < len(argv) else None
-            index += 2
-            continue
-        if token.startswith("--"):
-            name, _, inline = token.partition("=")
-            if name in FLAGS and inline:
-                flags[name] = inline
-            index += 1
-            continue
-        positional.append(token)
-        index += 1
-    return positional, flags
-
-
-def main(argv):
-    verb = argv[0] if argv else ""
-    rest, flags = _split_args(argv[1:])
-    repo = flags.get("--repo")
-    cwd = flags.get("--cwd")
-
-    if verb in ("write", "save") and len(rest) >= 3:
-        body = sys.stdin.read()
-        print(json.dumps(write_fact(rest[0], rest[1], " ".join(rest[2:]), body, repo),
-                         indent=1, sort_keys=True))
-    elif verb == "list":
-        index = _load_index() or reindex()
-        entries = index["facts"]
-        if rest:
-            entries = [e for e in entries if e["scope"] == rest[0]]
-        if repo:
-            entries = [e for e in entries if e.get("repo") == repo]
-        print(json.dumps(entries, indent=1, sort_keys=True))
-    elif verb in ("read", "recall") and rest:
-        path = ref_path(rest[0])
-        if not os.path.exists(path):
-            sys.exit(f"memory: no such memory {rest[0]!r}")
-        with open(path, encoding="utf-8", errors="replace") as fh:
-            sys.stdout.write(fh.read())
-    elif verb == "forget" and rest:
-        print(json.dumps(forget(rest[0]), indent=1, sort_keys=True))
-    elif verb == "reindex":
-        index = reindex()
-        print(json.dumps({"facts": len(index["facts"]), "repos": len(index["repos"]),
-                          "unreadable": index["unreadable"]}, indent=1, sort_keys=True))
-    elif verb == "project":
-        print(json.dumps({"targets": project()}, indent=1, sort_keys=True))
-    elif verb == "context":
-        try:
-            sys.stdout.write(render_context(_load_index() or reindex(),
-                                            repo=repo or repo_key(cwd)))
-        except Exception:
-            pass
-    elif verb == "session":
-        try:
-            sys.stdout.write(session(cwd))
-        except Exception:
-            pass
-    elif verb == "key":
-        print(repo_key(rest[0] if rest else None))
-    elif verb == "path":
-        print(ref_path(rest[0]) if rest else memory_root())
-    else:
-        sys.exit(__doc__.strip())
-
-
-if __name__ == "__main__":
-    main(sys.argv[1:])