Architecture

Engram sits between your agent runtime and protocol services, with explicit boundaries for storage, funding, encryption, and identity.

High-Level Topology

Agent Runtime (LangChain / LlamaIndex / custom / MCP tools)
  -> EngramSDK orchestration
     -> Policy engine (deterministic)
     -> Budget guard + running spend
     -> Wallet + funding + encryption
     -> Provider interface (store/retrieve/renew)
     -> Identity + delegation + attestations
     -> Index pointer flush for recovery
  -> Protocol + infra layers
     -> Filecoin storage network
     -> ERC-8004 contracts
     -> Vincent wallet services

Core Components

1) Policy Engine (resolvePolicy)

• pure function
• stable defaults by priority
• explicit override precedence

2) Runtime Coordinator (EngramSDK)

Coordinates operation flow across provider, wallet, identity, and logger while preserving deterministic guardrails.

3) Provider Abstraction (StorageProvider)

Defines required methods:

• store(data, policy)
• retrieve(cid)
• renew(cid, policy)

This keeps lifecycle behavior stable while allowing backend substitution (synapse, mock, and future providers).

4) Identity and Registry Layer

Handles agent identity registration, attestations, and index pointer updates required for recovery workflows.

5) Delegation Layer

Creates and verifies signed capability tokens for agent-to-agent read access delegation.

Operation Sequence: store

App calls sdk.store(data, opts)
  -> resolve policy
  -> enforce budget cap
  -> check/fund balance path
  -> optional encrypt
  -> provider.store
  -> optional on-chain attestation
  -> update in-memory index
  -> flush index pointer (unless skipped)
  -> return StorageReceipt

Operation Sequence: renew

App calls sdk.renew(cid, opts)
  -> compute daysUntilExpiry
  -> renew if force || within threshold
  -> enforce budget cap
  -> optional wallet signing
  -> provider.renew
  -> optional on-chain attestation
  -> return RenewResult

Recovery Path

Store and prune operations keep the memory index pointer updated. Restore flows reconstruct state from that pointer and agent identity context.

This model supports cold restarts without relying on centralized mutable app databases.

Data Boundaries and Mutability

• Stored payloads are immutable once addressed by CID
• Active index is mutable runtime state
• prune mutates index tracking only
• new state versions should be stored as new CIDs

Security Boundaries

• Encryption path is explicit (encrypt: true)
• Delegation tokens are signed and time-bound
• On-chain attestation path can be enabled per deployment
• Key custody remains with operator/Vincent controls

Failure Domains

• Provider outages: affect store/retrieve/renew
• Wallet/funding issues: affect paid operations
• RPC/contract issues: affect registration, attestations, index updates
• Config errors: can affect all domains

Mitigation strategy should include retries, monitoring, and environment-specific fallback modes.