anchor-memory 0.7.0__py3-none-any.whl

anchor/__init__.py

@@ -0,0 +1,3 @@
+"""anchor — mm + ms for AI agents. See DESIGN.md."""
+
+__version__ = "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/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/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

anchor/index.py

@@ -0,0 +1,126 @@
+"""Index — the map of "what's explained where", plus BM25 over the archive.
+Rebuilt from the archive JSONL on load; rebuild is cheap, no persistence needed."""
+import math
+import re
+from collections import Counter
+
+TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+BM25_STOP = {
+    "the", "a", "an", "and", "or", "of", "to", "in", "on", "for", "with", "at",
+    "by", "is", "are", "was", "were", "be", "been", "it", "its", "this", "that",
+    "as", "from", "was", "were", "but", "not", "so", "if", "then", "than",
+    "into", "about", "over", "after", "under", "out", "up", "down", "can",
+    "will", "would", "could", "should", "do", "does", "did", "done", "have",
+    "has", "had", "i", "we", "you", "he", "she", "they", "them", "their",
+}
+
+
+def tokenize(text):
+    return [t for t in TOKEN_RE.findall(text.lower())
+            if len(t) > 1 and t not in BM25_STOP]
+
+
+def norm_word(w):
+    """Light plural-fold for fuzzy fact matching."""
+    return w[:-1] if len(w) > 4 and w.endswith("s") else w
+
+
+EXPLAIN_MARKERS = (" is ", " is a", " is the", "decided", "because", "purpose",
+                   "wrote", "created", "made", "built", "added", "implemented",
+                   "uses", "handles", "parses", "exposes", "fixed", "changed",
+                   "summary")
+
+
+def _explain_score(rec, entity):
+    """How much this record EXPLAINS the entity (vs merely mentioning it).
+    Conversation-only memory lives in decisions, compaction summaries and
+    definition-shaped prose — those must outrank bare tool-JSON mentions.
+    Markers count 0.5 each (uncapped) so purpose-rich records tie out thin ones."""
+    s = 0.0
+    low = rec["text"].lower()
+    el = entity.lower()
+    kind = rec.get("kind", "")
+    if kind == "decision":
+        s += 2
+    elif kind == "tool_call":
+        s += 1
+    if "[compaction" in low or kind == "compaction":
+        s += 2
+    if el in low:
+        s += 2
+        if low.find(el) < 200:      # mentioned early = talked about, not passed by
+            s += 1
+    s += sum(0.5 for m in EXPLAIN_MARKERS if m in low)
+    return s
+
+
+def build_entity_table(records):
+    """entity -> {type, line, explained_in, first_seen}
+    `line` comes from the BEST-EXPLAINING record, not the first mention.
+    Single pass: each record is scored once per entity it mentions."""
+    records = list(records)
+    table = {}
+    for rec in records:
+        text = rec["text"]
+        for e in rec.get("entities", []):
+            entry = table.setdefault(
+                e, {"type": "file" if "/" in e or "." in e else "name",
+                    "line": "", "explained_in": [], "first_seen": rec["id"],
+                    "_best": -1.0, "_best_id": None, "_best_i": -1})
+            entry["explained_in"].append(rec["id"])
+            variants = (e, e.replace("/", "\\"), e.replace("\\", "/"))
+            i = next((text.find(v) for v in variants if v in text), -1)
+            if i == -1:
+                continue
+            score = _explain_score(rec, e)
+            if score > entry["_best"]:
+                entry["_best"] = score
+                entry["_best_id"] = rec["id"]
+                entry["_best_i"] = i
+                snippet = text[max(0, i - 40):i + 160].replace("\n", " ").strip()
+                entry["line"] = ("..." + snippet + "...") if i > 40 else snippet
+    for entry in table.values():
+        entry["best_evidence"] = entry.pop("_best_id")
+        entry.pop("_best_i")
+        entry.pop("_best")
+    return table
+
+
+class BM25:
+    """Standard BM25 over archive record texts. k1=1.5, b=0.75."""
+
+    def __init__(self, records, k1=1.5, b=0.75):
+        self.k1, self.b = k1, b
+        self.recs = list(records)
+        self.docs = [tokenize(r["text"]) for r in self.recs]
+        self.avgdl = (sum(len(d) for d in self.docs) / len(self.docs)) if self.docs else 1.0
+        self.tfs = [Counter(d) for d in self.docs]
+        self.df = Counter()
+        for d in self.docs:
+            for t in set(d):
+                self.df[t] += 1
+        self.N = len(self.recs)
+
+    def _idf(self, t):
+        df = self.df.get(t, 0)
+        return math.log((self.N - df + 0.5) / (df + 0.5) + 1.0)
+
+    def search(self, query, k=8):
+        q = tokenize(query)
+        if not q:
+            return []
+        scored = []
+        for i, (rec, tf) in enumerate(zip(self.recs, self.tfs)):
+            dl = len(self.docs[i]) or 1
+            s = 0.0
+            for t in q:
+                f = tf.get(t, 0)
+                if not f:
+                    continue
+                s += self._idf(t) * f * (self.k1 + 1) / (
+                    f + self.k1 * (1 - self.b + self.b * dl / self.avgdl))
+            if s > 0:
+                scored.append((s, rec))
+        scored.sort(key=lambda x: -x[0])
+        return scored[:k]