Skip to main content

​
Architecture Overview

Memproof is an embeddable library (Python & TypeScript) — not a standalone service. It runs in-process alongside your AI agent, intercepting every memory operation and routing it through a deterministic control path before it reaches the underlying memory backend.
Memproof does not replace your memory store. It wraps it with risk assessment, policy enforcement, and audit logging.

​
Design Principles

  1. Adapter-first — storage and retrieval stay in your existing memory provider.
  2. Control-plane-first — every mutation passes through policy and risk checks before reaching the backend.
  3. Deterministic decisions — the same input combined with the same policy version always produces the same decision.
  4. Forensic-grade lineage — each pipeline stage emits an immutable event to the Trailproof audit trail.
  5. Progressive enforcement — deploy in monitor, enforce, or strict modes as your confidence grows.

​
Component Diagram

Memproof control path: Operation Received → Risk Assessment (5-factor scoring) → Policy Engine (YAML rules) → Decision Branching (ALLOW/DENY/QUARANTINE/APPROVAL) → Provider Attempted → Committed/Blocked → Trailproof Audit Trail

​
Components

Operation Orchestrator

Central pipeline that normalizes requests, sequences the risk/policy/approval stages, and delegates to the adapter. See Control Path.

Risk Engine

Scores each operation across 5 weighted factors: operation type, PII detection, secrets detection, source trust, and scope anomalies. See Risk Engine.

Policy Engine

Evaluates YAML-defined rules in priority order. First matching rule wins. Produces one of four actions: allow, deny, require_approval, or quarantine. See Policy Engine.

Audit Trail

Tamper-evident audit trail powered by Trailproof. Records an event for every pipeline stage with SHA-256 hash chains and optional HMAC signing. See Audit Trail.

Approval Broker

Bridges require_approval decisions to an external approval system (Attesta) or an internal manual queue.

Quarantine Store

Retains the full payload of quarantined operations so they can be reviewed and released or discarded.

​
The Adapter Pattern

Memproof connects to any memory backend through the MemoryAdapter interface. Built-in adapters exist for LangGraph checkpoints, OpenAI Sessions, and MCP memory servers. You can also write a custom adapter for any backend. 
from memproof.adapters.base import MemoryAdapter

class MemoryAdapter(ABC):
    provider_name: str  # e.g., "langgraph", "openai_sessions"

    async def create_memory(self, memory: MemoryRecord) -> MemoryRecord: ...
    async def update_memory(self, memory_id: str, patch: dict) -> MemoryRecord: ...
    async def delete_memory(self, memory_id: str) -> bool: ...
    async def get_memory(self, memory_id: str) -> MemoryRecord | None: ...
    async def search_memories(self, query: str, scope: dict, limit: int, filters: dict | None) -> list[MemorySearchHit]: ...
Each adapter maps provider-specific errors to canonical error codes: NOT_FOUND, CONFLICT, VALIDATION_ERROR, PROVIDER_UNAVAILABLE, and PERMISSION_DENIED.

​
Instantiation

The Memproof class wires all components together. A single constructor call is all you need: 
from memproof import Memproof

mp = Memproof(
    policy="./memproof.yaml",       # path to your policy YAML
    adapter="langgraph",            # or "openai_sessions", "mcp", "in_memory"
    trail_store="jsonl",            # or "memory" (default)
    trail_store_path="./audit.jsonl",
    trail_signing_key="your-secret-key",
)
For production, use trail_store="jsonl" with a trail_signing_key to get durable, tamper-evident audit logs.

​
Data Flow Summary

Every memory operation — remember, update, forget, search — follows the same six-stage control path:
  1. received — request accepted and normalized
  2. risk_assessed — risk score and factors computed
  3. policy_decided — action determined from YAML rules
  4. approval_requested — conditional, only for require_approval
  5. provider_attempted — adapter calls the memory backend
  6. committed or blocked — terminal state with full event trail
Each stage emits an immutable event to the Audit Trail, producing a complete forensic record for every operation.