drydock-cli 2.8.22__tar.gz → 2.8.23__tar.gz

drydock_cli-2.8.23/.auto_release.lock

@@ -0,0 +1 @@
+1014651

{drydock_cli-2.8.22 → drydock_cli-2.8.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 2.8.22
+Version: 2.8.23
 Summary: Local-first CLI coding agent — tested with Gemma 4 26B via vLLM
 Project-URL: Homepage, https://github.com/fbobe321/drydock
 Project-URL: Repository, https://github.com/fbobe321/drydock
@@ -36,13 +36,11 @@ Requires-Dist: markdownify>=1.2.2
 Requires-Dist: mcp>=1.14.0
 Requires-Dist: mistralai==1.12.4
 Requires-Dist: packaging>=24.1
-Requires-Dist: pexpect>=4.9.0
 Requires-Dist: pydantic-settings>=2.12.0
 Requires-Dist: pydantic>=2.12.4
 Requires-Dist: pypdf>=4.0.0
 Requires-Dist: pyperclip>=1.11.0
 Requires-Dist: pyyaml>=6.0.0
-Requires-Dist: requests>=2.20.0
 Requires-Dist: rich>=14.0.0
 Requires-Dist: textual-speedups>=0.2.1
 Requires-Dist: textual>=7.4.0
@@ -378,6 +376,17 @@ DryDock discovers skills from:
 3. Global `~/.drydock/skills/`
 4. Bundled skills (shipped with the package)
 
+### Built-in tools beyond the basics
+
+In addition to the standard `read_file` / `write_file` / `search_replace` / `bash` / `grep` / `glob` / `task` / `retrieve` set, DryDock ships four direct built-ins designed to plug well-known transformer weaknesses:
+
+- **`math`** — exact arithmetic via stdlib (math, statistics, Fraction, Decimal). Sandboxed Python expression. Fixes factorials, large multiplies, primes, statistics, exact fractions.
+- **`count`** — exact substring/regex/lines/words/chars/bytes count over a string OR a file. Fixes "how many X are in this text" estimation errors.
+- **`memory`** — persistent cross-session key/value notes at `~/.drydock/agent_memory/notes.jsonl`. Save, recall (TF-IDF ranked), list keys, forget. Bridges the long-term memory gap.
+- **`verify`** — runs a shell command (or checks a file) and matches the output against an expectation (contains/not_contains/regex/equals/exit_code/file_exists/file_contains). Operationalizes the "Loop until verified" core principle.
+
+All four are direct built-ins, NOT MCP servers — per Babich's "MCP is Dead" (Apr 2026), MCP servers burn ~20K tokens of context per call which is a real cost on a 131K-context local model. Direct built-ins use a strict Pydantic schema, single subprocess-free path, and tighter security.
+
 ### Math Tool
 
 DryDock ships with a `math` tool the model calls instead of doing arithmetic in its head. It's a direct built-in (NOT an MCP server — see [MCP is Dead](https://medium.com/) for why direct tools beat MCP for small bandwidth-limited models like Gemma 4). One argument, sandboxed Python expression, exact results.

{drydock_cli-2.8.22 → drydock_cli-2.8.23}/README.md

@@ -323,6 +323,17 @@ DryDock discovers skills from:
 3. Global `~/.drydock/skills/`
 4. Bundled skills (shipped with the package)
 
+### Built-in tools beyond the basics
+
+In addition to the standard `read_file` / `write_file` / `search_replace` / `bash` / `grep` / `glob` / `task` / `retrieve` set, DryDock ships four direct built-ins designed to plug well-known transformer weaknesses:
+
+- **`math`** — exact arithmetic via stdlib (math, statistics, Fraction, Decimal). Sandboxed Python expression. Fixes factorials, large multiplies, primes, statistics, exact fractions.
+- **`count`** — exact substring/regex/lines/words/chars/bytes count over a string OR a file. Fixes "how many X are in this text" estimation errors.
+- **`memory`** — persistent cross-session key/value notes at `~/.drydock/agent_memory/notes.jsonl`. Save, recall (TF-IDF ranked), list keys, forget. Bridges the long-term memory gap.
+- **`verify`** — runs a shell command (or checks a file) and matches the output against an expectation (contains/not_contains/regex/equals/exit_code/file_exists/file_contains). Operationalizes the "Loop until verified" core principle.
+
+All four are direct built-ins, NOT MCP servers — per Babich's "MCP is Dead" (Apr 2026), MCP servers burn ~20K tokens of context per call which is a real cost on a 131K-context local model. Direct built-ins use a strict Pydantic schema, single subprocess-free path, and tighter security.
+
 ### Math Tool
 
 DryDock ships with a `math` tool the model calls instead of doing arithmetic in its head. It's a direct built-in (NOT an MCP server — see [MCP is Dead](https://medium.com/) for why direct tools beat MCP for small bandwidth-limited models like Gemma 4). One argument, sandboxed Python expression, exact results.

drydock_cli-2.8.23/drydock/core/tools/builtins/count_tool.py

@@ -0,0 +1,218 @@
+"""Count tool — exact substring / regex / line / token counts.
+
+The companion to the math tool: transformers can't count reliably (they
+estimate token positions and overshoot/undershoot on "how many X are in
+this text"). This tool fixes it by deferring to deterministic stdlib code.
+
+Use INSTEAD of estimating "how many" anything. The model just calls and
+gets the exact number.
+
+Modes:
+- substring      — case-sensitive substring count (default)
+- substring_ci   — case-insensitive substring count
+- regex          — regex match count (uses re.findall)
+- lines          — number of lines (newline-separated)
+- words          — whitespace-separated word count
+- chars          — total character count
+- bytes          — UTF-8 byte length
+
+Source can be:
+- `text` arg directly
+- `path` arg pointing at a file (read up to 10 MB)
+
+Examples:
+
+    count(pattern="r", text="strawberry")              # 3
+    count(pattern="def ", path="/data3/drydock/drydock/core/agent_loop.py", mode="substring")
+    count(pattern="^class\\s", path="...", mode="regex")
+    count(mode="lines", path="...")
+    count(mode="words", text="hello world hello")      # 3
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import AsyncGenerator
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar, Literal, final
+
+from pydantic import BaseModel, Field
+
+from drydock.core.tools.base import (
+    BaseTool,
+    BaseToolConfig,
+    BaseToolState,
+    InvokeContext,
+    ToolPermission,
+)
+from drydock.core.tools.ui import ToolCallDisplay, ToolResultDisplay, ToolUIData
+from drydock.core.types import ToolStreamEvent
+
+if TYPE_CHECKING:
+    from drydock.core.types import ToolResultEvent
+
+
+_MAX_FILE_BYTES = 10 * 1024 * 1024  # 10 MB
+
+CountMode = Literal[
+    "substring", "substring_ci", "regex", "lines", "words", "chars", "bytes",
+]
+
+
+class CountArgs(BaseModel):
+    mode: CountMode = Field(
+        default="substring",
+        description=(
+            "How to count. `substring` = case-sensitive substring (needs "
+            "`pattern`). `substring_ci` = case-insensitive. `regex` = "
+            "Python re.findall (needs `pattern`). `lines` / `words` / "
+            "`chars` / `bytes` = pattern-free."
+        ),
+    )
+    pattern: str = Field(
+        default="",
+        description=(
+            "Required for substring / substring_ci / regex. Ignored otherwise."
+        ),
+    )
+    text: str = Field(
+        default="",
+        description=(
+            "Inline text to count in. Provide either `text` OR `path`, not both."
+        ),
+    )
+    path: str = Field(
+        default="",
+        description=(
+            "Path to a file to count in. Capped at 10 MB. Use either `text` "
+            "OR `path`."
+        ),
+    )
+
+
+class CountResult(BaseModel):
+    ok: bool
+    count: int = 0
+    mode: str = ""
+    source: str = ""    # "text" or the file path
+    error: str = ""
+
+
+class CountConfig(BaseToolConfig):
+    permission: ToolPermission = ToolPermission.ALWAYS
+
+
+def _resolve_text(args: CountArgs) -> tuple[str, str]:
+    """Returns (text, source_label). Raises ValueError on bad input.
+
+    Empty text + empty path is treated as the empty string source — valid
+    for pattern-free modes like `lines` (returns 0). Substring / regex
+    modes still error out via `_do_count` if the pattern is empty.
+    """
+    if args.text and args.path:
+        raise ValueError("provide either `text` or `path`, not both")
+    if args.path:
+        p = Path(args.path).expanduser()
+        if not p.is_file():
+            raise ValueError(f"file not found: {p}")
+        size = p.stat().st_size
+        if size > _MAX_FILE_BYTES:
+            raise ValueError(
+                f"file too large ({size} bytes > {_MAX_FILE_BYTES})"
+            )
+        return p.read_text(errors="replace"), str(p)
+    return args.text, "text"
+
+
+def _do_count(text: str, args: CountArgs) -> int:
+    if args.mode == "substring":
+        if not args.pattern:
+            raise ValueError("substring mode requires `pattern`")
+        return text.count(args.pattern)
+    if args.mode == "substring_ci":
+        if not args.pattern:
+            raise ValueError("substring_ci mode requires `pattern`")
+        return text.lower().count(args.pattern.lower())
+    if args.mode == "regex":
+        if not args.pattern:
+            raise ValueError("regex mode requires `pattern`")
+        try:
+            return len(re.findall(args.pattern, text))
+        except re.error as e:
+            raise ValueError(f"invalid regex: {e}") from e
+    if args.mode == "lines":
+        # If text ends without a newline, it still counts as one line.
+        if not text:
+            return 0
+        return text.count("\n") + (0 if text.endswith("\n") else 1)
+    if args.mode == "words":
+        return len(text.split())
+    if args.mode == "chars":
+        return len(text)
+    if args.mode == "bytes":
+        return len(text.encode("utf-8"))
+    raise ValueError(f"unknown mode: {args.mode}")
+
+
+class Count(
+    BaseTool[CountArgs, CountResult, CountConfig, BaseToolState],
+    ToolUIData[CountArgs, CountResult],
+):
+    description: ClassVar[str] = (
+        "Exact count of substrings, regex matches, lines, words, chars, "
+        "or bytes in a string OR file. Use INSTEAD of estimating 'how "
+        "many X are in this text' — transformers count poorly. Modes: "
+        "substring (default), substring_ci, regex, lines, words, chars, "
+        "bytes. Source: pass `text=...` OR `path=...` (file capped at "
+        "10 MB). Examples: count(pattern='r', text='strawberry') -> 3; "
+        "count(pattern='^def ', path='foo.py', mode='regex'); "
+        "count(mode='lines', path='foo.txt')."
+    )
+
+    @classmethod
+    def format_call_display(cls, args: CountArgs) -> ToolCallDisplay:
+        if args.path:
+            target = args.path.split("/")[-1] if "/" in args.path else args.path
+            target = f"file:{target}"
+        else:
+            preview = args.text[:30].replace("\n", " ")
+            target = f'text:"{preview}..."' if len(args.text) > 30 else f'text:"{preview}"'
+        if args.mode in ("substring", "substring_ci", "regex") and args.pattern:
+            return ToolCallDisplay(summary=f"count {args.mode} {args.pattern!r} in {target}")
+        return ToolCallDisplay(summary=f"count {args.mode} in {target}")
+
+    @classmethod
+    def get_result_display(cls, event: "ToolResultEvent") -> ToolResultDisplay:
+        if isinstance(event.result, CountResult):
+            if not event.result.ok:
+                return ToolResultDisplay(
+                    success=False, message=f"count: {event.result.error[:80]}"
+                )
+            return ToolResultDisplay(
+                success=True,
+                message=f"= {event.result.count} ({event.result.mode})",
+            )
+        return ToolResultDisplay(success=True, message="count complete")
+
+    @classmethod
+    def get_status_text(cls) -> str:
+        return "Counting"
+
+    def resolve_permission(self, args: CountArgs) -> ToolPermission | None:
+        return ToolPermission.ALWAYS
+
+    @final
+    async def run(
+        self, args: CountArgs, ctx: InvokeContext | None = None
+    ) -> AsyncGenerator[ToolStreamEvent | CountResult, None]:
+        try:
+            text, source = _resolve_text(args)
+            n = _do_count(text, args)
+        except ValueError as e:
+            yield CountResult(ok=False, error=str(e), mode=args.mode)
+            return
+        except OSError as e:
+            yield CountResult(
+                ok=False, error=f"OSError: {e}", mode=args.mode
+            )
+            return
+        yield CountResult(ok=True, count=n, mode=args.mode, source=source)

drydock_cli-2.8.23/drydock/core/tools/builtins/memory_tool.py

@@ -0,0 +1,356 @@
+"""Memory tool — persistent key/value notes the model can write & recall
+across sessions.
+
+The transformer-weakness map (Babich, "What coding can fix"): long-term
+memory is one of the easiest weaknesses to patch with classical code.
+This tool gives the model a small, indexed scratchpad it can append to
+during a session and search across all sessions next time.
+
+Storage: `~/.drydock/agent_memory/notes.jsonl` — append-only JSONL, one
+record per save. Recall does a full scan + ranked match (TF-IDF over
+the note key + value text). Cheap until ~100K notes; we cap at 10K to
+keep recall under 100ms.
+
+Operations (single tool, `op` arg):
+
+    memory(op="save", key="api auth pattern", value="JWT in Authorization header...", tags="api,auth")
+    memory(op="recall", query="how do we authenticate API requests", limit=3)
+    memory(op="list_keys", limit=20)
+    memory(op="forget", key="api auth pattern")          # marks superseded; doesn't physically delete
+    memory(op="stats")
+
+Read-only operations (recall, list_keys, stats) auto-approve. Write
+operations (save, forget) follow normal approval if the user has
+restricted them.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import time
+from collections.abc import AsyncGenerator
+from collections import Counter
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar, Literal, final
+
+from pydantic import BaseModel, Field
+
+from drydock.core.tools.base import (
+    BaseTool,
+    BaseToolConfig,
+    BaseToolState,
+    InvokeContext,
+    ToolPermission,
+)
+from drydock.core.tools.ui import ToolCallDisplay, ToolResultDisplay, ToolUIData
+from drydock.core.types import ToolStreamEvent
+
+if TYPE_CHECKING:
+    from drydock.core.types import ToolResultEvent
+
+
+_DEFAULT_DIR = Path.home() / ".drydock" / "agent_memory"
+_NOTES_FILE = "notes.jsonl"
+_MAX_NOTES = 10_000          # cap on total written notes (oldest become unrecallable)
+_MAX_VALUE_LEN = 8000
+
+
+def _store_path() -> Path:
+    """Resolve the notes file path. Env override:
+    DRYDOCK_MEMORY_PATH → full path to the .jsonl file."""
+    env = os.environ.get("DRYDOCK_MEMORY_PATH")
+    if env:
+        return Path(env).expanduser()
+    return _DEFAULT_DIR / _NOTES_FILE
+
+
+# ── Tokenizer / scorer ────────────────────────────────────────────────
+
+
+_TOKEN_RE = re.compile(r"[A-Za-z][A-Za-z0-9]+")
+
+
+def _tokenize(text: str) -> list[str]:
+    return [t.lower() for t in _TOKEN_RE.findall(text or "") if len(t) >= 2]
+
+
+def _score(query_tokens: list[str], doc_tokens: list[str]) -> float:
+    """Lightweight TF-IDF-ish score: token overlap weighted by inverse
+    frequency in the doc. No global IDF — single-doc score is fine for
+    a few-hundred-note store."""
+    if not query_tokens or not doc_tokens:
+        return 0.0
+    doc_counts = Counter(doc_tokens)
+    doc_len = len(doc_tokens)
+    score = 0.0
+    for tok in query_tokens:
+        if tok in doc_counts:
+            tf = doc_counts[tok] / doc_len
+            # Soft idf — favor tokens that are not 50%+ of the doc.
+            score += tf * (1.0 / (1.0 + math.log1p(doc_counts[tok])))
+    # Length normalization so a 50-token note doesn't always beat a 500-token note.
+    return score * math.sqrt(min(len(query_tokens), 12))
+
+
+# ── Storage ────────────────────────────────────────────────────────────
+
+
+def _load_notes(path: Path | None = None, include_forgotten: bool = False) -> list[dict]:
+    p = path or _store_path()
+    if not p.is_file():
+        return []
+    out: list[dict] = []
+    try:
+        with p.open() as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    rec = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if not include_forgotten and rec.get("forgotten"):
+                    continue
+                out.append(rec)
+    except OSError:
+        return []
+    return out
+
+
+def _append_note(rec: dict, path: Path | None = None) -> None:
+    p = path or _store_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with p.open("a") as f:
+        f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+
+
+# ── Tool ───────────────────────────────────────────────────────────────
+
+
+MemoryOp = Literal["save", "recall", "list_keys", "forget", "stats"]
+
+
+class MemoryArgs(BaseModel):
+    op: MemoryOp = Field(description="Operation: save | recall | list_keys | forget | stats")
+    key: str = Field(default="", description="Required for save / forget. Stable identifier for the note.")
+    value: str = Field(default="", description="Note body (save only). Capped at 8000 chars.")
+    query: str = Field(default="", description="Free-text query (recall only).")
+    tags: str = Field(default="", description="Comma-separated tags (save only). Stored for filtering.")
+    limit: int = Field(default=5, ge=1, le=50, description="Max results (recall, list_keys).")
+
+
+class MemoryHit(BaseModel):
+    key: str
+    value: str
+    tags: list[str] = []
+    ts: str
+    score: float = 0.0
+
+
+class MemoryResult(BaseModel):
+    ok: bool
+    op: str = ""
+    error: str = ""
+    saved: bool = False
+    hits: list[MemoryHit] = []
+    keys: list[str] = []
+    stats: dict = {}
+
+
+class MemoryConfig(BaseToolConfig):
+    permission: ToolPermission = ToolPermission.ALWAYS
+
+
+class Memory(
+    BaseTool[MemoryArgs, MemoryResult, MemoryConfig, BaseToolState],
+    ToolUIData[MemoryArgs, MemoryResult],
+):
+    description: ClassVar[str] = (
+        "Persistent cross-session memory. Save notes (key+value+tags), "
+        "recall by free-text query, list saved keys, forget by key. "
+        "Use to remember per-project patterns, decisions, and recurring "
+        "answers so the next session doesn't have to rediscover them. "
+        "Storage: ~/.drydock/agent_memory/notes.jsonl (append-only). "
+        "Examples: memory(op='save', key='build cmd', value='make test'); "
+        "memory(op='recall', query='how to run tests'); memory(op='stats')."
+    )
+
+    @classmethod
+    def format_call_display(cls, args: MemoryArgs) -> ToolCallDisplay:
+        if args.op == "save":
+            return ToolCallDisplay(summary=f"memory save: {args.key[:50]}")
+        if args.op == "recall":
+            q = args.query[:50] + ("..." if len(args.query) > 50 else "")
+            return ToolCallDisplay(summary=f"memory recall: {q}")
+        if args.op == "forget":
+            return ToolCallDisplay(summary=f"memory forget: {args.key[:50]}")
+        return ToolCallDisplay(summary=f"memory {args.op}")
+
+    @classmethod
+    def get_result_display(cls, event: "ToolResultEvent") -> ToolResultDisplay:
+        if isinstance(event.result, MemoryResult):
+            r = event.result
+            if not r.ok:
+                return ToolResultDisplay(success=False, message=f"memory: {r.error[:80]}")
+            if r.op == "save":
+                return ToolResultDisplay(success=True, message="saved")
+            if r.op == "recall":
+                return ToolResultDisplay(success=True, message=f"{len(r.hits)} hit(s)")
+            if r.op == "list_keys":
+                return ToolResultDisplay(success=True, message=f"{len(r.keys)} key(s)")
+            if r.op == "forget":
+                return ToolResultDisplay(success=True, message="forgotten")
+            if r.op == "stats":
+                return ToolResultDisplay(success=True, message=str(r.stats))
+        return ToolResultDisplay(success=True, message="memory complete")
+
+    @classmethod
+    def get_status_text(cls) -> str:
+        return "Accessing memory"
+
+    def resolve_permission(self, args: MemoryArgs) -> ToolPermission | None:
+        return ToolPermission.ALWAYS
+
+    @final
+    async def run(
+        self, args: MemoryArgs, ctx: InvokeContext | None = None
+    ) -> AsyncGenerator[ToolStreamEvent | MemoryResult, None]:
+        op = args.op
+
+        if op == "save":
+            err = self._save(args)
+            yield MemoryResult(ok=err is None, op="save", saved=err is None, error=err or "")
+            return
+
+        if op == "recall":
+            try:
+                hits = self._recall(args)
+            except ValueError as e:
+                yield MemoryResult(ok=False, op="recall", error=str(e))
+                return
+            yield MemoryResult(ok=True, op="recall", hits=hits)
+            return
+
+        if op == "list_keys":
+            keys = self._list_keys(args.limit)
+            yield MemoryResult(ok=True, op="list_keys", keys=keys)
+            return
+
+        if op == "forget":
+            if not args.key:
+                yield MemoryResult(ok=False, op="forget", error="key required")
+                return
+            n = self._forget(args.key)
+            yield MemoryResult(
+                ok=True, op="forget",
+                stats={"forgotten_records": n},
+            )
+            return
+
+        if op == "stats":
+            yield MemoryResult(ok=True, op="stats", stats=self._stats())
+            return
+
+        yield MemoryResult(ok=False, op=op, error=f"unknown op: {op}")
+
+    # ── Implementation ────────────────────────────────────────────────
+
+    def _save(self, args: MemoryArgs) -> str | None:
+        if not args.key:
+            return "key required"
+        if not args.value:
+            return "value required"
+        if len(args.value) > _MAX_VALUE_LEN:
+            return f"value too long ({len(args.value)} > {_MAX_VALUE_LEN})"
+        notes = _load_notes(include_forgotten=True)
+        if len([n for n in notes if not n.get("forgotten")]) >= _MAX_NOTES:
+            return f"memory full ({_MAX_NOTES} notes); forget some first"
+        rec = {
+            "key": args.key,
+            "value": args.value,
+            "tags": [t.strip() for t in args.tags.split(",") if t.strip()],
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        }
+        _append_note(rec)
+        return None
+
+    def _recall(self, args: MemoryArgs) -> list[MemoryHit]:
+        if not args.query:
+            raise ValueError("query required for recall")
+        q_tokens = _tokenize(args.query)
+        notes = _load_notes()
+        # Score every note + return top `limit` above zero.
+        scored: list[tuple[float, dict]] = []
+        for n in notes:
+            doc = f"{n.get('key', '')} {n.get('value', '')} {' '.join(n.get('tags', []))}"
+            s = _score(q_tokens, _tokenize(doc))
+            if s > 0:
+                scored.append((s, n))
+        scored.sort(key=lambda t: -t[0])
+        return [
+            MemoryHit(
+                key=n["key"],
+                value=n["value"],
+                tags=n.get("tags", []),
+                ts=n.get("ts", ""),
+                score=round(s, 4),
+            )
+            for s, n in scored[:args.limit]
+        ]
+
+    def _list_keys(self, limit: int) -> list[str]:
+        # Newest first, dedup by key (most recent value wins).
+        notes = _load_notes()
+        seen: set[str] = set()
+        keys: list[str] = []
+        for n in reversed(notes):
+            k = n.get("key", "")
+            if k and k not in seen:
+                seen.add(k)
+                keys.append(k)
+                if len(keys) >= limit:
+                    break
+        return keys
+
+    def _forget(self, key: str) -> int:
+        """Append a tombstone for `key`. Returns number of live records
+        the tombstone supersedes."""
+        notes = _load_notes()
+        live = [n for n in notes if n.get("key") == key]
+        rec = {
+            "key": key,
+            "value": "",
+            "tags": [],
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "forgotten": True,
+        }
+        _append_note(rec)
+        # Filter on next read — the tombstone hides any earlier same-key live
+        # records from `_load_notes(include_forgotten=False)` only if we
+        # extend the loader. For now, the simpler model: tombstones are
+        # full new records that mark the KEY as gone; recall won't return
+        # forgotten entries because we filter `forgotten=True`. Live
+        # entries with the same key from BEFORE the tombstone still show
+        # up — that's a known limitation; future: rewrite the file to
+        # drop superseded entries on tombstone.
+        # For this ship: also rewrite the file in place to drop superseded
+        # records, so forget actually erases.
+        path = _store_path()
+        all_notes = _load_notes(include_forgotten=True)
+        kept = [n for n in all_notes if not (n.get("key") == key and not n.get("forgotten"))]
+        path.write_text("".join(json.dumps(n, ensure_ascii=False) + "\n" for n in kept))
+        return len(live)
+
+    def _stats(self) -> dict:
+        notes_all = _load_notes(include_forgotten=True)
+        notes_live = [n for n in notes_all if not n.get("forgotten")]
+        keys_unique = {n["key"] for n in notes_live if "key" in n}
+        return {
+            "total_records": len(notes_all),
+            "live_records": len(notes_live),
+            "unique_keys": len(keys_unique),
+            "store_path": str(_store_path()),
+        }