MemOS README

The project's README from github.com/MemTensor/MemOS. As one markdown file: README.md.

MemOS Logo   MemOS 2.0 Stardust（星尘）

Docs ArXiv X Discord
Resources

Give your Agent persistent memory and the ability to grow.

English | 中文

MemOS agent ecosystem: OpenClaw, Hermes, and DeepSeek Harness

[!TIP] New: Connect MemOS to DeepSeek Harness (dsh)

Add automatic recall, background capture, hybrid retrieval, and a local Memory Viewer to DeepSeek Harness—powered by the same MemOS core used across agent ecosystems.

Get started →

👾 MemOS: Memory Operating System for LLM & AI Agents

MemOS is a Memory Operating System for LLMs and AI agents that unifies store / retrieve / manage for long-term memory, enabling context-aware and personalized interactions with KB, multi-modal, tool memory, and enterprise-grade optimizations built in.

Key Features

News

📊 Performance

MemOS leads across multiple benchmarks — evaluated against mainstream commercial memory products across 5 user memory and 5 agent memory tasks.

Benchmark Score
LoCoMo 88.83
LongMemEval 89.20
PersonaMem v2 40.58
HaluMem 80.91
BEAM-10M 56.75
GDPVal 62.07
LiveCodeBench 64.96
OmniMath 61.00
SWE-Bench 38.46
BrowseComp-Plus 23.85

Evaluated via OmniMemEval — https://github.com/MemTensor/OmniMemEval.

🎯 What MemOS Is For

MemOS gives AI agents long-term memory. Common uses:

🚀 Quick Start

MemOS is built around four entry points. Pick the one that matches your scenario.

Cloud API Self-Host MemOS Cloud Plugin Local Plugin
Best for Your app, fully managed Teams on own infra OpenClaw users, zero ops DeepSeek Harness, Hermes, or OpenClaw; on-device
Setup Get an API key docker compose up openclaw plugins install npm install + agent-specific setup
Infra needed None (hosted) Neo4j + Qdrant None (uses MemOS Cloud) None (local SQLite)
Data lives MemOS Cloud Your servers MemOS Cloud Your machine

☁️ Use the Cloud API (Hosted)

You want to add memory to your app through a fully managed service — no infrastructure to run.

1. Get an API key:

2. Add and search memories:

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"}

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

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

Next steps:

🖥️ Self-Host the MemOS Service

You want to run MemOS as a REST service on your own machine or cluster.

Option A — Docker (recommended):

git clone https://github.com/MemTensor/MemOS.git
cd MemOS
cp docker/.env.example .env          # fill in your API keys in .env
cd docker
docker compose up                    # starts MemOS API + Neo4j + Qdrant

The API is served at http://localhost:8000.

Option B — Run with uvicorn (without Docker):

git clone https://github.com/MemTensor/MemOS.git
cd MemOS
cp docker/.env.example .env          # fill in your API keys in .env
# Ensure Neo4j and Qdrant are running, then:
cd src
uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8000 --workers 1

See docker/.env.example-full for all configuration options (LLM provider, embedder, vector DB, graph DB, scheduler). The full deployment guide is at https://memos-docs.openmem.net/open_source/getting_started/rest_api_server/.

Try the API:

import requests, json

headers = {"Content-Type": "application/json"}
base = "http://localhost:8000/product"

# 1. Create a memory cube
requests.post(f"{base}/create_cube", headers=headers, data=json.dumps({
    "cube_name": "Alice's memory",
    "owner_id": "alice",
    "cube_id": "alice_cube",
}))

# 2. Add a memory
requests.post(f"{base}/add", headers=headers, data=json.dumps({
    "user_id": "alice",
    "writable_cube_ids": ["alice_cube"],
    "messages": [{"role": "user", "content": "I like strawberry"}],
    "async_mode": "sync",
}))

# 3. Search memories
res = requests.post(f"{base}/search", headers=headers, data=json.dumps({
    "query": "What do I like?",
    "user_id": "alice",
    "readable_cube_ids": ["alice_cube"],
}))
print(res.json())

🧠 MemOS Plugin: Persistent Memory for Your AI Agents ✨

MemOS gives OpenClaw, Hermes, and DeepSeek Harness a shared local memory core; the managed MemOS Cloud Plugin is available for OpenClaw and DeepSeek Harness 🏃🏻

🔌 Plugin 💡 Core Features 🧩 Resources
🧠 memos-local-plugin 2.0 🌐 Website · 📖 Docs · 🐙 GitHub · 📦 NPM
☁️ MemOS Cloud Plugin 🖥️ MemOS Dashboard · 📖 Full Tutorial

1. MemOS Cloud Plugin

Use MemOS Cloud for persistent memory in OpenClaw or DeepSeek Harness — no infrastructure to run.

Install:

openclaw plugins install @memtensor/memos-cloud-openclaw-plugin@latest
openclaw gateway restart

The plugin recalls memories from MemOS Cloud before each agent run and saves new messages back after the run ends.

DeepSeek Harness

Connect DeepSeek Harness to MemOS Cloud through its native plugin mechanism. Before the first model step of each user request, the plugin recalls relevant cloud memories; after a successful turn, it saves the new user and assistant messages back to MemOS Cloud.

  1. Create a MemOS API Key.

  2. Install the cloud plugin into the default DSH web profile:

    npx @deepseek-ai/dsh plugin --profile web add @memtensor/memos-cloud-dsh-plugin@latest

  3. Add the API Key to ~/.dsh/.credentials.yaml:

    MEMOS_API_KEY: mpg-your-key

  4. Add the minimal plugin configuration to ~/.dsh/settings.yaml:

    memos-cloud:
  apiKeyEnv: MEMOS_API_KEY

  5. Restart the DSH Web profile:

    npx @deepseek-ai/dsh web

The cloud plugin is fail-open: a temporary MemOS Cloud outage does not interrupt the current DSH task.

2. Local Plugin (OpenClaw, Hermes, and DeepSeek Harness)

You use DeepSeek Harness, Hermes Agent, or OpenClaw and want 100% on-device memory — nothing leaves your machine.

Install for DeepSeek Harness (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/MemTensor/MemOS/main/apps/memos-local-plugin/install.sh | bash -s -- --agent dsh --profile web

Install for OpenClaw or Hermes (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/MemTensor/MemOS/main/apps/memos-local-plugin/install.sh | bash

Install (Windows PowerShell):

irm https://raw.githubusercontent.com/MemTensor/MemOS/main/apps/memos-local-plugin/install.ps1 -OutFile "$env:TEMP\memos-install.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\memos-install.ps1"

Requires Node.js and an already-installed DeepSeek Harness, OpenClaw, or Hermes. The installer deploys MemOS to the selected agent runtime; the DeepSeek Harness target installs it as an out-of-tree DSH bundle, while the OpenClaw and Hermes targets write the initial config.yaml in their respective agent homes.

Features: hybrid retrieval (FTS5 + vector), smart dedup, tiered skill evolution (L1 traces / L2 policies / L3 world model), multi-agent collaboration, local-first SQLite storage.

🤝 Community

QR Code

📚 Citation

If you use MemOS in your research, please cite:

@article{li2025memos_long,
  title={MemOS: A Memory OS for AI System},
  author={Li, Zhiyu and Song, Shichao and Xi, Chenyang and Wang, Hanyu and Tang, Chen and Niu, Simin and Chen, Ding and Yang, Jiawei and Li, Chunyu and Yu, Qingchen and Zhao, Jihao and Wang, Yezhaohui and Liu, Peng and Lin, Zehao and Wang, Pengyuan and Huo, Jiahao and Chen, Tianyi and Chen, Kai and Li, Kehang and Tao, Zhen and Ren, Junpeng and Lai, Huayi and Wu, Hao and Tang, Bo and Wang, Zhenren and Fan, Zhaoxin and Zhang, Ningyu and Zhang, Linfeng and Yan, Junchi and Yang, Mingchuan and Xu, Tong and Xu, Wei and Chen, Huajun and Wang, Haofeng and Yang, Hongkang and Zhang, Wentao and Xu, Zhi-Qin John and Chen, Siheng and Xiong, Feiyu},
  journal={arXiv preprint arXiv:2507.03724},
  year={2025},
  url={https://arxiv.org/abs/2507.03724}
}

@article{li2025memos_short,
  title={MemOS: An Operating System for Memory-Augmented Generation (MAG) in Large Language Models},
  author={Li, Zhiyu and Song, Shichao and Wang, Hanyu and Niu, Simin and Chen, Ding and Yang, Jiawei and Xi, Chenyang and Lai, Huayi and Zhao, Jihao and Wang, Yezhaohui and others},
  journal={arXiv preprint arXiv:2505.22101},
  year={2025},
  url={https://arxiv.org/abs/2505.22101}
}

⚖️ License

MemOS is licensed under the Apache 2.0 License.

MemOS (MemTensor/MemOS)

Searching Database…

11.9K ·GitHub
MemOS
What is this?MemOS is a Memory Operating System for LLMs and AI agents that unifies storing, retrieving, and managing long-term memory, so agents can have context-aware, personalized interactions instead of starting from scratch each session.
Is this a hosted service, a self-hosted server, or a plugin for my agent?It is all three: a fully-managed Cloud API, a self-hosted REST service you run with Docker, and local/cloud plugins you install into OpenClaw, Hermes Agent, or DeepSeek Harness.
How do I get started with it?For the Cloud API, sign up on the MemOS dashboard and get an API key (starts with mpg-); to self-host, run docker compose up; to add it to an existing agent, npm install the local or cloud plugin (e.g. via 'openclaw plugins install' for OpenClaw).
What infrastructure do I need if I self-host it?Self-hosting requires Neo4j (graph DB) and Qdrant (vector DB); the local agent plugins skip that and just need Node.js plus an already-installed DeepSeek Harness, OpenClaw, or Hermes, storing everything in a local SQLite file instead.
What happens if the MemOS Cloud goes down while I'm using the plugin?The cloud plugin is designed to fail open, so a temporary MemOS Cloud outage won't block or interrupt whatever task the agent is currently running.
Which agent runtimes does it plug into?Official plugins exist for OpenClaw, Hermes Agent, and DeepSeek Harness, with local plugin installers provided for macOS/Linux (shell) and Windows (PowerShell).
Where does the self-hosted service actually run?It runs as a REST API server, launched either via Docker (recommended) or directly with uvicorn, on your own machine or cluster.
Does my memory data ever leave my machine?Only if you choose the Cloud API or Cloud Plugin; the Local Plugin keeps 100% of memory on-device with no cloud dependency, using local-first SQLite storage.
What makes MemOS's memory different from a typical vector embedding store?Memory is structured as an inspectable, editable graph rather than a black-box embedding store, and it supports multi-modal content like text, images, tool traces, and personas retrieved together.
What is tiered skill evolution (L1/L2/L3)?It's how the local plugin turns raw interaction traces (L1) into learned policies (L2) and eventually crystallized world-model skills (L3), letting the agent reuse experience across tasks instead of just storing raw logs.
How good is MemOS compared to other memory products?On the OmniMemEval benchmark it leads 14 commercial memory products, scoring 88.83 on LoCoMo and 89.20 on LongMemEval, and it helped OpenClaw raise average task completion from 36.63% to 50.87% across five agent tasks.
What's the Memory Viewer?It's a dashboard bundled with the local plugin that lets you inspect and browse the stored memories, traces, and skills on your own machine.
What are similar projects?EverOS, brigade, OpenViking, Raven, Memori, m_flow, ruflo, mem0
Which topics is it in?neo4j, graph-database, self-evolving, hermes, memory-management, long-term-memory, vector-database, openclaw, dsh, agent-memory, dsh-plugin, memory
Creator
MemTensor
Size
72.2 MB
Stars
11.9K
Updated
CommitSep 22Releasev2.0.34Sep 23
Age
1y
Commits · 90 Days