> ## Documentation Index
> Fetch the complete documentation index at: https://memproof.kyberon.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Architecture
> High-level architecture of Memproof as an embeddable memory control layer
# 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](https://trailproof.kyberon.dev/docs/introduction) audit trail.
5. **Progressive enforcement** -- deploy in `monitor`, `enforce`, or `strict` modes as your confidence grows.
## Component Diagram
## Components
Central pipeline that normalizes requests, sequences the risk/policy/approval stages, and delegates to the adapter. See [Control Path](/concepts/control-path).
Scores each operation across 5 weighted factors: operation type, PII detection, secrets detection, source trust, and scope anomalies. See [Risk Engine](/concepts/risk-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](/concepts/policy-engine).
Tamper-evident audit trail powered by [Trailproof](https://trailproof.kyberon.dev/docs/introduction). Records an event for every pipeline stage with SHA-256 hash chains and optional HMAC signing. See [Audit Trail](/concepts/event-ledger).
Bridges `require_approval` decisions to an external approval system (Attesta) or an internal manual queue.
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.
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](/concepts/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](/concepts/event-ledger), producing a complete forensic record for every operation.