cogito-mem 0.2.0__py3-none-any.whl

cogito_mem/__init__.py

@@ -0,0 +1,29 @@
+"""cogito-mem: a fast, simple, local memory for agents.
+
+    from cogito_mem import Memory
+    mem = Memory()                      # ~/.cogito-mem, EmbeddingGemma 2 via llama.cpp
+    mem.handle({"op": "append", "items": [{"author": "user", "text": "..."}]})
+    mem.handle({"op": "query", "text": "..."})
+
+``Client`` sends the same dictionaries to the local service instead.
+"""
+
+__version__ = "0.2.0"
+
+__all__ = ["Memory", "Config", "Client", "ApiError", "__version__"]
+
+
+def __getattr__(name):  # keep `import cogito_mem` light for hooks and the MCP bridge
+    if name in ("Memory", "Config"):
+        from . import memory
+
+        return getattr(memory, name)
+    if name == "Client":
+        from .client import Client
+
+        return Client
+    if name == "ApiError":
+        from .errors import ApiError
+
+        return ApiError
+    raise AttributeError(name)

cogito_mem/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

cogito_mem/api.py

@@ -0,0 +1,226 @@
+"""Request validation for the two operations (requirements §3).
+
+Requests have static keys: an unknown key is an error, an optional key may be left
+out or set to null, and the defaults below fill it in.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from . import timeutil
+from .errors import invalid
+
+NAMESPACE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+KINDS = ("message", "piece", "digest", "statement")
+
+DEFAULT_NAMESPACE = "default"
+DEFAULT_THREAD = "default"
+DEFAULT_TOP_K = 10
+MAX_TOP_K = 100
+DEFAULT_MAX_TOKENS = 1000
+MAX_MAX_TOKENS = 100_000
+MAX_ITEMS = 1000
+MAX_TEXT_CHARS = 4_000_000
+
+_APPEND_KEYS = {"op", "namespace", "import", "items"}
+_ITEM_KEYS = {"thread_id", "author", "valid_at", "title", "text", "client_ref", "retracts"}
+_QUERY_KEYS = {"op", "namespace", "text", "context", "filter", "as_of", "top_k", "max_tokens"}
+_FILTER_KEYS = {"thread_id", "author", "kind", "valid_after", "valid_before", "include_retracted"}
+
+
+@dataclass
+class ItemIn:
+    author: str
+    text: str
+    thread_id: str = DEFAULT_THREAD
+    valid_at: int | None = None
+    title: str | None = None
+    client_ref: str | None = None
+    retracts: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AppendIn:
+    namespace: str
+    import_: bool
+    items: list[ItemIn]
+
+
+@dataclass
+class FilterIn:
+    thread_id: str | None = None
+    author: str | None = None
+    kind: list[str] | None = None
+    valid_after: int | None = None
+    valid_before: int | None = None
+    include_retracted: bool = False
+
+
+@dataclass
+class QueryIn:
+    namespace: str
+    text: str
+    context: str | None
+    filter: FilterIn
+    as_of: int | None
+    top_k: int
+    max_tokens: int
+
+
+def _check_keys(obj: dict, allowed: set[str], where: str) -> None:
+    unknown = sorted(set(obj) - allowed)
+    if unknown:
+        raise invalid(f"unknown key{'s' if len(unknown) > 1 else ''} in {where}: {', '.join(unknown)}")
+
+
+def _opt_str(obj: dict, key: str, where: str, *, non_empty: bool = True) -> str | None:
+    value = obj.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise invalid(f"{where}{key} must be a string")
+    if non_empty and not value.strip():
+        raise invalid(f"{where}{key} must not be empty")
+    return value
+
+
+def _opt_time(obj: dict, key: str, where: str) -> int | None:
+    value = obj.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise invalid(f"{where}{key} must be an RFC 3339 string")
+    try:
+        return timeutil.parse(value)
+    except ValueError as exc:
+        raise invalid(f"{where}{key}: {exc}") from None
+
+
+def _opt_int(obj: dict, key: str, default: int, lo: int, hi: int) -> int:
+    value = obj.get(key)
+    if value is None:
+        return default
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise invalid(f"{key} must be an integer")
+    if not lo <= value <= hi:
+        raise invalid(f"{key} must be between {lo} and {hi}, got {value}")
+    return value
+
+
+def _namespace(body: dict) -> str:
+    ns = body.get("namespace")
+    if ns is None:
+        return DEFAULT_NAMESPACE
+    if not isinstance(ns, str) or not NAMESPACE_RE.match(ns):
+        raise invalid(
+            "namespace must be 1-64 characters of letters, digits, '.', '_' or '-', "
+            "starting with a letter or digit"
+        )
+    return ns
+
+
+def parse_append(body: dict) -> AppendIn:
+    _check_keys(body, _APPEND_KEYS, "the append request")
+    namespace = _namespace(body)
+    import_ = body.get("import")
+    if import_ is None:
+        import_ = False
+    if not isinstance(import_, bool):
+        raise invalid("import must be true or false")
+    raw_items = body.get("items")
+    if not isinstance(raw_items, list) or not raw_items:
+        raise invalid("items must be a non-empty list")
+    if len(raw_items) > MAX_ITEMS:
+        raise invalid(f"at most {MAX_ITEMS} items per request, got {len(raw_items)}")
+    items = []
+    last_valid = None
+    for i, raw in enumerate(raw_items):
+        where = f"items[{i}]."
+        if not isinstance(raw, dict):
+            raise invalid(f"items[{i}] must be an object")
+        _check_keys(raw, _ITEM_KEYS, f"items[{i}]")
+        author = _opt_str(raw, "author", where)
+        if author is None:
+            raise invalid(f"{where}author is required")
+        text = raw.get("text")
+        if not isinstance(text, str) or not text.strip():
+            raise invalid(f"{where}text is required and must be a non-empty string")
+        if len(text) > MAX_TEXT_CHARS:
+            raise invalid(f"{where}text is longer than {MAX_TEXT_CHARS} characters")
+        thread_id = _opt_str(raw, "thread_id", where) or DEFAULT_THREAD
+        valid_at = _opt_time(raw, "valid_at", where)
+        title = _opt_str(raw, "title", where, non_empty=False)
+        client_ref = _opt_str(raw, "client_ref", where)
+        retracts = raw.get("retracts")
+        if retracts is None:
+            retracts = []
+        if not isinstance(retracts, list) or not all(isinstance(r, str) and r for r in retracts):
+            raise invalid(f"{where}retracts must be a list of item ids")
+        if import_:
+            if valid_at is None:
+                raise invalid(f"{where}valid_at is required when import is true")
+            if last_valid is not None and valid_at < last_valid:
+                raise invalid(f"{where}valid_at must not decrease when import is true")
+            last_valid = valid_at
+        items.append(
+            ItemIn(
+                author=author,
+                text=text,
+                thread_id=thread_id,
+                valid_at=valid_at,
+                title=title or None,
+                client_ref=client_ref,
+                retracts=list(dict.fromkeys(retracts)),
+            )
+        )
+    return AppendIn(namespace=namespace, import_=import_, items=items)
+
+
+def parse_query(body: dict) -> QueryIn:
+    _check_keys(body, _QUERY_KEYS, "the query request")
+    namespace = _namespace(body)
+    text = body.get("text")
+    if not isinstance(text, str) or not text.strip():
+        raise invalid("text is required and must be a non-empty string")
+    if len(text) > MAX_TEXT_CHARS:
+        raise invalid(f"text is longer than {MAX_TEXT_CHARS} characters")
+    context = _opt_str(body, "context", "", non_empty=False) or None
+    raw_filter = body.get("filter")
+    if raw_filter is None:
+        raw_filter = {}
+    if not isinstance(raw_filter, dict):
+        raise invalid("filter must be an object")
+    _check_keys(raw_filter, _FILTER_KEYS, "filter")
+    kind = raw_filter.get("kind")
+    if kind is not None:
+        if isinstance(kind, str):
+            raise invalid("filter.kind must be a list of kinds, e.g. [\"message\"]")
+        if not isinstance(kind, list) or not all(isinstance(k, str) for k in kind):
+            raise invalid("filter.kind must be a list of kinds")
+        bad = sorted(set(kind) - set(KINDS))
+        if bad:
+            raise invalid(f"unknown kind {bad[0]!r}; kinds are {', '.join(KINDS)}")
+    include_retracted = raw_filter.get("include_retracted")
+    if include_retracted is None:
+        include_retracted = False
+    if not isinstance(include_retracted, bool):
+        raise invalid("filter.include_retracted must be true or false")
+    flt = FilterIn(
+        thread_id=_opt_str(raw_filter, "thread_id", "filter."),
+        author=_opt_str(raw_filter, "author", "filter."),
+        kind=kind,
+        valid_after=_opt_time(raw_filter, "valid_after", "filter."),
+        valid_before=_opt_time(raw_filter, "valid_before", "filter."),
+        include_retracted=include_retracted,
+    )
+    return QueryIn(
+        namespace=namespace,
+        text=text,
+        context=context,
+        filter=flt,
+        as_of=_opt_time(body, "as_of", ""),
+        top_k=_opt_int(body, "top_k", DEFAULT_TOP_K, 1, MAX_TOP_K),
+        max_tokens=_opt_int(body, "max_tokens", DEFAULT_MAX_TOKENS, 1, MAX_MAX_TOKENS),
+    )

cogito_mem/capture/__init__.py

@@ -0,0 +1,128 @@
+"""Capture chats into the memory as you go (requirements §3.5).
+
+Each source turns its chat files into append items with a stable ``client_ref``,
+so sending a message twice changes nothing. Live capture appends normally (the
+memory learns of a message when it is captured); backfilling old files uses
+``import`` so ``as_of`` sees them as if the memory had been running then.
+
+Obvious secrets (API keys, tokens, private keys) are replaced with ``[redacted]``
+before anything is stored, because the memory never forgets. Text inside
+``<private>…</private>`` is left out. ``COGITO_MEM_CAPTURE=off`` pauses capture.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Iterable, Protocol
+
+BATCH = 200
+
+_SECRETS = [
+    re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----.*?-----END [A-Z0-9 ]*PRIVATE KEY-----", re.S),
+    re.compile(r"\bsk-(?:ant-|proj-)?[A-Za-z0-9_\-]{20,}"),
+    re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}"),
+    re.compile(r"\bgithub_pat_[A-Za-z0-9_]{22,}"),
+    re.compile(r"\bglpat-[A-Za-z0-9_\-]{20,}"),
+    re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b"),
+    re.compile(r"\bxox[abposr]-[A-Za-z0-9\-]{10,}"),
+    re.compile(r"\bAIza[0-9A-Za-z_\-]{35}"),
+    re.compile(r"\bhf_[A-Za-z0-9]{30,}"),
+    re.compile(r"\beyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}"),
+    re.compile(r"(?i)(?<=\bbearer )[A-Za-z0-9._~+/=\-]{16,}"),
+]
+# ``password=…``, also inside a longer name (``OPENROUTER_API_KEY=…``), and the password in a URL.
+_ASSIGNED = re.compile(
+    r"(?i)(?<![A-Za-z0-9])((?:api[_-]?key|secret(?:[_-]?key)?|access[_-]?token|auth[_-]?token|password|passwd"
+    r"|client[_-]?secret)[\"']?\s*[:=]\s*[\"']?)([^\s\"']{8,})"
+)
+_URL_PASSWORD = re.compile(r"(://[^/\s:@]+:)[^/\s@]+(?=@)")
+_PRIVATE = re.compile(r"<private>.*?(?:</private>|\Z)", re.S | re.I)
+
+REDACTED = "[redacted]"
+
+
+def redact(text: str) -> str:
+    for pattern in _SECRETS:
+        text = pattern.sub(REDACTED, text)
+    text = _URL_PASSWORD.sub(lambda m: m.group(1) + REDACTED, text)
+    return _ASSIGNED.sub(lambda m: m.group(1) + REDACTED, text)
+
+
+def without_private(text: str) -> str:
+    """The text without what is marked ``<private>…</private>`` (an unclosed tag hides the rest)."""
+    return _PRIVATE.sub("", text)
+
+
+def enabled(setting: str = "COGITO_MEM_CAPTURE") -> bool:
+    """A capture switch: on unless the variable says ``off`` (or 0, false, no)."""
+    return os.environ.get(setting, "on").strip().lower() not in ("0", "off", "false", "no")
+
+
+class Sink(Protocol):
+    def handle(self, body: dict) -> dict: ...
+
+
+def send(sink: Sink, items: list[dict], namespace: str = "default", import_: bool = False) -> dict:
+    """Append items in batches. Returns counts of added and duplicate items."""
+    counts = {"added": 0, "duplicate": 0}
+    if import_:
+        items = sorted(items, key=lambda it: it["valid_at"])
+    for i in range(0, len(items), BATCH):
+        body = {"op": "append", "namespace": namespace, "import": import_, "items": items[i : i + BATCH]}
+        for result in sink.handle(body)["items"]:
+            counts[result["status"]] += 1
+    return counts
+
+
+class Cursor:
+    """How far into a chat file capture has read: a byte offset and the line number there."""
+
+    def __init__(self, path: Path):
+        self.path = path
+        try:
+            state = json.loads(path.read_text())
+            self.offset, self.line = int(state["offset"]), int(state["line"])
+        except (OSError, ValueError, KeyError, TypeError):
+            self.offset, self.line = 0, 0
+
+    def save(self, offset: int, line: int) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps({"offset": offset, "line": line}))
+        tmp.replace(self.path)
+        self.offset, self.line = offset, line
+
+
+def read_new_lines(path: Path, offset: int = 0, line: int = 0) -> tuple[list[tuple[int, str]], int, int]:
+    """Complete lines after byte ``offset`` as (line number, text), plus the new offset and line.
+
+    Line numbers count from the start of the file, so they are stable ids for a line.
+    """
+    size = path.stat().st_size
+    if offset > size:  # the file was replaced
+        offset, line = 0, 0
+    with open(path, "rb") as fh:
+        fh.seek(offset)
+        data = fh.read()
+    end = data.rfind(b"\n") + 1
+    if end == 0:
+        return [], offset, line
+    raw_lines = data[:end].split(b"\n")[:-1]
+    out = [(line + i, raw.decode("utf-8", "replace")) for i, raw in enumerate(raw_lines)]
+    return out, offset + end, line + len(raw_lines)
+
+
+def jsonl(lines: Iterable[tuple[int, str]]) -> Iterable[tuple[int, dict]]:
+    for n, line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(obj, dict):
+            yield n, obj

