anchor-memory 0.7.0__tar.gz

anchor_memory-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anchor contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

anchor_memory-0.7.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: anchor-memory
+Version: 0.7.0
+Summary: anchor — agents that remember their own work. mm + ms memory for AI agents: an append-only session archive, an entity index, a dangling-reference trigger and a search ladder that recovers what context compaction destroys.
+Author: anchor contributors
+License: MIT
+Project-URL: Homepage, https://zacharyol.github.io/anchor-memory/
+Project-URL: Documentation, https://zacharyol.github.io/anchor-memory/#docs
+Project-URL: Repository, https://github.com/zacharyol/anchor-memory
+Keywords: ai,agent,memory,context-window,compaction,context-limit,llm,mcp,model-context-protocol,rag,retrieval,claude,opencode,agent-memory,long-running-agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# anchor — agents that remember their own work
+
+**anchor = mm + ms.** Memory management plus memory search for AI agents.
+
+When a long-running agent hits its context limit, compaction summarizes the
+history — and the summary silently drops the details: the tool the agent built
+(`p3c2`), the file it wrote, the decision it made, the approach it tried and
+rejected. The agent then *rebuilds things it already built*. anchor fixes this
+in two halves:
+
+- **mm (memory management)** — every raw session event lands in an append-only
+  archive *before* compaction can destroy it, and every entity (tool names,
+  file paths, decisions) is extracted into an index: `entity → where it's
+  explained`.
+- **ms (memory search)** — a dangling-reference trigger notices *"the agent
+  sees `p3c2` and doesn't know what it is"* **for the agent** (agents are bad
+  at noticing this themselves), then a search ladder recovers the answer with
+  citations: index → workspace files → BM25 over raw history → LLM rewording
+  → piece-by-piece reconstruction. Misses return a **tried-log** (the negative
+  result), which the relay passes to the next searcher.
+
+Pure **stdlib Python** — no pip dependencies to run, works offline, optional
+local-Ollama for one rung. Ships as an **MCP server** so Claude Code, OpenCode
+and any MCP client can use it in one config block.
+
+## install
+
+```
+pip install anchor-memory        # from PyPI (once published — see site for status)
+```
+
+or straight from this repo — works right now:
+
+```
+pip install git+https://github.com/zacharyol/anchor-memory.git
+```
+
+Website & full setup guide: https://zacharyol.github.io/anchor-memory/
+
+## quickstart
+
+```
+anchor-mcp                      # starts the MCP server (stdio)
+python -m anchor.selftest       # offline end-to-end test with numbers
+python -m anchor.replay         # ingest your own OpenCode session history
+```
+
+Wire it into your agent (one block, then restart the session):
+
+```json
+{ "mcpServers": { "anchor": { "command": "anchor-mcp" } } }
+```
+
+Your agent gains: `anchor_resolve` (what was p3c2?), `anchor_check` (which
+names in this summary are unexplained?), `anchor_search` (BM25 over raw
+history), `anchor_sessions`, `anchor_sync` (incremental ingest from the live
+session database), `anchor_stats`, and `anchor_relay` (shard-searchers with
+negative-result merge — the last resort before "unfindable").
+
+## measured results (real session history, llama3.1:8B judge-free agent)
+
+| version | change | vanilla → anchored recall | token overhead |
+|---|---|---|---|
+| v0.3 | bulk cards | 33% → 44% | +48% |
+| v0.4 | selective card | 33% → 44% | **+5%** |
+| v0.5 | junk filter, repeats (n=36) | 19% → **47%** | +5% |
+| v0.6 | best-explanation cards (n=72) | 19% → **42%** | +5% |
+
+Trigger fire precision on labeled real data: 58% (firing is free — junk is
+filtered at the card layer). Sampling wobble ±5–6%: model randomness is small;
+question difficulty dominates. Full methodology:
+[docs/BENCHMARK.md](docs/BENCHMARK.md).
+
+## how it's made
+
+- [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md) — the architecture walk-through:
+  the two memory classes, the write path, the trigger rules, every ladder rung,
+  the relay, the data formats.
+- [docs/BENCHMARK.md](docs/BENCHMARK.md) — how the numbers above are produced
+  and how to reproduce them on your own session history.
+- [DESIGN.md](anchor/DESIGN.md) — the original design doc, kept as written.
+
+## why open source
+
+Memory loss after compaction is the defining production failure of long
+running agents ("context rot"). anchor's answer is deliberately simple:
+archive raw, index entities, detect the gap automatically, search in a cost
+ladder, and never trust a summary when the primary source still exists.
+MIT licensed — take it, wire it, fork it.
+
+## works with
+
+Claude Code · OpenCode · any MCP client · local Ollama (optional, rung 2)
+
+MIT License · repo: https://github.com/zacharyol/anchor-memory

