> ## 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.

# Models

> Pydantic models, enumerations, and data types used throughout the Memproof API.

# Models

All models are defined in `memproof.models.core` and re-exported from the top-level `memproof` package. Every model is a Pydantic `BaseModel` (or `str, Enum` for enumerations).

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from memproof import (
    MemoryScope, OperationContext, MemoryRecord,
    RiskFactor, RiskAssessment, PolicyDecision,
    MemoryOperationResponse, OperationStatusResponse,
    MemorySearchResponse,
    OperationType, OperationStatus, RiskLevel,
    DecisionAction, ActorType,
)
```

***

## Enumerations

### OperationType

Identifies the kind of memory operation.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class OperationType(str, Enum):
    remember = "remember"
    update   = "update"
    forget   = "forget"
    search   = "search"
    get      = "get"
```

### OperationStatus

Tracks the lifecycle state of an operation as it moves through the pipeline.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class OperationStatus(str, Enum):
    received         = "received"
    pending_approval = "pending_approval"
    committed        = "committed"
    blocked          = "blocked"
    quarantined      = "quarantined"
    failed           = "failed"
```

| Value              | Meaning                                                                                            |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| `received`         | The request has been accepted but processing has not completed.                                    |
| `pending_approval` | The policy engine returned `require_approval`. A human reviewer must call `approve()` or `deny()`. |
| `committed`        | The operation completed successfully and the memory has been persisted (or deleted).               |
| `blocked`          | The policy engine denied the operation.                                                            |
| `quarantined`      | The operation was quarantined for later review.                                                    |
| `failed`           | An unexpected error occurred during processing.                                                    |

### RiskLevel

Categorical risk level derived from the numeric risk score.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class RiskLevel(str, Enum):
    low      = "low"
    medium   = "medium"
    high     = "high"
    critical = "critical"
```

### DecisionAction

The action taken by the policy engine after evaluating rules against the risk assessment.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class DecisionAction(str, Enum):
    allow            = "allow"
    deny             = "deny"
    require_approval = "require_approval"
    quarantine       = "quarantine"
```

### ActorType

Identifies the type of actor performing an operation.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class ActorType(str, Enum):
    agent  = "agent"
    user   = "user"
    system = "system"
```

***

## Value Objects

### MemoryScope

Identifies the multi-tenant hierarchy a memory belongs to. Every memory is scoped to at least a tenant, project, and agent.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class MemoryScope(BaseModel):
    tenant_id: str
    project_id: str
    agent_id: str
    session_id: str | None = None
    subject_id: str | None = None
```

<ParamField path="tenant_id" type="str" required>
  Top-level tenant identifier.
</ParamField>

<ParamField path="project_id" type="str" required>
  Project within the tenant.
</ParamField>

<ParamField path="agent_id" type="str" required>
  Agent that owns or created the memory.
</ParamField>

<ParamField path="session_id" type="str | None" default="None">
  Optional session identifier. Use this to scope memories to a specific conversation session.
</ParamField>

<ParamField path="subject_id" type="str | None" default="None">
  Optional subject identifier. Use this to scope memories to a specific end-user or entity the memory is about.
</ParamField>

#### Example

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from memproof import MemoryScope

scope = MemoryScope(
    tenant_id="acme",
    project_id="assistant",
    agent_id="agent-1",
    session_id="sess-001",
    subject_id="user-42",
)
```

***

### OperationContext

Captures the identity and metadata of the actor performing an operation.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class OperationContext(BaseModel):
    actor_type: ActorType
    actor_id: str
    source: str
    request_id: str | None = None
    correlation_id: str | None = None
    timestamp: datetime
    metadata: dict[str, Any] | None = None
```

<ParamField path="actor_type" type="ActorType" required>
  The type of actor: `"agent"`, `"user"`, or `"system"`.
</ParamField>

<ParamField path="actor_id" type="str" required>
  Unique identifier of the actor performing the operation.
</ParamField>

<ParamField path="source" type="str" required>
  The originating system or framework (e.g., `"langgraph"`, `"web-ui"`, `"api"`).
</ParamField>

<ParamField path="request_id" type="str | None" default="None">
  Optional request-level identifier for tracing.
</ParamField>

<ParamField path="correlation_id" type="str | None" default="None">
  Optional correlation identifier for linking related operations across services.
</ParamField>

<ParamField path="timestamp" type="datetime" required>
  ISO 8601 timestamp of when the operation was initiated. Accepts both `datetime` objects and ISO 8601 strings (Pydantic coerces strings automatically).
</ParamField>

<ParamField path="metadata" type="dict[str, Any] | None" default="None">
  Arbitrary key-value metadata associated with the operation context.
</ParamField>

#### Example

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from memproof import OperationContext

context = OperationContext(
    actor_type="agent",
    actor_id="agent-1",
    source="langgraph",
    timestamp="2026-01-15T10:30:00Z",
    request_id="req-abc",
    correlation_id="corr-xyz",
)
```

***

## Record Models

### MemoryRecord

