Memory Lifecycle

Engram memory flow is designed to be deterministic and auditable.

store(data, options?)

store executes these phases:

1. Resolve policy from priority plus explicit overrides
2. Enforce budget (maxSpendUSDFC) before network operations
3. Fund wallet path if balance is insufficient
4. Encrypt payload when encrypt: true
5. Submit to provider and return CID/deal metadata
6. Optionally attest on-chain (attestOnChain)
7. Flush CID index pointer for restore operations

const receipt = await sdk.store(
  { chainOfThoughtDigest, decision },
  { priority: 'critical', encrypt: true }
)

Receipt Contract

interface StorageReceipt {
  cid: string
  dealId: string
  ttlTimestamp: Date
  spendUSDFC: number
  policy: { replication: number; ttlDays: number; encrypt: boolean }
  identityAddress?: string
  attestationTx?: string
}

Priority Baselines

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

retrieve(cid, options?)

retrieve fetches by CID and decrypts when payload metadata indicates encryption.

const memory = await sdk.retrieve(receipt.cid)

renew(cid, options?)

renew checks TTL proximity against renewThresholdDays. It is idempotent and safe for scheduled execution.

const result = await sdk.renew(receipt.cid)
if (result.renewed) {
  console.log('Memory TTL extended')
}

Renew Result

interface RenewResult {
  cid: string
  dealId: string
  renewed: boolean
  daysUntilExpiry: number
}

Behavior notes:

• if outside threshold and not forced, returns renewed: false
• if forced ({ force: true }), renew path executes immediately

prune(cid)

prune removes a CID from the active index. It does not mutate immutable Filecoin content.

await sdk.prune(receipt.cid)

Prune Result

interface PruneResult {
  cid: string
  pruned: boolean
}

Recovery Model

Each store/prune operation updates the index pointer used by restore flows. This is what allows "cold key recovery" behavior after restarts or machine changes.

Operationally, treat index updates as critical:

• do not bypass flushes for durable memory records
• reserve _skipFlush for ephemeral internal payloads only

Scheduled Lifecycle Pattern

A practical cron-like pattern:

1. periodic renew over tracked CIDs
2. re-store long-lived evolving state as new CID snapshots
3. prune obsolete CIDs from active index
4. run canary retrieve checks for critical records