anchor_memory-0.7.0/README.md

@@ -0,0 +1,95 @@
+# anchor — agents that remember their own work
+
+**anchor = mm + ms.** Memory management plus memory search for AI agents.
+
+When a long-running agent hits its context limit, compaction summarizes the
+history — and the summary silently drops the details: the tool the agent built
+(`p3c2`), the file it wrote, the decision it made, the approach it tried and
+rejected. The agent then *rebuilds things it already built*. anchor fixes this
+in two halves:
+
+- **mm (memory management)** — every raw session event lands in an append-only
+  archive *before* compaction can destroy it, and every entity (tool names,
+  file paths, decisions) is extracted into an index: `entity → where it's
+  explained`.
+- **ms (memory search)** — a dangling-reference trigger notices *"the agent
+  sees `p3c2` and doesn't know what it is"* **for the agent** (agents are bad
+  at noticing this themselves), then a search ladder recovers the answer with
+  citations: index → workspace files → BM25 over raw history → LLM rewording
+  → piece-by-piece reconstruction. Misses return a **tried-log** (the negative
+  result), which the relay passes to the next searcher.
+
+Pure **stdlib Python** — no pip dependencies to run, works offline, optional
+local-Ollama for one rung. Ships as an **MCP server** so Claude Code, OpenCode
+and any MCP client can use it in one config block.
+
+## install
+
+```
+pip install anchor-memory        # from PyPI (once published — see site for status)
+```
+
+or straight from this repo — works right now:
+
+```
+pip install git+https://github.com/zacharyol/anchor-memory.git
+```
+
+Website & full setup guide: https://zacharyol.github.io/anchor-memory/
+
+## quickstart
+
+```
+anchor-mcp                      # starts the MCP server (stdio)
+python -m anchor.selftest       # offline end-to-end test with numbers
+python -m anchor.replay         # ingest your own OpenCode session history
+```
+
+Wire it into your agent (one block, then restart the session):
+
+```json
+{ "mcpServers": { "anchor": { "command": "anchor-mcp" } } }
+```
+
+Your agent gains: `anchor_resolve` (what was p3c2?), `anchor_check` (which
+names in this summary are unexplained?), `anchor_search` (BM25 over raw
+history), `anchor_sessions`, `anchor_sync` (incremental ingest from the live
+session database), `anchor_stats`, and `anchor_relay` (shard-searchers with
+negative-result merge — the last resort before "unfindable").
+
+## measured results (real session history, llama3.1:8B judge-free agent)
+
+| version | change | vanilla → anchored recall | token overhead |
+|---|---|---|---|
+| v0.3 | bulk cards | 33% → 44% | +48% |
+| v0.4 | selective card | 33% → 44% | **+5%** |
+| v0.5 | junk filter, repeats (n=36) | 19% → **47%** | +5% |
+| v0.6 | best-explanation cards (n=72) | 19% → **42%** | +5% |
+
+Trigger fire precision on labeled real data: 58% (firing is free — junk is
+filtered at the card layer). Sampling wobble ±5–6%: model randomness is small;
+question difficulty dominates. Full methodology:
+[docs/BENCHMARK.md](docs/BENCHMARK.md).
+
+## how it's made
+
+- [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md) — the architecture walk-through:
+  the two memory classes, the write path, the trigger rules, every ladder rung,
+  the relay, the data formats.
+- [docs/BENCHMARK.md](docs/BENCHMARK.md) — how the numbers above are produced
+  and how to reproduce them on your own session history.
+- [DESIGN.md](anchor/DESIGN.md) — the original design doc, kept as written.
+
+## why open source
+
+Memory loss after compaction is the defining production failure of long
+running agents ("context rot"). anchor's answer is deliberately simple:
+archive raw, index entities, detect the gap automatically, search in a cost
+ladder, and never trust a summary when the primary source still exists.
+MIT licensed — take it, wire it, fork it.
+
+## works with
+
+Claude Code · OpenCode · any MCP client · local Ollama (optional, rung 2)
+
+MIT License · repo: https://github.com/zacharyol/anchor-memory

