# MemOS > MemOS is a long-term memory system for AI agents and applications. It automatically extracts, stores, and retrieves personalized memories from conversations so your AI remembers users across sessions. ## For agents reading this file - To get raw Markdown of any page below, append `.md` to its URL. - **Locale**: all links below are English. Prefix `/cn` to get Chinese: `/cn/memos_cloud/getting_started/quick_start.md` - Full documentation text: [/llms-full.txt](/llms-full.txt) - OpenAPI spec (Cloud): [/cn/api_docs/api.json](/cn/api_docs/api.json) - Source repo: https://github.com/MemTensor/MemOS - CLI: `pip install memos-cli` — see [CLI guide](/mcp_agent/cli/guide) - Dashboard: https://memos-dashboard.openmem.net ### Quick integration ```bash pip install MemoryOS -U ``` ```python import os import requests import json os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY" # Get from https://memos-dashboard.openmem.net/apikeys/ os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1" headers = { "Content-Type": "application/json", "Authorization": f"Token {os.environ['MEMOS_API_KEY']}" } # 1. Store a conversation as memory data = { "user_id": "memos_user_123", "conversation_id": "0610", "messages": [ {"role": "user", "content": "I've planned to travel to Guangzhou this summer. What chain hotels are available?"}, {"role": "assistant", "content": "You can consider 7 Days Inn, All Seasons, Hilton, etc."}, {"role": "user", "content": "I'll choose 7 Days Inn."}, {"role": "assistant", "content": "Alright, feel free to ask if you have any other questions."} ] } res = requests.post( f"{os.environ['MEMOS_BASE_URL']}/add/message", headers=headers, data=json.dumps(data) ) print(f"add result: {res.json()}") # 2. Recall relevant memories later data = { "query": "I want to travel during National Day. Recommend a city I haven't been to and a hotel I haven't stayed at.", "user_id": "memos_user_123", "conversation_id": "0928" } res = requests.post( f"{os.environ['MEMOS_BASE_URL']}/search/memory", headers=headers, data=json.dumps(data) ) print(f"search result: {res.json()}") ``` ### Routing guide | User wants to... | Start here | |---|---| | Add memory to their app (API) | [Integrate into Your App](/memos_cloud/getting_started/quick_start) | | Use via MCP / CLI / Plugin | [Use in Agents](/memos_cloud/getting_started/agent_usage) | | Understand concepts | [Overview](/memos_cloud/getting_started/overview) | | Self-host open source | [Installation Guide](/open_source/getting_started/installation) | | API reference | [API Overview](/api_docs/start/overview) | --- ## MemOS Cloud ### Getting Started - [MemOS Overview](/memos_cloud/getting_started/overview): Memory Operation System, giving AI applications long-term memory. - [Cloud Service & Open Source](/memos_cloud/getting_started/cloud_and_opensource): Choose the MemOS memory solution that best fits your needs. - [Use in Agents](/memos_cloud/getting_started/agent_usage): Connect MemOS to Agent workflows through plugins, MCP, CLI, and APIs. - [Integrate into Your App](/memos_cloud/getting_started/quick_start): Configure a MemOS Cloud account and create your first memory in five minutes. ### Concepts - [Raw Input Content](/memos_cloud/introduction/raw_inputs): MemOS can generate memories from different kinds of raw input content. - [Memory Categories](/memos_cloud/introduction/memory_types): Understand the different categories of memories generated and used by MemOS. - [Multi-user / Multi-Agent Isolation](/memos_cloud/introduction/isolation_filters): Understand how MemOS Cloud separates users, Agents, conversations, and shared knowledge. - [Time Awareness](/memos_cloud/introduction/time_awareness): How memories update over time, keep history, and understand "now" and "before" during retrieval. - [FAQ](/memos_cloud/introduction/faq): Understand MemOS concepts such as RAG, open source deployment, private deployment, memory lifecycle, and scheduling. #### How MemOS Works - [Memory Production](/memos_cloud/introduction/mem_production): Memory production turns raw conversations, behavior events, tool calls, and knowledge content into structured memories that can be searched, updated, and scheduled. - [Memory Scheduling](/memos_cloud/introduction/mem_schedule): Memory scheduling decides which memories should be prepared in advance, prioritized, or temporarily downgraded while conversations and tasks are running. - [Memory Recall](/memos_cloud/introduction/mem_recall): Memory recall finds the content that is most relevant, trustworthy, and suitable to inject into context when a user makes a request. - [Memory Lifecycle Management](/memos_cloud/introduction/mem_lifecycle): Memory lifecycle management keeps memories evolving through generation, use, merging, archiving, and cleanup, so the memory base stays accurate, clean, and traceable. - [MemOS Algorithm Overview](/memos_cloud/introduction/algorithm): Transforming large models from disposable dialogue tools into intelligent agents with true long-term memory and adaptive capabilities. ### Core Operations - [Add Message](/memos_cloud/mem_operations/add_message): MemOS automatically processes multimodal content such as text, files, and images into retrievable personal memories. - [Search Memory](/memos_cloud/mem_operations/search_memory): MemOS recalls relevant memories through semantic retrieval and filtering. - [Delete Memory](/memos_cloud/mem_operations/delete_memory): Delete user memories from MemOS Cloud by memory_id, or delete all memories for a user in the current project by user_id. - [Add Feedback](/memos_cloud/mem_operations/add_feedback): Add natural-language user feedback, and MemOS automatically updates memories. - [Continuous Conversation Chat](/memos_cloud/mem_operations/chat): MemOS provides a conversation API with built-in memory management, so you do not need to manually assemble context. ### More Features - [Memory Filters](/memos_cloud/features/filters): Use memory filters during retrieval to filter by memory source, tags, metadata, time range, and other conditions. - [Async Mode](/memos_cloud/features/async_mode): Use async mode when adding messages; the interface returns immediately while actual processing is queued in the background by MemOS. - [Multimodal Messages](/memos_cloud/features/multimodal): Integrate images and documents into interactions with MemOS when adding messages. - [Custom Tags](/memos_cloud/features/custom_tags): Use tags according to your business needs when adding messages. - [Self-Evolving](/memos_cloud/features/self-evolving): Memory is not just storage — MemOS automatically distills reusable structured methods from conversations, letting Agent capabilities evolve continuously with use. - [Knowledge Base](/memos_cloud/features/knowledge_base): Create a knowledge base associated with the project, and combine user memory with knowledge base to supplement knowledge when retrieving memories. - [Tool Calling](/memos_cloud/features/tool_calling): Add tool calling information, integrating tool calling decisions, execution results, and usage trajectories into MemOS memory. ### Support and Troubleshooting - [Cloud FAQs](/memos_cloud/support/faq): Troubleshoot common MemOS Cloud issues related to accounts, projects, API Keys, quotas, knowledge bases, and API calls. - [Limits](/memos_cloud/support/limit): Register and log in to enjoy free quota, facilitating quick experience and verification of memory functions. ## Open Source - [Search memories](/api-reference/search-memories) `POST /product/search`: Search memories for a specific user. - [Add memories](/api-reference/add-memories) `POST /product/add`: Add memories for a specific user. - [Get all memories for user](/api-reference/get-all-memories-for-user) `POST /product/get_all`: Get all memories or subgraph for a specific user. If search_query is provided, returns a subgraph based on the query. Otherwise, returns all memories of the specified type. - [Get memories for user](/api-reference/get-memories-for-user) `POST /product/get_memory`: Get memories for user with pagination support. - [Get memory by id](/api-reference/get-memory-by-id) `GET /product/get_memory/{memory_id}`: Get a specific memory by its ID. - [Delete memories for user](/api-reference/delete-memories-for-user) `POST /product/delete_memory`: Delete memories for a specific user. - [Chat with MemOS (Complete Response)](/api-reference/chat-with-memos-(complete-response)) `POST /product/chat/complete`: Chat with MemOS for a specific user. Returns complete response (non-streaming). - [Chat with MemOS](/api-reference/chat-with-memos) `POST /product/chat/stream`: Chat with MemOS for a specific user. Returns SSE stream. - [Chat with MemOS playground](/api-reference/chat-with-memos-playground) `POST /product/chat/stream/playground`: Chat with MemOS for a specific user in playground. Returns SSE stream. - [Get suggestion queries](/api-reference/get-suggestion-queries) `POST /product/suggestions`: Get suggestion queries for a specific user with language preference. - [Feedback memories](/api-reference/feedback-memories) `POST /product/feedback`: Feedback memories for a specific user. - [Get detailed scheduler status](/api-reference/get-detailed-scheduler-status) `GET /product/scheduler/allstatus`: Get detailed scheduler status including running tasks and queue metrics. - [Get scheduler running status](/api-reference/get-scheduler-running-status) `GET /product/scheduler/status`: Get scheduler running status. - [Get scheduler task queue status](/api-reference/get-scheduler-task-queue-status) `GET /product/scheduler/task_queue_status`: Get scheduler task queue backlog/pending status for a user. - [Wait until scheduler is idle for a specific user](/api-reference/wait-until-scheduler-is-idle-for-a-specific-user) `POST /product/scheduler/wait`: Wait until scheduler is idle for a specific user. - [Stream scheduler progress for a user](/api-reference/stream-scheduler-progress-for-a-user) `GET /product/scheduler/wait/stream`: Stream scheduler progress via Server-Sent Events (SSE). - [Get user names by memory ids](/api-reference/get-user-names-by-memory-ids) `POST /product/get_user_names_by_memory_ids`: Get user names by memory ids. - [Check if mem cube id exists](/api-reference/check-if-mem-cube-id-exists) `POST /product/exist_mem_cube_id`: Check if mem cube id exists. ### Getting Started - [Installation Guide](/open_source/getting_started/installation): Complete installation guide for MemOS. - [Your First Memory](/open_source/getting_started/your_first_memory): Let’s build your first plaintext memory in MemOS! **GeneralTextMemory** is the easiest way to get hands-on with extracting, embedding, and searching simple text memories. - [Core Concepts](/open_source/home/core_concepts): MemOS treats memory as a first-class citizen. Its core design revolves around how to orchestrate, store, retrieve, and govern memory for your LLM applications. - [Architecture](/open_source/home/architecture): MemOS is made up of **core modules** that work together to turn your LLM into a truly **memory-augmented system** — from orchestration to storage to retrieval. - [REST API Server](/open_source/getting_started/rest_api_server): MemOS provides a REST API service written using FastAPI. Users can perform all operations via REST interfaces. - [MemOS Examples](/open_source/getting_started/examples): Congratulations - you've mastered the Quick Start and built your first working memory! Now it's time to see how far you can take MemOS by combining different memory types and features. Use these curat ### MOS - [MemOS API Development Guide (Components & Handlers Architecture)](/open_source/modules/mos/overview): MemOS v2.0 adopts a more modular and decoupled architecture. The legacy MOS class is deprecated; Components + Handlers is now recommended for development. - [MemCube](/open_source/modules/mem_cube): `MemCube` is your memory container that manages three types of memories: textual memory, activation memory, and parametric memory. It provides a simple interface for loading, saving, and operating on - [MemReader](/open_source/modules/mem_reader): MemReader is your "memory translator". It translates messy user inputs (chat, documents, images) into structured memory fragments the system can understand. - [MemScheduler](/open_source/modules/mem_scheduler): MemScheduler is your "memory organization scheduler". It asynchronously manages memory flow and updates in the background, coordinating interactions between working memory, long-term memory, and activ - [MemChat](/open_source/modules/mem_chat): MemChat is your "memory diplomat". It coordinates user input, memory retrieval, and LLM generation to create coherent conversations with long-term memory. - [MemFeedback](/open_source/modules/mem_feedback): MemFeedback is your "memory error notebook". It enables your Agent to understand 'You remembered it wrong' and automatically correct the memory database. It is a key component for achieving self-evolv ### Memories - [Memory Modules Overview](/open_source/modules/memories/overview): Complete guide to MemOS memory systems - from lightweight text memory to advanced graph structures, choose the right memory module for your needs - [KVCacheMemory: Key-Value Cache for Activation Memory](/open_source/modules/memories/kv_cache_memory): `KVCacheMemory` is a specialized memory module in MemOS for storing and managing key-value (KV) caches, primarily used to accelerate large language model (LLM) inference and support efficient context - [Parametric Memory *(Coming Soon)*](/open_source/modules/memories/parametric_memory) #### Plaintext Memory - [NaiveTextMemory: Simple Plain Text Memory](/open_source/modules/memories/naive_textual_memory): The most lightweight memory module in MemOS, designed for rapid prototyping and simple scenarios. No vector database required—quickly retrieve memories using keyword matching. - [GeneralTextMemory: General-Purpose Textual Memory](/open_source/modules/memories/general_textual_memory): `GeneralTextMemory` is a flexible, vector-based textual memory module in MemOS, designed for storing, searching, and managing unstructured knowledge. It is suitable for conversational agents, personal - [PreferenceTextMemory: Textual Memory for User Preferences](/open_source/modules/memories/preference_textual_memory): `PreferenceTextMemory` is a textual memory module in MemOS for storing and managing user preferences. It is suitable for scenarios where memory retrieval needs to be based on user preferences. - [TreeTextMemory: Structured Hierarchical Textual Memory](/open_source/modules/memories/tree_textual_memory): > - [Neo4j Graph Database](/open_source/modules/memories/neo4j_graph_db): This module provides graph-based memory storage and querying for memory-augmented systems such as RAG, cognitive agents, or personal memory assistants.
It defines a clean abstraction (`BaseGraphD - [PolarDB Graph Database](/open_source/modules/memories/polardb_graph_db): Configuration and usage of PolarDB graph database in the MemOS framework. MemOS supports using **PolarDB** (based on Apache AGE extension) as a graph database backend for storing and retrieving knowle ### Best Practice - [Performance Tuning](/open_source/best_practice/performance_tuning) - [Network Workarounds](/open_source/best_practice/network_workarounds): Here are some solutions to address the network issues you may encounter during developing. - [Common Errors and Solutions](/open_source/best_practice/common_errors_solutions) - [MemOS MCP Integration Guide](/open_source/best_practice/mcp_for_cozespace_and_tools) ### Contribution - [Contributing to MemOS](/open_source/contribution/overview): Welcome to the MemOS contribution guide! Learn how to set up your development environment, follow our workflow, write good commit messages, improve documentation, and add tests. - [Setting Up Your Development Environment](/open_source/contribution/setting_up): To contribute to MemOS, you'll need to set up your local development environment. - [Development Workflow](/open_source/contribution/development_workflow) - [Commit Guidelines](/open_source/contribution/commit_guidelines) - [Documentation Writing Guidelines](/open_source/contribution/writing_docs): This project uses Nuxt Content to build a documentation system that supports Markdown and rich Vue components. - [How to Write Unit Tests](/open_source/contribution/writing_tests): This project uses [pytest](https://docs.pytest.org/) for unit testing. ## Self-developed Models Overview ### Extraction Model - [Usage Examples](/self_developed_model/extraction_usage_example): Extract fact and preference memories from dialogue using the in-house memos-extractor-0.6b model. ### Reranker Model - [Usage Examples](/self_developed_model/reranker_usage_example): Rerank memory relevance based on the self-developed memos-reranker small model. ## Agent - [Cloud Plugin vs Local Plugin](/openclaw/plugin_compare): The cloud plugin is for quick MemOS Cloud adoption, while the local plugin brings local-first long-term memory and self-evolution to OpenClaw and Hermes. This guide helps you choose the right option. - [OpenClaw Plugin Changelog](/openclaw/changes) ### Installation Guide - [OpenClaw Cloud Plugin](/openclaw/guide): Enhance your OpenClaw's memory and reduce token by 72%. MemOS OpenClaw plugin is now live! - [Local Plugin](/openclaw/local_plugin): Use @memtensor/memos-local-plugin to bring local-first long-term memory, three-tier retrieval, skill crystallization, and an observable management panel to OpenClaw and Hermes Agent. ### Usage Examples - [Knowledge Base Usage](/openclaw/examples/knowledge_base): Create a knowledge base in MemOS Cloud Dashboard and configure its knowledge base ID in the OpenClaw cloud plugin. - [Multi-Agent Memory Isolation](/openclaw/examples/multi_agent) - [Secondary Filtering for Memory Recall](/openclaw/examples/recall_filter) - [Local Plugin Usage](/openclaw/examples/hermes_usage): Basic usage, memory tools, team sharing, and multi-agent examples for the MemOS local plugin in OpenClaw and Hermes. ## Agent Framework Support ### MCP Services - [MemOS MCP Usage Guide](/mcp_agent/mcp/guide) ### CLI - [MemOS CLI](/mcp_agent/cli/guide): Connect MemOS to local terminals and Agent workflows through command-line tools. ### Agent Development - [User Guide](/mcp_agent/agent/guide): Published plugin tools directly access the MemOS cloud service API, quickly adding long-term memory capabilities to your Agent, making conversations more considerate and continuous. ## API Documentation ### Get Started - [Overview](/api_docs/start/overview) - [Project Configuration](/api_docs/start/configuration): Understand how projects, API Keys, knowledge base associations, and request logs work together for multi-project management, knowledge base binding, and configuration troubleshooting. ### Core Operations - [Add Message](/api_docs/core/add_message) `POST /add/message`: This API allows you to add one or more messages to a specific conversation. As illustrated in the examples bellow, you can add messages in real time during a user-assistant interaction, import histori - [Search Memory](/api_docs/core/search_memory) `POST /search/memory`: This API queries a user’s memory and returns the fragments most relevant to the input for the Agent to use. Returned memory can include Fact Memory, Preference Memory, Tool Memory, and Skill. Skills c - [Get Memory](/api_docs/core/get_memory) `POST /get/memory`: Retrieve a user’s memories, including factual, preference, and tool memories. - [Delete Memory](/api_docs/core/delete_memory) `POST /delete/memory`: This API is used to delete specified user memories, supporting batch deletion. - [Add Feedback](/api_docs/message/add_feedback) `POST /add/feedback`: This API is used to add feedback to current session messages, allowing MemOS to correct memories based on user feedback. ### Self-developed Models - [Extract Memory](/api_docs/core/extract_memory) `POST /extract/memory`: Uses MemOS’s self-developed extraction model to extract and return fact and preference memories directly from conversation messages. - [Rerank](/api_docs/core/rerank) `POST /rerank`: Provides a memory reranking API based on the memos-reranker small model. It takes a user query and a list of candidate memories and completes memory relevance reranking with a single call. ### Messages - [Get Message](/api_docs/message/get_message) `POST /get/message`: This API retrieves the historical conversation records between a user and the assistant for a specified session, with the option to limit the number of results. As shown in the examples bellow, you ca - [Get Task Status](/api_docs/message/get_status) `POST /get/status`: Get the status of an asynchronous processing task. ### Chat - [Chat](/api_docs/chat/chat) `POST /chat` ### Knowledge Base - [Create Knowledge Base](/api_docs/knowledge/create_kb) `POST /create/knowledgebase`: Create a knowledgebase associated with the project. - [Delete Knowledge Base](/api_docs/knowledge/remove_kb) `POST /delete/knowledgebase`: Delete a knowledgebase from the current project. To permanently delete it, please operate from the Console - Knowledgebase page. - [Create Knowledge Base File](/api_docs/knowledge/add_kb_doc) `POST /add/knowledgebase-file`: Upload files to a specified Knowledge Base. By default, files are uploaded as documents. When file[].type is skill, upload a Markdown Skill file or ZIP Skill package. - [Get Knowledge Base File](/api_docs/knowledge/get_kb_doc) `POST /get/knowledgebase-file`: Get file information in one of two ways: pass file_ids to retrieve specific file details, or pass knowledgebase_id to list files under a Knowledge Base. Choose only one mode; passing both knowledgebas - [Delete Knowledge Base File](/api_docs/knowledge/delete_kb_doc) `POST /delete/knowledgebase-file`: Delete files from a specified Knowledge Base. When a Skill file is deleted, the associated Skill is deleted as well. ### Help & Support - [Error Codes](/api_docs/help/error_codes) ## Use Cases ### Best Practice - [Build a Memory-Enhanced Knowledge Base Q&A Assistant](/usecase/knowledge_qa_assistant): Combine long-term memory with a knowledge base to move beyond “one-size-fits-all” retrieval results—deliver personalized, more accurate answers based on each user’s background and preferences, and tur - [Let the Financial Assistant Understand Customer Preferences Behind Behaviors](/usecase/financial_assistant): With MemOS, user operations and conversational behaviors are abstracted into "memories," enabling the identification and extraction of underlying investment preferences to deliver more personalized se - [A Writing Assistant with Memory is More Useful](/usecase/writting_assistant): With MemOS, your product will automatically remember the user's writing habits and context, making the creative process more coherent and effortless. - [Building a Home Life Assistant with Memory](/usecase/home_assistant): With the support of MemOS, a home assistant can connect daily chores and long-term plans, quickly understanding and responding to the user’s real needs. ### Frameworks & Platforms - [Claude MCP](/usecase/frameworks/claude_mcp) - [Coze Plugin](/usecase/frameworks/coze_plugin): The Coze plugin tool directly accesses MemOS cloud service interfaces to quickly add long-term memory capabilities to your Agent, making conversations more thoughtful and continuous.