strata-agent-memory 0.2.0__py3-none-any.whl

agent_memory/__init__.py

@@ -0,0 +1,12 @@
+"""agent-memory: portable, auditable, cross-vendor memory for LLM agents.
+
+The unit of memory is a *claim* made by an identified author (human or agent,
+with vendor lineage) inside a scope, bound to *evidence* that can be re-run.
+Context handed to any agent is a *compiled view* over that ledger, and every
+compilation is itself recorded so you can always answer: what did this agent
+see, what did it claim, and can the proof be re-run.
+
+The core is dependency-free (Python 3.10+ standard library only).
+"""
+
+__version__ = "0.2.0"

agent_memory/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+import sys
+
+sys.exit(main())

agent_memory/audit.py

@@ -0,0 +1,345 @@
+"""Audit: the questions a human asks when something went wrong, answered from the ledger.
+
+- What is verified, and by whom? Which verifications are same-vendor only, or come
+  from the claim's own author?
+- Do cross-lineage verifiers refute more than same-lineage ones? (lineage_matrix)
+- Which outcome claims have receipts nobody has re-run?
+- Which outcome claims cite a receipt whose command never succeeded?
+- Which outcome claims rest on static evidence only (lint clean, never executed)?
+- Which receipts declare an assurance class stronger than their content backs?
+- What has been refuted, and what was built on top of it (taint chains)?
+- Which claims are stale because the world moved (files changed, commits gone)?
+- How often do claims like this one turn out wrong, and how long does each class of
+  binding keep matching? (reliability, same_lineage_agreement, staleness,
+  judgment_calibration; docs/PHASE3-RELIABILITY.md)
+- Which records carry a signature, and does every signature check out? (signatures;
+  a signature says who filed a record, never that it is true)
+- How much of memory is human-authored vs agent-authored?
+- Which contracts are open, and do their claims meet the bar?
+- What did each agent session actually get shown (compilation receipts)?
+"""
+from __future__ import annotations
+
+import re
+from collections import Counter, defaultdict
+from typing import Dict, List, Optional
+
+from . import evidence as ev
+from . import reliability as rel
+from . import signing
+from .contracts import status_of
+from .records import is_redacted
+from .trust import TIERS, assess, lineage_differs, summarize
+
+# Anything a compiled view would have to render on its own line. The renderer collapses
+# these (review S5); the audit names the records that carried them, because a statement
+# shaped like a document is a statement written to be read as one.
+_CONTROL_RE = re.compile(r"[\x00-\x1f\x7f]")
+_FORMATTED_FIELDS = ("statement", "rationale", "example")
+
+
+def _formatting_problem(text: str) -> Optional[str]:
+    """The first line of ``text`` that could forge structure in a compiled view, or None."""
+    lines = text.splitlines()
+    if not _CONTROL_RE.search(text) and not any(line.lstrip().startswith("#") for line in lines):
+        return None
+    for line in lines:
+        if line.lstrip().startswith("#") or _CONTROL_RE.search(line):
+            return line.strip()[:120]
+    filled = [line for line in lines if line.strip()]
+    return (filled[-1] if filled else text).strip()[:120]
+
+
+def _same_session_other_harness(claim_author: dict, verifier: dict) -> bool:
+    """True when a "cross-vendor" verification came out of the claim's own session.
+
+    Harness and vendor are self-asserted outside ``serve``'s token path (review S9), so
+    one shell that exports a different AGENT_MEMORY_HARNESS produces a verification that
+    counts as independent. Same user, same session, different harness is what that looks
+    like from the ledger, and it is free to compute.
+    """
+    session = claim_author.get("session")
+    return bool(
+        session and session != "unknown"
+        and verifier.get("session") == session
+        and verifier.get("user") == claim_author.get("user")
+        and verifier.get("harness") != claim_author.get("harness")
+    )
+
+
+def report(ledger, recheck: bool = False, cwd: Optional[str] = None, timeout: Optional[float] = 300,
+           path_map=None) -> dict:
+    assessment = assess(ledger)
+    claims = ledger.claims()
+    by_id = {c["id"]: c for c in claims}
+    rep: Dict = {
+        "project": ledger.config.get("project"),
+        # whether this machine trusts the repository's config.json, and so whether its
+        # policy keys decided anything (review F-3, F-6)
+        "trusted": bool(getattr(ledger, "trusted", True)),
+        "records": Counter(r["kind"] for r in ledger.all()),
+        "tiers": summarize(assessment),
+        "authors": Counter(),
+        "human_vs_agent": Counter(),
+        "vendors": Counter(),
+        "unrechecked_outcomes": [],
+        "failing_receipt_outcomes": [],
+        "static_only_outcomes": [],
+        "assurance_overridden": [],
+        "same_vendor_only": [],
+        "self_verified_by_author": [],
+        "same_session_different_harness": [],
+        "formatted_statements": [],
+        "redactions": {"count": 0, "ids": []},
+        # absent and empty mean opposite things (an absent key allows every command, an
+        # empty list allows none), so the report carries both facts
+        "recheck_allow_set": "recheck_allow" in ledger.config,
+        "recheck_allow": list(ledger.config.get("recheck_allow") or []),
+        "lineage_matrix": {},
+        "same_lineage_refutation_rate": None,
+        "cross_lineage_refutation_rate": None,
+        "refuted": [],
+        "taint_chains": [],
+        "stale": [],
+        "asserted_facts": [],
+        "contracts": [],
+        "compilations": [],
+        "signatures": {},
+        "recheck": [],
+    }
+    # measured history, computed from the ledger alone: counts, intervals, and the word
+    # "insufficient history" wherever there are too few of them
+    measured = rel.report(ledger, assessment)
+    rep["reliability"] = measured["table"]
+    rep["same_lineage_agreement"] = measured["same_lineage_agreement"]
+    rep["staleness"] = measured["staleness"]
+    rep["judgment_calibration"] = measured["judgment_calibration"]
+    for c in claims:
+        a = c["author"]
+        rep["authors"][f"{a.get('harness')}:{a.get('user')}"] += 1
+        rep["human_vs_agent"][a.get("kind")] += 1
+        rep["vendors"][a.get("vendor")] += 1
+        info = assessment[c["id"]]
+        b = c["body"]
+        entry = {"id": c["id"], "type": b["type"], "statement": b["statement"][:160], "by": a.get("harness"), "vendor": a.get("vendor"), "ts": c["ts"]}
+        if b["type"] == "outcome" and info["tier"] == "evidenced":
+            rep["unrechecked_outcomes"].append(entry)
+        if b["type"] == "outcome":
+            # legacy ledgers can hold these; the filing rule rejects new ones (§4)
+            unmet = ev.unmet_expectations(ledger, c)
+            if unmet:
+                rep["failing_receipt_outcomes"].append({**entry, "receipts": unmet})
+            # a declared class above the computed default backs nothing, so this reads the
+            # receipts rather than the declaration
+            backed = ev.max_assurance(ev.effective_assurance(eb) for _, eb in ev.resolve_evidence(ledger, c))
+            if backed in ("static", "attested"):
+                # a clean static gate is not evidence that the thing runs
+                rep["static_only_outcomes"].append({**entry, "assurance": backed})
+        if info["tier"] == "self-verified":
+            rep["same_vendor_only"].append({**entry, "verified_by": info["verified_by"]})
+        if info.get("self_verified_by_author"):
+            rep["self_verified_by_author"].append({**entry, "verified_by": info["verified_by"]})
+        if info["tier"] == "refuted":
+            # sorted: dependents_of returns a set, and an audit two runs cannot reproduce
+            # byte for byte is not the audit this ledger promises
+            deps = sorted(d for d in ledger.dependents_of(c["id"], through_kinds=("claim",)) if d in by_id)
+            rep["refuted"].append({**entry, "reasons": info["reasons"], "dependents": len(deps)})
+            if deps:
+                rep["taint_chains"].append({"root": c["id"], "tainted": [{"id": d, "statement": by_id[d]["body"]["statement"][:120]} for d in deps]})
+        if info["tier"] == "stale":
+            rep["stale"].append({**entry, "reasons": info["reasons"]})
+        if info["tier"] == "asserted" and b["type"] == "fact":
+            rep["asserted_facts"].append(entry)
+        for field in _FORMATTED_FIELDS:
+            value = b.get(field)
+            problem = _formatting_problem(value) if isinstance(value, str) else None
+            if problem:
+                rep["formatted_statements"].append({**entry, "field": field, "line": problem})
+                break
+    # assurance is self-declared, so say which receipts declared more than they can back
+    cited_by: Dict[str, List[str]] = defaultdict(list)
+    for c in claims:
+        for item in c["body"].get("evidence", []):
+            if isinstance(item, str):
+                cited_by[item].append(c["id"])
+    for rec in ledger.by_kind("evidence"):
+        b = rec["body"]
+        if not ev.assurance_is_declared(b):
+            continue
+        rep["assurance_overridden"].append({
+            "id": rec["id"], "kind": b.get("kind"), "declared": b.get("assurance"),
+            "computed": ev.default_assurance(b), "by": rec["author"].get("harness"),
+            "what": str(b.get("cmd") or b.get("path") or b.get("url") or b.get("sha") or "")[:120],
+            "claims": sorted(cited_by.get(rec["id"], [])),
+        })
+    # verifier lineage: the refutation rate of same-lineage vs cross-lineage review is
+    # the number that decides whether the cross-vendor rule earns its keep
+    same_counts = Counter()
+    cross_counts = Counter()
+    for v in ledger.by_kind("verification"):
+        claim = by_id.get(v["body"].get("claim"))
+        if claim is None:
+            continue
+        verdict = v["body"]["verdict"]
+        key = f"{claim['author'].get('vendor')}->{v['author'].get('vendor')}"
+        cell = rep["lineage_matrix"].setdefault(key, {"verified": 0, "refuted": 0, "inconclusive": 0})
+        cell[verdict] += 1
+        (cross_counts if lineage_differs(claim["author"], v["author"]) else same_counts)[verdict] += 1
+        if _same_session_other_harness(claim["author"], v["author"]):
+            cb = claim["body"]
+            rep["same_session_different_harness"].append({
+                "id": claim["id"], "verification": v["id"], "verdict": verdict,
+                "statement": cb["statement"][:160], "by": claim["author"].get("harness"),
+                "verified_by": v["author"].get("harness"), "user": v["author"].get("user"),
+                "session": v["author"].get("session"),
+            })
+    for name, counts in (("same_lineage_refutation_rate", same_counts), ("cross_lineage_refutation_rate", cross_counts)):
+        decisive = counts["verified"] + counts["refuted"]  # inconclusive is not a verdict
+        rep[name] = (counts["refuted"] / decisive) if decisive else None
+    for rec in ledger.by_kind("contract"):
+        st = status_of(ledger, rec["id"], assessment)
+        tiers = Counter(c["tier"] for c in st["claims"])
+        rep["contracts"].append({"id": st["id"], "title": st["title"], "status": st["status"], "claims": len(st["claims"]), "tiers": dict(tiers)})
+    for rec in ledger.by_kind("compilation"):
+        b = rec["body"]
+        rep["compilations"].append({"id": rec["id"], "ts": rec["ts"], "role": b["role"], "mode": b["mode"], "reader": (b.get("reader") or {}).get("harness"),
+                                    "included": len(b["included"]), "excluded": len(b["excluded"]), "tokens": b.get("used_tokens")})
+    # what was erased. The tombstones are still here, which is the point: an audit can
+    # say that something was removed, by whom and why (review C1).
+    redacted = [r for r in ledger.all() if is_redacted(r)]
+    rep["redactions"] = {
+        "count": len(redacted),
+        "ids": [r["id"] for r in redacted],
+        "items": [{"id": r["id"], "kind": r["kind"], "reason": str(r["body"].get("reason", ""))[:120],
+                   "by": (r["body"].get("redacted_by") or {}).get("user"),
+                   "at": r["body"].get("redacted_at")} for r in redacted],
+    }
+    # who signed what. Verification needs the optional extra, so on a machine without it
+    # every attestation is reported as unverifiable rather than as good or bad, and a
+    # signature never moves a claim between tiers either way (§5).
+    sig = signing.report(ledger)
+    attested_by_author = Counter()
+    for record_id in sig["by_record"]:
+        signed = ledger.get(record_id)
+        if signed is not None:
+            a = signed["author"]
+            attested_by_author[f"{a.get('harness')}:{a.get('user')}"] += 1
+    rep["signatures"] = {
+        "attested": sig["attested"], "valid": sig["valid"], "invalid": sig["invalid"],
+        "unknown": sig["unknown"], "unavailable": sig["unavailable"],
+        "invalid_items": [i for i in sig["items"] if i["status"] != "valid"],
+        "by_author": dict(attested_by_author),
+    }
+    if recheck:
+        for c in claims:
+            info = assessment[c["id"]]
+            if info["tier"] in ("refuted", "tainted"):
+                continue
+            unmet = set(ev.unmet_expectations(ledger, c))
+            for r in ev.recheck_claim(ledger, c, cwd=cwd, timeout=timeout, path_map=path_map):
+                if r["outcome"] == "skipped":
+                    continue
+                entry = {"claim": c["id"], "evidence": r["evidence"], "outcome": r["outcome"], "detail": r["detail"][:200]}
+                if r.get("role"):  # an environment mismatch is staleness, not a refutation
+                    entry["role"] = r["role"]
+                if r["outcome"] == "match" and r["evidence"] in unmet:
+                    entry["note"] = ev.FAILING_RECEIPT_NOTE  # reproducing a failure verifies nothing
+                rep["recheck"].append(entry)
+    return rep
+
+
+def format_report(rep: dict) -> str:
+    lines = [f"# Audit: {rep['project']}", ""]
+    lines.append("records: " + ", ".join(f"{k}={v}" for k, v in sorted(rep["records"].items())))
+    lines.append("tiers:   " + ", ".join(f"{t}={rep['tiers'].get(t, 0)}" for t in TIERS))
+    lines.append("authors: " + ", ".join(f"{k}={v}" for k, v in rep["authors"].most_common()))
+    lines.append("kind:    " + ", ".join(f"{k}={v}" for k, v in rep["human_vs_agent"].items()))
+    lines.append("vendors: " + ", ".join(f"{k}={v}" for k, v in rep["vendors"].most_common()))
+    if not rep.get("trusted", True):
+        lines.append("repo:    UNTRUSTED -- config.json's policy keys (recheck_allow, "
+                     "recheck_allow_shell, redact, path_map, org_path, signers, vendor_map, "
+                     "cross_vendor_required) were ignored; run `agent-memory trust .` to honour them")
+    if not rep.get("recheck_allow_set"):
+        lines.append("warning: config.recheck_allow is not set: the re-check lane will run whatever "
+                     "command a receipt records; run `agent-memory init` to write the starter list")
+    elif not rep.get("recheck_allow"):
+        # deliberate, and the opposite of the absent case: nothing is re-run here
+        lines.append("note: recheck_allow is empty: no receipt will be re-run on this machine")
+
+    def section(title: str, rows: List[dict], fmt):
+        lines.append("")
+        lines.append(f"## {title} ({len(rows)})")
+        for r in rows[:50]:
+            lines.append("- " + fmt(r))
+        if len(rows) > 50:
+            lines.append(f"- ... {len(rows) - 50} more")
+
+    section("Outcome claims with receipts nobody re-ran", rep["unrechecked_outcomes"],
+            lambda r: f"{r['id']} [{r['by']}] {r['statement']}")
+    section("Outcome claims whose receipts did not succeed", rep["failing_receipt_outcomes"],
+            lambda r: f"{r['id']} [{r['by']}] {r['statement']} -- receipts: {', '.join(r['receipts'])}")
+    section("Outcome claims backed only by static evidence (static-pass/dynamic-fail risk)",
+            rep["static_only_outcomes"], lambda r: f"{r['id']} [{r['by']}, {r['assurance']}] {r['statement']}")
+    section("Receipts whose assurance was declared above the computed default", rep["assurance_overridden"],
+            lambda r: f"{r['id']} [{r['by']}] declared {r['declared']}, computed {r['computed']}: {r['what']}"
+                      + (f" (cited by {', '.join(r['claims'])})" if r["claims"] else " (cited by no claim)"))
+    section("Verified only by the same vendor (collusion risk)", rep["same_vendor_only"],
+            lambda r: f"{r['id']} [{r['vendor']} verified by {', '.join(r['verified_by'])}] {r['statement']}")
+    section("Verified only by the claim's own author", rep["self_verified_by_author"],
+            lambda r: f"{r['id']} [{r['by']}] {r['statement']}")
+    section("Verified from the claim's own session under another harness (collusion risk)",
+            rep.get("same_session_different_harness", []),
+            lambda r: f"{r['id']} [{r['by']} -> {r['verified_by']}, {r['user']} session {r['session']}] "
+                      f"{r['statement']}")
+    section("Statements shaped like a document (injection risk)", rep.get("formatted_statements", []),
+            lambda r: f"{r['id']} [{r['by']}] {r['field']} starts a line with: {r['line']}")
+    section("Refuted", rep["refuted"], lambda r: f"{r['id']} {r['statement']} -- {'; '.join(r['reasons'])} (dependents: {r['dependents']})")
+    section("Taint chains", rep["taint_chains"], lambda r: f"{r['root']} -> " + ", ".join(t['id'] for t in r['tainted']))
+    section("Stale", rep["stale"], lambda r: f"{r['id']} {r['statement']} -- {'; '.join(r['reasons'])}")
+    section("Facts with no evidence (asserted)", rep["asserted_facts"], lambda r: f"{r['id']} [{r['by']}] {r['statement']}")
+    section("Contracts", rep["contracts"], lambda r: f"{r['id']} {r['status']}: {r['title']} ({r['claims']} claims {r['tiers']})")
+    section("Compilation receipts", rep["compilations"],
+            lambda r: f"{r['id']} {r['ts']} {r['role']}/{r['mode']} for {r['reader']}: {r['included']} in, {r['excluded']} out, {r['tokens']} tok")
+    red = rep.get("redactions") or {}
+    if red.get("count"):
+        lines.append("")
+        lines.append(f"## Redacted records ({red['count']})")
+        for item in (red.get("items") or [{"id": i} for i in red.get("ids", [])])[:50]:
+            lines.append(f"- {item['id']}" + (f" [{item.get('kind')}] by {item.get('by')} "
+                                              f"at {item.get('at')}: {item.get('reason')}"
+                                              if item.get("reason") is not None else ""))
+    sig = rep.get("signatures") or {}
+    if sig.get("attested"):
+        lines.append("")
+        lines.append(f"## Signatures ({sig['attested']})")
+        lines.append(f"- valid={sig.get('valid', 0)} invalid={sig.get('invalid', 0)} "
+                     f"unknown_key={sig.get('unknown', 0)} unverifiable={sig.get('unavailable', 0)}")
+        if sig.get("by_author"):
+            lines.append("- attested records by author: "
+                         + ", ".join(f"{k}={v}" for k, v in sorted(sig["by_author"].items())))
+        for item in sig.get("invalid_items", [])[:50]:
+            lines.append(f"- {item['id']} over {item['record']} [{item['key_id']}]: {item['status']} -- "
+                         f"{item['detail']}")
+    lines.append("")
+    lines.append(f"## Verifier lineage (refutation rates) ({len(rep['lineage_matrix'])})")
+    for key, cell in sorted(rep["lineage_matrix"].items()):
+        total = cell["verified"] + cell["refuted"]
+        rate = f"{cell['refuted'] / total:.2f}" if total else "n/a"
+        lines.append(f"- {key:<32} verified={cell['verified']} refuted={cell['refuted']} "
+                     f"inconclusive={cell['inconclusive']} refutation_rate={rate}")
+    def _rate(value):
+        return "n/a" if value is None else f"{value:.2f}"
+    lines.append(f"- same-lineage refutation rate: {_rate(rep['same_lineage_refutation_rate'])} | "
+                 f"cross-lineage refutation rate: {_rate(rep['cross_lineage_refutation_rate'])}")
+    if "reliability" in rep:
+        lines.append("")
+        lines.append(rel.format_report({"table": rep["reliability"],
+                                        "same_lineage_agreement": rep["same_lineage_agreement"],
+                                        "staleness": rep["staleness"],
+                                        "judgment_calibration": rep["judgment_calibration"]}).rstrip("\n"))
+    if rep["recheck"]:
+        section("Evidence re-check", rep["recheck"],
+                lambda r: f"{r['claim']} {r['evidence']}: {r['outcome']} -- {r['detail']}"
+                          + (" [environment binding: staleness, not refutation]" if r.get("role") == "environment" else "")
+                          + (f" [{r['note']}]" if r.get("note") else ""))
+    return "\n".join(lines) + "\n"