Audit Trail Configuration

Every memory operation in Memproof emits lifecycle events to an audit trail powered by Trailproof. 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

In-Memory (default)
JSONL (durable)

Events are stored in memory. Suitable for development and testing. Data is lost on process exit.

Python
TypeScript

mp = Memproof(
    policy="memproof.yaml",
    trail_store="memory",   # this is the default
)

const mp = new Memproof({
  policy: "memproof.yaml",
  trailStore: "memory",   // this is the default
});

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.

Python
TypeScript

mp = Memproof(
    policy="memproof.yaml",
    trail_store="jsonl",
    trail_store_path="./memproof_audit.jsonl",
)

const mp = new Memproof({
  policy: "memproof.yaml",
  trailStore: "jsonl",
  trailStorePath: "./memproof_audit.jsonl",
});

Event Signing

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

Python
TypeScript

mp = Memproof(
    policy="memproof.yaml",
    trail_store="jsonl",
    trail_store_path="./memproof_audit.jsonl",
    trail_signing_key="your-secret-key-from-vault",
)

const mp = new Memproof({
  policy: "memproof.yaml",
  trailStore: "jsonl",
  trailStorePath: "./memproof_audit.jsonl",
  trailSigningKey: "your-secret-key-from-vault",
});

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.

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:

Python
TypeScript

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

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
}

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.

Querying the Audit Trail

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

Python
TypeScript

# 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}")

// 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}`);
}

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

Python
TypeScript

events = mp.query_audit_trail(
    metadata={"operation_id": "op-abc123"},
)

const events = mp.queryAuditTrail({
  metadata: { operationId: "op-abc123" },
});

TrailEvent Structure

Each event in the audit trail is a Trailproof TrailEvent:

Python
TypeScript

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)

interface TrailEvent {
  eventId: string;
  eventType: string;
  timestamp: Date;
  actor: string | null;
  metadata: Record<string, unknown>;
  hash: string;
  prevHash: string | null;
  signature: string | null;
}

Environment Variable Configuration

All trail settings can be configured via environment variables:

export MEMPROOF_TRAIL_STORE="jsonl"
export MEMPROOF_TRAIL_STORE_PATH="./memproof_audit.jsonl"
export MEMPROOF_TRAIL_SIGNING_KEY="your-secret-key"

See Configuration for the full environment variable reference.

Learn More

For advanced Trailproof features — custom stores, chain semantics, and more — see the Trailproof documentation.

​Event Types

​Choosing a Trail Store

​Event Signing

​Verifying the Audit Trail

​Querying the Audit Trail

​TrailEvent Structure

​Environment Variable Configuration

​Learn More

Event Types

Choosing a Trail Store

Event Signing

Verifying the Audit Trail

Querying the Audit Trail

TrailEvent Structure

Environment Variable Configuration

Learn More