anchor_memory-0.7.0/anchor/__init__.py

@@ -0,0 +1,3 @@
+"""anchor — mm + ms for AI agents. See DESIGN.md."""
+
+__version__ = "0.7.0"

anchor_memory-0.7.0/anchor/archive.py

@@ -0,0 +1,72 @@
+"""Archive — the mm side. Append-only JSONL of raw session events, written
+BEFORE compaction can destroy anything. Every record is citable by id."""
+import json
+import os
+import time
+
+from . import extract
+
+
+class Archive:
+    def __init__(self, path):
+        self.path = path
+        os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+        self._n = 0
+        if os.path.exists(path):  # resume ids after restart
+            with open(path, "r", encoding="utf-8") as f:
+                for line in f:
+                    if line.strip():
+                        self._n += 1
+        self._fh = open(path, "a", encoding="utf-8")
+
+    def append(self, kind, text, task="", compaction=0, entities=None, ts=None, **extra):
+        """Record one raw event. Entities auto-extracted when not given.
+        Extra keyword fields (session, source_id, source_ts) pass through."""
+        if entities is None:
+            entities = extract.extract_entities(text)
+        rec = {
+            "id": "a%06d" % (self._n + 1),
+            "ts": ts if ts is not None else time.time(),
+            "kind": kind,          # message | tool_call | tool_result | decision
+            "task": task,
+            "compaction": compaction,
+            "entities": entities,
+            "text": text,
+        }
+        rec.update(extra)
+        self._fh.write(json.dumps(rec, ensure_ascii=False) + "\n")
+        self._fh.flush()
+        self._n += 1
+        return rec["id"]
+
+    def get(self, rec_id):
+        for rec in self.iter():
+            if rec["id"] == rec_id:
+                return rec
+        return None
+
+    def iter(self):
+        if not os.path.exists(self.path):
+            return
+        with open(self.path, "r", encoding="utf-8") as f:
+            for line in f:
+                if line.strip():
+                    yield json.loads(line)
+
+    def count(self):
+        return self._n
+
+    def reopen(self, path=None):
+        """Close the append handle and recount (used after a file swap)."""
+        self._fh.close()
+        if path:
+            self.path = path
+        self._n = 0
+        with open(self.path, "r", encoding="utf-8") as f:
+            for line in f:
+                if line.strip():
+                    self._n += 1
+        self._fh = open(self.path, "a", encoding="utf-8")
+
+    def close(self):
+        self._fh.close()

anchor_memory-0.7.0/anchor/bench.py

