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

# Audit Trail Configuration

> Configure durable audit trail storage, HMAC signing, and hash chain verification with Trailproof.

Every memory operation in Memproof emits lifecycle events to an audit trail powered by [Trailproof](https://trailproof.kyberon.dev/docs/introduction). These events form a tamper-evident, hash-chained record of what happened, when, and why.

## Event Types

Each operation progresses through a sequence of namespaced events:

| Event Type                             | Emitted When                                        |
| -------------------------------------- | --------------------------------------------------- |
| `memproof.pipeline.received`           | Operation enters the control path                   |
| `memproof.pipeline.risk_assessed`      | Risk engine produces a score and level              |
| `memproof.pipeline.policy_decided`     | Policy engine returns allow/deny/approve/quarantine |
| `memproof.pipeline.approval_requested` | Operation is sent to the approval broker            |
| `memproof.pipeline.provider_attempted` | Adapter backend call is made                        |
| `memproof.pipeline.committed`          | Memory successfully persisted                       |
| `memproof.pipeline.blocked`            | Operation denied or quarantined                     |

## Choosing a Trail Store

<Tabs>
  <Tab title="In-Memory (default)">
    Events are stored in memory. Suitable for development and testing. Data is lost on process exit.

    <Tabs>
      <Tab title="Python">
        ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        mp = Memproof(
            policy="memproof.yaml",
            trail_store="memory",   # this is the default
        )
        ```
      </Tab>

      <Tab title="TypeScript">
        ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        const mp = new Memproof({
          policy: "memproof.yaml",
          trailStore: "memory",   // this is the default
        });
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="JSONL (durable)">
    Events are appended to a JSONL (JSON Lines) file on disk. Each event is a single line, making the file append-only and easy to process with standard tools. Suitable for production deployments.

    <Tabs>
      <Tab title="Python">
        ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        mp = Memproof(
            policy="memproof.yaml",
            trail_store="jsonl",
            trail_store_path="./memproof_audit.jsonl",
        )
        ```
      </Tab>

      <Tab title="TypeScript">
        ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        const mp = new Memproof({
          policy: "memproof.yaml",
          trailStore: "jsonl",
          trailStorePath: "./memproof_audit.jsonl",
        });
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Event Signing

Provide a signing key to enable HMAC-SHA256 signing. Trailproof signs each event and stores the signature in the `TrailEvent`:

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    mp = Memproof(
        policy="memproof.yaml",
        trail_store="jsonl",
        trail_store_path="./memproof_audit.jsonl",
        trail_signing_key="your-secret-key-from-vault",
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    const mp = new Memproof({
      policy: "memproof.yaml",
      trailStore: "jsonl",
      trailStorePath: "./memproof_audit.jsonl",
      trailSigningKey: "your-secret-key-from-vault",
    });
    ```
  </Tab>
</Tabs>

<Warning>
  Store the signing key in a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.). If the key is compromised, an attacker could forge valid signatures for fabricated events.
</Warning>

## Verifying the Audit Trail

Trailproof links each event to its predecessor using SHA-256 hashes. Call `verify_audit_trail()` / `verifyAuditTrail()` to validate the entire hash chain and detect any tampering:

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    result = mp.verify_audit_trail()

    if result.valid:
        print(f"Chain intact: {result.event_count} events verified")
    else:
        print(f"Chain broken: {result.error}")
        # Investigate the broken link
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    const result = mp.verifyAuditTrail();

    if (result.valid) {
      console.log(`Chain intact: ${result.eventCount} events verified`);
    } else {
      console.log(`Chain broken: ${result.error}`);
      // Investigate the broken link
    }
    ```
  </Tab>
</Tabs>

<Tip>
  Run verification on a schedule (e.g., every hour or as part of a health check) to detect tampering early. If the chain breaks, the verification result identifies the first invalid event.
</Tip>

## Querying the Audit Trail

Use the `query_audit_trail()` / `queryAuditTrail()` method to search events:

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    # All committed events for a tenant
    events = mp.query_audit_trail(
        event_type="memproof.pipeline.committed",
        metadata={"tenant_id": "acme-corp"},
        limit=50,
    )

    for event in events:
        print(f"{event.event_type} at {event.timestamp}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    // All committed events for a tenant
    const events = mp.queryAuditTrail({
      eventType: "memproof.pipeline.committed",
      metadata: { tenantId: "acme-corp" },
      limit: 50,
    });

    for (const event of events) {
      console.log(`${event.eventType} at ${event.timestamp}`);
    }
    ```
  </Tab>
</Tabs>

You can also retrieve all events for a single operation by filtering on `operation_id` in the metadata:

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    events = mp.query_audit_trail(
        metadata={"operation_id": "op-abc123"},
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    const events = mp.queryAuditTrail({
      metadata: { operationId: "op-abc123" },
    });
    ```
  </Tab>
</Tabs>

## TrailEvent Structure

Each event in the audit trail is a Trailproof `TrailEvent`:

<Tabs>
  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    class TrailEvent:
        event_id: str           # globally unique ID
        event_type: str         # e.g. "memproof.pipeline.committed"
        timestamp: datetime     # UTC timestamp
        actor: str | None       # who triggered the event
        metadata: dict          # operation_id, tenant_id, stage-specific data
        hash: str               # SHA-256 hash for chain integrity
        prev_hash: str | None   # hash of the previous event in the chain
        signature: str | None   # HMAC-SHA256 signature (if signing enabled)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    interface TrailEvent {
      eventId: string;
      eventType: string;
      timestamp: Date;
      actor: string | null;
      metadata: Record<string, unknown>;
      hash: string;
      prevHash: string | null;
      signature: string | null;
    }
    ```
  </Tab>
</Tabs>

## Environment Variable Configuration

All trail settings can be configured via environment variables:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
export MEMPROOF_TRAIL_STORE="jsonl"
export MEMPROOF_TRAIL_STORE_PATH="./memproof_audit.jsonl"
export MEMPROOF_TRAIL_SIGNING_KEY="your-secret-key"
```

See [Configuration](/api-reference/config) for the full environment variable reference.

## Learn More

For advanced Trailproof features -- custom stores, chain semantics, and more -- see the [Trailproof documentation](https://trailproof.kyberon.dev/docs/introduction).