Empowering AI with True Memory · Enterprise-Grade Intelligent Memory System
Make every conversation built on understanding.
EverMemOS is a next-generation AI memory system designed for enterprises and organizations. It extracts, stores, and retrieves structured memories from massive conversational data, enabling AI assistants to truly understand users, groups, and business contexts.
|
[2025-10-28] 🎉 v1.0.0 First Stable Release!
|
🎯 Core Vision: Build AI memory that never forgets, making every conversation built on previous understanding.
💡 Unique Advantages:
- 🧠 Multi-Level Memory Extraction - Comprehensive capture of episodic memory, user profiles, and group characteristics
- 🔍 Intelligent Retrieval Fusion - Keyword, vector, hybrid search + Rerank reordering
- 💾 Multi-Storage Architecture - Integrated MongoDB + Elasticsearch + Milvus storage
- 🏗️ Layered Design - Clear separation: Agentic → Memory → Business → Infrastructure
EverMemOS is an open-source project designed to provide long-term memory capabilities to conversational AI agents. This codebase is the official implementation of the paper "EverMemOS". It extracts, structures, and retrieves information from conversations, enabling agents to maintain context, recall past interactions, and progressively build user profiles. This results in more personalized, coherent, and intelligent conversations.
- MemCell (Memory Cell): An atomic unit of memory extracted from conversations. It represents a single piece of information, such as a fact, an event, or a user preference.
- User Profile: A structured summary of a user's characteristics, preferences, and history, aggregated from multiple MemCells.
- Memory Extraction: A pipeline that processes raw conversation logs, identifies meaningful segments, and converts them into structured MemCells and User Profiles.
- Memory-Enhanced Conversation: The process of leveraging extracted memories to provide relevant context to Large Language Models (LLMs), enabling them to generate more informed and personalized responses.
Expand/Collapse Directory Structure
memsys-opensource/
├── src/ # Source code directory
│ ├── agentic_layer/ # Agentic layer - unified memory interface
│ ├── memory_layer/ # Memory layer - memory extraction
│ │ ├── memcell_extractor/ # MemCell extractor
│ │ ├── memory_extractor/ # Memory extractor
│ │ └── prompts/ # LLM prompt templates
│ ├── retrieval_layer/ # Retrieval layer - memory retrieval
│ ├── biz_layer/ # Business layer - business logic
│ ├── infra_layer/ # Infrastructure layer
│ ├── core/ # Core functionality (DI/lifecycle/middleware)
│ ├── component/ # Components (LLM adapters, etc.)
│ └── common_utils/ # Common utilities
├── demo/ # Demo code → [📖 Demo Guide](demo/README.md)
├── data/ # Sample conversation data → [📊 Data Guide](data/README.md)
├── evaluation/ # Evaluation scripts
├── data_format/ # Data format definitions
├── docs/ # Documentation
├── config.json # Configuration file
├── env.template # Environment variable template
├── pyproject.toml # Project configuration
└── README.md # Project description
- Python 3.10+
- uv (recommended package manager)
- MongoDB Installation Guide, Redis, Elasticsearch, Milvus (optional)
# 1. Clone the repository
git clone https://github.com/your-org/memsys_opensource.git
cd memsys_opensource
# 2. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 3. Install project dependencies
uv sync
# 4. Configure environment variables
cp env.template .env
# Edit the .env file and fill in the necessary configurations:
# - LLM_API_KEY: Defaults to OpenRouter. Please enter your OpenRouter API Key.
# - DEEPINFRA_API_KEY: Enter your DeepInfra API Key for Embedding and Rerank services.
# - Other databases (MongoDB/Redis/ES/Milvus) should be configured according to your local or remote deployment.
The demo showcases the end-to-end functionality of EverMemOS.
Step 1: Extract Memories
Run the memory extraction script to process sample conversation data and build the memory database:
python demo/extract_memory.pyThis script will:
- Read conversation data from the
data/directory - Extract MemCells and save them to the configured database (e.g., MongoDB)
- Generate user profiles and save them to
demo/memcell_outputs/directory
💡 Tip: By default, the script extracts memories for the ASSISTANT scenario. You can optionally extract memories for the GROUP_CHAT scenario:
- Open the
demo/extract_memory.pyfile.- Locate the
EXTRACT_CONFIGsection.- Change
scenario_typefromScenarioType.ASSISTANTtoScenarioType.GROUP_CHAT.- Run the extraction script again.
You can run either one or both scenarios.
Step 2: Chat with Memory
After extracting memories, start the interactive chat demo:
python demo/chat_with_memory.pyThis will launch a command-line interface where you can converse with an agent that utilizes the just-extracted memories. For more details on chat features, tips, and suggested questions, please see the Demo Guide.
The evaluation framework provides a systematic way to measure the performance of the memory system, based on the LoCoMo evaluation dataset.
# Stage 1: MemCell Extraction
python evaluation/locomo_evaluation/stage1_memcells_extraction.py
# Stage 2: Index Building
python evaluation/locomo_evaluation/stage2_index_building.py
# Stage 3: Memory Retrieval
python evaluation/locomo_evaluation/stage3_memory_retrivel.py
# Stage 4: Response Generation
python evaluation/locomo_evaluation/stage4_response.py
# Stage 5: Evaluation
python evaluation/locomo_evaluation/stage5_eval.pyEach script corresponds to a stage in the evaluation pipeline, from data processing to performance scoring.
⚙️ Evaluation Configuration: Before running the evaluation, you can modify the
evaluation/locomo_evaluation/config.pyfile to adjust the experiment settings:
ExperimentConfig.experiment_name: Change this to alter the save directory for the results.ExperimentConfig.llm_service: Select the LLM service to use (e.g.,"openai"or"vllm").ExperimentConfig.llm_config: Configure parameters for the selected LLM service in this dictionary, such as the model,base_url, andapi_key.
Use V3 API to store single message memory:
curl -X POST http://localhost:1995/api/v3/agentic/memorize \
-H "Content-Type: application/json" \
-d '{
"message_id": "msg_001",
"create_time": "2025-02-01T10:00:00+08:00",
"sender": "user_103",
"sender_name": "Chen",
"content": "We need to complete the product design this week",
"group_id": "group_001",
"group_name": "Project Discussion Group"
}'EverMemOS supports a standardized group chat data format (GroupChatFormat). You can use scripts for batch storage:
# Use script for batch storage
uv run python src/bootstrap.py src/run_memorize.py \
--input data/group_chat.json \
--api-url http://localhost:1995/api/v3/agentic/memorize
# Validate file format
uv run python src/bootstrap.py src/run_memorize.py \
--input data/group_chat.json \
--validate-onlyGroupChatFormat Example:
{
"version": "1.0.0",
"conversation_meta": {
"group_id": "group_001",
"name": "Project Discussion Group",
"user_details": {
"user_101": {
"full_name": "Alice",
"role": "Product Manager"
}
}
},
"conversation_list": [
{
"message_id": "msg_001",
"create_time": "2025-02-01T10:00:00+08:00",
"sender": "user_101",
"content": "Good morning everyone"
}
]
}For complete format specifications, please refer to Group Chat Format Specification.
For detailed installation, configuration, and usage instructions, please refer to:
- 📚 Quick Start Guide - Complete installation and configuration steps
- 📖 API Usage Guide - API endpoints and data format details
- 🔧 Development Guide - Architecture design and development best practices
- 🚀 Bootstrap Usage - Script runner usage instructions
- 📝 Group Chat Format Specification - Standardized data format
- Quick Start Guide - Installation, configuration, and startup
- Development Guide - Architecture design and best practices
- Bootstrap Usage - Script runner
- Dependency Management - Package management and version control
- Agentic V3 API - Agentic layer API
- Agentic V2 API - Agentic layer API (legacy)
- Dependency Injection Framework - DI container usage guide
- 📖 Demo Guide - Interactive examples and memory extraction demos
- 📊 Data Guide - Sample conversation data and format specifications
EverMemOS adopts a layered architecture design, mainly including:
- Agentic Layer: Memory extraction, vectorization, retrieval, and reranking
- Memory Layer: MemCell extraction, episodic memory management
- Retrieval Layer: Multi-modal retrieval and result ranking
- Business Layer: Business logic and data operations
- Infrastructure Layer: Database, cache, message queue adapters, etc.
- Core Framework: Dependency injection, middleware, queue management, etc.
For more architectural details, please refer to the Development Guide.
We welcome all forms of contributions! Whether it's reporting bugs, proposing new features, or submitting code improvements.
Before contributing, please read our Contributing Guide to learn about:
- Development environment setup
- Code standards and best practices
- Git commit conventions (Gitemoji)
- Pull Request process
We are building a vibrant open-source community!
- GitHub Issues: Submit issues and suggestions
- Discussions: Join discussions
- Email: [Contact email to be added]
- Community: [Community link to be added]
Thanks to all the developers who have contributed to this project!
This project is licensed under the Apache License 2.0. This means you are free to use, modify, and distribute this project, with the following key conditions:
- You must include a copy of the Apache 2.0 license
- You must state any significant changes made to the code
- You must retain all copyright, patent, trademark, and attribution notices
- If a NOTICE file is included, you must include it in your distribution
Thanks to the following projects and communities for their inspiration and support:
- (To be added)
If this project helps you, please give us a ⭐️
Made with ❤️ by the EverMemOS Team