@@ -0,0 +1,249 @@
+"""v0.3 — precision labeling + A/B benchmark on real compaction data.
+
+Two modes:
+
+  python -m anchor.bench --sample N     dump N random fires + their ground truth
+                                        for precision labeling
+  python -m anchor.bench [--sessions N] [--entities N] [--model NAME]
+                                        A/B: vanilla summary vs anchored summary
+                                        (auto-resolved citation cards injected),
+                                        same questions, real Ollama, token counts.
+"""
+import json
+import os
+import random
+import statistics
+import time
+
+from .archive import Archive
+from .index import BM25, build_entity_table
+from .ladder import Resolver
+from .replay import DEFAULT_DB, load_opencode_db
+from .trigger import find_dangling
+from .ollama_client import _post
+
+QUESTION = ("Before this summary, you were working in the same session and made "
+            "or used things that are only named above. What is '{e}' and what "
+            "did you do with it? One short paragraph, from memory.")
+
+
+# generic names that are named but never "forgotten knowledge" (label aid)
+GENERIC = {"readme.md", "license", "package.json", "opencode.json", "agents.md",
+           "cmd.exe", "powershell.exe", "python.exe", "server.py", "start.bat",
+           "install.bat", "index.html", "todo.md", "notes.txt", "game.log",
+           "settings.json", "config.json", ".gitignore", "requirements.txt"}
+
+
+def build(db, max_sessions=None):
+    out = db + ".anchor.jsonl"
+    if os.path.exists(out):
+        os.remove(out)
+    arch = Archive(out)
+    n_sess, n_comp, probes = load_opencode_db(db, arch, max_sessions)
+    records = list(arch.iter())
+    table = build_entity_table(records)
+    return arch, table, BM25(records), probes
+
+
+def fire_set(summary):
+    return [d["entity"] for d in find_dangling(summary)]
+
+
+def make_qa(summary, table, k):
+    """(entity, ground-truth line) for entities the summary names but doesn't explain."""
+    qa = []
+    for e in fire_set(summary):
+        if e.lower() in GENERIC or e not in table:
+            continue
+        gt = table[e]["line"] or ""
+        if len(gt) > 30:
+            qa.append((e, gt))
+        if len(qa) >= k:
+            break
+    return qa
+
+
+def chat_full(model, messages, timeout=180, num_ctx=8192, retries=3, temp=0.2):
+    last = None
+    for attempt in range(retries):
+        try:
+            resp = _post("/api/chat", {
+                "model": model, "messages": messages, "stream": False,
+                "options": {"num_ctx": num_ctx, "temperature": temp}}, timeout)
+            usage = {"prompt": resp.get("prompt_eval_count", 0),
+                     "output": resp.get("eval_count", 0)}
+            return resp.get("message", {}).get("content", "").strip(), usage
+        except Exception as e:  # Ollama 500s / timeouts: back off and retry
+            last = e
+            time.sleep(5 * (attempt + 1))
+    raise last
+
+
+def fact_overlap(answer, ground_truth):
+    """Fraction of ground-truth content words present in the answer
+    (plural-folded — 'villagers' matches 'villager' — to cut metric noise)."""
+    from .index import tokenize, norm_word
+    gt = {norm_word(w) for w in tokenize(ground_truth) if len(w) > 3}
+    if not gt:
+        return 0.0
+    a = {norm_word(w) for w in tokenize(answer)}
+    return sum(1 for w in gt if w in a) / len(gt)
+
+
+def card(entity, r):
+    c = f"- {entity}: {(r['what'] or '')[:160]}"
+    if r.get("file"):
+        c += f" (file: {r['file']})"
+    return c
+
+
+MEMORY_INTRO = "\n\nYour memory of the above (from your session archive):\n"
+
+
+def run_bench(sessions_n, entities_k, model, resolve_cap=12, repeats=1,
+              arms=("vanilla", "selective"), title_filter=None):
+    arch, table, bm25, probes = build(DEFAULT_DB, max_sessions=None)
+    resolver = Resolver(arch, table, bm25, llm=None)
+    random.seed(7)
+    probes = random.sample(probes, min(sessions_n, len(probes)))
+
+    rows = []
+    for p in probes:
+        if title_filter and title_filter.lower() not in (p["session"] or "").lower():
+            continue
+        summary = p["summary"]
+        qa = make_qa(summary, table, entities_k)
+        if not qa:
+            continue
+        resolver.workspace_root = p["workspace"] or resolver.workspace_root
+        if "bulk" in arms:  # v0.3 behavior, kept for comparison runs
+            fired = fire_set(summary)[:resolve_cap]
+            bulk_cards = []
+            for e in fired:
+                r = resolver.resolve(e, hint="")
+                if r["found"]:
+                    bulk_cards.append(card(e, r))
+            bulk_ctx = summary + MEMORY_INTRO + "\n".join(bulk_cards)
+
+        for entity, gt in qa:
+            r = resolver.resolve(entity, hint="")
+            # ground truth = union of true memory facets (index line + the
+            # resolver's evidence line/docstring) — an answer echoing any
+            # genuine recovered fact scores, whichever facet it echoes
+            gt_full = gt + " " + (r["what"] or "")
+            # v0.5 junk filter at the card layer: skip generic names and
+            # resolutions that add no real "what" line
+            use_card = (r["found"] and entity.lower() not in GENERIC
+                        and len(r["what"] or "") > 30)
+            sel_ctx = summary + MEMORY_INTRO + (card(entity, r) if use_card else "")
+            for arm in arms:
+                ctx = summary if arm == "vanilla" else sel_ctx
+                for rep in range(repeats):
+                    t0 = time.perf_counter()
+                    try:
+                        ans, usage = chat_full(model, [
+                            {"role": "system", "content":
+                                "You are a coding agent continuing after a context "
+                                "compaction. Answer only from your memory of the session."},
+                            {"role": "user", "content": ctx + "\n\n" + QUESTION.format(e=entity)}])
+                    except Exception as e:
+                        rows.append({"session": p["session"][:40], "entity": entity,
+                                     "arm": arm, "repeat": rep, "overlap": None,
+                                     "tokens": 0, "latency": round(
+                                         time.perf_counter() - t0, 1),
+                                     "answer": f"<call failed: {e}>"})
+                        continue
+                    lat = time.perf_counter() - t0
+                    rows.append({"session": p["session"][:40], "entity": entity,
+                                 "arm": arm, "repeat": rep,
+                                 "overlap": fact_overlap(ans, gt_full),
+                                 "tokens": usage["prompt"] + usage["output"],
+                                 "latency": round(lat, 1), "answer": ans[:200]})
+
+    # ---------------- report ----------------
+    if not rows:
+        print("no QA pairs produced — nothing to score")
+        return
+    print(f"model: {model}   repeats: {repeats}   arms: {', '.join(arms)}")
+    print(f"\nper-question (mean coverage over repeats):")
+    seen = {}
+    for r in rows:
+        seen.setdefault((r["entity"], r["arm"]), []).append(r["overlap"])
+    for (entity, arm), ovs in seen.items():
+        mean = sum(ovs) / len(ovs)
+        print(f"  {entity:<40} {arm:<10} {mean:>4.0%}  (n={len(ovs)})")
+
+    base = None
+    q = {}
+    for r in rows:
+        if r["overlap"] is not None:
+            q.setdefault((r["arm"], r["session"], r["entity"]), []).append(r["overlap"])
+
+    # persist raw rows so analysis never needs another 144 LLM calls
+    out_path = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                            "bench_results.jsonl")
+    with open(out_path, "a", encoding="utf-8") as f:
+        for r in rows:
+            f.write(json.dumps(r) + "\n")
+    print(f"rows appended to {out_path}")
+
+    base = None
+    for arm in arms:
+        arm_rows = [r for r in rows if r["arm"] == arm]
+        if not arm_rows:
+            continue
+        failed = sum(1 for r in arm_rows if r["overlap"] is None)
+        valid = [r for r in arm_rows if r["overlap"] is not None]
+        if not valid:
+            continue
+        acc = sum(1 for r in valid if r["overlap"] >= 0.5) / len(valid)
+        ovs = [r["overlap"] for r in valid]
+        mean_overlap = sum(ovs) / len(ovs)
+        std_overlap = statistics.pstdev(ovs) if len(ovs) > 1 else 0.0
+        # true sampling wobble: mean of per-question std over repeats
+        wobbles = [statistics.pstdev(v) for (a, _, _), v in q.items()
+                   if a == arm and len(v) > 1]
+        wobble = sum(wobbles) / len(wobbles) if wobbles else 0.0
+        toks = sum(r["tokens"] for r in valid) / len(valid)
+        if arm == "vanilla":
+            base = toks
+        delta = f"({(toks - base) / base:+.0%} vs vanilla)" if base else ""
+        print(f"\n{arm.upper()}: recall {acc:.0%}, fact coverage "
+              f"{mean_overlap:.0%} ± {std_overlap:.0%} pooled, "
+              f"sampling wobble ±{wobble:.0%}, "
+              f"{toks:.0f} tokens/question {delta}, "
+              f"n={len(valid)}" + (f" ({failed} failed calls)" if failed else ""))
+
+
+def run_sample(n):
+    arch, table, bm25, probes = build(DEFAULT_DB)
+    random.seed(7)
+    fires = []
+    for p in probes:
+        for e in fire_set(p["summary"]):
+            fires.append((e, table.get(e, {}).get("line", "")))
+    random.shuffle(fires)
+    print(f"{len(fires)} total fires; random sample of {n} with ground truth:\n")
+    for e, line in fires[:n]:
+        print(f"  {e:<28} {line[:110]}")
+
+
+if __name__ == "__main__":
+    import argparse
+    import sys
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # cp1252-safe
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--sample", type=int, default=0)
+    ap.add_argument("--sessions", type=int, default=6)
+    ap.add_argument("--entities", type=int, default=4)
+    ap.add_argument("--repeats", type=int, default=3)
+    ap.add_argument("--arms", default="vanilla,selective")
+    ap.add_argument("--model", default="gemma4:26b")
+    ap.add_argument("--title", default=None, help="only probes whose session title contains this")
+    args = ap.parse_args()
+    if args.sample:
+        run_sample(args.sample)
+    else:
+        run_bench(args.sessions, args.entities, args.model,
+                  repeats=args.repeats, arms=tuple(args.arms.split(",")),
+                  title_filter=args.title)

