Documentation
Learn how to use MetaMemory
Everything you need to give your AI agents persistent, intelligent memory.
Getting Started
Installation
Set up MetaMemory in your project with npm, pnpm, or yarn. Install dependencies, generate the Prisma client for PostgreSQL storage, configure your Pinecone vector database, and run initial migrations. Optional Redis (caching) and Neo4j (graph retrieval) setup included.
Quick Start
Store your first memory and run an adaptive search in under 5 minutes. Create memory entries with automatic multi-vector encoding across semantic, emotional, process, and context dimensions. Perform searches and observe how Thompson Sampling adapts retrieval strategies to your query patterns.
Configuration
Configure the full backend stack: PostgreSQL via Prisma ORM for structured storage, Pinecone for 1536-dimensional semantic embeddings, Redis for pattern-based cache invalidation, and Neo4j for entity relationship graphs. Tune similarity thresholds (default 0.55), recency decay rates, and channel weights.
Core Concepts
Memory Engine
The central orchestration layer that manages the full memory lifecycle: CRUD operations, automatic multi-vector embedding generation, emotional tagging, graph relationship creation, and episode tracking. Memories are indexed across four specialized vector spaces and retrieved through five parallel channels fused via weighted Reciprocal Rank Fusion.
Multi-Vector Encoding
Each memory is encoded into four specialized embedding spaces: semantic (1536d via OpenAI), emotional trajectory (132d capturing temporal emotion dynamics), process sequence (132d with positional encoding for action steps), and situational context (64d encoding task type, domain, complexity). Fusion weights α are learned per-context via gradient descent on retrieval feedback.
Adaptive Retrieval
A 7-layer self-improving system that continuously refines retrieval quality. Layer 1–2: Thompson Sampling and UCB for strategy selection. Layer 3–4: gradient boosting (50 stumps, η=0.1) for effectiveness prediction after 100+ samples. Layer 5–6: Bayesian parameter optimization and LLM-discovered meta-memory rules. Layer 7: online drift detection with automatic rollback.
Emotional Intelligence
Emotions are modeled as continuous trajectories rather than static labels, capturing the evolution of affect within an episode (e.g., frustration → insight → satisfaction). Each trajectory is encoded into a 132-dimensional embedding with volatility, trend, and range features. The emotional retrieval channel computes trajectory-level similarity, grounded in cognitive science research on affective memory.
Guides
LangChain Integration
Drop-in memory adapter for LangChain agents. Replace default LangChain memory with MetaMemory using the custom BaseMemory adapter, giving your chains persistent multi-vector memory with five-channel retrieval and adaptive strategy selection. Zero architecture changes required.
CrewAI Integration
Shared memory across CrewAI agent teams. Configure MetaMemory as the shared knowledge layer for your crews, enabling agents to collaboratively build and query a common memory pool with role-based access, episode tracking, and cross-agent memory consolidation.
Episode Tracking
Group related interactions into coherent episodes with automatic consolidation. The EpisodeTracker groups conversation turns and memory operations, tracks emotional arcs across the episode lifecycle, and triggers automatic memory creation when episodes close, preserving the temporal and emotional context that makes episodic recall effective.
Memory Consolidation
LLM-powered merging that achieves 70% compression while preserving semantic fidelity. The consolidation service identifies redundant or overlapping memories, merges them via GPT-4, and maintains a graph of memory relationships. Reduces storage footprint and retrieval noise without losing key information.
API Reference
Memory API
Full CRUD operations, search, and bulk management. Create memories with automatic multi-vector encoding. Search with configurable retrieval strategies (semantic, temporal, emotional, keyword, graph) and filters for userId, emotion, time range. Weighted RRF fusion with query-type-specific channel weights.
Strategy API
Inspect and control the adaptive learning system. Query active Thompson Sampling posteriors (Beta distributions per strategy arm), view gradient boosting predictions, trigger Bayesian parameter optimization, access meta-memory rules, and override the multi-armed bandit selector for specific contexts.
Episode API
Manage the full episode lifecycle: create, update, and close episodes programmatically. Query by time range, emotional state, or participant. Retrieve the complete memory trail for each episode, including emotional trajectory data and temporal metadata for chronological reconstruction.
Conversation API
Persistent chat context with automatic memory integration. Manage long-running conversations with message history, emotional state tracking per turn, configurable context windows for token-efficient retrieval, and automatic memory creation from conversation content.