# EverOS

> Provides cross-session long-term memory for DeepSeek Harness, automatically retrieves local EverOS history and saves conversation logs; normal conversations remain unaffected if EverOS fails.

## Metadata

- Author: [@EverMind-AI](https://github.com/EverMind-AI)
- Repo: <https://github.com/EverMind-AI/EverOS.git>
- GitHub: [EverMind-AI/EverOS](https://github.com/EverMind-AI/EverOS)
- Stars: 12,251
- Language: Python
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://evermind.ai/everos>
- Topics: `agent-memory`, `agentic-ai`, `ai`, `chats`, `clawdbot`, `clawdbot-skill`, `deepseek-harness`, `dsh`, `dsh-plugin`, `llm`, `long-term-memory`, `mcp`, `memory`, `memory-management`, `python3`, `rag`, `skills`
- Forks: 898
- Open Issues: 73
- Last push: 2026-08-17T11:51:02.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:EverMind-AI/EverOS/examples/dsh
```

## Wiki

## 一句话定位
EverOS 为 DeepSeek Harness 提供跨会话的长期记忆，让 AI 助手记住你之前在其它会话里说过的话、做过的事。本地优先运行，所有对话轨迹保存在你自己的 EverOS 服务里。

## 核心能力
- 在每一轮用户输入开始时，自动从 EverOS 的用户轨和智能体轨并行检索历史记忆，并把命中内容附加到当前上下文
- 在每一轮对话结束时，把用户消息、助手文本、工具调用与工具结果落库到 EverOS，无需立刻触发模型抽取
- 按空闲时间、消息数、Token 数、切换会话或最长延迟等条件批量整理记忆，避免每轮都消耗抽取算力
- 检测到本机 EverOS 不可用时自动拉起一个（仅限环回地址），插件销毁时关闭自己启动的进程，不会误杀已存在的进程
- 用 `<everos_memory>` 标签把检索到的内容隔离开，反向阻止历史记忆操纵模型，且插件自身的注入不会被再次保存
- 把同一 DSH 会话的写入串行化，避免单会话内的并发写竞争，并在新会话读取前先整理旧会话以保证读到最新数据

## 技术实现
- **语言**: TypeScript
- **关键依赖**: @deepseek-ai/cordis、@deepseek-ai/dsh-agent、@deepseek-ai/schemastery、@deepseek-ai/dsh-session
- **架构模式**: 通过 `cordis.patch.yml` 注入名为 `everos-memory` 的插件；监听 `agent/pre-step`、`agent/turn-stopping`、`session/disposed` 三个 DSH 钩子驱动 Recall / Capture / Flush 三阶段
- **入口文件**: src/index.ts

## 适用场景
在多个 DSH 会话间复用上下文，例如希望 AI 记住你的代码偏好、历史项目经验或工具使用习惯。需要在本地装好 EverOS 服务（`uv tool install everos && everos init`），否则插件会尝试自动拉起一个。当处理敏感仓库时请先评估 EverOS 的存储和模型提供商配置，因为它会把对话轨迹落库。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.6+ | 由 `dsh-agent` / `dsh-llm` / `dsh-session` 三个 peer 依赖锁定在 `>=0.1.0-rc.6 <0.2.0-0` |
| Node.js | ^22.19.0 \|\| >=24.0.0 | 来自 `package.json` 的 `engines.node` 字段 |
| 平台 | 跨平台 | 全部依赖 Node.js 内置模块，无原生绑定 |
| 原生模块 | 无 | 仅使用 `node:child_process`、`node:crypto`、`node:os`、`node:path` 等内置 API |

## 安装方式
```bash
dsh plugin --profile web add github:EverMind-AI/EverOS/examples/dsh
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| baseUrl | 字符串 | EverOS 服务地址，未写协议头会自动补 `http://`，尾部 `/` 会被去掉 | `http://127.0.0.1:8000` |
| apiVersion | 字符串 | API 路由协商；`auto` 先试 v2，命中 404 再回退 v1；也允许强制 `v1` / `v2` | `auto` |
| appId | 字符串 | EverOS 应用分区标识，所有写入和检索都带上它 | `dsh` |
| projectId | 字符串 | 项目分区标识，留空则由工作目录名 + 路径哈希自动派生 | 工作目录派生 |
| userId | 字符串 | 用户记忆的所有者，留空取 `USER` / `USERNAME` 环境变量，再不行取系统账户 | 系统账户 |
| agentId | 字符串 | 智能体记忆的所有者，留空则取 DSH 智能体预设名 | DSH 预设 |
| recallMethod | 字符串 | 检索方式：`keyword` 仅需 LLM；`vector` / `hybrid` / `agentic` 需 EverOS 配齐 Embedding 与 Rerank 凭据 | `keyword` |
| queryN | 数字 | 召回查询混入的最近用户消息条数 | `3` |
| queryMaxChars | 数字 | 召回查询字符串的字符上限 | `2000` |
| recallTopK | 数字 | 每个所有者轨道（用户轨 / 智能体轨）的返回条数上限 | `5` |
| recallMaxChars | 数字 | 注入到上下文的记忆块字符上限 | `12000` |
| recallTimeoutMs | 数字 | 单次检索的超时（毫秒） | `5000` |
| captureTimeoutMs | 数字 | 落库请求和批量整理请求的超时（毫秒） | `15000` |
| captureMaxChars | 数字 | 单条消息的字符上限，超出会被截断并打上截断标记 | `50000` |
| flushIdleMs | 数字 | 捕获到一轮新事件后，空闲多久触发批量整理（毫秒） | `30000` |
| flushTokenThreshold | 数字 | 累积 Token 估算达到此值立刻触发批量整理 | `12000` |
| flushMessageThreshold | 数字 | 累积消息条数达到此值立刻触发批量整理 | `50` |
| flushMaxDelayMs | 数字 | 非空缓冲区最长保留多久（毫秒） | `300000` |
| flushOnSessionSwitch | 布尔 | 切到新会话前是否先把同工作区的其它待整理会话整理完，保证读到的记忆是最新的 | `true` |
| autoStart | 布尔 | 检测到本机 EverOS 不可用时是否自动拉起（仅限环回地址） | `true` |
| startCommand | 字符串 | 自动拉起 EverOS 的命令行，按空白拆分、不走 shell | `everos server start` |
| everosDir | 字符串 | 自动拉起命令的工作目录 | 进程目录 |
| readinessTimeoutMs | 数字 | 自动拉起后等待 EverOS 健康检查通过的总超时（毫秒） | `60000` |
| readinessIntervalMs | 数字 | 自动拉起时的健康检查间隔（毫秒） | `1000` |

> 兼容写法：以上所有字段也支持通过 `EVEROS_DSH_*` 环境变量设置（详见 README），或在 DSH Cordis profile 的 `config` 块里以 YAML 形式写入。

## 常见问题

**Q: 装上就能直接用吗？**

A: 还需要本机已经安装并初始化好 EverOS（`uv tool install everos && everos init`）。否则插件会尝试自动拉起一个本地进程（仅限环回地址）。EverOS 1.2.3 支持关键字召回这条基础路径；想用批量落库优化则需要更新到带 `defer_extraction` 能力的 EverOS 版本。

**Q: 数据存在哪里？会不会自动上传到云端？**

A: 原始对话数据保存在本地 EverOS 服务（默认 `~/.everos/`）。但 EverOS 本身可能按你配置的提供商调用云端 LLM / Embedding / Rerank，所以"是否上云"取决于你给 EverOS 配了什么，而不是本插件。

**Q: EverOS 出问题会不会让对话直接崩？**

A: 不会。检索、落库、整理三段路径都做了 fail-open 保护：失败时只写一条 warn 日志，不会拒绝 DSH 的任何步骤或用户轮次。

**Q: 想撤回一条记忆怎么办？**

A: 目前没有内置的"忘记"或"管理"工具，召回路径也没有管理界面。要清理记忆只能直接操作 EverOS 的存储目录，或等待后续版本提供显式工具。

**Q: 想加快检索怎么办？**

A: 如果你已经给 EverOS 配置好了 Embedding 和 Rerank 凭据，可以把 `recallMethod` 改成 `vector` 或 `hybrid`，同时把 `recallTimeoutMs` 适当调小。仅 LLM 的环境务必保持 `keyword`，否则会因为缺能力而报错。

**Q: 怎么覆盖默认配置？**

A: 三种方式：通过 `EVEROS_DSH_*` 环境变量、在 DSH Cordis profile 的 `config` YAML 里写键值、或者直接修改插件安装目录里的 `cordis.patch.yml` 重新加载。

**Q: 插件启动的 EverOS 进程什么时候会关？**

A: 只在插件自身被销毁（DSH 关闭 / 插件被卸载）时关闭它自己拉起的进程。本机已经存在的 EverOS 进程不会被本插件终止，但插件会持续轮询直到它健康可用。

**Q: DSH 还在 RC 阶段，插件会不会突然失效？**

A: 插件的 peer 依赖把 DSH 锁在 `0.1.x` 系列（`>=0.1.0-rc.6 <0.2.0-0`），跨大版本时需要先升级本插件。同时 DSH 自身仍处于 RC 阶段，插件 API 在稳定版前仍可能调整。

## 上手难度
入门 — 只需要装好 EverOS 并跑一次 `everos init`，再按 DSH 插件的标准流程加载即可，所有配置项都给出了默认值。

## 已知问题与限制
- DSH 当前仍是发布候选版本，插件 API 在稳定版前可能调整
- 附件只记录图片元数据（媒体类型、尺寸），不保存图片字节内容
- EverOS 的 add API 暂无幂等键，网络失败后的重试可能导致至少一次的重复落库
- 召回路径暂未提供管理界面或显式的 remember / forget 工具
- `vector` / `hybrid` / `agentic` 等非关键字检索方式需要 EverOS 端配齐 Embedding 与 Rerank 凭据
- 批量落库优化依赖 `defer_extraction` 能力，EverOS 1.2.3 不支持该字段

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [EverOS](https://deepseek-plugin.org/plugins/EverMind-AI/EverOS/examples/dsh)
Wiki generated by AI (model: `MiniMax-M3`)