Index

GLLM Memory Library.

A Python library for managing memory in AI applications using the Mem0 platform. Provides a simple interface for storing, searching, and managing conversational memory.

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, is_important=False) 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
is_important	bool	Force all added memories to retain important status. Defaults to False.	False

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.

get_retrieval_reranker_awaitable_runner()

Return one optional awaitable runner for retrieval reranker invoker calls.

Override this in clients that manage async resources on their own event loop or worker thread, such as SDK adapters with one persistent background loop.

Returns:

Type	Description
Callable[[Any], Any] | None	Callable[[Any], Any] | None: Runner that resolves awaitables on a provider-owned loop or thread, or None when the caller loop is safe.

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, include_important=False, rerank=False) 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
include_important	bool	If True, includes all important memories in addition to query matches. Results are deduplicated and sorted with important memories first. Defaults to False.	False
rerank	bool	If True, applies re-ranking to search results. Defaults to False.	False

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, is_important=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
is_important	bool | None	Flag indicating if the memory is important. If None, the existing is_important state remains unchanged. Defaults to None.	None

Returns:

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

BaseMemoryLMComponent(lm_invoker, fallback_lms=None)

Bases: LMComponent, ABC

Base LM component contract for memory runtimes.

Attributes:

Name	Type	Description
prompt_vars	set[str]	Prompt variables required by the default memory prompt.
default_system_template	str	Default system prompt template.
default_user_template	str	Default user prompt template.

build_request(*, messages, response_format=None, tools=None, tool_choice='auto', runtime_kwargs=None)

Build one normalized memory request from provider runtime inputs.

Parameters:

Name	Type	Description	Default
messages	list[dict[str, Any]]	Normalized memory messages.	required
response_format	dict[str, Any] | None	Optional structured-output hint. Defaults to None.	None
tools	list[dict[str, Any]] | None	Optional tool payload. Defaults to None.	None
tool_choice	str	Optional tool-choice hint. Defaults to "auto".	'auto'
runtime_kwargs	dict[str, Any] | None	Extra provider runtime arguments. Defaults to None.	None

Returns:

Name	Type	Description
MemoryLLMRequest	MemoryLLMRequest	Normalized request object.

execute(*, messages, response_format=None, tools=None, tool_choice='auto', **kwargs) async

Execute one memory request through the component's internal contract.

Parameters:

Name	Type	Description	Default
messages	list[dict[str, Any]]	Normalized memory messages.	required
response_format	dict[str, Any] | None	Optional structured-output hint. Defaults to None.	None
tools	list[dict[str, Any]] | None	Optional tool payload. Defaults to None.	None
tool_choice	str	Optional tool-choice hint. Defaults to "auto".	'auto'
**kwargs	Any	Extra provider runtime arguments.	{}

Returns:

Name	Type	Description
MemoryLLMResponse	MemoryLLMResponse	Provider-neutral memory response.

invoke_memory_lm(*, request, system_instruction, messages_text) async

Invoke the configured LM runtime for one normalized memory request.

This method depends on the inherited LMComponent._invoke_lm runtime contract. Before invoking it, the component validates that the inherited callable still accepts the required keyword arguments used by gllm_memory.

Parameters:

Name	Type	Description	Default
request	MemoryLLMRequest	Normalized memory request.	required
system_instruction	str	Prepared system instruction text.	required
messages_text	str	Prepared current-message text.	required

Returns:

Name	Type	Description
MemoryLLMResponse	MemoryLLMResponse	Wrapped native LM output.

Raises:

Type	Description
TypeError	If the inherited _invoke_lm contract is unavailable or no longer accepts the required keyword arguments.

run_memory(request) abstractmethod

Run one normalized memory request.

Parameters:

Name	Type	Description	Default
request	MemoryLLMRequest	Normalized memory request.	required

Returns:

Type	Description
MemoryLLMResponse | Awaitable[MemoryLLMResponse]	MemoryLLMResponse | Awaitable[MemoryLLMResponse]: Provider-neutral memory response.

Mem0Client(*, api_key, instruction=None, timeout_sec=30, host=None)

Bases: Mem0BaseClient

Mem0 Platform client implementation.

This class implements the BaseMemoryClient interface using the Mem0 platform API. It provides methods for adding, searching, updating, and deleting memories with proper scope handling and metadata management. Time-based filtering semantics are documented on Mem0BaseClient.

Attributes:

Name	Type	Description
api_key	str	API key for Mem0 authentication.
instruction	str	Custom instructions for memory handling.
timeout_sec	int	Timeout in seconds for API requests.
host	str | None	Host URL for self-hosted Mem0 instance.
app_id	str | None	Application ID from Mem0 project.

Initialize the Mem0 Platform client.

Parameters:

