Overview
The Memory system in elizaOS stores and retrieves agent memories, messages, documents, and other data. Memories can be searched by embedding similarity, filtered by metadata, and organized into different tables.
Memory Type
interface Memory {
id?: UUID;
createdAt?: number;
content: Content;
embedding?: number[];
entityId: UUID;
agentId?: UUID;
roomId: UUID;
worldId?: UUID;
metadata?: MemoryMetadata;
sessionId?: string;
sessionKey?: string;
}
Unique identifier for the memory
Unix timestamp (milliseconds) when memory was created
Memory content with text, actions, and metadata
Vector embedding for semantic search
ID of the entity that created this memory
ID of the agent associated with this memory
ID of the room/conversation this memory belongs to
ID of the world/server this memory belongs to
Type-specific metadata (message, document, fragment, etc.)
Session UUID for filtering memories by conversation session
Full session key for routing (e.g., “agent:123:telegram:+14155551234”)
MemoryType
Built-in memory types:
enum MemoryType {
DOCUMENT = "document",
FRAGMENT = "fragment",
MESSAGE = "message",
DESCRIPTION = "description",
CUSTOM = "custom"
}
Represents a whole document or large piece of text
A chunk/segment of a DOCUMENT (for embedding and search)
A conversational message from user or agent
Descriptive information about an entity or concept
Custom memory type for extensions
interface MessageMetadata {
type?: "message";
timestamp?: number;
scope?: "shared" | "private" | "room";
sessionKey?: string;
sender?: SenderIdentity;
provider?: string;
chatType?: MessageChatType;
wasMentioned?: boolean;
// ... platform-specific fields
}
Session key for conversation routing
Sender information (id, name, username)
Platform name (telegram, discord, slack)
Type of chat (dm, group, channel, thread)
interface DocumentMetadata {
type?: "document";
source?: string;
sourceId?: UUID;
scope?: MemoryScope;
}
interface FragmentMetadata {
type?: "fragment";
documentId: UUID;
position: number;
}
ID of the parent document
Position of fragment within document
Functions
createMessageMemory
Create a message memory.
import { createMessageMemory } from "@elizaos/core";
const memory = createMessageMemory({
entityId: userId,
agentId: agentId,
roomId: roomId,
content: {
text: "Hello, world!",
source: "telegram"
},
embedding: [0.1, 0.2, ...] // optional
});
Memory creation parameters
Entity that created the memory
Type Guards
isDocumentMemory
import { isDocumentMemory } from "@elizaos/core";
if (isDocumentMemory(memory)) {
// memory.metadata is DocumentMetadata
}
isFragmentMemory
import { isFragmentMemory } from "@elizaos/core";
if (isFragmentMemory(memory)) {
console.log(memory.metadata.documentId);
console.log(memory.metadata.position);
}
import { isMessageMetadata } from "@elizaos/core";
if (memory.metadata && isMessageMetadata(memory.metadata)) {
console.log(memory.metadata.sender);
}
getMemoryText
Safely extract text from a memory.
import { getMemoryText } from "@elizaos/core";
const text = getMemoryText(memory, "default text");
Default value if no text found (default: "")
Runtime Memory Operations
The AgentRuntime provides methods for memory operations:
createMemory
await runtime.createMemory(memory: Memory, tableName: string): Promise<void>
Table name: “messages”, “documents”, “fragments”, etc.
await runtime.createMemory(
{
entityId: userId,
roomId: roomId,
content: { text: "Hello!" }
},
"messages"
);
getMemories
await runtime.getMemories(params: {
roomId: UUID;
count?: number;
unique?: boolean;
tableName: string;
agentId?: UUID;
start?: number;
end?: number;
}): Promise<Memory[]>
Room to get memories from
Maximum number of memories to return
Only return unique memories (by entity)
Start timestamp (Unix milliseconds)
End timestamp (Unix milliseconds)
const messages = await runtime.getMemories({
roomId: roomId,
count: 10,
tableName: "messages"
});
searchMemories
await runtime.searchMemories(params: {
tableName: string;
roomId: UUID;
embedding: number[];
match_threshold?: number;
match_count?: number;
unique?: boolean;
}): Promise<Memory[]>
Similarity threshold (0-1, default: 0.7)
Maximum results to return (default: 10)
const queryEmbedding = await runtime.embed("search query");
const similar = await runtime.searchMemories({
tableName: "documents",
roomId: roomId,
embedding: queryEmbedding,
match_threshold: 0.8,
match_count: 5
});
Example: Working with Memories
import {
AgentRuntime,
createMessageMemory,
getMemoryText
} from "@elizaos/core";
// Create a message memory
const memory = createMessageMemory({
entityId: userId,
roomId: roomId,
content: {
text: "What is TypeScript?",
source: "telegram"
}
});
// Store it
await runtime.createMemory(memory, "messages");
// Retrieve recent messages
const recentMessages = await runtime.getMemories({
roomId: roomId,
count: 10,
tableName: "messages"
});
// Extract text safely
for (const msg of recentMessages) {
const text = getMemoryText(msg);
console.log(text);
}
// Search by similarity
const queryEmbed = await runtime.embed("programming languages");
const relevantDocs = await runtime.searchMemories({
tableName: "documents",
roomId: roomId,
embedding: queryEmbed,
match_count: 3
});