MemOS: a memory layer for LLM agents, from hosted API to local SQLite

The gap MemOS targets: agents that forget between turns

An agent loop without memory starts each task from zero. Conversation history is the usual patch, but it grows without bound, and once it is trimmed the agent loses the user preferences and prior tool outcomes it had already learned. MemOS is aimed at that gap. The README describes it as a Memory Operating System for LLMs and AI agents that unifies store, retrieve and manage for long-term memory. The intended users are developers building assistants that need consistent context across sessions, support systems that recall past tickets, personalized agents, and multi-agent setups where memory is either shared or isolated per agent. The README is explicit that memory is structured as a graph rather than a black-box embedding store, which matters if you expect to inspect and edit what the agent remembers. Multi-modal memory for text, images, tool traces and personas is listed as a first-class feature, so tool call history is treated as memory rather than as log noise.

How memory moves through MemOS: cubes, scheduler, feedback

The architecture visible in the README has four moving parts. Memory records live in a graph, exposed through a unified API that supports add, retrieve, edit and delete. Knowledge bases are managed as composable memory cubes, which is the mechanism for isolation and controlled sharing across users, projects and agents. Writes do not have to block the request path: MemScheduler runs memory operations asynchronously, which the README frames as the way to keep production stable under high concurrency. Retrieval is hybrid, and the local plugin release notes name the two halves as FTS5 plus vector search. On top of that sits a feedback loop: natural-language feedback can correct, supplement or replace existing memories, and the local plugin material describes tiered evolution across L1 traces, L2 policies, L3 world models and crystallized skills. That tiering is the part worth scrutinizing. It implies a promotion pipeline where raw traces become policies and then reusable skills, and the README does not document the promotion criteria or how a bad promotion is rolled back.

Installing MemOS and running a first add and search

The README presents four entry points rather than one install path, and picking the wrong one wastes time. The hosted Cloud API needs no infrastructure: you sign up on the MemOS dashboard, open API Keys, and copy a key that starts with mpg-. The README warns to keep it server-side. The example below is the README's own, showing one memory write followed by a search for the same user. The response from the search call is printed as JSON, and the user_id field is what ties the two calls together.

import requests

API_KEY = "mpg-..."                  # keep this server-side
base = "https://memos.memtensor.cn/api/openmem/v1"
headers = {"Authorization": f"Token {API_KEY}", "Content-Type": "application/json"}

requests.post(f"{base}/add/message", headers=headers, json={
    "user_id": "alice",
    "conversation_id": "conv_001",
    "messages": [{"role": "user", "content": "I like strawberry"}],
})

res = requests.post(f"{base}/search/memory", headers=headers, json={
    "query": "What do I like?",
    "user_id": "alice",
})
print(res.json())

If you want the service on your own machines instead, the README's comparison table says the self-host path is docker compose up and that it requires Neo4j and Qdrant. The repository ships a Dockerfile for the Python service. It builds on python:3.11-slim, sets PYTHONPATH to /app/src, exposes port 8000, and starts uvicorn against memos.api.server_api:app with a health check on http://localhost:8000/health.

docker build -t memos .
docker run -p 8000:8000 memos

For local, on-device memory the README points to the local plugin, installed as an npm package with agent-specific setup, and the comparison table lists DeepSeek Harness, Hermes and OpenClaw as the supported agents. The Python package itself is named MemoryOS in pyproject.toml, requires Python 3.10 or newer, and the Makefile's install target is poetry install --extras all --with dev --with test. Note the naming split: the package you pip or poetry install is MemoryOS, while the plugin you npm install is memos-local-plugin.

Where MemOS is the wrong tool

Self-hosting is not a single container. The README's table lists Neo4j and Qdrant as required infrastructure, so the self-host path is a two-datastore deployment before you have written any memory logic. The repository Dockerfile builds only the API service; it does not stand up the graph or vector stores. Teams that want one process and one file should look at the local plugin path instead, which the table says uses local SQLite and needs no infrastructure. The second limitation is agent coverage. The local plugin material names DeepSeek Harness, Hermes Agent and OpenClaw. If your agent framework is not one of those, the plugin route does not apply and you are back to the HTTP API or self-hosting. Third, the benchmark table in the README is a vendor-published summary evaluated through the project's own OmniMemEval harness, so treat the numbers as a claim about that harness rather than an independent measurement. Finally, the asynchronous ingestion path is described as the production-stability mechanism, but the README does not document what happens to in-flight memory writes when the scheduler is interrupted. If your application cannot tolerate a memory write that lands late or not at all, that gap matters.

MemOS against a plain vector store

The obvious alternative is what most teams already have: a vector database plus a table of conversation history. The difference is not retrieval quality, it is what gets stored and who can change it. A vector store holds embeddings; MemOS holds a graph of memory records that can be added, edited and deleted through the API, and the README's selling point is that this is inspectable rather than a black box. A vector store also has no notion of a knowledge base as a shareable unit; MemOS composes memory cubes so the same system can isolate one project's memory and share another's across agents. The feedback loop is the other structural difference. Correcting a vector store means re-embedding or deleting rows; MemOS accepts natural-language feedback to supplement or replace a memory. If your requirement is nearest-neighbour search over documents you control and you never need to correct a single remembered fact, a vector store is less machinery for the same job.

Licence, versioning and upgrade cost

MemOS is Apache-2.0, declared both in the repository metadata and in pyproject.toml as license = {text = "Apache-2.0"}, with the OSI Approved :: Apache Software License classifier. That is a permissive licence, and the usual obligations around attribution and notice files apply; this is a description of the licence text, not legal advice. The practical upgrade cost comes from the version spread. pyproject.toml declares version 2.0.33, the newest release in the list is v2.0.32, and the local plugin is versioned separately on a faster cadence (v2.0.17 and v2.0.18-beta.1 within four days of each other in August 2026). The plugin also ships beta tags, so pinning matters. The last push to the default branch was on 2026-08-28, three weeks before this writing, so the project is moving, but you should expect the Python core and the npm plugin to drift apart and plan upgrades per component rather than as one version bump.

Editorial conclusion

Adopt MemOS if you need one memory layer with several deployment shapes and you can accept that the canonical Python package is MemoryOS while the headline plugins are npm packages. Do not adopt it if your retrieval needs are one vector index and nothing more, or if you cannot run Neo4j and Qdrant for self-hosting. Before committing, verify three things: that your API key prefix is mpg-, that the local plugin supports your agent rather than only DeepSeek Harness, Hermes and OpenClaw, and that the benchmark scores you care about come from OmniMemEval rather than from a vendor table.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes