Skip to content
Back to search

MindMemOS

简体中文 │ Website │ API Docs │ PYPI SDK │ Deployment Guide

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mindscale-noah/MindMemOS with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mindscale-noah/MindMemOS'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mindscale-noah--mindmemos/badge.svg)](/listings/mindscale-noah--mindmemos)

HTML

<a href="/listings/mindscale-noah--mindmemos"><img src="/api/listings/mindscale-noah--mindmemos/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

MindMemOS offers **two deployment modes** (official cloud service, local self-hosting) and **three access methods** (HTTP API, Python SDK / CLI, agent plugin). Any combination works — server and client speak the same protocol:

| Access Method | Use Case | Cloud base_url | Local base_url | | :--- | :--- | :--- | :--- | | [HTTP API](https://mindmemos.cn/api-docs) | Call directly from business apps | `https://mindmemos.cn` | `http://127.0.0.1:8000` | | [Python SDK / CLI](https://pypi.org/project/mindmemos-sdk/) | Integrate into business apps | `https://mindmemos.cn` | `http://127.0.0.1:8000` | | [OpenClaw Plugin](https://www.npmjs.com/package/@mindmemos/openclaw-plugin) | Agent auto-recalls / writes memory | `https://mindmemos.cn` | `http://127.0.0.1:8000` | | [DeepSeek Harness Plugin](https://www.npmjs.com/package/@mindmemos/deepseek-harness-plugin) | Agent auto-recalls / writes memory (dsh) | `https://mindmemos.cn` | `http://127.0.0.1:8000` |

To try it without deploying, use the official cloud service (request an API key on the [website](https://mindmemos.cn)); for on-premises or offline use, start with Local Deployment below.

1. Local Deployment

MindMemOS uses `uv` to manage dependencies and run local commands. For detailed configuration instructions, see [docs/deploy/instruction.md](docs/deploy/instruction.md).

1.1 Prepare Configuration Files

cp .env.example .env
cp config/mindmemos/dev.example.yaml config/mindmemos/dev.yaml

Before startup, configure at least the following three model routers in `config/mindmemos/dev.yaml`:

- `chat_model_router`: supports memory extraction, Skill evolution, and other generation tasks. - `embed_model_router`: generates semantic embeddings; make sure its dimensions match the Qdrant dimension configuration. - `rerank_model_router`: optional; reranks memory retrieval results.

The schema memory-extraction flow is versioned: `algo_config.add.schema.version` defaults to `v2` (rule-based graph fusion) and can be pinned to `v1` (develop-compatible flow) per project. Storage is compatible in both directions; see the deployment guide for binding and effective timing.

Configure an API key and its bound `project_id` in `config/mindmemos/api_keys.yaml`.

1.2 Start the Service

Start the local service:

make dev

`make dev` starts the full Docker dependency stack before starting FastAPI.

To start only core dependencies:

make dev-core          # Qdrant + Neo4j + Kafka
make db-observability  # Qdrant + Neo4j + Kafka + ClickHouse + OTel + Grafana

The default local service port is 8000:

FastAPI:   http://127.0.0.1:8000

Stop the local service:

make dev-down

2. Access Methods

Cloud and local self-hosting use the same access protocol. Local keys come from `config/mindmemos/api_keys.yaml`; cloud keys are obtained from the [website](https://mindmemos.cn).

2.1 HTTP API

HTTP is the base access method — the SDK and plugins also talk HTTP underneath. Once the service is up, first use curl to verify the endpoints work, then wire up your business logic. Define the address and key before calling (pick local or cloud):

export BASE_URL=http://127.0.0.1:8000   # Local self-host; change to https://mindmemos.cn for cloud
export API_KEY=dev-api-key-001          # Local example key; use a website-issued key for cloud

Add a memory:

curl -sS -X POST "$BASE_URL/v1/memory/add" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "u_123",
    "messages": [{"role": "user", "content": "I like iced Americanos."}]
  }'

Search memories:

curl -sS -X POST "$BASE_URL/v1/memory/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What kind of coffee does the user like?", "top_k": 3}'

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 494 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="./assets/mindmemos-readme-hero.png" alt="MindMemOS Memory For AI Agents">
  3. </p>
  4. <p align="center">
  5. <a href="https://mindmemos.cn">
  6. <img src="https://img.shields.io/badge/Website-mindmemos.cn-0A66C2?labelColor=gray&logo=googlechrome&logoColor=white" alt="MindMemOS Website">
  7. </a>
  8. <a href="https://mindmemos.cn/#/api-docs">
  9. <img src="https://img.shields.io/badge/FastAPI-Docs-009688?labelColor=gray&logo=fastapi&logoColor=white" alt="MindMemOS FastAPI Docs">
  10. </a>
  11. <a href="https://pypi.org/project/mindmemos-sdk/">
  12. <img src="https://img.shields.io/pypi/v/mindmemos-sdk?color=%2334D058&label=pypi%20sdk&labelColor=gray&logo=pypi&logoColor=white" alt="MindMemOS SDK PyPI version">
  13. </a>
  14. <a href="https://www.npmjs.com/package/@mindmemos/openclaw-plugin">
  15. <img src="https://img.shields.io/npm/v/%40mindmemos%2Fopenclaw-plugin?label=npm%20plugin&labelColor=gray&logo=npm&logoColor=white" alt="MindMemOS OpenClaw Plugin npm version">
  16. </a>
  17. <a href="https://www.npmjs.com/package/@mindmemos/deepseek-harness-plugin">
  18. <img src="https://img.shields.io/npm/v/%40mindmemos%2Fdeepseek-harness-plugin?label=dsh%20plugin&labelColor=gray&logo=npm&logoColor=white" alt="MindMemOS DeepSeek Harness Plugin npm version">
  19. </a>
  20. <a href="https://arxiv.org/abs/2608.12428">
  21. <img src="https://img.shields.io/badge/arXiv-2608.12428-B31B1B?labelColor=gray&logo=arxiv&logoColor=white" alt="MindMemOS arXiv paper">
  22. </a>
  23. <a href="#license">
  24. <img src="https://img.shields.io/badge/license-MIT-blue.svg?labelColor=gray" alt="MIT License">
  25. </a>
  26. </p>
  27. <p align="center">
  28. <strong><a href="README_ZH.md">简体中文</a></strong>
  29. &nbsp;&nbsp;│&nbsp;&nbsp;
  30. <strong><a href="https://mindmemos.cn">Website</a></strong>
  31. &nbsp;&nbsp;│&nbsp;&nbsp;
  32. <strong><a href="https://mindmemos.cn/#/api-docs">API Docs</a></strong>
  33. &nbsp;&nbsp;│&nbsp;&nbsp;
  34. <strong><a href="https://pypi.org/project/mindmemos-sdk/">PYPI SDK</a></strong>
  35. &nbsp;&nbsp;│&nbsp;&nbsp;
  36. <strong><a href="docs/deploy/instruction.md">Deployment Guide</a></strong>
  37. </p>
  38. <p align="center">
  39. Accurately remember user and task context and reuse it across agents; evolve memory through ongoing interactions, automatically distill Skills, and connect with file-based knowledge systems so experience truly becomes capability.
  40. </p>
  41. > ⭐ **Star us on GitHub to automatically upgrade to a Pro quota membership.**
  42. ## 📰 News
  43. - **2026-10-31**: We released the multimodal mode of MindMemOS — it significantly outperforms multiple strong baselines on the MemEye and Mem-Gallery benchmarks. Full comparison in the multimodal benchmark section below.
  44. - **2026-08-18**: We released the [DeepSeek Harness Plugin](https://www.npmjs.com/package/@mindmemos/deepseek-harness-plugin), letting DeepSeek Harness (dsh) agents automatically recall and write MindMemOS memories.
  45. - **2026-08-14**: We released the [MindMemOS 1.0 technical report](https://arxiv.org/abs/2608.12428), *MindMemOS: A Portable and Self-Evolving Memory Operating Layer for AI Agents*.
  46. - **2026-07-17**: MindMemOS integrated with [LLM4AD_NEXT](https://github.com/Optima-CityU/LLM4AD_Next), providing searchable long-term memory for algorithm design tasks and enabling the accumulation and reuse of cross-task experience, domain knowledge, and constraints.
  47. - **2026-06-30**: MindMemOS was officially released!
  48. ## 🌟 Core Features
  49. - **Portable across agents**: Persist user profiles, preferences, project facts, tool experience, and skill candidates as reusable assets, allowing OpenClaw, Hermes, Claude Code, OpenHands, and other agents to share or transfer the same long-term memory.
  50. - **Self-evolving memory system**: Continuously improve memory quality through schema learning, dreaming, and feedback by automatically learning frequent memory patterns, consolidating memories offline, and using interaction corrections to optimize add/search workflows.
  51. - **Multimodal memory**: Images ride alongside text in vanilla `add`/`search` under `algo_config.multimodal.mode` (`off`/`basic`/`enhanced`, per-project overridable) — store originals in S3/MinIO (the only image backend), index them with a multimodal embedding model (`mm_embed_model_router`, SigLIP2-compatible), and in `enhanced` extract visual facts with a VLM and retrieve through a multimodal agent. Image hits carry `metadata.image_url` — a permanent mirror URL when configured, else a short-lived presigned URL on S3/MinIO, else an equally short-lived signed proxy URL that needs no API key — plus `metadata.blob_id` for re-download. Disabled by default (`off`), with byte-identical text-only behavior.
  52. - **Memory and Skills integration**: Experience memories can be distilled into skill candidates, while skill execution results, failure traces, and user feedback flow back into the memory system to drive continuous skill evolution.
  53. - **Plugin integrations**: Connect MindMemOS to different agents and workflows through plugins that retrieve and inject relevant memories before interactions and automatically write conversations back afterward. The [OpenClaw Plugin](https://www.npmjs.com/package/@mindmemos/openclaw-plugin) and [DeepSeek Harness Plugin](https://www.npmjs.com/package/@mindmemos/deepseek-harness-plugin) are currently available, with more integrations in progress.
  54. <p align="center">
  55. <img src="./assets/mindmemos-benchmark-overview.png" alt="MindMemOS benchmark results overview">
  56. </p>
  57. ## 🚀 Quick Start
  58. MindMemOS offers **two deployment modes** (official cloud service, local self-hosting) and **three access methods** (HTTP API, Python SDK / CLI, agent plugin). Any combination works — server and client speak the same protocol:
  59. | Access Method | Use Case | Cloud base_url | Local base_url |
  60. | :--- | :--- | :--- | :--- |
  61. | [HTTP API](https://mindmemos.cn/api-docs) | Call directly from business apps | `https://mindmemos.cn` | `http://127.0.0.1:8000` |
  62. | [Python SDK / CLI](https://pypi.org/project/mindmemos-sdk/) | Integrate into business apps | `https://mindmemos.cn` | `http://127.0.0.1:8000` |
  63. | [OpenClaw Plugin](https://www.npmjs.com/package/@mindmemos/openclaw-plugin) | Agent auto-recalls / writes memory | `https://mindmemos.cn` | `http://127.0.0.1:8000` |
  64. | [DeepSeek Harness Plugin](https://www.npmjs.com/package/@mindmemos/deepseek-harness-plugin) | Agent auto-recalls / writes memory (dsh) | `https://mindmemos.cn` | `http://127.0.0.1:8000` |
  65. To try it without deploying, use the official cloud service (request an API key on the [website](https://mindmemos.cn)); for on-premises or offline use, start with Local Deployment below.
  66. ### 1. Local Deployment
  67. MindMemOS uses `uv` to manage dependencies and run local commands. For detailed configuration instructions, see [docs/deploy/instruction.md](docs/deploy/instruction.md).
  68. #### 1.1 Prepare Configuration Files
  69. ```bash
  70. cp .env.example .env
  71. cp config/mindmemos/dev.example.yaml config/mindmemos/dev.yaml
  72. ```
  73. Before startup, configure at least the following three model routers in `config/mindmemos/dev.yaml`:
  74. - `chat_model_router`: supports memory extraction, Skill evolution, and other generation tasks.
  75. - `embed_model_router`: generates semantic embeddings; make sure its dimensions match the Qdrant dimension configuration.
  76. - `rerank_model_router`: optional; reranks memory retrieval results.
  77. The schema memory-extraction flow is versioned: `algo_config.add.schema.version` defaults to `v2` (rule-based graph fusion) and can be pinned to `v1` (develop-compatible flow) per project. Storage is compatible in both directions; see the deployment guide for binding and effective timing.
  78. Configure an API key and its bound `project_id` in `config/mindmemos/api_keys.yaml`.
  79. #### 1.2 Start the Service
  80. Start the local service:
  81. ```bash
  82. make dev
  83. ```
  84. `make dev` starts the full Docker dependency stack before starting FastAPI.
  85. To start only core dependencies:
  86. ```bash
  87. make dev-core # Qdrant + Neo4j + Kafka
  88. make db-observability # Qdrant + Neo4j + Kafka + ClickHouse + OTel + Grafana + MinIO
  89. ```
  90. `make dev` / `make db` also start MinIO (the S3-compatible store for multimodal images) with its bucket bootstrap; pass `MINIO=0` to skip it for a text-only layout — images always need MinIO, so that layout also sets `algo_config.multimodal.mode: "off"`. `dev-down` / `db-clean` with `MINIO=0` leave the MinIO container and its volume untouched (see the [deploy guide](docs/deploy/instruction.md)).
  91. The default local service port is 8000:
  92. ```text
  93. FastAPI: http://127.0.0.1:8000
  94. ```
  95. Stop the local service:
  96. ```bash
  97. make dev-down
  98. ```
  99. ### 2. Access Methods
  100. Cloud and local self-hosting use the same access protocol. Local keys come from `config/mindmemos/api_keys.yaml`; cloud keys are obtained from the [website](https://mindmemos.cn).
  101. #### 2.1 HTTP API
  102. HTTP is the base access method — the SDK and plugins also talk HTTP underneath. Once the service is up, first use curl to verify the endpoints work, then wire up your business logic. Define the address and key before calling (pick local or cloud):
  103. ```bash
  104. export BASE_URL=http://127.0.0.1:8000 # Local self-host; change to https://mindmemos.cn for cloud
  105. export API_KEY=dev-api-key-001 # Local example key; use a website-issued key for cloud
  106. ```
  107. Add a memory:
  108. ```bash
  109. curl -sS -X POST "$BASE_URL/v1/memory/add" \
  110. -H "Authorization: Bearer $API_KEY" \
  111. -H "Content-Type: application/json" \
  112. -d '{
  113. "user_id": "u_123",
  114. "messages": [{"role": "user", "content": "I like iced Americanos."}]
  115. }'
  116. ```
  117. Search memories:
  118. ```bash
  119. curl -sS -X POST "$BASE_URL/v1/memory/search" \
  120. -H "Authorization: Bearer $API_KEY" \
  121. -H "Content-Type: application/json" \
  122. -d '{"query": "What kind of coffee does the user like?", "top_k": 3}'
  123. ```
  124. Multimodal projects accept images on both calls (the server-side mode requirement is in the
  125. [config docs](docs/config/README.md)); image hits answer with `metadata.image_url` and
  126. `metadata.blob_id`:
  127. ```bash
  128. curl -sS -X POST "$BASE_URL/v1/memory/search" \
  129. -H "Authorization: Bearer $API_KEY" \
  130. -H "Content-Type: application/json" \
  131. -d '{"query": "Describe the user desk setup", "top_k": 3, "multimodal": true}'
  132. ```
  133. A `code` of `ok` with readable memory content means the access works. curl is just a smoke-test helper; the shown format is for bash. Other environments / languages and the remaining endpoints (get / list / delete / update / feedback / dreaming / skills, etc.) are all covered in the [API docs](https://mindmemos.cn/api-docs).
  134. #### 2.2 Configure the SDK
  135. Install the Python SDK:
  136. ```bash
  137. pip install mindmemos-sdk
  138. ```
  139. Run the authentication command and configure the service address, API key, and default user when prompted:
  140. ```bash
  141. mindmemos auth
  142. ```
  143. | Setting | Local Service | Cloud Service |
  144. | :--- | :--- | :--- |
  145. | `base_url` | `http://127.0.0.1:8000` | `https://mindmemos.cn` |
  146. | `api_key` | An enabled API key from `config/mindmemos/api_keys.yaml` | An API key obtained from the [MindMemOS website](https://mindmemos.cn) |
  147. | `user_id` | A stable identifier for the current end user, such as `u_123` | A stable identifier for the current end user, such as `u_123` |
  148. The configuration is saved to `~/.mindmemos/settings.json`. Check the current configuration with:
  149. ```bash
  150. mindmemos config show
  151. ```
  152. The local service automatically determines the `project_id` and memory algorithm from the API key, so SDK calls do not need to pass `project_id`. The `user_id` distinguishes users within the same project and can be overridden in an individual `add` or `search` call.
  153. If you prefer not to use the local configuration file, pass connection parameters explicitly when creating the client:
  154. ```python
  155. from mindmemos_sdk import MindMemOSClient
  156. with MindMemOSClient(
  157. base_url="http://127.0.0.1:8000",
  158. api_key="<api_key>",
  159. user_id="u_123",
  160. ) as client:
  161. ...
  162. ```
  163. Explicit parameters take precedence over values in `~/.mindmemos/settings.json`.
  164. #### 2.3 Add and Search Memories with the SDK
  165. After completing the configuration above, `MindMemOSClient()` automatically reads the service address, API key, and default `user_id`. The SDK adds the authentication header automatically, so there is no need to construct HTTP requests manually:
  166. ```python
  167. from mindmemos_sdk import DialogueMessage, MindMemOSClient
  168. with MindMemOSClient() as client:
  169. add_result = client.memory.add(
  170. messages=[
  171. DialogueMessage(
  172. role="user",
  173. content="I like iced Americanos.",
  174. )
  175. ],
  176. mode="sync",
  177. )
  178. for item in add_result.memories:
  179. print(item.operation, item.memory_id, item.content)
  180. search_result = client.memory.search(
  181. "What kind of coffee does the user like?",
  182. top_k=5,
  183. search_strategy="fast",
  184. # token_budget=2000, # optional: strict token budget (enables retention)
  185. )
  186. for memory in search_result.memories:
  187. print(memory.id, memory.memory)
  188. ```
  189. Trigger cloud evolution for a registered Skill:
  190. ```python
  191. from mindmemos_sdk import MindMemOSClient
  192. with MindMemOSClient() as client:
  193. result = client.skills.evolve("my-skill", mode="sync")
  194. print("evolved:", result.evolved)
  195. print("pending:", result.pending_count)
  196. print("threshold:", result.threshold)
  197. print("new versions:", result.new_version_ids)
  198. ```
  199. Local and cloud services use the same SDK call pattern. To switch between them, reconfigure only the `base_url` and corresponding API key.
  200. #### 2.4 Use the CLI
  201. After running `mindmemos auth`, you can also add and search memories directly with the CLI included in the SDK:
  202. ```bash
  203. mindmemos memory add --content "I like iced Americanos"
  204. mindmemos memory search "coffee preferences" --top-k 5
  205. ```
  206. The `memory` subcommand also supports get / update / delete / feedback / dreaming, and the `skill` subcommand supports register / list / evolve / push / pull / history and more. For the full command list, parameter reference, and troubleshooting, see the [CLI Guide](docs/cli/instruction.md).
  207. #### 2.5 OpenClaw Plugin
  208. **Installing via our [`mindmemos-cli` skill](skills/mindmemos-cli/SKILL.md) is recommended**: deploy `skills/mindmemos-cli/` to your agent's skills directory and let the agent follow its instructions. The skill's [reference docs](skills/mindmemos-cli/references/openclaw-plugin.md) cover installation, permissions, and common troubleshooting.
  209. <details>
  210. <summary><b>Manual installation (not recommended)</b></summary>
  211. **First install the SDK and complete `auth` configuration (required)**: the plugin communicates with the local machine through the `mindmemos` CLI, so you must install the Python SDK first and make sure the `mindmemos` command is available:
  212. ```bash
  213. pip install mindmemos-sdk # or: uv add mindmemos-sdk
  214. mindmemos --version # confirm the command is available
  215. ```
  216. Then configure `base_url`, API key, and `user_id` with `mindmemos auth` (pointing at either the cloud or a local service):
  217. ```bash
  218. mindmemos auth
  219. mindmemos config show # confirm the configuration took effect
  220. ```
  221. > Skipping these two steps before installing the plugin causes the logs to error out (`mindmemos` command not found / auth not configured), and the plugin will not be able to read or write memories properly.
  222. Install and enable the plugin:
  223. ```bash
  224. openclaw plugins install @mindmemos/openclaw-plugin
  225. openclaw plugins enable mindmemos-memory
  226. ```
  227. (`@mindmemos/openclaw-plugin` is the npm package name; `mindmemos-memory` is the plugin id.) Manual installation easily runs into two pitfalls:
  228. - **Write permission (required)**: the plugin's `agent_end` write hook needs `allowConversationAccess`; otherwise everything looks fine, but memories are never actually stored after a turn:
  229. ```bash
  230. openclaw config set plugins.entries.mindmemos-memory.hooks.allowConversationAccess true
  231. openclaw gateway restart
  232. ```
  233. - **`cli` PATH**: an OpenClaw process launched from the GUI does not inherit your terminal PATH. Set `cli` to the absolute path of `mindmemos` (e.g. the output of `which mindmemos`), or the logs will report `ENOENT`. `cli` must be a single executable — a multi-word value such as `uv run mindmemos` does not work; point it at an executable wrapper script if you need one.
  234. Once installed, enabled, and the gateway restarted, the plugin recalls and injects relevant memories before each user turn and writes the conversation back automatically when the turn ends.
  235. Full commands, configuration options, and troubleshooting are in the [OpenClaw plugin integration docs](skills/mindmemos-cli/references/openclaw-plugin.md).
  236. </details>
  237. #### 2.6 DeepSeek Harness Plugin
  238. **Installing via our [`mindmemos-cli` skill](skills/mindmemos-cli/SKILL.md) is recommended**: deploy `skills/mindmemos-cli/` to your agent's skills directory and let the agent follow its instructions. The skill's [reference docs](skills/mindmemos-cli/references/deepseek-harness-plugin.md) cover installation and common troubleshooting.
  239. <details>
  240. <summary><b>Manual installation (not recommended)</b></summary>
  241. **First install the SDK and complete `auth` configuration (required)**: the plugin communicates with the local machine through the `mindmemos` CLI, so you must install the Python SDK first and make sure the `mindmemos` command is available:
  242. ```bash
  243. pip install mindmemos-sdk # or: uv add mindmemos-sdk
  244. mindmemos --version # confirm the command is available
  245. ```
  246. Then configure `base_url`, API key, and `user_id` with `mindmemos auth` (pointing at either the cloud or a local service):
  247. ```bash
  248. mindmemos auth
  249. mindmemos config show # confirm the configuration took effect
  250. ```
  251. > Skipping these two steps before installing the plugin causes the logs to error out (`mindmemos` command not found / auth not configured), and the plugin will not be able to read or write memories properly.
  252. Install the plugin into a dsh profile (`dsh plugin` forwards to pnpm and installs the package into the profile's `node_modules`):
  253. ```bash
  254. dsh plugin --profile <name> add @mindmemos/deepseek-harness-plugin
  255. ```
  256. (`@mindmemos/deepseek-harness-plugin` is the npm package name; `mindmemos-memory` is the plugin id.) dsh composes plugins through layered `cordis.patch.yml` files, so register the plugin by adding an `insert` entry to the profile patch (`~/.dsh/profiles/<name>/cordis.patch.yml`):
  257. ```yaml
  258. - insert:
  259. - id: mindmemos-memory
  260. name: '@mindmemos/deepseek-harness-plugin'
  261. config:
  262. userId: alice
  263. appId: deepseek-harness
  264. ```
  265. Restart dsh with that profile. Once registered, the plugin recalls and injects relevant memories before each user turn and writes the conversation back automatically when the turn ends.
  266. Full commands, configuration options, and troubleshooting are in the [DeepSeek Harness plugin integration docs](skills/mindmemos-cli/references/deepseek-harness-plugin.md).
  267. </details>
  268. ## 📊 Benchmark
  269. ### 💬 Conversational Memory: LoCoMo
  270. - **Benchmark**: [LoCoMo](https://arxiv.org/abs/2402.17753), a mainstream benchmark for long-conversation memory covering single-hop, multi-hop, temporal, and open-domain question answering.
  271. | Method | Single-hop | Multi-hop | Temporal | Open-domain | Overall |
  272. | :--------------------------- | :--------: | :-------: | :------: | :---------: | :-----: |
  273. | Mem0 | 68.97 | 61.70 | 58.26 | 50.00 | 64.20 |
  274. | MemU | 74.91 | 72.34 | 43.61 | 54.17 | 66.67 |
  275. | MemOS | 85.37 | 79.43 | 75.08 | 64.58 | 80.76 |
  276. | Zep | 90.84 | 81.91 | 77.26 | 75.00 | 85.22 |
  277. | EverOS | 96.67 | 91.84 | 89.72 | 76.04 | 93.05 |
  278. | **MindMemOS-MindVanilla** | 92.03 | 85.82 | 83.80 | 66.67 | 87.60 |
  279. | **MindMemOS-MindSchema** | **96.79** | **93.97** | **90.34** | **82.29** | **94.03** |
  280. ### 👤 User Profile Memory: PersonaMem
  281. - **Benchmark**: [PersonaMem](https://arxiv.org/abs/2504.14225), a memory benchmark centered on user profiles and preference understanding that evaluates recall, tracking, revisiting, suggestion, recommendation, and generalization of user traits.
  282. | Method | Recall | Ack. Lat. | Trk. Evo. | Revisit | Suggest | Recom. | General. | Overall |
  283. | :----- | :----: | :-------: | :-------: | :-----: | :-----: | :-----: | :------: | :-----: |
  284. | Mem0 | 46.51 | 41.18 | 65.47 | 90.91 | 12.90 | 34.55 | 43.86 | 51.61 |
  285. | MemU | 64.34 | 64.71 | 66.20 | 87.88 | 31.18 | 67.27 | 84.21 | 65.70 |
  286. | MemOS | 53.49 | 82.35 | 66.91 | 79.80 | 41.94 | 69.09 | 75.44 | 63.67 |
  287. | EverOS | 74.42 | 64.71 | 64.03 | 85.86 | 35.48 | 65.45 | 84.21 | 67.57 |
  288. | **MindMemOS-MindVanilla** | 76.74 | 88.24 | 65.47 | 87.88 | 17.20 | 80.00 | 82.46 | 67.74 |
  289. | **MindMemOS-MindSchema** | 81.40 | 64.71 | 64.75 | 82.83 | 47.31 | 76.36 | 73.68 | 70.63 |
  290. ### 🌙 Memory Consolidation: MemoryAgentBench (FactConsolidation)
  291. - **Benchmark**: [MemoryAgentBench](https://arxiv.org/abs/2507.05257) FactConsolidation. Scores in the table are the average Substring Exact Match across four context sizes.
  292. | Method | SH score | SH archived | MH score | MH archived |
  293. |:-----------------------------------| :------: | :---------: | :------: | :---------: |
  294. | **GPT-4o-mini** | | | | |
  295. | Mem0 | 0.180 | — | 0.020 | — |
  296. | MemoRAG | 0.270 | — | 0.070 | — |
  297. | HippoRAG-v2 | 0.540 | — | 0.050 | — |
  298. | MindMemOS-MindVanilla | 0.635 | — | 0.118 | — |
  299. | **MindMemOS-MindVanilla + Dreaming** | 0.738 | 21.4% | 0.180 | 19.4% |
  300. | **GPT-5-mini** | | | | |
  301. | Infini Memory | 0.800 | — | 0.220 | — |
  302. | MindMemOS-MindVanilla | 0.900 | — | 0.190 | — |
  303. | **MindMemOS-MindVanilla + Dreaming** | 0.920 | 23.5% | 0.250 | 21.5% |
  304. ### 🖼️ Multimodal Memory: MemEye & Mem-Gallery
  305. - **Benchmarks**: [MemEye](https://huggingface.co/datasets/MemEyeBench/MemEye) (8 tasks, 742 questions — multi-turn dialogs interleaving images; EM on MCQ, BLEU-1 and LLM-Judge on open questions, macro-averaged over tasks) and [Mem-Gallery](https://huggingface.co/datasets/Ethan-Bei/Mem-Gallery) (20 tasks, 1,711 open questions; token-level F1, BLEU-1 and LLM-Judge, micro-averaged over questions).
  306. | Method | MemEye EM | MemEye B-1 | MemEye Judge | Mem-Gallery F1 | Mem-Gallery B-1 | Mem-Gallery Judge |
  307. | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
  308. | MemoryOS | 45.75 | 13.12 | 34.91 | 43.09 | 37.76 | 64.64 |
  309. | A-MEM | 49.73 | 21.11 | 38.27 | 44.08 | 38.37 | 64.35 |
  310. | SimpleMem | 50.34 | 9.42 | 42.59 | 34.73 | 28.90 | 58.33 |
  311. | HyperMem | 47.82 | 19.64 | 36.43 | 44.57 | 33.42 | 66.76 |
  312. | M2A | 52.31 | 6.31 | 44.50 | 15.04 | 10.28 | 51.81 |
  313. | MMA | 50.96 | 16.32 | 43.81 | 26.99 | 20.60 | 60.87 |
  314. | SRAG | 58.36 | **31.48** | 50.54 | 41.07 | 35.03 | 67.06 |
  315. | UniversalRAG | 60.49 | 11.23 | 52.61 | 48.36 | 41.90 | 70.63 |
  316. | **MindMemOS-MindVanilla** (text-only) | 43.03 | 20.32 | 26.26 | 38.72 | 32.59 | 70.68 |
  317. | **MindMemOS-MindVanilla + MM basic** | 59.77 | 27.02 | 47.80 | 54.73 | 47.75 | 85.06 |
  318. | **MindMemOS-MindVanilla + MM enhanced** | 63.45 | 25.49 | 50.80 | 55.66 | 48.98 | 87.06 |
  319. | **MindMemOS-MindVanilla + MM enhanced + agentic** | **65.89** | 27.09 | **53.30** | **57.06** | **50.45** | **89.14** |
  320. - **Text-only** (`mode: off`): plain vanilla without images, as the control.
  321. - **MM basic** (`mode: basic`): stores the original images and recalls them by similarity to the query with a multimodal embedding, appended after the text results; no extra LLM calls on add or search.
  322. - **MM enhanced** (`mode: enhanced`): on add, a VLM extracts a description and visual facts for every image; on search, the relevant visual facts and the evidence images linked to the recalled facts are returned as well.
  323. - **MM enhanced + agentic**: enhanced with `search_strategy: agentic` — a multimodal agent searches over several rounds and views images before submitting the evidence.
  324. Setup: `vanilla` algorithm; every row answers with `gpt-4.1-mini`; image embeddings local SigLIP2 (`siglip2-base-patch16-384`). The baseline rows are reproductions under identical conditions (mean of 3 runs; source: our team's MHG research, [arXiv:2610.29995](https://arxiv.org/abs/2610.29995)); the four MindMemOS rows are this repository's implementation (mean of 2 runs, 2026-10). Judge models differ between the groups (`gpt-4.1-mini` here vs `GPT-5.4-mini` for the baselines), so compare Judge scores within a group, not across. Step-by-step run guide: the [multimodal section](docs/eval/README.md#multimodal-memeye--mem-gallery-vanilla-multimodal-mode-off--basic--enhanced) of the evaluation guide.
  325. ### 🧠 Skill Self-Evolution: SpreadsheetBench-Verified
  326. - **Benchmark**: [SpreadsheetBench-Verified](https://huggingface.co/datasets/KAKA22/SpreadsheetBench/blob/main/spreadsheetbench_verified_400.tar.gz), a 400-task verified subset of SpreadsheetBench covering diverse real-world spreadsheet operations.
  327. | Method | Success Rate | Time / Task (s) | Agent Tokens | Evolve Tokens |
  328. | :----- | :----------: | :-------------: | :----------: | :-----------: |
  329. | No-skill | 51.3% ± 0.8% | 11.227 | 10.4M | - |
  330. | Init-skill | 48.0% ± 1.4% | 15.350 | 16.9M | - |
  331. | **MindMemOS-MindEvolve-Unsup.** | **55.3% ± 0.9%** | 15.470 | 27.3M | 5.8M |
  332. | **MindMemOS-MindEvolve-Sup.** | **57.2% ± 2.4%** | 15.631 | 25.2M | 5.5M |
  333. ## 🗺️ Coming Features
  334. - **Lite mode**: Designed around low dependencies, replaceable components, and easy embedding, with database backends, async tasks, and log storage decoupled into flexible lightweight components that support in-memory calls and simplified deployment.
  335. - **Skills system**: Govern large and redundant skill libraries and distribute them intelligently; continuously evolve and optimize skills based on real usage; automatically synthesize new skills from frequent user scenarios and refine them through offline simulation.
  336. - **File system memory**: Structure scattered knowledge from local files, documents, project artifacts, and agent outputs into searchable and connected file knowledge objects or knowledge graphs, helping agents complete user tasks more effectively.
  337. - **Agent integrations**: Continue expanding support for coding agents, OpenClaw, Codex-style workflows, and long-running multi-agent systems.
  338. ## Contributing
  339. Contributions of all kinds are welcome. Please open pull requests against the `develop` branch. After review,
  340. accepted changes will be merged into `develop`; maintainers periodically merge stable `develop` updates into `main`
  341. for release.
  342. ## 💬 Community
  343. Join the MindMemOS Feishu group for project updates, usage discussions, and community participation.
  344. <p align="center">
  345. <img src="./assets/feishu-group-small.png" alt="MindMemOS Feishu group QR code">
  346. </p>
  347. ## 📝 Citation
  348. If you find MindMemOS useful in your research, please cite our technical report:
  349. ```bibtex
  350. @misc{liang2026mindmemos,
  351. title = {MindMemOS: A Portable and Self-Evolving Memory Operating Layer for AI Agents},
  352. author = {Liang, Kaichao and Cui, Yuqi and Kong, Hao and Huang, Xinyuan and Hou, Guohaotian and Kang, Qingcan and Chen, Liang and Yin, Yiyang and Ye, Ke and Guo, Jiaquan and Chen, Da and Zeng, Lingan and Peng, Yixing and Yao, Rong and Kai, Shixiong and Yuan, Mingxuan},
  353. year = {2026},
  354. eprint = {2608.12428},
  355. archivePrefix= {arXiv},
  356. primaryClass = {cs.AI},
  357. url = {https://arxiv.org/abs/2608.12428},
  358. }
  359. ```
  360. ## 📄 License
  361. This project is open source under the MIT License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.