MemoryStore
Defined in: src/memory/types.ts:83
Interface for a memory store backend.
Extends MemoryStoreConfig with the runtime methods a store provides. Every store is
searchable; the resolved writable flag declares whether it also accepts writes, which is how
the MemoryManager decides where to route them. search_memory can query all stores, while
add_memory can only write to writable stores.
Extends
Section titled “Extends”Properties
Section titled “Properties”readonly name: string;Defined in: src/memory/types.ts:52
Identifier for this store, used to target specific stores in search/add tools. Must be unique.
Inherited from
Section titled “Inherited from”description?
Section titled “description?”readonly optional description?: string;Defined in: src/memory/types.ts:54
Human-readable description of what this store contains. Included in tool descriptions.
Inherited from
Section titled “Inherited from”maxSearchResults?
Section titled “maxSearchResults?”readonly optional maxSearchResults?: number;Defined in: src/memory/types.ts:59
Default maximum number of results this store returns per search, used when a caller does not
pass a per-call maxSearchResults.
Inherited from
Section titled “Inherited from”MemoryStoreConfig.maxSearchResults
extraction?
Section titled “extraction?”readonly optional extraction?: ExtractionConfig;Defined in: src/memory/types.ts:72
Automatic-extraction configuration for this store. When set, the MemoryManager runs the configured triggers and writes extracted (or, with no extractor, raw) messages to this store. Requires the store to be writable. Omit for a purely tool-driven store.
Inherited from
Section titled “Inherited from”writable
Section titled “writable”readonly writable: boolean;Defined in: src/memory/types.ts:90
Whether this store accepts writes.
false: searchable only; never written to.true: searchable and writable. Requires at least one write sink —add,addMessages, or both — to be implemented.
Overrides
Section titled “Overrides”Methods
Section titled “Methods”search()
Section titled “search()”search(query, options?): Promise<MemoryEntry[]>;Defined in: src/memory/types.ts:92
Search the store for entries matching the query, ordered by relevance.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
query | string |
options? | SearchOptions |
Returns
Section titled “Returns”Promise<MemoryEntry[]>
add()?
Section titled “add()?”optional add(content, metadata?): Promise<unknown>;Defined in: src/memory/types.ts:109
Add a single piece of content to the store. Used by the add_memory tool, the programmatic
MemoryManager.add, and by extraction when an ExtractionConfig.extractor produces
discrete entries (an extraction config with an extractor requires this method).
A store satisfies writable: true with add, addMessages, or both. A store may also
implement add while declaring writable: false, in which case it is never invoked.
Extraction writes are at-least-once: if one entry in a batch fails, the whole batch is retried, so
add may be called again with content it already stored. Implementations used with extraction
should tolerate duplicate writes (e.g. dedupe, or accept that retries may re-store an entry).
The resolved value is store-specific (e.g. a created record id or a write receipt) — each backend may return whatever shape fits it. The MemoryManager does not consume this value (it only awaits completion); callers using a store directly can read it.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
content | string |
metadata? | Record<string, JSONValue> |
Returns
Section titled “Returns”Promise<unknown>
addMessages()?
Section titled “addMessages()?”optional addMessages(messages, context?): Promise<unknown>;Defined in: src/memory/types.ts:129
Ingest a batch of conversation messages, preserving their role structure. This is the sink for automatic extraction that does not distill facts client-side: the manager hands the filtered MessageData batch straight here in one call — no serialization, no model call. Backends that turn raw turns into memory themselves (e.g. role-aware conversational APIs that summarize server-side) implement this so the user/assistant structure survives. A store using extraction implements this method, unless it configures an ExtractionConfig.extractor (which produces discrete entries written via add instead).
Satisfies writable: true the same way add does. The resolved value is store-specific
and not consumed by the manager.
A store scopes its writes (e.g. by tenant or namespace) through its own configuration. The AddMessagesContext parameter lets the manager pass additional per-batch context to the store.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
messages | MessageData[] | The filtered messages to ingest, in order |
context? | AddMessagesContext | Manager-supplied per-batch context (see AddMessagesContext) |
Returns
Section titled “Returns”Promise<unknown>
getTools()?
Section titled “getTools()?”optional getTools(): Tool[];Defined in: src/memory/types.ts:138
Returns store-specific tools to register with the agent, through a MemoryManager. Registers
tools alongside search_memory / add_memory tools if enabled on the MemoryManager.
Implement to expose backend-specific capabilities (e.g. a store-native query tool).
Optional, mirrors Plugin.getTools.
Returns
Section titled “Returns”Tool[]
Array of tools provided by this store