# MemoryOS: A Hierarchical Memory Operating System for Long-Running AI Agents

> MemoryOS is an open-source Python framework that brings operating-system-style memory management to AI agents, organising interactions into short-term, mid-term, and long-term tiers. Accepted as an oral paper at EMNLP 2025, it achieved a 49.11% F1 improvement over baselines on the LoCoMo long-conversation benchmark.

**BAI-LAB/MemoryOS** — [EMNLP 2025 Oral] MemoryOS is designed to provide a memory operating system for personalized AI agents.

- Repository: https://github.com/BAI-LAB/MemoryOS
- Website: https://baijia.online/memoryos/
- Stars: 1,591 · Forks: 165
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/bai-lab-memoryos

## The Problem MemoryOS Addresses in Long-Running Agents

A standard AI agent session has no memory beyond the current context window. Once the conversation ends or the window fills, previous interactions are gone. Agents that are supposed to know your preferences, work history, or recurring goals must either receive all prior context on every call (expensive and slow) or forget it (unhelpful). MemoryOS treats this as an operating system resource management problem, not just a retrieval problem.

The framework is designed for personalised AI agents: assistants that serve a specific user over many sessions and need to build and maintain a user profile, track knowledge the user has shared, and recall relevant past interactions. The BAI-LAB research group at the paper's affiliated institution published it as an EMNLP 2025 Oral paper, and the codebase was open-sourced in May 2025.

## The Four-Module Hierarchical Architecture

MemoryOS models memory as three tiers: short-term, mid-term, and long-term personal memory. These tiers correspond to different time horizons and access costs. Short-term memory holds the current session context. Mid-term memory accumulates patterns and summaries from recent sessions. Long-term memory holds stable user profiles and persistent knowledge.

Four modules govern how information moves through these tiers. The Storage module handles writes into each tier. The Updating module decides when and how to promote information from short-term toward long-term storage, updating summaries and the user profile as new interactions arrive. The Retrieval module queries across all tiers to find relevant memories for a given prompt. The Generation module integrates retrieved memories with the current request before sending it to the LLM.

The framework supports a `similarity_threshold` parameter that controls retrieval sensitivity. The documentation identifies this as a configurable parameter; its default value affects what gets recalled and should be adjusted based on how precise or broad the retrieval needs to be for a given application.

## Installing MemoryOS with Docker

The repository ships a Dockerfile that builds a Python 3.10 slim environment and installs the MemoryOS dependencies from the `memoryos-pypi/` directory:

```dockerfile
FROM python:3.10-slim
WORKDIR /app
COPY memoryos-pypi/ ./memoryos-pypi/
RUN pip install --no-cache-dir -r memoryos-pypi/requirements.txt
```

The repository also includes a PyPI package distribution (`memoryos-pypi/`) for direct installation without Docker. The project additionally publishes a MemoryOS-MCP server in the `memoryos-mcp/` subdirectory for agent clients that communicate through the Model Context Protocol.

As of V1.2 (released 2025-07-18), ChromaDB is supported as an alternative vector database backend. The ChromaDB variant lives in the `memoryos-chromadb/` directory and has its own getting-started section in the README. A playground platform was opened on 2025-09-11 at the project website for users who want to try MemoryOS without a local install.

## MCP Server Integration and Supported Agent Clients

MemoryOS-MCP exposes the memory framework as a set of MCP tools that any compatible agent client can call. This means adding long-term memory to an existing AI workflow does not require rewriting the agent; you configure the MCP server and the client connects to it.

The README lists three supported agent clients: Claude Desktop (via `claude_desktop_config.json`), Cline (a VS Code extension, via VS Code settings), and Cursor (an AI code editor, via the settings panel). On the model provider side, the support table includes OpenAI (GPT-4, GPT-3.5), Deepseek, Qwen, and others; the README also notes support for reasoning models such as Deepseek-r1 and Qwen3 as of the 2025-07-07 update.

The parallelisation improvements in V1.07 (2025-07-07) reduced latency by a factor of five compared to the earlier implementation.

## Benchmark Results and What They Cover

The paper reports results on the LoCoMo dataset, a benchmark for long-conversation memory. MemoryOS achieved average improvements of 49.11% in F1 score and 46.18% in BLEU-1 score compared to baselines on that dataset. The repository includes evaluation code in the `eval/` directory for reproducing these results.

LoCoMo tests long-horizon personal conversation recall. It does not measure latency at scale, multi-user isolation, or behaviour when memory stores grow very large over months of use. These are relevant concerns for production deployments that the benchmark does not cover. Teams should run their own evaluation on a representative sample of their target conversations before depending on the benchmark numbers as a performance proxy.

## Limitations and When MemoryOS Is the Wrong Tool

MemoryOS manages personal memory for a single user context. It is not designed as a shared knowledge base for multiple users, a document retrieval system for large corpora, or a general vector store. Projects that need full-text search over organisational documents, or that require separate memory namespaces for many users simultaneously, would need additional architecture on top of MemoryOS or a different tool entirely.

The framework requires an LLM provider for its Generation module. There is no local-only mode that avoids an API call; you must have a working API key for one of the supported providers. The framework also depends on an embedding model for retrieval: the 2025-07-14 update added support for BGE-M3 and Qwen3 embeddings.

The last push to the main branch was on 2026-07-07. The most recent release on GitHub is V1.2, dated 2025-07-18. Development appears to have slowed since early 2026.

## Conclusion

MemoryOS fits teams building personalised AI assistants or agents that must maintain coherent context across many sessions, where a flat conversation history quickly becomes too large to use or too expensive to pass in full. It is not a general-purpose vector store or a drop-in session persistence layer. Before integrating it into a production system, verify that the LLM provider you use is in the support list and that the similarity_threshold parameter is tuned for your retrieval patterns, since the documentation flags this as a configurable but sensitive parameter.

## FAQ

### What is MemoryOS?

MemoryOS is an open-source Python framework that provides hierarchical memory management for AI agents. It organises agent interactions into short-term, mid-term, and long-term tiers, and uses four modules (Storage, Updating, Retrieval, Generation) to keep relevant context available across long or repeated conversations. The project was accepted at EMNLP 2025.

### How do I use MemoryOS?

MemoryOS can be deployed via Docker using the included Dockerfile, which installs dependencies from the `memoryos-pypi/` directory. A MCP server variant (`memoryos-mcp/`) lets agent clients like Claude Desktop, Cline, or Cursor connect to the memory framework without code changes. A hosted playground is also available at the project website.

### Which LLM providers does MemoryOS support?

MemoryOS supports OpenAI (GPT-4, GPT-3.5), Deepseek (including Deepseek-r1), and Qwen (including Qwen3), among others listed in the repository's support table. An API key for at least one of these providers is required, as the framework calls an LLM for its Generation module.

## Sources

- [BAI-LAB/MemoryOS on GitHub](https://github.com/BAI-LAB/MemoryOS)
- [License: Apache-2.0](https://github.com/BAI-LAB/MemoryOS/blob/main/LICENSE)
- [Project website](https://baijia.online/memoryos/)
- [README](https://github.com/BAI-LAB/MemoryOS/blob/main/README.md)
- [Releases](https://github.com/BAI-LAB/MemoryOS/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bai-lab-memoryos