# MemOS

> Provides local four-layer long-term memory for DeepSeek Harness (L1 trajectory / L2 strategy / L3 world model / skills), with automatic retrieval each user turn and support for registering six memory tools.

## Metadata

- Author: [@MemTensor](https://github.com/MemTensor)
- Repo: <https://github.com/MemTensor/MemOS.git>
- GitHub: [MemTensor/MemOS](https://github.com/MemTensor/MemOS)
- Stars: 10,843
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://memos.openmem.net>
- Topics: `agent`, `agentic-ai`, `ai`, `ai-agents`, `chatgpt`, `claude`, `deepseek-harness`, `dsh-plugin`, `hermes`, `llm`, `long-term-memory`, `mcp`, `memory`, `memory-management`, `openclaw`, `rag`, `self-evolving`, `self-hosted`, `skills`, `token-savings`
- Forks: 999
- Open Issues: 74
- Last push: 2026-08-20T14:15:01.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:MemTensor/MemOS/apps/memos-local-plugin
```

## Wiki

## 一句话定位
MemOS 为 DeepSeek Harness 注入本地优先的长期记忆能力：通过 SQLite 把每轮对话、工具结果、用户反馈沉淀为可检索的四层记忆，并在每个用户轮次自动把相关历史回填到上下文，让 DSH 具备跨会话的连续性。

## 核心能力
- 在每个被接受的非空用户轮次开始时执行一次有上限的自动检索，把相关历史以 `<memos_context>` 形式注入到模型提示中
- 异步捕获对话轮次、工具调用与代码执行结果，写入本地 SQLite 数据库
- 注册六个面向模型调用的记忆工具（`memos_search` / `memos_get` / `memos_timeline` / `memos_environment` / `memos_skill_list` / `memos_skill_get`），供模型主动查询或加载更详细的历史
- 提供基于本地 HTTP/SSE 的 Viewer 面板（默认 `127.0.0.1:18801`），可视化浏览和编辑记忆数据
- 自动复用宿主 DSH 已配置的模型与凭据作为辅助 LLM（如摘要、反思），无需重复配置 API Key
- 通过 L1 轨迹 / L2 策略 / L3 世界模型 / 技能 四层结构，从历史中归纳可复用的子任务策略并固化为可调用技能

## 技术实现
- **语言**: TypeScript（ESM 模块）
- **关键依赖**: `@deepseek-ai/cordis`（Cordis 注入容器）、`better-sqlite3`（本地存储）、`@huggingface/transformers`（本地向量嵌入）、`@preact/signals` + Vite Viewer（面板 UI）
- **架构模式**: 以 Cordis bundle 形式注入宿主进程；不启动独立守护进程、不走 JSON-RPC sidecar；通过 `agent/pre-step` / `session/event` / `session/disposed` 等宿主事件钩子串联自动检索与后台捕获，并通过 DSH 的 `tools` 服务注册记忆工具
- **入口文件**: `apps/memos-local-plugin/adapters/deepseek-harness/index.ts`（apply 钩子），由 `cordis.patch.yml` 注入到 Cordis bundle 栈

## 适用场景
当用户希望 DeepSeek Harness 的对话能够在多次会话之间保持上下文连续性，或者希望把项目知识、工具调用结果沉淀为可复用的私有记忆时使用。它特别适合长周期项目协作、个人知识库累积、以及需要让模型记住用户偏好与历史决策的工作流。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | >=0.1.0-rc.5 <0.2.0 | 宿主平台，DSH 仍在开发者预览，跨预览版可能需调整适配器 |
| Node.js | ^22.19.0 \|\| >=24.0.0 | DSH 0.1.0-rc.5 的硬性要求，覆盖包自身声明的 >=20.0.0 |
| pnpm | 11.7.0 | 用于原生依赖构建脚本审批；一键安装器在缺失时会临时下载，结束后清理 |
| 平台 | macOS / Linux | 一键安装脚本仅支持 macOS+Linux；Windows 用户可走 DSH 原生 `dsh plugin` 流 |
| 原生模块 | better-sqlite3、onnxruntime-node、esbuild、sharp | 均为 pnpm 11 需要在 `pnpm-workspace.yaml` 中显式 allowBuilds 的构建脚本包 |

## 安装方式
```bash
dsh plugin --profile web add github:MemTensor/MemOS/apps/memos-local-plugin
```

安装完成后需重启当前 DSH profile（`Ctrl+C`/`SIGINT` 或 `SIGTERM` 后再次启动）才能使新 bundle 生效。

## 配置项
插件通过 Cordis 的 `memos-local-memory` 行接收配置，可直接修改 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 覆盖默认值。注意：DSH 的 patch 层是整体替换 `config`，覆盖时需要保留全部字段。

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `enabled` | boolean | 是否挂载该适配器；关闭后插件完全不生效 | `true` |
| `profileId` | string | 命名空间回退标识；带 `agentPreset` 的会话会以会话值为准 | `default` |
| `home` | string | 运行时根目录；留空时为 `$DSH_HOME/memos-plugin/`（默认 `~/.dsh/memos-plugin/`） | `""` |
| `recallEnabled` | boolean | 是否对每个被接受的非空用户轮次执行自动检索；同轮重复进入会去重 | `true` |
| `captureEnabled` | boolean | 是否在轮次与工具完成后异步写入数据库 | `true` |
| `toolsEnabled` | boolean | 是否注册六个 `memos_*` 工具供模型调用；关闭后只能靠自动检索 | `true` |
| `hostLlmEnabled` | boolean | 是否在 MemOS 未显式配置 LLM 时复用 DSH 已配置的模型与凭据 | `true` |
| `viewerEnabled` | boolean | 是否启用本地 HTTP/SSE Viewer；关闭后只有无头记忆运行时 | `true` |
| `viewerPort` | number | Viewer 监听端口（1–65535），多 profile 共存需分配不同端口 | `18801` |
| `recallTimeoutMs` | number | 自动检索与 `memos_search` 共享的请求超时（毫秒，最小 100）；实际生效上限 3000ms | `3000` |
| `contextMaxChars` | number | 注入到模型的 `<memos_context>` 内容上限（最小 256） | `6000` |
| `toolResultMaxChars` | number | 记忆工具返回给模型的结果体上限（最小 128） | `1200` |
| `failOnStartupError` | boolean | 启动失败时是否中断 DSH profile 启动；默认只记警告继续运行 | `false` |

## 常见问题

**Q: 卸载插件会一并删除记忆数据吗？**

A: 不会。`dsh plugin remove` 只移除依赖与 bundle 层，运行时目录（`$DSH_HOME/memos-plugin/`）下的 `data/`、`skills/`、`config.yaml` 会保留下来供重新安装时复用；只有手动删除目录才会清空记忆。

**Q: 安装后是否需要单独配置 API Key？**

A: 默认情况下 MemOS 会复用宿主 DSH 已配置的模型凭据，无需在 MemOS 中重复填写；只有在 `config.yaml` 显式设置了非空的 `llm.provider` 时，才会使用该 provider 自身的凭据。

**Q: 升级插件版本或调整 `config.yaml` 后需要做什么？**

A: 需要重启当前 DSH profile 才能生效；DSH 不会在运行中自动发现新安装的包，导入的模块也会在进程生命周期内被缓存。Viewer 内的 Settings 保存 `config.yaml` 也会提示需要手动重启宿主。

**Q: 自动检索每次都会触发吗？问候语会被跳过吗？**

A: 不会跳过。所有被接受的非空用户轮次（含 `hello` 等问候语，以及恢复的会话与 fork）都会触发一次自动检索；同轮重复进入会做去重，插件与工具生成的消息不会触发。

**Q: Viewer 面板能远程访问吗？**

A: 不能。Viewer 仅绑定 `127.0.0.1` 或 `localhost` 的回环地址，配置文件中 `viewer.bindHost` 设置为非回环地址会被拒绝；不要把回环端口放到反向代理或隧道后。Viewer 没有内置身份认证，开启密码保护需要写入 `.auth.json`。

**Q: 多 DSH profile 同时启用 Viewer 会有冲突吗？**

A: 会。多 profile 不能共用同一个 Viewer 端口，需要分配不同的 `viewerPort` 或仅在一个 profile 中启用 Viewer；不同 profile 共享同一运行时目录时会共用底层记忆，浏览器 cookie 在同主机不同端口间共享，注意登录态互相覆盖。

## 上手难度
入门 — 仅需一条 `dsh plugin` 安装命令即可获得自动检索能力，无需手工配置 API Key 或数据库；进阶用户可按需调整 Cordis 配置项或 `config.yaml` 中的 LLM、embedder、viewer 等设置。

## 已知问题与限制
- **DSH 仍在开发者预览**：适配器针对 DSH 0.1.0-rc.5/rc.6 验证，跨预览版的破坏性变更可能让插件失效
- **后台队列与重启间隙的捕获缺口**：自动检索从不等待上一轮的捕获、关系分类或意图分类；正常 SIGINT/SIGTERM 时 Cordis 会尝试 bounded drain，但 SIGKILL、崩溃或预算耗尽都可能留下未落库的一轮
- **Viewer 仅本地**：默认监听 `127.0.0.1:18801`，不支持远程访问；多 profile 不能共享同一端口，浏览器 cookie 跨端口共享会互相覆盖登录态
- **JSON 输出是提示工程而非强制 schema**：DSH 当前没有 provider-neutral 的强制 JSON/Schema 输出，MemOS 在 prompt 内提供 JSON 契约并在本地解析，超时/截断/格式错误会触发失败回退
- **预请求阶段的路由边界**：每轮自动检索跑在 DSH 关闭该轮 `agent/request` 之前，因此只能读到上一次持久化的请求路由；如果不存在则使用 agent 公开默认
- **背景恢复没有归属路由**：在启用 L2/L3/Skill 结晶的全量模式下，启动期的 stale recovery 与 10 分钟 dirty-episode rescore 不归属于任何 DSH 请求；当 MemOS provider 为 `host` 时这两个后台任务会被禁用
- **依赖构建脚本需要审批**：首次安装 `2.0.16-beta.1` 等版本时 pnpm 11 会拦截原生模块构建脚本，需要在 `pnpm-workspace.yaml` 中明确允许 `better-sqlite3`、`esbuild`、`onnxruntime-node`、`sharp`；`protobufjs` 与 MemOS 自带的 postinstall 提示脚本不应允许
- **不要降级 Transformers.js**：4.x 之前的 3.x / ONNX Runtime 1.21 在 macOS 上 DSH 调用 `process.exit()` 时存在析构崩溃，使用本地嵌入的 profile 不能降级该组合

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [MemOS](https://deepseek-plugin.org/plugins/MemTensor/MemOS/apps/memos-local-plugin)
Wiki generated by AI (model: `MiniMax-M3`)