Name	Type	Description	Default
api_key	str	API key for Mem0 authentication.	required
instruction	str | None	Custom instructions for memory handling. Defaults to default_instruction_prompt if not provided.	None
timeout_sec	int	Timeout in seconds for API requests. Defaults to 30.	30
host	str | None	Host URL for self-hosted Mem0 instance. Defaults to None.	None

MemoryLLMRequest(messages, response_format=None, tools=None, tool_choice='auto', runtime_kwargs=dict()) dataclass

Normalized request passed from a memory provider bridge to one LM component.

Attributes:

Name	Type	Description
messages	list[dict[str, Any]]	Normalized memory messages.
response_format	dict[str, Any] | None	Optional structured-output hint. Defaults to None.
tools	list[dict[str, Any]] | None	Optional tool payload. Defaults to None.
tool_choice	str	Optional tool-choice hint. Defaults to "auto".
runtime_kwargs	dict[str, Any]	Extra provider runtime arguments. Defaults to an empty dict.

MemoryLLMResponse(output, metadata=dict()) dataclass

Provider-neutral LM response returned by one memory LM component.

Attributes:

Name	Type	Description
output	Any	Native LM output or already-normalized structured payload.
metadata	dict[str, Any]	Optional provider-agnostic metadata. Defaults to an empty dict.

MemoryLMComponent(lm_invoker, fallback_lms=None)

Bases: BaseMemoryLMComponent

Default memory LM component owned by gllm_memory.

This component applies the built-in message-to-prompt mapping used by the memory runtime before delegating execution to the inherited LMComponent invocation flow.

run_memory(request) async

Run one normalized memory request with the default prompt mapping.

Parameters:

Name	Type	Description	Default
request	MemoryLLMRequest	Normalized memory request.	required

Returns:

Name	Type	Description
MemoryLLMResponse	MemoryLLMResponse	Wrapped native LM output.

MemoryManager(*, api_key=None, instruction=None, host=None, config=None, use_knowledge_graph=None, _enable_semantic_dedupe_scheduler=True)

Main memory manager that orchestrates the memory system.

This class provides a platform-agnostic interface for memory operations, allowing users to work with the gllm_memory SDK without needing to know which memory platform is used internally.

Initialize the MemoryManager.

Parameters:

Name	Type	Description	Default
api_key	str | None	API key for authentication. Required for Mem0Client. Defaults to None.	None
instruction	str | None	Custom instructions for memory handling. Defaults to None.	None
host	str | None	Host for the memory client. Defaults to None.	None
config	dict[str, Any] | MemoryManagerConfig | None	Memory configuration payload or config object. If provided, resolves the configured backend path. Defaults to None.	None
use_knowledge_graph	bool | None	Deprecated compatibility shim for legacy callers. The value is ignored because knowledge graph activation is derived from config. Defaults to None.	None
_enable_semantic_dedupe_scheduler	bool	Internal flag used by the library to avoid recursive scheduler registration when building internal dedupe runners. Defaults to True.	True

Raises:

Type	Description
RuntimeError	If client initialization fails due to invalid API key or configuration.
ValueError	If knowledge graph is enabled but its default configuration is unavailable.

add(user_id, agent_id, messages=None, scopes=None, metadata=None, infer=True, is_important=False) 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
is_important	bool	Force all added memories to retain important status. Defaults to False.	False

Returns:

Type	Description
list[Chunk]	list[Chunk]: List of created memory chunks containing the stored memory data. Returns [] when the input is blocked by the memory-input guardrail, including when the guardrail itself raises unexpectedly during the request-time check (fails closed).

Raises:

Type	Description
Exception	If the operation fails due to client errors or invalid parameters.
RuntimeError	If explicit memory-input guardrail setup fails on the first write.

delete(memory_ids=None, user_id=None, agent_id=None, scopes=None, metadata=None) 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. If provided, only memories with these IDs will be deleted. Defaults to None.	None
user_id	str | None	User identifier for scope-based deletion. Used when deleting by user scope. Defaults to None.	None
agent_id	str | None	Agent identifier for scope-based deletion. Used when deleting by agent scope. Defaults to None.	None
scopes	set[MemoryScope] | None	Set of scopes for identifier-based deletion. Defines which memory scopes to target. Defaults to {MemoryScope.USER}.	None
metadata	dict[str, str] | None	Metadata filters to include with the deletion. Defaults to None.	None

Returns:

Type	Description
list[Chunk]	list[Chunk]: List of deleted memory chunks containing the removed memory data.

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

Delete memories based on a query.

Parameters:

Name	Type	Description	Default
query	str	Search query string to identify memories to delete. Required.	required
user_id	str | None	User identifier for the memory operation. Used to scope the deletion operation. Defaults to None.	None
agent_id	str | None	Agent identifier for the memory operation. Used to scope the deletion operation. Defaults to None.	None
scopes	set[MemoryScope] | None	Set of scopes for the operation. Defines which memory scopes to target. Defaults to {MemoryScope.USER}.	None
metadata	dict[str, str] | None	Metadata filters to include with the deletion. Defaults to None.	None
threshold	float | None	Minimum similarity threshold for matching memories. Defaults to 0.3 (provider-specific default).	0.3
top_k	int | None	Maximum number of memories to delete. Defaults to 10 (provider-specific default).	10

Returns:

Type	Description
list[Chunk]	list[Chunk]: List of deleted memory chunks containing the removed memory data.

Raises:

Type	Description
Exception	If the operation fails due to client errors or invalid parameters.

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

List all memories for a given user identifier with pagination.

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 filters to include with the memory. Defaults to None.	None
keywords	str | list[str] | None	Keywords to search for in memory content. Can be a single string or list of strings. 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 matching the specified criteria.

Raises:

Type	Description
Exception	If the operation fails due to client errors or invalid parameters.

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

Search memories using the memory provider.

Parameters:

Name	Type	Description	Default
query	str	Search query string. Required for memory retrieval.	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 filters 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
include_important	bool	If True, includes all important memories in addition to query matches. Results are deduplicated and sorted with important memories first. Defaults to False.	False
rerank	bool	If True, applies re-ranking to search results. Defaults to False.	False

Returns:

Type	Description
list[Chunk]	list[Chunk]: List of retrieved memory chunks matching the search criteria. If include_important=True, returns union of query matches and important memories.

Raises:

Type	Description
Exception	If the operation fails due to client errors or invalid parameters.

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

Update an existing memory by ID.

Parameters:

Name	Type	Description	Default
memory_id	str	Unique identifier of the memory to update. Required.	required
new_content	str | None	Updated content for the memory. If None or an empty string, 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
is_important	bool | None	Flag indicating if the memory is important. If None, the existing is_important state remains unchanged. Defaults to None.	None

Returns:

Name	Type	Description
Chunk	Chunk | None	The updated memory chunk containing the modified memory data.
None	Chunk | None	If the memory is not found or the input is blocked by the memory-input guardrail, including when the guardrail itself raises unexpectedly during the request-time check (fails closed).

Raises:

Type	Description
Exception	If the operation fails due to client errors or invalid parameters.
RuntimeError	If explicit memory-input guardrail setup fails on the first write.

MemoryManagerConfig(config, backend_key=MemoryProviderType.MEM0, backend_options=None)

Represent one immutable configuration payload for MemoryManager.

Attributes:

Name	Type	Description
_config	dict[str, Any]	Core memory-engine configuration payload.
_backend_key	str	Internal backend key selected for the config.
_backend_options	dict[str, Any]	Backend-specific auxiliary options.

Initializes a new instance of the MemoryManagerConfig class.

Parameters:

Name	Type	Description	Default
config	dict[str, Any]	Underlying memory-engine config payload.	required
backend_key	str	Internal backend key selected by the library. Defaults to MemoryProviderType.MEM0.	MEM0
backend_options	dict[str, Any] | None	Internal backend-specific options. Defaults to None.	None

builder() classmethod

Create a fluent builder for MemoryManagerConfig.

Returns:

Name	Type	Description
MemoryManagerConfigBuilder	MemoryManagerConfigBuilder	New builder instance.

get_backend_key()

Return the internal backend key selected for this config object.

Returns:

Name	Type	Description
str	str	Internal backend key.

get_backend_options()

Return a safe copy of the backend-specific options.

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Cloned backend-specific options.

to_dict()

Return a safe copy of the core config payload.

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: Cloned core config payload.

MemoryProviderType

Bases: StrEnum

Supported memory provider types.

Attributes:

Name	Type	Description
MEM0	str	Mem0 Platform provider.

Neo4jGraphStoreConfig(uri, user, password, max_connection_pool_size=DEFAULTS.knowledge_graph_neo4j_max_connection_pool_size) dataclass

Represent one caller-facing Neo4j graph-store config.

Attributes:

Name	Type	Description
uri	str	Neo4j connection URI.
user	str	Neo4j username.
password	str	Neo4j password.
max_connection_pool_size	int	Maximum Neo4j connection pool size.

to_config_dict()

Convert one config object into a plain Neo4j config payload.

Returns:

Type	Description
dict[str, str | int]	dict[str, str | int]: Plain Neo4j config payload.

build_memory_client(provider, **kwargs)

Create a memory client for the specified provider.

Parameters:

Name	Type	Description	Default
provider	str	The name of the memory provider.	required
**kwargs		Additional keyword arguments passed to the client constructor.	{}

Returns:

Name	Type	Description
BaseMemoryClient	BaseMemoryClient	The created memory client instance.

Raises:

Type	Description
ValueError	If the provider is not supported.