cogito_mem/capture/claude_code.py

@@ -0,0 +1,253 @@
+"""Claude Code: read the session transcript (JSONL) after each turn.
+
+The ``Stop`` and ``SessionEnd`` hooks run ``cogito-mem capture claude-code``, which
+reads the hook's JSON from stdin and hands the work to a background process, so
+the chat never waits for the memory.
+
+Kept: the user's typed messages and the assistant's text replies, without what is
+marked ``<private>…</private>``, and what the session did: one ``actions`` item for
+each run of tool calls between two prompts, with the commands it ran (and which
+failed or did not run) and the files it read, edited or wrote, such as
+"Ran `pytest -q` (failed), `pytest -q`. Edited src/x.py. Read README.md."
+(``COGITO_MEM_CAPTURE_ACTIONS=off`` leaves these out). Left out: tool output and
+file contents, thinking, sub-agent (sidechain) turns, slash-command output,
+injected system reminders and the summary Claude Code writes when it compacts a
+session.
+
+``client_ref`` is the transcript line's ``uuid`` (for an ``actions`` item, that of its
+first tool call, so reading a turn again, whole or from its middle, adds no second
+copy); ``thread_id`` is the session id; ``title`` is the project, the line's ``cwd``
+(a Claude Code worktree, ``<repo>/.claude/worktrees/<name>``, counts as its
+repository), so recall can prefer the current project.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Iterable
+
+from . import Cursor, Sink, enabled, jsonl, read_new_lines, redact, send, without_private
+
+ACTIONS = "actions"  # the author of what a turn did (store.SIDE_AUTHOR)
+ACTION_CHARS = 800  # about one piece (``split.PIECE_TOKENS``), so a busy turn cannot fill a reply
+COMMAND_CHARS = 80
+
+_SKIP_PREFIXES = (
+    "<command-name>",
+    "<command-message>",
+    "<command-args>",
+    "<local-command-stdout>",
+    "<local-command-stderr>",
+    "<bash-input>",
+    "<bash-stdout>",
+    "<bash-stderr>",
+    "Caveat: The messages below were generated",
+    "[Request interrupted by user",
+    "<user-prompt-submit-hook>",
+    "This session is being continued from a previous conversation",  # a compaction summary
+    "<task-notification>",  # a background task finishing, reported to Claude, not typed
+)
+_REMINDER = re.compile(r"<system-reminder>.*?</system-reminder>", re.S)
+_WORKTREE = re.compile(r"[\\/]\.claude[\\/]worktrees[\\/][^\\/]+.*$", re.S)
+_VERBS = {"Read": "Read", "NotebookRead": "Read", "Edit": "Edited", "MultiEdit": "Edited", "NotebookEdit": "Edited",
+          "Write": "Wrote"}  # fmt: skip
+_NOT_RUN = ("<tool_use_error>", "The user doesn't want to", "[Request interrupted")
+_EXIT_CODE = re.compile(r"Exit code (\d+)")
+
+
+def projects_dir() -> Path:
+    base = os.environ.get("CLAUDE_CONFIG_DIR")
+    return (Path(base).expanduser() if base else Path.home() / ".claude") / "projects"
+
+
+def project_of(cwd: object) -> str | None:
+    """The project a working directory belongs to: the directory, or a worktree's repository."""
+    if not isinstance(cwd, str) or not cwd.strip():
+        return None
+    cwd = cwd.rstrip("/\\") or cwd
+    return _WORKTREE.sub("", cwd) or cwd
+
+
+def project_folder(project: str) -> str:
+    """The folder name Claude Code gives a project under ``~/.claude/projects``."""
+    return re.sub(r"[^A-Za-z0-9]", "-", project)
+
+
+def _text_of(content: object) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = [b.get("text", "") for b in content if isinstance(b, dict) and b.get("type") == "text"]
+        return "\n\n".join(p for p in parts if p)
+    return ""
+
+
+def items_from_lines(
+    lines: Iterable[tuple[int, dict]], session_id: str | None = None, actions: bool = False
+) -> list[dict]:
+    """The messages as items, in order; with ``actions``, also one item per turn for its tool calls."""
+    items = []
+    turns: list[tuple[dict, dict]] = []  # (actions item, its tool calls by id)
+    calls: dict | None = None  # the tool calls of the turn under way
+    for _, rec in lines:
+        kind = rec.get("type")
+        if kind not in ("user", "assistant") or any(rec.get(k) for k in ("isSidechain", "isMeta", "isCompactSummary")):
+            continue
+        message = rec.get("message")
+        if not isinstance(message, dict):
+            continue
+        text = without_private(_REMINDER.sub("", _text_of(message.get("content")))).strip()
+        if text and not text.startswith(_SKIP_PREFIXES) and rec.get("uuid"):
+            author = "user" if kind == "user" else "assistant"
+            items.append(_item(rec, author, redact(text), f"claude-code:{rec['uuid']}", session_id))
+        if not actions:
+            continue
+        content = message.get("content")
+        blocks = [b for b in content if isinstance(b, dict)] if isinstance(content, list) else []
+        if kind == "user" and not any(b.get("type") == "tool_result" for b in blocks):
+            calls = None  # a prompt: the turn's actions end here
+        for block in blocks:
+            if block.get("type") == "tool_use" and isinstance(block.get("input"), dict):
+                if calls is None:
+                    if not rec.get("uuid"):
+                        continue
+                    calls = {}
+                    turns.append((_item(rec, ACTIONS, "", f"claude-code:{rec['uuid']}:actions", session_id), calls))
+                    items.append(turns[-1][0])
+                call = {"name": block.get("name"), "input": block["input"], "cwd": rec.get("cwd")}
+                calls[block.get("id") or len(calls)] = call
+            elif block.get("type") == "tool_result" and calls is not None and block.get("tool_use_id") in calls:
+                calls[block["tool_use_id"]]["outcome"] = _outcome(block)
+    for item, turn in turns:
+        item["text"] = _summary(list(turn.values()))
+    return [it for it in items if it["text"]]
+
+
+def _item(rec: dict, author: str, text: str, client_ref: str, session_id: str | None) -> dict:
+    item = {
+        "author": author,
+        "thread_id": rec.get("sessionId") or session_id or "default",
+        "text": text,
+        "client_ref": client_ref,
+    }
+    project = project_of(rec.get("cwd"))
+    if project:
+        item["title"] = project
+    if isinstance(rec.get("timestamp"), str):
+        item["valid_at"] = rec["timestamp"]
+    return item
+
+
+def _outcome(result: dict) -> str | None:
+    """``failed``, ``not run`` (refused or interrupted), or None for a call that went through."""
+    text = _text_of(result.get("content")).lstrip()
+    if text.startswith(_NOT_RUN):
+        return "not run"
+    code = _EXIT_CODE.match(text)
+    if result.get("is_error") or (code and code.group(1) != "0"):
+        return "failed"
+    return None
+
+
+def _summary(calls: list[dict]) -> str:
+    """One sentence per kind of action: the commands in order, then the files by what was done to them."""
+    commands: list[str] = []
+    files: dict[str, list[str]] = {}
+    for call in calls:
+        args, outcome = call["input"], call.get("outcome")
+        cwd = call["cwd"] if isinstance(call["cwd"], str) else ""
+        if call["name"] == "Bash" and isinstance(args.get("command"), str) and args["command"].strip():
+            entry = f"`{_command(args['command'], cwd)}`" + (f" ({outcome})" if outcome else "")
+            if entry not in commands:
+                commands.append(entry)
+            continue
+        path = args.get("file_path") or args.get("notebook_path")
+        if not isinstance(path, str) or not path.strip() or outcome:  # a failed edit changed nothing
+            continue
+        paths = files.setdefault(_VERBS.get(call["name"]) or f"Used {call['name']} on", [])
+        if _relative(path, cwd) not in paths:
+            paths.append(_relative(path, cwd))
+    changed = {p for verb, paths in files.items() if verb != "Read" for p in paths}
+    if "Read" in files:  # files are read before they are edited: that says nothing more
+        files["Read"] = [p for p in files["Read"] if p not in changed]
+    kinds = [("Ran", commands), *sorted(files.items(), key=lambda kv: kv[0] == "Read")]
+    parts = [(verb, entries) for verb, entries in kinds if entries]
+    # Each kind gets an equal share of the room, and what a short one leaves goes to the others.
+    texts = [""] * len(parts)
+    room = ACTION_CHARS
+    by_length = sorted(range(len(parts)), key=lambda i: sum(len(e) + 2 for e in parts[i][1]))
+    for left, i in zip(range(len(parts), 0, -1), by_length):
+        texts[i] = _listing(*parts[i], room // left)
+        room -= len(texts[i]) + 1
+    text = redact(" ".join(texts))
+    return text if len(text) <= ACTION_CHARS else text[: ACTION_CHARS - 2] + " …"
+
+
+def _listing(verb: str, entries: list[str], room: int) -> str:
+    """``Verb a, b, c.`` with as many entries as fit in ``room`` characters, and how many more there were."""
+    text = verb
+    for n, entry in enumerate(entries):
+        if n and len(text) + len(entry) + (3 if n == len(entries) - 1 else 18) > room:
+            return f"{text}, and {len(entries) - n} more."
+        text += (", " if n else " ") + entry
+    return text + "."
+
+
+def _command(command: str, cwd: str) -> str:
+    """The command's first line, cut to ``COMMAND_CHARS``, with paths under ``cwd`` relative to it."""
+    command = redact(command.strip())  # before it is cut, so no part of a secret is left
+    base = re.escape(cwd.rstrip("/\\"))
+    if base:
+        command = re.sub(rf"^cd +([\"']?){base}[/\\]?\1 *(?:&&|;) *", "", command)
+        command = re.sub(rf"(?<![^\s\"'=:(]){base}[/\\]", "", command)
+    first, *rest = command.splitlines() or [""]
+    if rest or len(first) > COMMAND_CHARS:
+        first = first[:COMMAND_CHARS].rstrip() + " …"
+    return first
+
+
+def _relative(path: str, cwd: str) -> str:
+    base = cwd.rstrip("/\\")
+    if base and path.startswith(base) and path[len(base) : len(base) + 1] in ("/", "\\"):
+        return path[len(base) + 1 :]
+    return path
+
+
+def capture_transcript(
+    sink: Sink,
+    transcript: Path,
+    state_dir: Path,
+    session_id: str | None = None,
+    namespace: str = "default",
+    import_: bool = False,
+) -> dict:
+    """Append the new messages of one transcript. Returns counts of added and duplicate items."""
+    session = session_id or transcript.stem
+    cursor = Cursor(state_dir / "claude-code" / f"{_safe(session)}.json")
+    lines, offset, line = read_new_lines(transcript, cursor.offset, cursor.line)
+    items = items_from_lines(jsonl(lines), session, actions=enabled("COGITO_MEM_CAPTURE_ACTIONS"))
+    if import_:
+        items = [it for it in items if "valid_at" in it]
+    counts = send(sink, items, namespace, import_) if items else {"added": 0, "duplicate": 0}
+    cursor.save(offset, line)
+    return counts
+
+
+def capture_all(sink: Sink, state_dir: Path, namespace: str = "default", root: Path | None = None) -> dict:
+    """Backfill every transcript under ~/.claude/projects (as history, with ``import``)."""
+    total = {"added": 0, "duplicate": 0, "files": 0}
+    base = root or projects_dir()
+    if not base.is_dir():
+        return total
+    for path in sorted(base.glob("*/*.jsonl")):
+        counts = capture_transcript(sink, path, state_dir, path.stem, namespace, import_=True)
+        total["added"] += counts["added"]
+        total["duplicate"] += counts["duplicate"]
+        total["files"] += 1
+    return total
+
+
+def _safe(name: str) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]", "_", name)[:128]