mneme-core 2.0.0__py3-none-any.whl

mneme_core/__init__.py

@@ -0,0 +1,4 @@
+"""mneme-core: vault-native memory engine for Claude Code."""
+
+__version__ = "2.0.0"
+__all__ = ["__version__"]

mneme_core/__main__.py

@@ -0,0 +1,8 @@
+"""Module execution entry point for ``python -m mneme_core``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

mneme_core/approval.py

@@ -0,0 +1,183 @@
+"""Human-approval gate for memory edits (conflict-resolution #4).
+
+An agent *proposes* a memory edit; the proposal starts in ``PENDING`` status.
+Edits in *durable* categories (IDENTITY, PREFERENCE, CLINICAL, LEGAL,
+FINANCIAL) must receive explicit human approval before they may be applied.
+Edits in the EPHEMERAL category (session notes, observations) may be applied
+while still PENDING.  A REJECTED proposal can never be applied.
+
+All user-supplied content is passed through :func:`mneme_core.privacy.redact`
+before being stored in the proposal.  Proposal IDs are deterministic
+(``uuid.uuid5``) so re-proposing identical inputs yields the same ID.
+
+Pure, deterministic, no IO, no network, no clock.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+
+from .privacy import redact
+
+# ---------------------------------------------------------------------------
+# Enumerations
+# ---------------------------------------------------------------------------
+
+_NAMESPACE = uuid.UUID("6ba7b810-9dad-11d1-80b4-00c04fd430c8")  # NAMESPACE_URL
+
+
+class ProposalStatus(str, Enum):  # noqa: UP042
+    """Lifecycle status of a :class:`MemoryProposal`.
+
+    Inherits ``str`` so instances serialise directly as JSON strings and
+    compare equal to their string values without an extra ``.value`` call.
+    ``UP042`` suppresses the Ruff suggestion to use ``StrEnum`` (Python 3.11+)
+    to stay consistent with the ``str`` + ``Enum`` pattern used elsewhere.
+    """
+
+    PENDING = "PENDING"
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"
+
+
+class EditCategory(str, Enum):  # noqa: UP042
+    """Semantic category of the memory edit being proposed.
+
+    * **EPHEMERAL** — low-stakes session/topic/observation; may be applied
+      without explicit approval.
+    * All other categories are *durable* and require human approval.
+    """
+
+    EPHEMERAL = "EPHEMERAL"
+    IDENTITY = "IDENTITY"
+    PREFERENCE = "PREFERENCE"
+    CLINICAL = "CLINICAL"
+    LEGAL = "LEGAL"
+    FINANCIAL = "FINANCIAL"
+
+
+#: Categories that require explicit human approval before an edit may be applied.
+DURABLE_CATEGORIES: frozenset[EditCategory] = frozenset(
+    {
+        EditCategory.IDENTITY,
+        EditCategory.PREFERENCE,
+        EditCategory.CLINICAL,
+        EditCategory.LEGAL,
+        EditCategory.FINANCIAL,
+    }
+)
+
+# ---------------------------------------------------------------------------
+# Proposal dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class MemoryProposal:
+    """An immutable record of a proposed memory edit.
+
+    Attributes
+    ----------
+    proposal_id:
+        Deterministic ``uuid5`` derived from ``action``, ``target_path``, and
+        the *redacted* content.  Identical inputs always produce the same ID.
+    action:
+        ``"create"`` | ``"update"`` | ``"delete"``.
+    target_path:
+        Vault-relative path of the note being created/modified/deleted.
+    content:
+        Proposed note content **after** redaction via
+        :func:`mneme_core.privacy.redact`.
+    category:
+        Semantic category governing approval requirements.
+    status:
+        Current lifecycle status (PENDING / APPROVED / REJECTED).
+    trust:
+        Proposer identity string; defaults to ``"agent"``.
+    """
+
+    proposal_id: str
+    action: str
+    target_path: str
+    content: str
+    category: EditCategory
+    status: ProposalStatus
+    trust: str
+
+
+# ---------------------------------------------------------------------------
+# Pure functions
+# ---------------------------------------------------------------------------
+
+
+def requires_human_approval(category: EditCategory) -> bool:
+    """Return ``True`` iff *category* is in :data:`DURABLE_CATEGORIES`."""
+    return category in DURABLE_CATEGORIES
+
+
+def propose(
+    *,
+    action: str,
+    target_path: str,
+    content: str,
+    category: EditCategory,
+    trust: str = "agent",
+) -> MemoryProposal:
+    """Create a new :class:`MemoryProposal` in PENDING status.
+
+    Content is redacted via :func:`~mneme_core.privacy.redact` before being
+    stored.  The ``proposal_id`` is a deterministic ``uuid5`` derived from
+    ``action + NUL + target_path + NUL + redacted_content`` so that identical
+    inputs always yield the same proposal ID.
+    """
+    redacted = redact(content)
+    # category and trust are part of proposal identity: an EPHEMERAL and a
+    # CLINICAL proposal for the same path+content must NOT share a proposal_id,
+    # else a downstream store keyed on it could alias the durable edit to an
+    # already-applied ephemeral one and bypass the human-approval gate.
+    seed = f"{action}\x00{target_path}\x00{category.value}\x00{trust}\x00{redacted}"
+    proposal_id = str(uuid.uuid5(_NAMESPACE, seed))
+    return MemoryProposal(
+        proposal_id=proposal_id,
+        action=action,
+        target_path=target_path,
+        content=redacted,
+        category=category,
+        status=ProposalStatus.PENDING,
+        trust=trust,
+    )
+
+
+def approve(proposal: MemoryProposal) -> MemoryProposal:
+    """Return a copy of *proposal* with ``status`` set to APPROVED.
+
+    Idempotent: approving an already-approved proposal returns an equivalent
+    object unchanged.
+    """
+    return dataclasses.replace(proposal, status=ProposalStatus.APPROVED)
+
+
+def reject(proposal: MemoryProposal) -> MemoryProposal:
+    """Return a copy of *proposal* with ``status`` set to REJECTED."""
+    return dataclasses.replace(proposal, status=ProposalStatus.REJECTED)
+
+
+def can_apply(proposal: MemoryProposal) -> bool:
+    """Return ``True`` iff the proposal may be applied to the vault.
+
+    Rules (deterministic, pure):
+
+    * A REJECTED proposal can **never** be applied.
+    * An APPROVED proposal can always be applied.
+    * A PENDING proposal may be applied only when its category is EPHEMERAL
+      (i.e. ``requires_human_approval`` is ``False``).
+    """
+    if proposal.status == ProposalStatus.REJECTED:
+        return False
+    if proposal.status == ProposalStatus.APPROVED:
+        return True
+    # PENDING: allowed only for non-durable (ephemeral) categories.
+    return not requires_human_approval(proposal.category)

mneme_core/audit.py

@@ -0,0 +1,82 @@
+"""Read-only vault audit aggregator (the console surface, v1).
+
+Produces a deterministic, read-only snapshot of the vault: note counts by
+memory type plus a security-scan summary. This is the programmatic/text console
+surface; a browser audit UI (timeline, graph explorer, token-ROI dashboard) is
+deferred. The aggregator never writes and never raises on a single bad file.
+
+No LLM, no network.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .security import scan_vault, summarize
+from .vault.frontmatter import parse
+
+
+@dataclass(frozen=True)
+class AuditReport:
+    """A read-only vault health + safety snapshot."""
+
+    note_count: int
+    type_counts: dict[str, int]
+    security: dict[str, Any]
+
+
+def build_audit(vault_root: Path) -> AuditReport:
+    """Walk the vault markdown and build a read-only audit snapshot.
+
+    Counts notes by frontmatter ``type`` (notes without parseable frontmatter
+    are bucketed as ``"(none)"``) and folds in a security-scan summary. Symlinks
+    that escape the vault are skipped; unreadable or malformed files never crash
+    the audit.
+    """
+    root_resolved = vault_root.resolve()
+    type_counts: dict[str, int] = {}
+    note_count = 0
+    for md_path in sorted(vault_root.rglob("*.md")):
+        try:
+            resolved = md_path.resolve()
+        except OSError:
+            continue
+        if not resolved.is_relative_to(root_resolved):
+            continue
+        try:
+            text = md_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        note_count += 1
+        type_name = "(none)"
+        try:
+            front, _ = parse(text)
+            if front is not None and front.type:
+                type_name = front.type
+        except Exception:  # noqa: BLE001 - audit must never crash on a bad note
+            type_name = "(unparseable)"
+        type_counts[type_name] = type_counts.get(type_name, 0) + 1
+
+    security = summarize(scan_vault(vault_root))
+    return AuditReport(note_count=note_count, type_counts=type_counts, security=security)
+
+
+def render_audit(report: AuditReport) -> str:
+    """Render an :class:`AuditReport` as a plain-text report."""
+    lines = ["# Vault audit", "", f"Notes: {report.note_count}", "", "## By type"]
+    if report.type_counts:
+        for type_name, count in sorted(report.type_counts.items()):
+            lines.append(f"- {type_name}: {count}")
+    else:
+        lines.append("- (no notes)")
+    lines.extend(["", "## Security"])
+    sec = report.security
+    lines.append(f"- files flagged: {sec.get('files_flagged', 0)}")
+    lines.append(f"- total findings: {sec.get('total_findings', 0)}")
+    by_kind = sec.get("by_kind", {})
+    if isinstance(by_kind, dict):
+        for kind, count in sorted(by_kind.items()):
+            lines.append(f"  - {kind}: {count}")
+    return "\n".join(lines) + "\n"

mneme_core/bench/__init__.py

@@ -0,0 +1,40 @@
+"""Benchmark helpers shared by the ``benchmarks/`` runner scripts.
+
+Three focused submodules:
+
+* :mod:`mneme_core.bench.metrics` - information-retrieval metric primitives
+  (nDCG@k, Recall@k, MRR) plus quantile helpers for latency distributions.
+* :mod:`mneme_core.bench.synth` - deterministic synthetic corpus and query
+  generator. Tests and benchmarks both lean on this so they exercise the
+  same shape of data.
+* :mod:`mneme_core.bench.hardware` - hardware/runtime probe that emits
+  ``hardware.json`` next to every benchmark result for reproducibility.
+
+The submodules are intentionally small and side-effect-free. Bench scripts
+own their own argparse, output, and CI guards.
+"""
+
+from .hardware import HardwareSnapshot, capture_hardware
+from .metrics import (
+    mean_reciprocal_rank,
+    ndcg_at_k,
+    percentiles,
+    recall_at_k,
+)
+from .synth import (
+    SyntheticCorpus,
+    SyntheticQuery,
+    build_synthetic_corpus,
+)
+
+__all__ = [
+    "HardwareSnapshot",
+    "SyntheticCorpus",
+    "SyntheticQuery",
+    "build_synthetic_corpus",
+    "capture_hardware",
+    "mean_reciprocal_rank",
+    "ndcg_at_k",
+    "percentiles",
+    "recall_at_k",
+]

mneme_core/bench/hardware.py

@@ -0,0 +1,110 @@
+"""Hardware and runtime snapshot for reproducible benchmark output.
+
+Every benchmark run drops a ``hardware.json`` next to its result so
+readers can interpret the numbers in context. The probe is deliberately
+shallow - just the fields a reader needs to decide whether two runs are
+comparable.
+
+Why not ``platform.uname()`` for everything: the fields below are the
+ones that materially affect numbers in the v1.0 benchmark set. CPU
+model and core count drive latency; OS family changes file-IO
+behavior; Python and (when available) Node versions pin the runtime.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass
+class HardwareSnapshot:
+    """Captured at the start of every benchmark run."""
+
+    os: str
+    os_release: str
+    cpu_model: str
+    cpu_count_logical: int
+    python_version: str
+    node_version: str | None
+    mneme_bench_seed: int
+
+
+def _detect_cpu_model() -> str:
+    """Best-effort CPU model string across OSes.
+
+    Linux: ``/proc/cpuinfo`` first non-empty ``model name``.
+    macOS: ``sysctl -n machdep.cpu.brand_string`` when ``sysctl`` is on
+    PATH. Windows and fallback: ``platform.processor()``.
+    """
+    system = platform.system().lower()
+    if system == "linux":
+        try:
+            cpuinfo = Path("/proc/cpuinfo").read_text(encoding="utf-8")
+            for line in cpuinfo.splitlines():
+                if line.startswith("model name"):
+                    return line.split(":", 1)[1].strip()
+        except OSError:
+            pass
+    if system == "darwin" and shutil.which("sysctl") is not None:
+        try:
+            out = subprocess.run(  # noqa: S603,S607
+                ["sysctl", "-n", "machdep.cpu.brand_string"],
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=2,
+            )
+            if out.returncode == 0:
+                return out.stdout.strip()
+        except (OSError, subprocess.SubprocessError):
+            pass
+    return platform.processor() or "unknown"
+
+
+def _detect_node_version() -> str | None:
+    """Return the ``node --version`` output, or ``None`` when absent."""
+    if shutil.which("node") is None:
+        return None
+    try:
+        out = subprocess.run(  # noqa: S603,S607
+            ["node", "--version"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=2,
+        )
+        if out.returncode == 0:
+            return out.stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return None
+
+
+def capture_hardware(seed: int = 42) -> HardwareSnapshot:
+    """Capture the snapshot. Always returns; never raises."""
+    cpu_count = os.cpu_count() or 0
+    return HardwareSnapshot(
+        os=platform.system() or "unknown",
+        os_release=platform.release() or "unknown",
+        cpu_model=_detect_cpu_model(),
+        cpu_count_logical=cpu_count,
+        python_version=sys.version.split()[0],
+        node_version=_detect_node_version(),
+        mneme_bench_seed=seed,
+    )
+
+
+def write_hardware_json(snapshot: HardwareSnapshot, out_path: Path) -> None:
+    """Serialize the snapshot to ``out_path`` as pretty JSON."""
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(
+        json.dumps(asdict(snapshot), indent=2) + "\n",
+        encoding="utf-8",
+    )

mneme_core/bench/harness.py

@@ -0,0 +1,258 @@
+"""Evaluation runner, dataset adapters, and head-to-head comparator.
+
+This module ships the runner infrastructure and format adapters only.
+The datasets (LongMemEval, LoCoMo) and any competitor retrieve functions
+(e.g. a claude-mem retrieve fn) are SUPPLIED BY THE OPERATOR at run time.
+This module makes no superiority claim about any retrieval system.
+
+Any public statement that one system "beats" or is "best" relative to
+another requires an operator-run, published benchmark with full
+experimental controls. The :func:`compare` function provides a purely
+descriptive readout of the numbers produced in a single run.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+from mneme_core.bench.metrics import (
+    mean_reciprocal_rank,
+    ndcg_at_k,
+    recall_at_k,
+)
+
+RetrieveIds = Callable[[str], list[str | int]]
+"""Query string -> ranked list of doc ids (best first)."""
+
+
+@dataclass(frozen=True)
+class EvalCase:
+    """One evaluation case: a query and the doc ids that should be retrieved."""
+
+    case_id: str
+    query: str
+    relevant_ids: tuple[str | int, ...]
+
+
+@dataclass(frozen=True)
+class CaseResult:
+    """Per-case metric scores for a single (query, retrieve) evaluation."""
+
+    case_id: str
+    recall_at_k: float
+    reciprocal_rank: float
+    ndcg_at_k: float
+
+
+@dataclass(frozen=True)
+class EvalReport:
+    """Aggregate evaluation report for one system over a case set."""
+
+    system_name: str
+    k: int
+    n_cases: int
+    mean_recall_at_k: float
+    mean_mrr: float
+    mean_ndcg_at_k: float
+    per_case: tuple[CaseResult, ...]
+
+
+def run_eval(
+    cases: Iterable[EvalCase],
+    retrieve: RetrieveIds,
+    *,
+    system_name: str,
+    k: int = 10,
+) -> EvalReport:
+    """Run deterministic evaluation of *retrieve* over *cases*.
+
+    For each case the retrieve function is called once. Metrics are
+    computed by reusing :func:`~mneme_core.bench.metrics.recall_at_k`,
+    :func:`~mneme_core.bench.metrics.mean_reciprocal_rank`, and
+    :func:`~mneme_core.bench.metrics.ndcg_at_k`. An empty retrieve result
+    scores zero on all metrics without raising. An empty case list returns
+    an all-zero report without raising. The order of ``per_case`` matches
+    the input iteration order.
+    """
+    case_results: list[CaseResult] = []
+
+    for case in cases:
+        retrieved: list[str | int] = retrieve(case.query)
+        rel: tuple[str | int, ...] = case.relevant_ids
+
+        r_at_k = recall_at_k(retrieved, rel, k)
+        rr = mean_reciprocal_rank([(retrieved, rel)])
+        n_at_k = ndcg_at_k(retrieved, rel, k)
+
+        case_results.append(
+            CaseResult(
+                case_id=case.case_id,
+                recall_at_k=r_at_k,
+                reciprocal_rank=rr,
+                ndcg_at_k=n_at_k,
+            )
+        )
+
+    n = len(case_results)
+    if n == 0:
+        return EvalReport(
+            system_name=system_name,
+            k=k,
+            n_cases=0,
+            mean_recall_at_k=0.0,
+            mean_mrr=0.0,
+            mean_ndcg_at_k=0.0,
+            per_case=(),
+        )
+
+    mean_r = sum(c.recall_at_k for c in case_results) / n
+    mean_mrr = sum(c.reciprocal_rank for c in case_results) / n
+    mean_n = sum(c.ndcg_at_k for c in case_results) / n
+
+    return EvalReport(
+        system_name=system_name,
+        k=k,
+        n_cases=n,
+        mean_recall_at_k=mean_r,
+        mean_mrr=mean_mrr,
+        mean_ndcg_at_k=mean_n,
+        per_case=tuple(case_results),
+    )
+
+
+def load_longmemeval(records: Iterable[dict[str, object]]) -> list[EvalCase]:
+    """Map LongMemEval-style records to :class:`EvalCase`.
+
+    Accepted key variants:
+
+    * ``case_id``: ``"question_id"`` | ``"id"`` | ``"case_id"``
+      (fallback ``"case-<i>"`` when none present).
+    * ``query``: ``"question"`` | ``"query"`` | ``"input"``.
+    * ``relevant_ids``: ``"answer_session_ids"`` | ``"relevant_ids"``
+      | ``"evidence_ids"`` | ``"gold_ids"`` (empty list when absent).
+
+    Records with no resolvable query are silently skipped. Never raises.
+    """
+    result: list[EvalCase] = []
+    for i, rec in enumerate(records):
+        query = _first_str(rec, ("question", "query", "input"))
+        if query is None:
+            continue
+        case_id = _first_str(rec, ("question_id", "id", "case_id")) or f"case-{i}"
+        rel_raw = _first_list(
+            rec, ("answer_session_ids", "relevant_ids", "evidence_ids", "gold_ids")
+        )
+        relevant_ids: tuple[str | int, ...] = tuple(v for v in rel_raw if isinstance(v, (str, int)))
+        result.append(EvalCase(case_id=case_id, query=query, relevant_ids=relevant_ids))
+    return result
+
+
+def load_locomo(records: Iterable[dict[str, object]]) -> list[EvalCase]:
+    """Map LoCoMo-style records to :class:`EvalCase`.
+
+    Accepted key variants:
+
+    * ``case_id``: ``"sample_id"`` | ``"id"``.
+    * ``query``: ``"question"`` | ``"query"``.
+    * ``relevant_ids``: ``"evidence"`` | ``"relevant_ids"`` | ``"gold_ids"``
+      (empty list when absent).
+
+    Records with no resolvable query are silently skipped. Never raises.
+    """
+    result: list[EvalCase] = []
+    for i, rec in enumerate(records):
+        query = _first_str(rec, ("question", "query"))
+        if query is None:
+            continue
+        case_id = _first_str(rec, ("sample_id", "id")) or f"case-{i}"
+        rel_raw = _first_list(rec, ("evidence", "relevant_ids", "gold_ids"))
+        relevant_ids: tuple[str | int, ...] = tuple(v for v in rel_raw if isinstance(v, (str, int)))
+        result.append(EvalCase(case_id=case_id, query=query, relevant_ids=relevant_ids))
+    return result
+
+
+def head_to_head(
+    cases: Iterable[EvalCase],
+    systems: dict[str, RetrieveIds],
+    *,
+    k: int = 10,
+) -> dict[str, EvalReport]:
+    """Run :func:`run_eval` for each system over the same materialised case set.
+
+    Cases are materialised once so every system is evaluated on an
+    identical sequence. Returns ``{system_name: EvalReport}``. Deterministic.
+    """
+    materialised: list[EvalCase] = list(cases)
+    return {
+        name: run_eval(materialised, retrieve_fn, system_name=name, k=k)
+        for name, retrieve_fn in systems.items()
+    }
+
+
+def compare(reports: dict[str, EvalReport]) -> dict[str, object]:
+    """Tabulate mean metrics across systems and identify the leader per metric.
+
+    Returns a dict with three keys:
+
+    * ``"systems"``: sorted list of system names.
+    * ``"metrics"``: ``{"recall_at_k": {name: val}, "mrr": {...},
+      "ndcg_at_k": {...}}``.
+    * ``"leader_by_metric"``: ``{"recall_at_k": <name>, ...}`` — the
+      system with the highest value for each metric.
+
+    IMPORTANT: ``leader_by_metric`` is a PURELY DESCRIPTIVE readout of
+    this run's measured numbers. It is NOT a published superiority claim.
+    Any public "best / beats X" assertion requires an operator-run,
+    published benchmark with full experimental controls; this harness only
+    measures. Ties are broken by choosing the lexicographically smallest
+    name among the joint-maximum scorers, ensuring a deterministic result.
+    """
+    names = sorted(reports)
+    recall_vals = {n: reports[n].mean_recall_at_k for n in names}
+    mrr_vals = {n: reports[n].mean_mrr for n in names}
+    ndcg_vals = {n: reports[n].mean_ndcg_at_k for n in names}
+
+    def _leader(vals: dict[str, float]) -> str:
+        if not vals:
+            return ""
+        max_val = max(vals.values())
+        candidates = sorted(n for n, v in vals.items() if v == max_val)
+        return candidates[0]
+
+    return {
+        "systems": names,
+        "metrics": {
+            "recall_at_k": recall_vals,
+            "mrr": mrr_vals,
+            "ndcg_at_k": ndcg_vals,
+        },
+        "leader_by_metric": {
+            "recall_at_k": _leader(recall_vals),
+            "mrr": _leader(mrr_vals),
+            "ndcg_at_k": _leader(ndcg_vals),
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _first_str(rec: dict[str, object], keys: tuple[str, ...]) -> str | None:
+    """Return the first non-empty string value found under any of *keys*."""
+    for key in keys:
+        val = rec.get(key)
+        if isinstance(val, str) and val:
+            return val
+    return None
+
+
+def _first_list(rec: dict[str, object], keys: tuple[str, ...]) -> list[object]:
+    """Return the first list value found under any of *keys*, else ``[]``."""
+    for key in keys:
+        val = rec.get(key)
+        if isinstance(val, list):
+            return val
+    return []