The persisted memory object as returned by the adapter.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class MemoryRecord(BaseModel):
    memory_id: str
    content: str
    tags: list[str] = Field(default_factory=list)
    scope: MemoryScope
    metadata: dict[str, Any] | None = None
    ttl_seconds: int | None = None
    created_at: datetime
    updated_at: datetime
```

<ParamField path="memory_id" type="str">
  Unique identifier for the memory record.
</ParamField>

<ParamField path="content" type="str">
  The stored memory content.
</ParamField>

<ParamField path="tags" type="list[str]" default="[]">
  Tags associated with the memory.
</ParamField>

<ParamField path="scope" type="MemoryScope">
  The scope hierarchy this memory belongs to.
</ParamField>

<ParamField path="metadata" type="dict[str, Any] | None" default="None">
  Arbitrary metadata attached to the memory.
</ParamField>

<ParamField path="ttl_seconds" type="int | None" default="None">
  Time-to-live in seconds, if set.
</ParamField>

<ParamField path="created_at" type="datetime">
  Timestamp when the memory was first created.
</ParamField>

<ParamField path="updated_at" type="datetime">
  Timestamp of the most recent update.
</ParamField>

***

## Risk and Policy Models

### RiskFactor

A single contributing factor to the overall risk score.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class RiskFactor(BaseModel):
    name: str
    contribution: float = Field(ge=0, le=1)
    description: str
    evidence: str | None = None
```

<ParamField path="name" type="str">
  Machine-readable name of the risk factor (e.g., `"pii_detected"`, `"cross_tenant"`).
</ParamField>

<ParamField path="contribution" type="float">
  Numeric contribution to the overall risk score, between 0.0 and 1.0.
</ParamField>

<ParamField path="description" type="str">
  Human-readable explanation of why this factor was triggered.
</ParamField>

<ParamField path="evidence" type="str | None" default="None">
  Optional supporting evidence or details.
</ParamField>

***

### RiskAssessment

The output of the risk engine, combining individual factors into an overall score and level.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class RiskAssessment(BaseModel):
    score: float = Field(ge=0, le=1)
    level: RiskLevel
    factors: list[RiskFactor]
    scorer: str
```

<ParamField path="score" type="float">
  Overall risk score between 0.0 (no risk) and 1.0 (maximum risk).
</ParamField>

<ParamField path="level" type="RiskLevel">
  Categorical risk level: `"low"`, `"medium"`, `"high"`, or `"critical"`.
</ParamField>

<ParamField path="factors" type="list[RiskFactor]">
  Individual risk factors that contributed to the score.
</ParamField>

<ParamField path="scorer" type="str">
  Identifier of the risk scoring algorithm or engine version that produced this assessment.
</ParamField>

***

### PolicyDecision

The output of the policy engine after evaluating rules.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class PolicyDecision(BaseModel):
    action: DecisionAction
    reason_codes: list[str]
    matched_rule_ids: list[str] | None = None
    policy_version: str
```

<ParamField path="action" type="DecisionAction">
  The decided action: `"allow"`, `"deny"`, `"require_approval"`, or `"quarantine"`.
</ParamField>

<ParamField path="reason_codes" type="list[str]">
  Machine-readable codes explaining why this decision was made (e.g., `["pii_detected", "high_risk"]`).
</ParamField>

<ParamField path="matched_rule_ids" type="list[str] | None" default="None">
  IDs of the policy rules that matched and triggered this decision.
</ParamField>

<ParamField path="policy_version" type="str">
  Version string of the policy configuration that was evaluated.
</ParamField>

***

## Response Models

### MemoryOperationResponse

Returned by `remember()` and `update()`. Contains the full result of a create or update operation.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class MemoryOperationResponse(BaseModel):
    operation_id: str
    status: OperationStatus
    memory: MemoryRecord | None = None
    risk_assessment: RiskAssessment | None = None
    decision: PolicyDecision
```

<ParamField path="operation_id" type="str">
  Unique identifier for this operation. Use this to track status via `get_operation_status()`, `approve()`, or `deny()`.
</ParamField>

<ParamField path="status" type="OperationStatus">
  Current status of the operation.
</ParamField>

<ParamField path="memory" type="MemoryRecord | None">
  The created or updated memory record. This is `None` when the operation was blocked, quarantined, or is pending approval.
</ParamField>

<ParamField path="risk_assessment" type="RiskAssessment | None">
  The risk assessment produced during pipeline execution.
</ParamField>

<ParamField path="decision" type="PolicyDecision">
  The policy engine's decision for this operation.
</ParamField>

#### Example

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
result = await mp.remember(
    content="user email is alice@example.com",
    scope={"tenant_id": "acme", "project_id": "p1", "agent_id": "a1"},
    context={
        "actor_type": "agent", "actor_id": "a1",
        "source": "langgraph", "timestamp": "2026-01-15T10:30:00Z",
    },
)

if result.status == OperationStatus.committed:
    print(f"Stored: {result.memory.memory_id}")
elif result.status == OperationStatus.pending_approval:
    print(f"Awaiting approval: {result.operation_id}")
elif result.status == OperationStatus.blocked:
    print(f"Blocked: {result.decision.reason_codes}")
```

