Memory Manager
Memory Manager for the GLLM Memory Library.
Provides a high-level interface for managing memory operations. Users work with the gllm_memory SDK without needing to know which memory platform is used internally.
MemoryManager(*, api_key=None, instruction=None, host=None, config=None, use_knowledge_graph=None, _enable_memory_maintenance_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 |
None
|
_enable_memory_maintenance_scheduler
|
bool
|
Internal flag used to avoid recursive scheduler registration when building maintenance 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. |
aclose()
async
Release background resources owned by this memory manager.
Awaiting this method cancels and joins pending retrieval bookkeeping so its provider client is not retained after the manager is no longer used.
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 |
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. |