PowerMem Documentation

The PowerMem Benchmark suite provides tools for evaluating PowerMem's performance. It consists of two primary components:

1. Benchmark Server: A REST API server built with FastAPI that exposes memory operations via an API for testing purposes. Located in the server/ directory.
2. LOCOMO Load Testing: A comprehensive benchmarking and load testing tool that utilizes the LOCOMO dataset to evaluate performance and metrics. Located in the locomo/ directory.

PowerMem is a persistent, self-evolving memory layer designed for AI applications and agents. It combines vector, full-text, and graph search with LLM-driven memory extraction and Ebbinghaus-style temporal decay.

Key features include:

• Two-layer distillation of Experience + Skill: A self-evolving memory mechanism.
• Multi-agent isolation: Support for separating memory across different agents.
• User profiles: Built-in support for managing user-specific context.
• Multimodal support: Standard handling of text, image, and audio signals.
• Hybrid Search: A 4-path hybrid search mechanism.

PowerMem provides several specialized API surfaces depending on your integration needs:

• Memory API: For performing synchronous memory operations.
• AsyncMemory API: For performing asynchronous memory operations.
• Agent APIs: For managing memory across multi-agent systems.
• MCP API: For integrating PowerMem as a Model Context Protocol (MCP) server for AI assistants.
• HTTP API Server: For interacting with PowerMem via a RESTful HTTP interface.

Multi-agent memory allows for the creation of isolated memory spaces for different AI agents while supporting collaboration. This architecture is useful for:

• Customer support systems: Separating support, sales, and technical agents.
• Development teams: Managing multiple agents working on the same project.
• Enterprise applications: Isolating different departments with interconnected memories.
• Complex workflows: Maintaining individual agent context while accessing shared information.

Core Concepts

• Memory Isolation: Each agent has a private memory space to prevent interference.
• Cross-Agent Collaboration: Agents can search across all memories to share information.
• Agent Identification: Memories are tagged with an agent_id to track ownership.
• Flexible Search: Ability to search within a single agent's memory or across all agents.

UserMemory is an advanced user profile management module that builds upon the base Memory module. It provides four core capabilities:

1. Conversation storage: Stores user conversations as event memories.
2. Profile extraction: Uses an LLM to automatically extract user-related information (e.g., basic info, interests, work background) from conversations.
3. Profile management: Provides mechanisms to save, update, and query user profiles.
4. Joint search: Allows for searching memories while optionally including profile information in the results.

It works by managing two internal components: a Memory instance for conversation events and a UserProfileStore for user profiles.

When working with memory decay and retention in PowerMem, keep these core principles in mind:

1. Time-based decay: Memories naturally decay over time following the Ebbinghaus curve.
2. Retention scoring: Calculate retention scores based on the time elapsed since the memory was created or last accessed.
3. Weighted search: For improved retrieval, combine semantic similarity scores with retention scores.
4. Spaced repetition: Use the forgetting curve to schedule optimal review times to maximize long-term retention.
5. Practical applications: These patterns are useful for building learning systems, recommendation engines, and memory optimization tools.

PowerMem supports two primary storage backends:

1. SQLite (Default): Zero external dependencies, works out of the box for coding agent scenarios. Requires powermem[server,extras] which includes sentence-transformers for local embedding.
2. OceanBase/seekdb: Recommended for production and cluster deployments. Requires setting the environment variable POWERMEM_INIT_DATABASE_PROVIDER=oceanbase before running the initialization command. Requires powermem[server,seekdb] which includes pyseekdb.

Memory isolation ensures that different AI agents maintain separate, private memory spaces to prevent interference.

Core Mechanics

• Automatic Tagging: When you instantiate a Memory object with an agent_id, all memories added through that instance are automatically tagged with that ID.
• Default Search Scope: By default, searches performed via a specific Memory instance are automatically filtered to only return memories belonging to that agent_id.
• Privacy: This architecture prevents agents from accidentally accessing or being influenced by the memories of other agents.
• Cross-Agent Access: While isolated by default, you can still perform cross-agent searches by explicitly providing different agent_id values in your search parameters when required for collaboration.

The LOCOMO benchmark evaluates memory techniques using five key metrics:

1. BLEU Score: Measures similarity between the model's response and the ground truth.
2. F1 Score: Measures the harmonic mean of precision and recall.
3. LLM Score: A binary score (0 or 1) where an LLM judge evaluates response correctness.
4. Token Consumption: The total number of tokens used to generate the final answer.
5. Latency: The time taken for both the search process and response generation.

Multimodal capability allows PowerMem to process non-text inputs by automatically converting them into text descriptions. These descriptions are then stored as searchable memories.

Supported Media Types:

• Images: Extracts information and generates text descriptions.
• Image URLs: Processes online image links.
• Audio: Converts speech to text.
• Audio URLs: Processes online audio links.
• Mixed Content: Handles composite messages containing text, images, and audio simultaneously.