API Reference
Memory
- class durag.memory.main.Memory(config: MemoryConfig = MemoryConfig(vector_store=VectorStoreConfig(provider='qdrant', config=QdrantConfig(collection_name='durag', embedding_model_dims=1536, client=None, host=None, port=None, path='/tmp/qdrant', url=None, api_key=None, on_disk=False)), llm=LlmConfig(provider='openai', config={}), embedder=EmbedderConfig(provider='openai', config={}), history_db_path='/home/docs/.durag/history.db', reranker=None, version='v1.1', custom_instructions=None))[source]
Bases:
MemoryBase- add(messages, *, user_id: str | None = None, agent_id: str | None = None, run_id: str | None = None, metadata: Dict[str, Any] | None = None, infer: bool = True, memory_type: str | None = None, prompt: str | None = None)[source]
Create a new memory.
Adds new memories scoped to a single session id (e.g. user_id, agent_id, or run_id). One of those ids is required.
- Parameters:
messages (str or List[Dict[str, str]]) – The message content or list of messages (e.g., [{“role”: “user”, “content”: “Hello”}, {“role”: “assistant”, “content”: “Hi”}]) to be processed and stored.
user_id (str, optional) – ID of the user creating the memory. Defaults to None.
agent_id (str, optional) – ID of the agent creating the memory. Defaults to None.
run_id (str, optional) – ID of the run creating the memory. Defaults to None.
metadata (dict, optional) – Metadata to store with the memory. Defaults to None.
infer (bool, optional) – If True (default), an LLM is used to extract key facts from ‘messages’ and decide whether to add, update, or delete related memories. If False, ‘messages’ are added as raw memories directly.
memory_type (str, optional) – Specifies the type of memory. Currently, only MemoryType.PROCEDURAL.value (“procedural_memory”) is explicitly handled for creating procedural memories (typically requires ‘agent_id’). Otherwise, memories are treated as general conversational/factual memories.
prompt (str, optional) – Prompt to use for the memory creation. Defaults to None.
- Returns:
- A dictionary containing the result of the memory addition operation, typically
including a list of memory items affected (added, updated) under a “results” key. Example for v1.1+: {“results”: [{“id”: “…”, “memory”: “…”, “event”: “ADD”}]}
- Return type:
- Raises:
DuragValidationError – If input validation fails (invalid memory_type, messages format, etc.).
VectorStoreError – If vector store operations fail.
EmbeddingError – If embedding generation fails.
LLMError – If LLM operations fail.
DatabaseError – If database operations fail.
- delete(memory_id)[source]
Delete a memory by ID.
- Parameters:
memory_id (str) – ID of the memory to delete.
- delete_all(user_id: str | None = None, agent_id: str | None = None, run_id: str | None = None)[source]
Delete all memories.
- property entity_store
Lazily initialize entity store on first use.
- get_all(*, filters: Dict[str, Any] | None = None, top_k: int = 20, **kwargs)[source]
List all memories.
- Parameters:
- Returns:
- A dictionary containing a list of memories under the “results” key.
Example for v1.1+: {“results”: [{“id”: “…”, “memory”: “…”, …}]}
- Return type:
- Raises:
ValueError – If filters doesn’t contain at least one of user_id, agent_id, run_id, or if top_k is invalid.
- reset()[source]
- Reset the memory store by:
Deletes the vector store collection Resets the database Recreates the vector store with a new client
- search(query: str, *, top_k: int = 20, filters: Dict[str, Any] | None = None, threshold: float = 0.1, rerank: bool = False, **kwargs)[source]
Searches for memories based on a query.
- Parameters:
query (str) – Query to search for.
top_k (int, optional) – Maximum number of results to return. Defaults to 20.
filters (dict) –
Filter dict containing entity IDs and optional metadata filters. Must contain at least one of: user_id, agent_id, run_id. Example: filters={“user_id”: “u1”, “agent_id”: “a1”}
Enhanced metadata filtering with operators: - {“key”: “value”} - exact match - {“key”: {“eq”: “value”}} - equals - {“key”: {“ne”: “value”}} - not equals - {“key”: {“in”: [“val1”, “val2”]}} - in list - {“key”: {“nin”: [“val1”, “val2”]}} - not in list - {“key”: {“gt”: 10}} - greater than - {“key”: {“gte”: 10}} - greater than or equal - {“key”: {“lt”: 10}} - less than - {“key”: {“lte”: 10}} - less than or equal - {“key”: {“contains”: “text”}} - contains text - {“key”: {“icontains”: “text”}} - case-insensitive contains - {“key”: “*”} - wildcard match (any value) - {“AND”: [filter1, filter2]} - logical AND - {“OR”: [filter1, filter2]} - logical OR - {“NOT”: [filter1]} - logical NOT
threshold (float, optional) – Minimum score for a memory to be included. Defaults to 0.1.
rerank (bool, optional) – Whether to rerank results. Defaults to False.
- Returns:
- A dictionary containing the search results under a “results” key.
Example for v1.1+: {“results”: [{“id”: “…”, “memory”: “…”, “score”: 0.8, …}]}
- Return type:
- Raises:
ValueError – If filters doesn’t contain at least one of user_id, agent_id, run_id, or if threshold/top_k values are invalid.
- update(memory_id, data, metadata: Dict[str, Any] | None = None)[source]
Update a memory by ID.
- Parameters:
- Returns:
Success message indicating the memory was updated.
- Return type:
Example
>>> m.update(memory_id="mem_123", data="Likes to play tennis on weekends") {'message': 'Memory updated successfully!'}
MemoryConfig
- class durag.configs.base.MemoryConfig(*, vector_store: VectorStoreConfig = <factory>, llm: LlmConfig = <factory>, embedder: EmbedderConfig = <factory>, history_db_path: str = '/home/docs/.durag/history.db', reranker: RerankerConfig | None = None, version: str = 'v1.1', custom_instructions: str | None = None)[source]
Bases:
BaseModel- embedder: EmbedderConfig
- llm: LlmConfig
- model_config = {}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- vector_store: VectorStoreConfig