Concepts

This page defines core Engram concepts so architecture and API behavior are predictable.

Mental Model: The Four Primitives

Engram is easiest to reason about as four primitives that compose:

1. Remember -> CID-based persistent memory
2. Pay -> wallet and funding path for storage lifecycle
3. Share -> capability delegation between agents
4. Prove -> optional on-chain receipts and auditable logs

These primitives map directly to the SDK's intended operating model for autonomous agents.

CID-Centric Memory

Engram treats memory as immutable content addressed by CID. The CID is the primary handle for:

• retrieval (retrieve)
• lifecycle operations (renew, prune)
• delegation scope (delegate)
• attestation context

Implication: updates are append-style (new CID), not in-place mutation.

Agent-Only vs Agents-With-Receipts

Two deployment modes are common:

• Agent-only mode: focus on autonomous execution and memory continuity
• Agents-with-receipts mode: additionally require cryptographic, externally verifiable operation evidence

attestOnChain and operation logs are the primary switches for receipt-rich deployments.

Policy Resolution

Every write resolves to a ResolvedPolicy:

interface ResolvedPolicy {
  replication: number
  ttlDays: number
  encrypt: boolean
}

Resolution logic is deterministic:

1. pick priority baseline (critical, standard, temporary, ephemeral)
2. apply explicit overrides (replication, ttlDays, encrypt)

Current defaults:

Priority	Replication	TTL	Encrypt
critical	5	365 days	true
standard	3	90 days	false
temporary	1	7 days	false
ephemeral	1	1 day	false

Policy behavior guarantees:

• no context -> defaults to standard
• explicit option values always override priority defaults
• same input context always produces the same resolved policy

Budget Guard

Engram tracks an in-process running spend (runningSpendUSDFC) and aborts writes/renewals when projected spend exceeds maxSpendUSDFC.

This check runs before storage operations to avoid hidden overages.

Active Index vs Underlying Storage

activeCids is an in-memory index representing currently tracked memory.

• prune removes a CID from this active index
• underlying immutable storage remains unchanged

This distinction is essential for operators who need index hygiene without destructive storage semantics.

Structured Execution Trail

Each operation emits structured log data designed for machine processing:

• event type (STORE, RETRIEVE, RENEW, PRUNE, etc.)
• decision context (policy, threshold checks, outcomes)
• spend and running totals
• attestation transaction references when enabled

Index Flush and Recoverability

After store and successful prune, the SDK flushes index state to a registry-linked pointer (unless _skipFlush is set for internal/ephemeral payloads).

This enables recovery patterns after process restarts by reconstructing indexed CIDs from durable pointers.

Delegation Token Model

Delegation issues a signed capability token with:

• target CID
• issuer DID/address
• recipient DID/address
• scope (agent/read)
• issued/expiry timestamps

Verification validates structure, recipient, signature, and expiry before trust.

This gives multi-agent collaboration without sharing root keys or introducing centralized token middleware.

Attestations

When attestOnChain is enabled, Engram emits event attestations for operations like store/renew/prune.

Use this for:

• verifiable audit trail
• post-incident analysis
• external trust boundaries