Class: AgentMemory

AgentMemory provides persistent, verifiable storage for AI agents using zero-knowledge proofs.

It operates on centralized state management where all memory metadata is stored at a single persistent storage address, eliminating local file dependencies:

Key characteristics:

Centralized State: All agents share a single source of truth at the persistent address
Atomic Updates: Compare-and-swap operations ensure consistency
Immediate Visibility: Updates are instantly visible to all agents
Auto-initialization: Persistent storage is created automatically if not provided

Memory Model:

Persistent Storage Address (Index 0)
  └── State JSON (padded to 1MB)
        └── memories{} (user defined identifiers)
              ├── "memory1" → { commitment, metadata, address }
              ├── "memory2" → { commitment, metadata, address }
              └── "memory3" → { commitment, metadata, address }

Individual Storage Addresses
  ├── Address1 → Actual data for memory1
  ├── Address2 → Actual data for memory2
  └── Address3 → Actual data for memory3

Consistency Guarantees

The system provides eventual consistency with immediate visibility:

Write Consistency: Atomic updates via compare-and-swap
Read Consistency: Always reads latest state from backend
Conflict Resolution: Retry logic handles concurrent modifications

Methods

batchRead()

batchRead(identifiers, options?): Promise<Map<string, string>>

Defined in: ensue-sdk.ts:799

Reads multiple memories in a single batch operation for efficiency.

Parameters

identifiers

string[]

Array of memory identifiers to read

options?

ReadOptions

Optional read options including proof verification

Returns

Promise<Map<string, string>>

Promise resolving to Map of identifier to data pairs

Throws

If any memory doesn't exist or proof verification fails

batchReadVerified()

batchReadVerified(identifiers): Promise<Map<string, string>>

Defined in: ensue-sdk.ts:912

Batch reads multiple memories with mandatory proof verification.

Parameters

identifiers

string[]

Returns

Promise<Map<string, string>>

getClient()

getClient(): EnsueClient

Defined in: ensue-sdk.ts:1031

Gets the underlying Ensue client for advanced operations.

Provides access to low-level operations like:

Custom query construction
Direct storage contract interaction
Manual proof verification
Batch operations with custom grouping

Use with caution - direct client usage bypasses AgentMemory's state management and consistency guarantees.

Returns

EnsueClient

The EnsueClient instance

getMemoryMetadata()

getMemoryMetadata(identifier): Promise<undefined | MemoryMetadata>

Defined in: ensue-sdk.ts:963

Retrieves metadata for a specific memory from centralized state.

Always returns the latest metadata from the persistent storage:

Creation and modification timestamps
Current data size
Storage location details

This ensures consistency when multiple agents are updating the same memory concurrently.

Parameters

identifier

string

Memory identifier

Returns

Promise<undefined | MemoryMetadata>

Promise resolving to current metadata

Throws

If memory doesn't exist in the system

getPersistentStorageAddress()

getPersistentStorageAddress(): WasmStorageAddress

Defined in: ensue-sdk.ts:1013

Returns

WasmStorageAddress

has()

has(identifier): Promise<boolean>

Defined in: ensue-sdk.ts:926

Checks if a memory exists in the centralized state. Always checks the current state from the persistent storage address. This ensures:

Immediate visibility of memories created by other agents
No false negatives due to stale local cache
Consistent view across all agents

Parameters

identifier

string

Identifier to check

Returns

Promise<boolean>

Promise resolving to true if memory exists in shared state

listMemoryIdentifiers()

listMemoryIdentifiers(): Promise<string[]>

Defined in: ensue-sdk.ts:943

Lists all memory identifiers in the centralized state.

Returns ALL memories visible to ANY agent sharing this persistent storage address.

Global View: See all memories, not just locally cached ones
Real-time: Includes memories just created by other agents
Consistent: All agents see the same list

Returns

Promise<string[]>

Promise resolving to array of all memory identifiers

read()

read(identifier, options?): Promise<string>

Defined in: ensue-sdk.ts:751

Reads data from memory by identifier. Currently reads the entire memory which maps to a the entirety of a single commitment.

Parameters

identifier

string

Identifier of the memory to read

options?

ReadOptions

If options.verifyProof is true, it will perform proof verification. Otherwise, it will read directly without proof

Returns

Promise<string>

Promise resolving to the stored string data

Throws

If memory doesn't exist or proof verification fails

readVerified()

readVerified(identifier): Promise<string>

Defined in: ensue-sdk.ts:905

Reads data with mandatory proof verification.

Parameters

identifier

string

Returns

Promise<string>

update_or_create_key()

update_or_create_key(identifier, data): Promise<void>

Defined in: ensue-sdk.ts:708

Creates or updates a memory with the given identifier. The method handles concurrent updates from multiple agents:

Uses atomic state updates with retry logic
Last-write-wins semantics for the same identifier

Parameters

identifier

string

Unique identifier for the memory

data

string

String data to store (truncated if >2MB)

Returns

Promise<void>

Throws

If encoding fails or state update fails after retries

verifyStorage()

verifyStorage(identifier): Promise<boolean>

Defined in: ensue-sdk.ts:979

Verifies the integrity of stored data using storage proofs.

Parameters

identifier

string

Memory identifier to verify

Returns

Promise<boolean>

Promise resolving to true if data stored matches the commitment tracked, false otherwise

Throws

If memory doesn't exist

create()

static create(secretKey, persistentStorageAddress?, rpcHost?, rpcPort?, options?): Promise<AgentMemory>

Defined in: ensue-sdk.ts:644

Creates a new AgentMemory instance with automatic persistent storage management.

Usage Patterns

Single Agent (Simplest)

const agent = await AgentMemory.create(secretKey);
// Automatically creates/loads persistent storage

Multi-Agent (Same Application)

// First agent creates the storage
const agent1 = await AgentMemory.create(key1);
const addr = agent1.getPersistentStorageAddress();

// Other agents use the same address
const agent2 = await AgentMemory.create(key2, addr.value);
const agent3 = await AgentMemory.create(key3, addr.value);

Cross-Session Persistence

// First session: address saved to file automatically
const agent = await AgentMemory.create(secretKey);

// Later session: address loaded from file automatically
const agent = await AgentMemory.create(secretKey);

Parameters

secretKey

Fq

32-byte secret key for cryptographic operations

persistentStorageAddress?

Fq

Optional pre-existing storage address

rpcHost?

string

RPC host of the storage backend (defaults to localhost)

rpcPort?

number

RPC port of the storage backend (defaults to 3030)

options?

AgentMemoryOptions

Configuration options including:

persistentAddressFile: Path to save/load persistent address
stateFile: Legacy parameter (kept for compatibility)
srsFile: Path to SRS file for proof generation

Returns

Promise<AgentMemory>

Promise resolving to initialized AgentMemory instance

Throws

If secret key is not exactly 32 bytes