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, instruction=None, host=None)
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.
Attributes:
| Name | Type | Description |
|---|---|---|
_client |
BaseMemoryClient
|
The underlying memory client instance. |
Initialize the MemoryManager.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
api_key
|
str
|
API key for authentication. Required for client initialization. |
required |
instruction
|
str | None
|
Custom instructions for memory handling. Defaults to None. |
None
|
host
|
str | None
|
Host for the memory client. Defaults to None. |
None
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If client initialization fails due to invalid API key or configuration. |
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. |
Raises:
| Type | Description |
|---|---|
Exception
|
If the operation fails due to client errors or invalid parameters. |
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, 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
|
The updated memory chunk containing the modified memory data. |
None |
Chunk
|
If the memory is not found or the operation fails. |
Raises:
| Type | Description |
|---|---|
Exception
|
If the operation fails due to client errors or invalid parameters. |