Memory client

Base client interface for memory providers.

This module defines the abstract interface that all memory clients must implement, following the Dependency Inversion Principle to make providers easily replaceable.

Authors

Budi Kurniawan (budi.kurniawan1@gdplabs.id)

BaseMemoryClient

Bases: ABC

Abstract interface for memory client implementations.

This interface defines the contract that all memory clients must follow, making it easy to swap implementations without changing the rest of the code.

add(user_id, agent_id, messages=None, scopes=None, metadata=None, infer=True) abstractmethod async

Add new memory items from a list of messages.

Parameters:

Name	Type	Description	Default
user_id	str	User identifier for the memory operation. Required.	required
agent_id	str	Agent identifier for the memory operation. Required.	required
messages	list[Message] | None	List of messages to store in memory. Each message contains role, contents, and metadata information. Defaults to None.	None
scopes	set[MemoryScope] | None	Set of scopes for the operation. Defaults to [MemoryScope.USER].	None
metadata	dict[str, str] | None	Metadata to include with the memory. Defaults to None.	None
infer	bool	Whether to infer relationships. Defaults to True.	True

Returns:

Type	Description
list[Chunk]	list[Chunk]: List of created memory chunks.

Raises:

Type	Description
Exception	If the operation fails.

delete(memory_ids=None, user_id=None, agent_id=None, scopes=None, metadata=None) abstractmethod async

Delete memories by IDs or by user identifier/scope.

Parameters:

Name	Type	Description	Default
memory_ids	list[str] | None	List of memory ID UUID strings for ID-based deletion. Defaults to None.	None
user_id	str | None	User identifier for scope-based deletion. Defaults to None.	None
agent_id	str | None	Agent identifier for scope-based deletion. Defaults to None.	None
scopes	set[MemoryScope] | None	Set of scopes for identifier-based deletion. Defaults to {MemoryScope.USER, MemoryScope.ASSISTANT}.	None
metadata	dict[str, str] | None	Metadata to include with the memory. Defaults to None.	None

Returns:

Type	Description
list[Chunk]	list[Chunk]: List of deleted memory chunks.

Raises:

Type	Description
ValueError	If neither memory_ids nor user_id/agent_id are provided.

delete_by_user_query(query, user_id=None, agent_id=None, scopes=None, metadata=None, threshold=0.3, top_k=10) abstractmethod async

Delete memories based on a query.

Parameters:

Name	Type	Description	Default
query	str	Search query string to identify memories to delete.	required
user_id	str | None	User identifier for the memory operation. Defaults to None.	None
agent_id	str | None	Agent identifier for the memory operation. Defaults to None.	None
scopes	set[MemoryScope] | None	Set of scopes for the operation. Defaults to {MemoryScope.USER, MemoryScope.ASSISTANT}.	None
metadata	dict[str, str] | None	Metadata to include with the memory. Defaults to None.	None
threshold	float | None	Minimum similarity threshold for matching. Defaults to 0.3.	0.3
top_k	int | None	Maximum number of memories to delete. Defaults to 10.	10

Returns:

Type	Description
list[Chunk]	list[Chunk]: List of deleted memory chunks.

Raises:

Type	Description
Exception	If the operation fails.

list_memories(user_id=None, agent_id=None, scopes=None, metadata=None, keywords=None, page=1, page_size=100) abstractmethod async

List all memories for a given user identifier.

Optionally filtering the results by specific keywords.

Parameters:

Name	Type	Description	Default
user_id	str | None	User identifier for the memory operation. Defaults to None.	None
agent_id	str | None	Agent identifier for the memory operation. Defaults to None.	None
scopes	set[MemoryScope] | None	Set of scopes for the operation. Defaults to {MemoryScope.USER}.	None
metadata	dict[str, str] | None	Metadata to include with the memory. Defaults to None.	None
keywords	str | list[str] | None	Keywords to search for in memory content. Defaults to None.	None
page	int	Page number for pagination. Defaults to 1.	1
page_size	int	Number of items per page. Defaults to 100.	100

Returns:

Type	Description
list[Chunk]	list[Chunk]: List of retrieved memory chunks.

Raises:

Type	Description
Exception	If the operation fails.

search(query, user_id=None, agent_id=None, scopes=None, metadata=None, threshold=0.3, top_k=10) abstractmethod async

Search memories using the memory provider.

Parameters:

Name	Type	Description	Default
query	str	Search query string.	required
user_id	str | None	User identifier for the memory operation. Defaults to None.	None
agent_id	str | None	Agent identifier for the memory operation. Defaults to None.	None
scopes	set[MemoryScope] | None	Set of scopes for the operation. Defaults to {MemoryScope.USER}.	None
metadata	dict[str, str] | None	Metadata to include with the memory. Defaults to None.	None
threshold	float | None	Minimum similarity threshold for results. Defaults to 0.3.	0.3
top_k	int | None	Maximum number of results to return. Defaults to 10.	10

Returns:

Type	Description
list[Chunk]	list[Chunk]: List of retrieved memory chunks.

Raises:

Type	Description
Exception	If the operation fails.

update(memory_id, new_content=None, metadata=None, user_id=None, agent_id=None, scopes=None) abstractmethod async

Update an existing memory by ID.

Parameters:

Name	Type	Description	Default
memory_id	str	Unique identifier of the memory to update.	required
new_content	str | None	Updated content for the memory. If None, the existing content remains unchanged. Defaults to None.	None
metadata	dict[str, str] | None	Updated metadata to merge or replace. Defaults to None.	None
user_id	str | None	User identifier for access control validation. Defaults to None.	None
agent_id	str | None	Agent identifier for access control validation. Defaults to None.	None
scopes	set[MemoryScope] | None	Set of scopes for the update operation. Defaults to {MemoryScope.USER, MemoryScope.ASSISTANT}.	None

Returns:

Type	Description
Chunk | None	Chunk | None: The updated memory chunk, or None if memory not found or operation fails.