Memory

Memory is fundamental to how Daydreams agents operate, allowing them to maintain state, recall past interactions, store learned information, and improve their performance over time. The framework provides a flexible system with different types of memory serving distinct purposes.

Core Memory Components (`BaseMemory`)

When creating an agent using createDreams, you configure its primary memory system via the memory option. This accepts an object conforming to the BaseMemory type, which holds implementations for different storage needs:

import { createDreams } from "@daydreamsai/core";
import { createMemory, createMemoryStore, createVectorStore } from "@daydreamsai/core";
import { createChromaVectorStore } from "@daydreamsai/chroma"; // Example
import { createMongoMemoryStore } from "@daydreamsai/mongo"; // Example
 
const agent = createDreams({
  model: /* ... */,
  memory: createMemory(
    // 1. MemoryStore: For key-value based storage
    await createMongoMemoryStore({ uri: "mongodb://localhost:27017" }),
 
    // 2. VectorStore: For embedding storage and similarity search
    createChromaVectorStore("my-agent-episodes")
  ),
  // Optional: Enable automatic episodic memory generation
  // generateMemories: true,
  // exportTrainingData: true, // Optionally save episodes for fine-tuning
  // trainingDataPath: './agent-training.jsonl'
});

The createMemory function bundles together two main storage interfaces:

MemoryStore: A key-value store interface for structured data persistence.
VectorStore: An interface for storing vector embeddings and performing similarity searches, primarily used for episodic memory.

The BaseMemory object passed to createDreams makes these stores available throughout the agent's systems.

`MemoryStore` (Key-Value Storage)

The MemoryStore handles the persistence of structured data associated with contexts and actions. It defines a simple key-value interface:

get<T>(key: string): Promise<T | null>: Retrieve data by key.
set<T>(key: string, value: T): Promise<void>: Store or update data by key.
delete(key: string): Promise<void>: Remove data by key.
clear(): Promise<void>: Remove all data (use with caution).

Uses:

Storing ContextState snapshots (key: "context:<contextId>").
Storing persistent Context memory (key: "memory:<contextId>").
Storing WorkingMemory snapshots between runs (key: "working-memory:<contextId>").
Storing persistent Action memory (key: defined in action.memory.key).

Implementations:

createMemoryStore(): Default in-memory store using a Map (data lost on restart). Found in @daydreamsai/core.
createMongoMemoryStore(): MongoDB-backed implementation. Found in @daydreamsai/mongo.
(Others like SQLite, Redis might be available or could be implemented)

`VectorStore` (Embedding Storage & Search)

The VectorStore is designed for handling high-dimensional vector embeddings, typically used for semantic search and retrieving relevant past experiences (Episodic Memory).

upsert(contextId: string, data: any): Promise<void>: Add or update vector embeddings, often associated with a specific context.
query(contextId: string, query: string): Promise<any[]>: Search for vectors similar to the query text within a specific context.
createIndex(indexName: string): Promise<void>: Create an index (if required by the backend).
deleteIndex(indexName: string): Promise<void>: Delete an index.

Uses:

Storing Episode embeddings for recall.
Potentially storing document embeddings for RAG (Retrieval-Augmented Generation) patterns (though not explicitly shown in the core loop).

Implementations:

createVectorStore(): Default no-op implementation (does nothing). Found in @daydreamsai/core.
createChromaVectorStore(): Implementation using ChromaDB. Found in @daydreamsai/chroma. Requires OPENAI_API_KEY for default embedding or a custom embedder.
(Others like Pinecone might be available or could be implemented)

Types of Memory Usage

Working Memory

Purpose: Short-term, temporary storage for a single agent.run cycle.
Content: Holds the sequence of Log objects (InputRef, OutputRef, Thought, ActionCall, ActionResult, EventRef, StepRef, RunRef) generated during the run.
Lifecycle: Created at the start of agent.run, populated during stream processing, used to build prompts at each step, and potentially snapshotted to the MemoryStore between runs.
Access: Available as ctx.workingMemory within handlers.

Context Memory

Purpose: Persistent state associated with a specific Context instance (e.g., chat history for a specific user session).
Structure: Defined by the create function in the context definition.
Lifecycle: Loaded from the MemoryStore when agent.getContext is called, updated by context logic or actions, saved back to the MemoryStore via agent.saveContext.
Access: Available as ctx.memory within context-related functions (render, onStep, etc.) and action handlers.

Action Memory

Purpose: Persistent state associated specifically with an Action, allowing it to maintain state across multiple calls within different runs or contexts.
Structure: Defined by the memory option in the action definition, using the memory() helper.
Lifecycle: Loaded from the MemoryStore before the action handler runs, potentially updated by the handler, saved back to the MemoryStore after the handler completes.
Access: Available as ctx.actionMemory within the action's handler.

Episodic Memory

Purpose: Enables the agent to learn from past experiences by recalling relevant "episodes" (sequences of observation/thought -> action -> result).
Structure: Defined by the Episode interface (observation, thoughts, result, timestamp, etc.).
Generation: Handled by generateEpisode (memory/utils.ts), which uses an LLM to summarize the Thought, ActionCall, and ActionResult. Triggered automatically if agent.memory.generateMemories is true.
Storage: The generated Episode (or its embedding) is stored in the VectorStore via agent.memory.vector.upsert().
Retrieval: When a new InputRef is processed (handleInput), the agent.memory.vector.query() method is called to find relevant past episodes based on the input content. Retrieved episodes are added to WorkingMemory.episodicMemory.
Training Data: Episodes can be exported as prompt/completion pairs for fine-tuning models using agent.exportAllTrainingData() or by setting exportTrainingData: true on the agent config.

By combining these memory types and storage backends, Daydreams agents can maintain short-term focus (Working Memory), long-term context state (Context/Action Memory), and learn from past interactions (Episodic Memory via VectorStore).

On this page