Memory System
Intelligent context retention across agent sessions. Build AI agents that truly remember past interactions, learn preferences, and provide personalized experiences.
Automatic Summarization
Sessions are intelligently summarized for future reference
Semantic Search
Find relevant memories using natural language queries
Context Preservation
Maintain continuity between agent sessions
Privacy-Focused
User-scoped data with end-to-end encryption
Vector Storage
Powered by pgvector for similarity matching
Smart Insights
AI-generated insights from usage patterns
Memory Types
Session Memories
Automatically generated summaries of agent activities within a session. These capture the essence of what happened, tools used, and outcomes achieved.
{
"id": "mem_abc123",
"session_id": "sess_xyz789",
"type": "session_summary",
"summary": "User analyzed weather data for travel planning",
"key_points": [
"Checked weather in NYC, London, Tokyo",
"Compared temperatures across cities",
"Focused on 7-day forecasts"
],
"tools_used": ["weather_current", "weather_forecast"],
"created_at": "2024-12-19T10:00:00Z"
}User Preferences
Persistent information about user preferences, patterns, and frequently used tools. Helps personalize the agent experience.
{
"preferred_tools": ["weather_current", "translate"],
"common_locations": ["New York", "London"],
"language": "en",
"timezone": "America/New_York",
"units": {
"temperature": "fahrenheit",
"distance": "imperial"
}
}Usage Patterns
Analytics on frequently used tools, common workflows, peak usage hours, and average session durations. Used for recommendations and insights.
Core Endpoints
Get All Memories
/memoryRetrieve all memories for the authenticated user.
{
"memories": [
{
"id": "mem_123456789",
"session_id": "sess_987654321",
"type": "session_summary",
"summary": "User worked on weather data analysis...",
"key_points": [
"Checked weather in NYC, London, Tokyo",
"Calculated average temperature: 72°F",
"Interested in climate patterns"
],
"created_at": "2024-12-19T10:00:00Z",
"relevance_score": 0.95
}
],
"total_count": 42
}Search Memories
/memory/searchPerform semantic search across all memories using natural language queries.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
qrequired | string | Natural language search query |
limit | integer | Number of results (default: 10, max: 50) |
threshold | number | Similarity threshold 0.0-1.0 (default: 0.7) |
GET /memory/search?q=weather%20analysis&limit=5&threshold=0.8{
"results": [
{
"id": "mem_123456789",
"summary": "User analyzed weather patterns across multiple cities",
"similarity_score": 0.89,
"session_id": "sess_987654321",
"created_at": "2024-12-19T10:00:00Z"
}
],
"query": "weather analysis",
"total_results": 5
}Get Session Timeline
/memory/sessions/{session_id}/timelineGet a detailed activity timeline for a specific session.
{
"session_id": "sess_987654321",
"timeline": {
"start_time": "2024-12-19T10:00:00Z",
"end_time": "2024-12-19T11:30:00Z",
"duration_minutes": 90,
"activities": [
{
"timestamp": "2024-12-19T10:05:00Z",
"tool": "weather_current",
"parameters": {"location": "New York"},
"result_summary": "Temperature: 75°F"
}
],
"summary": {
"total_activities": 15,
"tools_used": ["weather_current", "calculate"],
"key_insights": [
"Focused on weather analysis",
"Compared multiple locations"
]
}
}
}Memory Creation
Manual Summarization
Force summary creation for a specific session:
/memory/sessions/{session_id}/summarize{
"force": true
}{
"memory_id": "mem_123456789",
"summary": "User performed weather analysis and calculations",
"key_points": [
"Analyzed weather in 5 cities",
"Calculated temperature averages"
],
"created_at": "2024-12-19T10:00:00Z"
}Advanced Features
Paginated Memory Retrieval
/memory/paginatedQuery Parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Results per page (1-100) |
cursor | string | Pagination cursor from previous response |
sort | string | Sort order: newest, oldest, relevance |
date_from | string | Filter start date (ISO format) |
date_to | string | Filter end date (ISO format) |
{
"memories": [...],
"pagination": {
"cursor": "eyJpZCI6MTIzLCJ0cyI6MTcwMzAwMTYwMH0=",
"has_more": true,
"total": 150
}
}Get Agent Context
Retrieve historical context to bootstrap new sessions with relevant information.
/memory/context/agent{
"context": {
"user_preferences": {
"preferred_tools": ["weather_current", "translate"],
"common_locations": ["New York", "London"],
"usage_patterns": {
"peak_hours": [9, 14, 20],
"average_session_duration": 45
}
},
"recent_activities": [
{
"summary": "Weather analysis project",
"date": "2024-12-18",
"relevant_tools": ["weather_current"]
}
],
"insights": [
"User frequently checks weather for travel planning",
"Prefers metric units for temperature"
]
}
}Memory Statistics
/memory/stats{
"statistics": {
"total_memories": 42,
"total_sessions": 156,
"summarized_sessions": 42,
"average_session_activities": 8.5,
"storage_used_mb": 2.5,
"oldest_memory": "2024-01-15T10:00:00Z",
"most_recent_memory": "2024-12-19T10:00:00Z"
}
}Background Processing
The memory system includes a background processor that automatically summarizes sessions. You can monitor its status and trigger manual runs.
Check Status
/memory/background/status{
"status": "running",
"last_run": "2024-12-19T10:00:00Z",
"next_run": "2024-12-19T10:05:00Z",
"stats": {
"sessions_processed": 1250,
"memories_created": 890,
"average_processing_time": 1.2,
"queue_length": 5
}
}Trigger Processing
/memory/background/triggerManually trigger the background processor to run immediately.
SDK Examples
from aphelion import Aphelion
client = Aphelion(api_key="your-api-key")
class IntelligentAssistant:
def __init__(self, client):
self.client = client
self.context = None
def load_context(self):
"""Load historical context for personalization."""
self.context = self.client.memory.get_context()
return self.context
def search_memories(self, query, limit=5):
"""Search for relevant past interactions."""
return self.client.memory.search(
query=query,
limit=limit,
threshold=0.7
)
def process_with_context(self, user_input):
"""Process input with memory awareness."""
# Search for relevant memories
memories = self.search_memories(user_input)
# Build context-aware response
relevant_context = [
m.summary for m in memories.results
if m.similarity_score > 0.8
]
if relevant_context:
print(f"Found {len(relevant_context)} relevant memories")
# Use context to enhance response
return self.process(user_input)
# Usage
assistant = IntelligentAssistant(client)
assistant.load_context()
# Process with memory awareness
response = assistant.process_with_context(
"What was the weather like last week?"
)import { Aphelion } from 'aphelion';
const client = new Aphelion({ apiKey: process.env.APHELION_API_KEY });
async function createMemoryAwareSession() {
// Load user context
const context = await client.memory.getContext();
// Create session with context
const session = await client.sessions.create({
services: context.user_preferences.preferred_tools
});
// Search relevant memories
const memories = await client.memory.search({
query: "recent activities",
limit: 5
});
console.log(`Found ${memories.results.length} relevant memories`);
console.log(`User preferences: ${JSON.stringify(context.user_preferences)}`);
return session;
}
// Get memory statistics
async function getMemoryInsights() {
const stats = await client.memory.getStats();
console.log(`Total memories: ${stats.statistics.total_memories}`);
console.log(`Sessions tracked: ${stats.statistics.total_sessions}`);
console.log(`Storage used: ${stats.statistics.storage_used_mb} MB`);
}Privacy & Security
Data Protection
- All memories are user-scoped
- End-to-end encryption for sensitive data
- No sharing between users
- GDPR compliant
Memory Deletion
Users have full control over their memory data.
/memory/memory/{memory_id}Best Practices
Session Design
- • Group related activities in sessions
- • Use meaningful session metadata
- • End sessions properly for better summaries
- • Avoid extremely long sessions
Memory Search
- • Use natural language queries
- • Adjust threshold for precision/recall
- • Combine with date filters for better results
- • Cache frequently accessed memories
Context Usage
- • Load agent context at session start
- • Update preferences based on patterns
- • Respect user privacy preferences
- • Use insights for personalization
Performance
- • Use pagination for large datasets
- • Implement client-side caching
- • Set appropriate search limits
- • Use date filters to narrow scope