Memory is the core synchronous memory management class in powermem. It provides a simple interface for storing, retrieving, and managing memories in LLM applications.
from powermem import Memory
memory = Memory(config=config)Create a new Memory instance.
Parameters:
config(dict, optional): Configuration dictionary. If None, loads from environment variables.storage_type(str, optional): Storage backend type (deprecated, use config).llm_provider(str, optional): LLM provider name (deprecated, use config).embedding_provider(str, optional): Embedding provider name (deprecated, use config).agent_id(str, optional): Agent identifier for multi-agent scenarios.
Example:
from powermem import Memory, auto_config
# Auto-load from .env
config = auto_config()
memory = Memory(config=config, agent_id="my_agent")add(messages, user_id=None, agent_id=None, run_id=None, metadata=None, filters=None, scope=None, memory_type=None, prompt=None, infer=True)
Add a memory to the store.
Parameters:
messages(str | dict | list[dict]): Memory content. Can be:- A string (will be converted to a message)
- A single message dict with
roleandcontent - A list of message dicts in OpenAI format
user_id(str, optional): User identifier.agent_id(str, optional): Agent identifier.run_id(str, optional): Run/conversation identifier.metadata(dict, optional): Additional metadata.filters(dict, optional): Filter metadata for sub-store routing and advanced filtering. Used for routing memories to specific sub-stores based on metadata values. See Filter Parameter Format below for format details.scope(str, optional): Memory scope (e.g., 'user', 'agent', 'session').memory_type(str, optional): Memory type classification.prompt(str, optional): Custom prompt for intelligent processing.infer(bool): Enable intelligent memory processing (default: True).
Returns:
dict: Result containing added memory information.
Example:
# Simple text memory
result = memory.add(
messages="User likes Python programming",
user_id="user123"
)
# With intelligent processing (default)
result = memory.add(
messages=[
{"role": "user", "content": "I'm Alice, a software engineer"},
{"role": "assistant", "content": "Nice to meet you!"}
],
user_id="user123"
# infer=True by default - enables intelligent fact extraction
)
# Single message dict
result = memory.add(
messages={"role": "user", "content": "I prefer dark mode"},
user_id="user123"
)Search for memories using semantic similarity.
Parameters:
query(str): Search query string.user_id(str, optional): Filter by user ID.agent_id(str, optional): Filter by agent ID.run_id(str, optional): Filter by run ID.filters(dict, optional): Metadata filters for advanced filtering. See Filter Parameter Format below for detailed documentation.limit(int): Maximum number of results (default: 30).threshold(float, optional): Similarity threshold (0.0-1.0) for filtering results.
Returns:
dict: Search results with memories and scores. Format:{ "results": [ { "memory": "memory content", "metadata": {...}, "score": 0.85, "id": 123, ... } ], "relations": [...] # If graph store is enabled }
Example:
results = memory.search(
query="user preferences",
user_id="user123",
limit=5,
threshold=0.7 # Only return results with similarity >= 0.7
)
for result in results.get('results', []):
print(f"Memory: {result['memory']}")
print(f"Score: {result.get('score', 0)}")The filters parameter allows you to perform advanced filtering on memory metadata. It supports both simple and complex filter formats with various operators.
Exact Match:
# Filter by exact value
filters = {"category": "food"}
filters = {"priority": "high"}
filters = {"status": "active"}List Values (IN operator):
# Filter where field value is in a list
filters = {"category": ["food", "drink", "dessert"]}
filters = {"tag": ["important", "urgent"]}None/Null Check:
# Filter where field is None
filters = {"deleted_at": None}Use comparison operators for numeric or date comparisons:
# Single comparison operator
filters = {"rating": {"gte": 4.0}} # rating >= 4.0
filters = {"price": {"lt": 100}} # price < 100
filters = {"age": {"gt": 18}} # age > 18
filters = {"score": {"lte": 0.8}} # score <= 0.8
# Multiple operators on same field (AND logic)
filters = {"rating": {"gte": 4.0, "lte": 5.0}} # 4.0 <= rating <= 5.0
filters = {"price": {"gt": 10, "lt": 100}} # 10 < price < 100Supported Comparison Operators:
eq: Equal to (==)ne: Not equal to (!=)gt: Greater than (>)gte: Greater than or equal to (>=)lt: Less than (<)lte: Less than or equal to (<=)
IN and NOT IN:
# Field value is in list
filters = {"category": {"in": ["food", "drink"]}}
filters = {"user_id": {"in": ["user1", "user2", "user3"]}}
# Field value is NOT in list
filters = {"status": {"nin": ["deleted", "archived"]}}
filters = {"tag": {"nin": ["deprecated"]}}LIKE and ILIKE:
# Case-sensitive pattern matching (LIKE)
filters = {"name": {"like": "%python%"}} # Contains "python"
filters = {"email": {"like": "%@example.com"}} # Ends with "@example.com"
# Case-insensitive pattern matching (ILIKE)
filters = {"title": {"ilike": "%tutorial%"}} # Contains "tutorial" (case-insensitive)
filters = {"description": {"ilike": "how to%"}} # Starts with "how to" (case-insensitive)Note: Use % as wildcard for pattern matching.
Combine multiple conditions using logical operators:
AND Logic:
# All conditions must be true
filters = {
"AND": [
{"user_id": "alice"},
{"category": "food"},
{"rating": {"gte": 4.0}}
]
}OR Logic:
# At least one condition must be true
filters = {
"OR": [
{"rating": {"gte": 4.0}},
{"priority": "high"}
]
}Nested Logic:
# Complex nested conditions
filters = {
"AND": [
{"user_id": "alice"},
{
"OR": [
{"rating": {"gte": 4.0}},
{"priority": "high"}
]
},
{"category": {"in": ["food", "drink"]}}
]
}You can filter on the following fields:
Standard Fields:
user_id(str): User identifieragent_id(str): Agent identifierrun_id(str): Run/conversation identifieractor_id(str): Actor identifierhash(str): Memory hashcreated_at(str/datetime): Creation timestampupdated_at(str/datetime): Last update timestampcategory(str): Memory category
Custom Metadata Fields:
Any fields stored in the metadata dictionary when adding memories are also filterable:
# When adding memory with custom metadata
memory.add(
messages="User likes Python",
user_id="user123",
metadata={
"tags": ["programming", "python"],
"priority": "high",
"rating": 5.0,
"department": "engineering"
}
)
# Filter by custom metadata fields
filters = {"tags": {"in": ["programming"]}}
filters = {"priority": "high"}
filters = {"rating": {"gte": 4.0}}
filters = {"department": "engineering"}Example 1: Filter by User ID and Category
results = memory.search(
query="favorite foods",
filters={"category": "food"}
)Example 2: Filter by Rating Range
results = memory.search(
query="restaurant recommendations",
filters={"rating": {"gte": 4.0, "lte": 5.0}}
)Example 3: Filter by Tags (IN operator)
results = memory.search(
query="programming tips",
filters={"tags": {"in": ["python", "tutorial"]}}
)Example 4: Filter by Time Range
from datetime import datetime, timedelta
# Memories created in the last 7 days
week_ago = (datetime.now() - timedelta(days=7)).isoformat()
filters = {"created_at": {"gte": week_ago}}
results = memory.search(
query="recent conversations",
filters=filters
)Example 5: Complex Filter with AND/OR
results = memory.search(
query="important tasks",
filters={
"AND": [
{"priority": "high"},
{
"OR": [
{"status": "pending"},
{"status": "in_progress"}
]
},
{"category": {"in": ["work", "personal"]}}
]
}
)Example 6: Filter by Custom Metadata
# Search for memories with specific custom tags
results = memory.search(
query="project updates",
filters={
"AND": [
{"project_id": "project-123"},
{"department": "engineering"},
{"status": {"ne": "archived"}}
]
}
)Example 7: Pattern Matching
# Find memories with email addresses from specific domain
results = memory.search(
query="contact information",
filters={"email": {"ilike": "%@company.com"}}
)-
Filter Precedence: When both
user_id/agent_id/run_idparameters andfiltersare provided, they are merged. The explicit parameters take precedence if there's a conflict. -
Storage Backend Support:
- OceanBase: Supports all operators and complex logic (AND/OR)
- SQLite: Supports simple equality filters only
- PostgreSQL: Supports simple equality filters
-
Performance: Filters are applied at the database level for optimal performance. Use filters to narrow down results before semantic search.
-
Metadata Fields: Custom metadata fields are stored in JSON format and can be filtered using the same syntax as standard fields.
Retrieve a specific memory by ID.
Parameters:
memory_id(int): Memory identifier.user_id(str, optional): User identifier for permission check.agent_id(str, optional): Agent identifier for permission check.
Returns:
dict | None: Memory data or None if not found.
Example:
memory_data = memory.get(123, user_id="user123")
if memory_data:
print(f"Content: {memory_data.get('memory', '')}")Update an existing memory.
Parameters:
memory_id(int): Memory identifier.content(str, optional): New memory content.user_id(str, optional): User identifier for permission check.agent_id(str, optional): Agent identifier for permission check.metadata(dict, optional): Updated metadata.
Returns:
dict: Updated memory data.
Example:
updated = memory.update(
memory_id=123,
content="User prefers Python over Java",
user_id="user123",
metadata={"updated_at": "2024-01-01"}
)Delete a memory by ID.
Parameters:
memory_id(int): Memory identifier.user_id(str, optional): User identifier for permission check.agent_id(str, optional): Agent identifier for permission check.
Returns:
bool: True if deleted, False otherwise.
Example:
success = memory.delete(123, user_id="user123")Delete all memories matching criteria.
Parameters:
user_id(str, optional): Filter by user ID.agent_id(str, optional): Filter by agent ID.run_id(str, optional): Filter by run ID.
Returns:
dict: Deletion result with count.
Example:
result = memory.delete_all(user_id="user123")
print(f"Deleted {result.get('count', 0)} memories")Retrieve all memories matching criteria.
Parameters:
user_id(str, optional): Filter by user ID.agent_id(str, optional): Filter by agent ID.run_id(str, optional): Filter by run ID.limit(int): Maximum number of results (default: 100).offset(int): Offset for pagination (default: 0).filters(dict, optional): Metadata filters for advanced filtering. See Filter Parameter Format above for detailed documentation.
Returns:
dict: All matching memories. Format:{ "results": [ { "id": 123, "memory": "content", "metadata": {...}, ... } ], "relations": [...] # If graph store is enabled }
Example:
# Simple retrieval
all_memories = memory.get_all(user_id="user123", limit=50, offset=0)
for mem in all_memories.get('results', []):
print(f"- {mem.get('memory', '')}")
# With advanced filters
all_memories = memory.get_all(
user_id="user123",
filters={
"category": "food",
"rating": {"gte": 4.0}
},
limit=50,
offset=0
)When infer=True (default), Memory automatically:
- Fact Extraction: Extracts facts from conversations
- Duplicate Detection: Prevents duplicate memories
- Memory Updates: Updates existing memories when information changes
- Conflict Resolution: Handles contradictory information
- Memory Consolidation: Merges related memories
Note: Intelligent processing is enabled by default. Set infer=False to disable it for simple storage operations.
See Getting Started Guide for more details on intelligent memory features.
All methods may raise exceptions. Common errors:
ValueError: Invalid parametersConnectionError: Storage backend connection issuesRuntimeError: LLM or embedding service errors
Example:
try:
result = memory.add(memory="Test", user_id="user123")
except Exception as e:
print(f"Error: {e}")