engram-memory-vault 1.8.1__py3-none-any.whl

engram/__init__.py

@@ -0,0 +1,7 @@
+"""engRAM - high-security, fully offline, encrypted vector memory for AI agents."""
+
+__version__ = "1.8.1"
+
+from . import offline_guard as _og
+
+_og.activate_from_env()

engram/acl.py

@@ -0,0 +1,91 @@
+"""Per-caller namespace access control + vault-adjacent settings.
+
+Config lives NEXT to the vault as `<vault>.config.json` (it contains no
+secrets - only ACLs and preferences). `packs/*` namespaces are ALWAYS
+read-only for every caller, including "*". Violations are hard errors.
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+
+from .crypto import CryptoError
+
+DEFAULT_CONFIG = {
+    "callers": {
+        "*": {"default_namespace": "main", "grants": {"*": "rw"}},
+    },
+    "settings": {
+        "auto_lock_minutes": 30,
+        "include_packs_in_search": True,
+        "unlock_tool_enabled": False,
+        "duplicate_threshold": 0.97,
+        "index_precision": "f32",
+    },
+}
+
+
+class AclError(CryptoError):
+    pass
+
+
+@dataclass
+class VaultConfig:
+    callers: dict = field(default_factory=lambda: DEFAULT_CONFIG["callers"].copy())
+    settings: dict = field(default_factory=lambda: DEFAULT_CONFIG["settings"].copy())
+
+    @staticmethod
+    def path_for(vault_path: str) -> str:
+        return vault_path + ".config.json"
+
+    @classmethod
+    def load(cls, vault_path: str) -> "VaultConfig":
+        p = cls.path_for(vault_path)
+        if not os.path.exists(p):
+            return cls()
+        data = json.loads(open(p).read())
+        cfg = cls()
+        cfg.callers = data.get("callers", cfg.callers)
+        cfg.settings = {**cfg.settings, **data.get("settings", {})}
+        return cfg
+
+    def save(self, vault_path: str) -> None:
+        with open(self.path_for(vault_path), "w") as f:
+            json.dump({"callers": self.callers, "settings": self.settings}, f, indent=2)
+
+    # -- ACL ---------------------------------------------------------------
+
+    def _caller_entry(self, caller: str) -> dict:
+        entry = self.callers.get(caller) or self.callers.get("*")
+        if entry is None:
+            raise AclError(f"Caller {caller!r} has no access to this vault")
+        return entry
+
+    def default_namespace(self, caller: str) -> str:
+        return self._caller_entry(caller).get("default_namespace", "main")
+
+    def grant_for(self, caller: str, namespace: str) -> str:
+        """Returns 'rw', 'ro', or raises AclError. packs/* is always ro."""
+        entry = self._caller_entry(caller)
+        grants = entry.get("grants", {})
+        grant = grants.get(namespace)
+        if grant is None:
+            for pattern, g in grants.items():
+                if pattern.endswith("*") and namespace.startswith(pattern[:-1]):
+                    grant = g
+                    break
+        if grant is None:
+            grant = grants.get("*")
+        if grant is None:
+            raise AclError(
+                f"Caller {caller!r} is not granted access to namespace {namespace!r}")
+        if namespace.startswith("packs/"):
+            return "ro"  # pack namespaces are immutable for everyone
+        return grant
+
+    def check(self, caller: str, namespace: str, write: bool) -> None:
+        grant = self.grant_for(caller, namespace)
+        if write and grant != "rw":
+            raise AclError(
+                f"Caller {caller!r} has read-only access to namespace {namespace!r}")

engram/audit.py

@@ -0,0 +1,54 @@
+"""Hash-chained, tamper-evident audit log (stored inside the sealed payload).
+
+Each entry's hash covers the previous entry's hash, so any edit, deletion,
+or reordering of history breaks the chain at a detectable point.
+A failure to write the audit entry fails the operation (fail-fast), never
+the other way around.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+
+GENESIS = "GENESIS"
+
+
+def _entry_hash(prev_hash: str, ts: float, caller: str, op: str, detail: str) -> str:
+    body = json.dumps(
+        {"prev": prev_hash, "ts": ts, "caller": caller, "op": op, "detail": detail},
+        sort_keys=True, separators=(",", ":"),
+    ).encode()
+    return hashlib.sha256(body).hexdigest()
+
+
+def append(conn, caller: str, op: str, detail: str) -> str:
+    row = conn.execute("SELECT hash FROM audit ORDER BY seq DESC LIMIT 1").fetchone()
+    prev = row["hash"] if row else GENESIS
+    ts = time.time()
+    h = _entry_hash(prev, ts, caller, op, detail)
+    conn.execute(
+        "INSERT INTO audit (ts, caller, op, detail, prev_hash, hash) VALUES (?,?,?,?,?,?)",
+        (ts, caller, op, detail, prev, h),
+    )
+    return h
+
+
+def head(conn) -> str:
+    row = conn.execute("SELECT hash FROM audit ORDER BY seq DESC LIMIT 1").fetchone()
+    return row["hash"] if row else GENESIS
+
+
+def verify(conn) -> tuple[bool, int, str]:
+    """Walk the chain. Returns (ok, entries_checked, message)."""
+    prev = GENESIS
+    n = 0
+    for row in conn.execute("SELECT * FROM audit ORDER BY seq"):
+        if row["prev_hash"] != prev:
+            return False, n, f"chain break at seq {row['seq']}: prev_hash mismatch"
+        want = _entry_hash(prev, row["ts"], row["caller"], row["op"], row["detail"])
+        if row["hash"] != want:
+            return False, n, f"chain break at seq {row['seq']}: entry hash mismatch"
+        prev = row["hash"]
+        n += 1
+    return True, n, f"audit chain intact ({n} entries)"

engram/bench.py

@@ -0,0 +1,88 @@
+"""Performance + RAM benchmark against the seed pack and a synthetic corpus.
+
+Reports embed/store/search latencies (p50/p95) and peak RSS, and checks the
+8GB-baseline budgets: search p95 < 100ms at the synthetic scale, total RSS
+< 1GB at 100k records with default settings.
+"""
+from __future__ import annotations
+
+import random
+import resource
+import sys
+import time
+
+import numpy as np
+
+from .vindex import build_index
+
+WORDS = ("report vault memory agent record office data schedule market key "
+         "index search secure backup ledger review batch upload form note").split()
+
+
+def _rss_mb() -> float:
+    rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+    return rss / (1024 * 1024) if sys.platform == "darwin" else rss / 1024
+
+
+def _pct(xs: list[float], p: float) -> float:
+    xs = sorted(xs)
+    return xs[min(len(xs) - 1, int(len(xs) * p))]
+
+
+def run(vault, synthetic_n: int = 20_000, queries: int = 50) -> dict:
+    rng = random.Random(42)
+    out: dict = {"synthetic_records": synthetic_n}
+
+    # 1) real embed+store latency on a small sample
+    t_store = []
+    for i in range(20):
+        text = f"benchmark memory {i}: " + " ".join(rng.choices(WORDS, k=10))
+        t0 = time.perf_counter()
+        vault.store(text, caller="bench", namespace="bench", tags=["bench"])
+        t_store.append((time.perf_counter() - t0) * 1000)
+    out["store_ms_p50"] = round(_pct(t_store, 0.50), 1)
+    out["store_ms_p95"] = round(_pct(t_store, 0.95), 1)
+
+    # 2) synthetic vector corpus at scale (index-only: isolates search speed)
+    dim = int(vault.header.model["dim"])
+    mat = np.random.default_rng(42).standard_normal((synthetic_n, dim)).astype(np.float32)
+    mat /= np.linalg.norm(mat, axis=1, keepdims=True)
+    t0 = time.perf_counter()
+    idx = build_index(dim, list(range(1, synthetic_n + 1)), mat,
+                      precision=vault.config.settings.get("index_precision", "f32"),
+                      force=None)
+    out["index_build_s"] = round(time.perf_counter() - t0, 2)
+    out["index_kind"] = idx.kind
+
+    t_search = []
+    for _ in range(queries):
+        q = mat[rng.randrange(synthetic_n)]
+        t0 = time.perf_counter()
+        idx.search(q, 10)
+        t_search.append((time.perf_counter() - t0) * 1000)
+    out["vector_search_ms_p50"] = round(_pct(t_search, 0.50), 2)
+    out["vector_search_ms_p95"] = round(_pct(t_search, 0.95), 2)
+
+    # 3) full hybrid search on the live vault (embed + vector + FTS + fuse)
+    t_hybrid = []
+    for _ in range(20):
+        t0 = time.perf_counter()
+        vault.search("benchmark memory " + rng.choice(WORDS), caller="bench", top_k=8)
+        t_hybrid.append((time.perf_counter() - t0) * 1000)
+    out["hybrid_search_ms_p50"] = round(_pct(t_hybrid, 0.50), 1)
+    out["hybrid_search_ms_p95"] = round(_pct(t_hybrid, 0.95), 1)
+
+    out["peak_rss_mb"] = round(_rss_mb(), 0)
+    out["budgets"] = {
+        "vector_search_p95_under_100ms": out["vector_search_ms_p95"] < 100,
+        "rss_under_1gb": out["peak_rss_mb"] < 1024,
+    }
+    # clean up bench records
+    rows = vault.db.conn.execute(
+        "SELECT id, ikey FROM records WHERE ns = 'bench'").fetchall()
+    for r in rows:
+        vault.db.delete(r["id"], shred=False)
+        vault.index.remove(r["ikey"])
+        vault._id_by_ikey.pop(r["ikey"], None)
+    vault.save()
+    return out