anchor_memory-0.7.0/anchor/extract.py

@@ -0,0 +1,82 @@
+"""Entity extraction. Offline, deterministic, stdlib only.
+
+Finds the names an agent leaves behind in its own transcript: file paths,
+snake_case / camelCase / UPPER_SNAKE identifiers, lowercase tokens containing
+digits (p3c2, l9, zzq9), and "tool X" / "named X" style mentions.
+"""
+import re
+
+PATH_RE = re.compile(r"(?:[A-Za-z]:[\\/])?(?:[\w.-]+[\\/]){0,6}[\w-]{2,}\.[A-Za-z]{1,5}\b")
+SNAKE_RE = re.compile(r"\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b")
+CAMEL_RE = re.compile(r"\b[a-z]+(?:[A-Z][a-z0-9]+)+\b")
+UPPER_RE = re.compile(r"\b[A-Z][A-Z0-9]{2,}(?:_[A-Z0-9]+)+\b")
+# lowercase token with at least one digit: p3c2, l9, zzq9
+DIGIT_RE = re.compile(r"\b[a-z][a-z0-9]*\d[a-z0-9]*\b")
+NAMED_RE = re.compile(
+    r"\b(?:tool|script|module|function|command|named|called)\s+([A-Za-z][\w-]{2,30})\b")
+
+# generic words that match the loose patterns but are never entities
+STOP = {
+    "the", "and", "for", "this", "that", "with", "from", "have", "not", "are",
+    "was", "but", "all", "can", "her", "she", "his", "has", "were", "been",
+    "will", "would", "could", "should", "than", "then", "them", "they", "its",
+    "our", "out", "about", "into", "over", "after", "under", "more", "most",
+    "some", "such", "only", "also", "just", "like", "when", "what", "which",
+    "who", "how", "why", "where", "while", "these", "those", "there", "here",
+    "one", "two", "three", "none", "true", "false", "self", "str", "int",
+    "float", "bool", "list", "dict", "set", "file", "path", "name", "tool",
+    "test", "data", "text", "line", "time", "make", "made", "used", "using",
+    "use", "new", "get", "put", "run", "ran", "see", "saw", "tmp", "temp",
+    "www", "com", "org", "http", "https", "utf", "bin", "usr", "var",
+    "e.g", "i.e", "etc",
+}
+
+
+def _clean(cands):
+    out = []
+    for c in cands:
+        c = c.strip(".\\/")
+        if c.lower() in STOP or len(c) < 3:
+            continue
+        # JSON-escaped newline artifacts: "\nName" inside a string literal
+        # extracts as "nName", "\nOutput" as "nOutput" — strip the artifact
+        if len(c) > 2 and c[0] in "nr" and c[1].isupper():
+            c = c[1:]
+            if c.lower() in STOP or len(c) < 3 or not is_entity(c):
+                continue
+        out.append(c)
+    return out
+
+
+# "tool named p3c2" makes NAMED_RE capture the keyword itself from the pair
+NAMED_KEYWORDS = {"named", "called"}
+
+
+def extract_entities(text):
+    """All candidate entities in `text`, most specific first (paths before names)."""
+    paths = _clean(m.group(0).replace("\\", "/") for m in PATH_RE.finditer(text))
+    # bare stems of paths are also entities (tools/p3c2.py -> p3c2)
+    stems = _clean(p.rsplit("/", 1)[-1].rsplit(".", 1)[0] for p in paths)
+    named = [m.group(1) for m in NAMED_RE.finditer(text)
+             if m.group(1).lower() not in NAMED_KEYWORDS]
+    # a captured "name" must be entity-shaped: digit, underscore or inner
+    # capital ("p3c2", "BreakInModMenu") — rejects plain verbs like "finishes"
+    named = [n for n in named if any(ch.isdigit() for ch in n)
+             or "_" in n or any(ch.isupper() for ch in n[1:])]
+    named = _clean(named)
+    upper = _clean(m.group(0) for m in UPPER_RE.finditer(text))
+    snake = _clean(m.group(0) for m in SNAKE_RE.finditer(text))
+    camel = _clean(m.group(0) for m in CAMEL_RE.finditer(text))
+    digits = _clean(m.group(0) for m in DIGIT_RE.finditer(text))
+    seen, out = set(), []
+    for group in (paths, stems, named, upper, snake, camel, digits):
+        for e in group:
+            if e not in seen:
+                seen.add(e)
+                out.append(e)
+    return out
+
+
+def is_entity(word):
+    """Is this single token shaped like an entity we care about?"""
+    return bool(extract_entities(word)) and word not in STOP