leos-agent 6.1.0 → 6.3.0

package/scripts/memory.py

@@ -0,0 +1,705 @@
+#!/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 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 _atomic_text(path, text, mode=0o644):
+    """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; these are readable config files
+        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():
+    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,
+    }
+    state.atomic_write(os.path.join(memory_root(), "index.json"), index)
+    _atomic_text(os.path.join(memory_root(), "MEMORY.md"), _render_memory_md(index))
+    return index
+
+
+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 _home(var, *parts):
+    base = os.environ.get(var)
+    if not base:
+        base = os.path.join(os.path.expanduser("~"), parts[0])
+        parts = parts[1:]
+    return os.path.join(base, *parts) if parts else base
+
+
+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(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()
+    # 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_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 = ""
+        mode = 0o644
+        if os.path.exists(target):
+            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 state._locked(_lock_path()):
+        os.makedirs(directory, exist_ok=True)
+        if len(_listdir(directory)) >= MAX_FACTS_PER_SCOPE:
+            sys.exit(f"memory: this scope is full ({MAX_FACTS_PER_SCOPE} facts) — consolidate or forget first")
+        path, action, created = _resolve_slot(directory, slug, type_)
+        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()
+        projection = project(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_):
+    """Same title+type updates in place; same title, different type gets -2."""
+    candidate = os.path.join(directory, f"{slug}.md")
+    parsed = parse_fact(candidate) if os.path.exists(candidate) else None
+    if parsed is None:
+        return candidate, ("created" if not os.path.exists(candidate) else "created"), None
+    if parsed[0].get("type") == type_:
+        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_:
+            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 state._locked(_lock_path()):
+        os.makedirs(trash, exist_ok=True)
+        # 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()
+        projection = project(index)
+    return {"forgotten": ref, "path": destination, "projection": projection}
+
+
+def session(cwd=None):
+    """One call for the bootstraps: refresh, project, return the block."""
+    index = reindex()
+    project(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:])