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

GET/memory

Retrieve all memories for the authenticated user.

Response
{
  "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

GET/memory/search

Perform semantic search across all memories using natural language queries.

Query Parameters

ParameterTypeDescription
qrequiredstringNatural language search query
limitintegerNumber of results (default: 10, max: 50)
thresholdnumberSimilarity threshold 0.0-1.0 (default: 0.7)
Request
GET /memory/search?q=weather%20analysis&limit=5&threshold=0.8
Response
{
  "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

GET/memory/sessions/{session_id}/timeline

Get a detailed activity timeline for a specific session.

Response
{
  "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

ℹ️Automatic Summarization
Sessions with 3 or more activities are automatically summarized by the background processor. No action required on your part.

Manual Summarization

Force summary creation for a specific session:

POST/memory/sessions/{session_id}/summarize
Request Body
{
  "force": true
}
Response
{
  "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

GET/memory/paginated

Query Parameters

ParameterTypeDescription
limitintegerResults per page (1-100)
cursorstringPagination cursor from previous response
sortstringSort order: newest, oldest, relevance
date_fromstringFilter start date (ISO format)
date_tostringFilter end date (ISO format)
Response
{
  "memories": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTIzLCJ0cyI6MTcwMzAwMTYwMH0=",
    "has_more": true,
    "total": 150
  }
}

Get Agent Context

Retrieve historical context to bootstrap new sessions with relevant information.

GET/memory/context/agent
Response
{
  "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

GET/memory/stats
Response
{
  "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

GET/memory/background/status
Response
{
  "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

POST/memory/background/trigger

Manually trigger the background processor to run immediately.

SDK Examples

Python - Intelligent Assistant with Memory
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?"
)
TypeScript - Memory-Aware Agent
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.

Delete all memories:
DELETE/memory
Delete specific memory:
DELETE/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

Next Steps