Agent Memory

Agent Memory provides working memory management for AI agents with session-based storage, timeline organization, and semantic search capabilities. Use it to store, retrieve, and search memory entries within isolated sessions. This system is designed to give AI agents the ability to maintain context and learn from interactions within bounded sessions, similar to how human working memory operates during conversations or tasks.

The system provides methods for creating memory sessions, storing memory entries with timestamps and metadata, and querying memories using exact matching or semantic search. Each memory entry belongs to a session and can be organized along timelines for logical separation. Sessions provide isolation between different conversations or tasks, while timelines within sessions allow you to categorize memories by topic, priority, or any other organizational scheme. The semantic search capability enables agents to find relevant memories even when exact keywords don’t match, making the system more intelligent than simple key-value storage.

Prerequisites

• Understanding of AI agent architecture and stateful behavior
• Raindrop framework installed in your project
• Familiarity with TypeScript and async/await patterns
• Basic knowledge of memory management concepts in AI systems

Configuration

Define agent memory in your application manifest:

application "demo-app" {
    agent_memory "demo-memory" {}
}

Tip

Agent Memory names must be unique and use kebab-case naming.

Access

Access agent memory through environment variables. The manifest name converts to uppercase with underscores, following the same pattern as other Raindrop resources. Once you access the memory resource, you can create multiple sessions to isolate different conversations or agent instances from each other.

// Manifest: agent_memory "demo-memory"
// Access via: env.DEMO_MEMORY
const { sessionId, workingMemory } = await env.DEMO_MEMORY.startWorkingMemorySession();

Core Interfaces

MemoryEntry

Represents a stored memory entry with metadata and timestamps:

interface MemoryEntry {
  id: string;              // Unique memory identifier
  in: string;              // Session ID this memory belongs to
  timeline: string;        // Timeline organization
  by: string;              // Creator or source identifier
  dueTo: string;           // Causal relationship identifier
  content: string;         // The actual memory content
  at: Date;                // Timestamp when memory was created
  key?: string;            // Optional metadata key for filtering
  agent?: string;          // Optional agent name that created this memory
}

NewMemoryEntry

Input interface for creating new memory entries:

interface NewMemoryEntry {
  content: string;         // Required: the memory content
  timeline?: string;       // Optional: defaults to "*defaultTimeline"
  key?: string;            // Optional: metadata key for filtering
  agent?: string;          // Optional: agent identifier
  sessionId?: string;      // Optional: explicit session override
}

WorkingMemoryQuery

Query interface for retrieving memories:

interface WorkingMemoryQuery {
  timeline?: string;       // Filter by timeline
  key?: string;            // Filter by metadata key
  nMostRecent?: number;    // Limit to N most recent entries
  startTime?: Date;        // Filter by time range start
  endTime?: Date;          // Filter by time range end
}

WorkingMemorySearchQuery

Search interface for semantic memory search:

interface WorkingMemorySearchQuery {
  timeline?: string;       // Optional timeline filter
  terms: string;           // Required search terms
  nMostRecent?: number;    // Optional result limit
  startTime?: Date;        // Optional time range start
  endTime?: Date;          // Optional time range end
}

Session Methods

startWorkingMemorySession()

Creates a new working memory session with a unique session identifier. Each session provides isolated memory storage, allowing you to run multiple agent conversations or tasks simultaneously without memory interference. The returned session ID can be stored and used later to reconnect to the same memory session.

Returns: Promise<{ sessionId: string, workingMemory: AgentWorkingMemory }>

const { sessionId, workingMemory } = await env.DEMO_MEMORY.startWorkingMemorySession();

getWorkingMemorySession()

Retrieves an existing working memory session by ID. This method allows you to reconnect to a previously created session, maintaining continuity in agent conversations or long-running tasks. Returns null if the session doesn’t exist or has been cleaned up.

Parameters:

• sessionId: string - The session identifier

Returns: Promise<AgentWorkingMemory | null>

const workingMemory = await env.DEMO_MEMORY.getWorkingMemorySession("session-123");

Memory Methods

putMemory()

Stores a new memory entry in the session with automatic timestamp assignment and metadata tracking. Each memory entry is tagged with the session ID, timeline, and creation timestamp, making it searchable through various query methods. The system automatically handles ID generation and ensures memories are properly indexed for retrieval.

Parameters:

• entry: NewMemoryEntry - The memory entry to store

Returns: Promise<string> - The unique memory entry ID

const entryId = await workingMemory.putMemory({
  content: "User prefers morning meetings",
  timeline: "conversation",
  key: "preference"
});

getMemory()

Queries memory entries using filters and time ranges, providing exact matching based on metadata fields like timeline and key. This method supports temporal filtering to find memories from specific time periods, and can limit results to the most recent entries. Use this when you need precise filtering based on known metadata values.

Parameters:

• query: WorkingMemoryQuery - Query filters and options

Returns: Promise<MemoryEntry[]> - Array of matching memory entries

const memories = await workingMemory.getMemory({
  timeline: "project-updates",
  nMostRecent: 10
});

searchMemory()

Performs semantic search across memory content using natural language understanding rather than exact keyword matching. This method analyzes the meaning of your search terms and finds relevant memories even when they use different wording. The results are ranked by relevance, with the most semantically similar memories returned first.

Parameters:

• query: WorkingMemorySearchQuery - Search terms and filters

Returns: Promise<MemoryEntry[]> - Array of matching entries ranked by relevance

const results = await workingMemory.searchMemory({
  terms: "meeting schedule calendar",
  nMostRecent: 5
});

endSession()

Ends the working memory session and performs cleanup of temporary data structures. The optional flush parameter allows you to preserve important memories to long-term storage before ending the session. Without flushing, all memories in the session are discarded when the session ends.

Parameters:

• options?: { flush?: boolean } - Optional cleanup options

Returns: Promise<void>

// Basic session end
await workingMemory.endSession();

// End with flush to long-term storage
await workingMemory.endSession({ flush: true });