***

### OperationStatusResponse

Returned by `forget()`, `approve()`, `deny()`, and `get_operation_status()`.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class OperationStatusResponse(BaseModel):
    operation_id: str
    operation_type: OperationType
    status: OperationStatus
    memory_id: str | None = None
    decision: PolicyDecision
    risk_assessment: RiskAssessment | None = None
    created_at: datetime | None = None
    updated_at: datetime | None = None
```

<ParamField path="operation_id" type="str">
  Unique identifier of the operation.
</ParamField>

<ParamField path="operation_type" type="OperationType">
  The type of operation: `"remember"`, `"update"`, `"forget"`, `"search"`, or `"get"`.
</ParamField>

<ParamField path="status" type="OperationStatus">
  Current lifecycle status.
</ParamField>

<ParamField path="memory_id" type="str | None">
  The ID of the affected memory, if applicable.
</ParamField>

<ParamField path="decision" type="PolicyDecision">
  The policy decision that governed this operation.
</ParamField>

<ParamField path="risk_assessment" type="RiskAssessment | None">
  The risk assessment, if one was performed.
</ParamField>

<ParamField path="created_at" type="datetime | None">
  When the operation was first received.
</ParamField>

<ParamField path="updated_at" type="datetime | None">
  When the operation status was last updated.
</ParamField>

***

### MemorySearchResponse

Returned by `search()`. Contains ranked search results.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class MemorySearchResponse(BaseModel):
    hits: list[MemorySearchHit]
```

<ParamField path="hits" type="list[MemorySearchHit]">
  Ordered list of search results, ranked by relevance score (highest first).
</ParamField>

***

### MemorySearchHit

A single search result pairing a memory record with its relevance score.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class MemorySearchHit(BaseModel):
    memory: MemoryRecord
    score: float = Field(ge=0, le=1)
```

<ParamField path="memory" type="MemoryRecord">
  The matching memory record.
</ParamField>

<ParamField path="score" type="float">
  Relevance score between 0.0 and 1.0.
</ParamField>

#### Example

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
results = await mp.search(
    query="dark mode",
    scope={"tenant_id": "acme", "project_id": "p1", "agent_id": "a1"},
    context={
        "actor_type": "agent", "actor_id": "a1",
        "source": "langgraph", "timestamp": "2026-01-15T10:31:00Z",
    },
)

for hit in results.hits:
    print(f"[{hit.score:.2f}] {hit.memory.content}")
```

***

## Audit Trail Models

### TrailEvent

An immutable audit event emitted at each stage of the orchestration pipeline. Events are stored in the [Trailproof](https://trailproof.kyberon.dev/docs/introduction) audit trail with SHA-256 hash chains and optional HMAC signing for tamper evidence.

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class TrailEvent:
    event_id: str
    event_type: str
    timestamp: datetime
    actor: str | None
    metadata: dict[str, Any]
    hash: str
    prev_hash: str | None
    signature: str | None
```

<ParamField path="event_id" type="str">
  Unique identifier for this event.
</ParamField>

<ParamField path="event_type" type="str">
  Namespaced event type (e.g., `"memproof.pipeline.received"`, `"memproof.pipeline.committed"`).
</ParamField>

<ParamField path="timestamp" type="datetime">
  When the event was created.
</ParamField>

<ParamField path="actor" type="str | None">
  The actor who triggered the event, if available.
</ParamField>

<ParamField path="metadata" type="dict[str, Any]">
  Event-specific data including `operation_id`, `tenant_id`, `project_id`, and stage-specific payload (e.g., risk assessment result, policy decision).
</ParamField>

<ParamField path="hash" type="str">
  SHA-256 hash of this event for chain integrity.
</ParamField>

<ParamField path="prev_hash" type="str | None">
  Hash of the previous event in the chain. `None` for the first event.
</ParamField>

<ParamField path="signature" type="str | None">
  HMAC-SHA256 signature if signing is enabled. `None` otherwise.
</ParamField>

***

## Request Models

These models are used internally by the `Memproof` class to structure requests before passing them to the orchestrator. You generally do not need to construct them directly -- the `Memproof` methods accept raw dictionaries and build these internally.

### MemoryCreateRequest

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class MemoryCreateRequest(BaseModel):
    content: str = Field(min_length=1)
    tags: list[str] | None = None
    scope: MemoryScope
    context: OperationContext
    metadata: dict[str, Any] | None = None
    ttl_seconds: int | None = Field(default=None, gt=0)
```

### MemoryUpdateRequest

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class MemoryUpdateRequest(BaseModel):
    content: str | None = None
    tags: list[str] | None = None
    metadata_patch: dict[str, Any] | None = None
    ttl_seconds: int | None = Field(default=None, gt=0)
    context: OperationContext
```

### MemorySearchRequest

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
class MemorySearchRequest(BaseModel):
    query: str = Field(min_length=1)
    scope: MemoryScope
    context: OperationContext
    limit: int = Field(default=20, ge=1, le=100)
    filters: dict[str, Any] | None = None
```