# 30 分钟给你的 Agent 搭好永久记忆：能 cat 能 git 能直接编辑，保姆级教程零门槛上手
**作者**: AYi
**日期**: 2026-06-23T12:38:56.000Z
**来源**: [https://x.com/AYi_AInotes/status/2069399806502453264](https://x.com/AYi_AInotes/status/2069399806502453264)
---
我最近搭Agent工作流有一个很大的感受，就是Openclaw、Hermes、以及Claude code、Codex等这些 Agent ，是不需要更大的上下文窗口的，它需要更好的记忆能力。我花了 30 分钟给常用的编码 Agent 接上持久记忆 —— 没开 Docker，没搭向量库集群，而且这次，它的大脑就是一堆我能直接打开、直接编辑的 Markdown 文件。
## 一、你的 Agent，每天醒来都失忆
做过 Agent 的人，大概都受过这个委屈：昨天它刚陪你定位完一个磨人的 bug，今天开个新会话，它对昨天发生的一切一无所知。
你那些决策、工作流、好不容易踩明白的坑，没有一样跟着它走。上下文被锁在上一段对话里，关掉就蒸发了。
我们的第一反应，通常是把 prompt 塞得更满。把历史记录、用户偏好、项目背景一股脑灌进上下文窗口，然后祈祷模型别忘。
但这条路很快撞墙。窗口有上限，token 要花钱，更要命的是——你塞进去的那点"记忆"是一次性的，关掉窗口就没了。
说到底，你缺的不是更大的 prompt，是一层持久记忆。
这篇我会带你用大约半小时，给一个 Agent 接上 EverOS，一个开源、本地优先的记忆操作系统。
不用搭 MongoDB，不用 Elasticsearch，也不用一整套向量数据库集群。
最妙的一点是，它把记忆存成你能直接打开、阅读、甚至手动改的 Markdown 文件。跟着走完，你的 Agent 就有了跨会话的长期记忆，而这份记忆是透明的，是你的。
那话不多说，咱们开始。
## 二、为什么是 EverOS，而不是再自己搓一个向量库
动手前，先花一分钟说清它跟"再写一个向量库"差在哪，因为这决定了这半小时值不值。
大多数记忆方案是个黑箱，你把文本喂进去，它吐一串向量存进数据库，检索时再还你一堆相似度分数。
那么问题来了：出错的时候，你根本不知道它到底"记住"了什么、为什么这么记，调试基本靠猜😂
EverOS 走的是另一条路，
它的存储是一套本地三件套：Markdown 当唯一可信来源，SQLite 管状态和处理队列，LanceDB 管向量、BM25 全文索引和标量过滤。
关键在第一件，你想知道 Agent 记住了什么？cat 一下就行，想改掉一条记错的？编辑器打开删掉就行，这种可检视性，是黑箱向量库怎么都给不了的。
顺一句佐证，官方那几个跑分也不难看：LoCoMo 93\.05%、LongMemEval\(\-S\) 83\.00%、HaluMem 大约 90%\+，都是官方口径，你自己掂量，但真正打动我的肯定不只是分数。
说白了，我们的Agent 的大脑，就是一堆能打开的文件。
好，理念讲完，咱直接上手操作。
## 第一步：环境准备（约 5 分钟）
一共三样东西。
Python 3\.10 以上，官方推荐 3\.12\+，一个叫 uv 的高性能包管理器，EverOS 用它管依赖和虚拟环境。
还有两个 API key——默认配置下，一个 OpenRouter 管 LLM 和多模态，一个 DeepInfra 管向量化和重排。
uv 没装的话，一行搞定：
```
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
key 这块先交个底：EverOS 兼容所有走 OpenAI 协议的端点。
所以你手上要是已经有 OpenAI、自建 vLLM 或者本地 Ollama，完全可以换掉默认那两家，下一步配置我会讲怎么改。
## 第二步：安装与初始化（约 5 分钟）
两种装法，按目的二选一：
想顺手读读代码、做点改造，从源码装：
```
git clone https://github.com/EverMind-AI/EverOS.git
cd EverOS
uv sync # 创建 ./.venv 并装依赖
source .venv/bin/activate # 或者给每条命令加 `uv run` 前缀
```
只想把它接进自己项目，直接装包：
```
uv pip install everos # 或者 pip install everos
```
两种方式装完，用同一条命令初始化：
```
everos init
```
它会生成一个起始 .env。打开，填进你那两个 key：
```
# 默认提供商：
# OpenRouter → LLM / 多模态
# DeepInfra → Embedding / Rerank
#
# 想换别的 OpenAI 兼容服务（OpenAI / vLLM / Ollama 等），
# 把对应的 *__BASE_URL 字段指过去就行。
```
这里插一句，别手滑：.env 里装着你的 key，记得先把它加进 .gitignore。
提交进仓库这种事，翻一次车够你后悔半天。
填完跑这两条确认没问题：
```
everos --help # 能看到命令列表，说明 CLI 装好了
make test # 源码安装方式下可跑测试套件
```
## 第三步：启动服务并验证（约 3 分钟）
起服务：
```
everos server start
```
让它在这个终端保持运行。新开一个终端，做次健康检查：
```
curl http://127.0.0.1:8000/health
```
一切正常的话，你会看到：
```
{"status":"ok"}
```
看到这行 ok，你的本地记忆服务就活了。
小提醒：文档写的默认端口是 8000，但你本地起来后亲眼确认一下，别想当然。接下来是这篇的核心。
## 第四步：第一条记忆——写进去，再搜回来（约 8 分钟）⭐
EverOS 最值钱的就一件事，我给它起了个名，叫核心循环：写入一条事实 → 落盘成持久的 Markdown → 通过本地索引搜回来。咱完整跑一遍。
先写一条关于用户的事实。注意带上 user_id，它决定这条记忆归谁——这也是 EverOS 能在多用户、多 Agent 场景下不串味的关键。
这里我得说句实在话。1\.0\.0 本地版写入/检索的确切调用方式（是 CLI 子命令还是 REST 请求体），请你一定以仓库根目录的 QUICKSTART.md 为准，README 自己也把权威示例指到了那儿。我不照搬旧版的接口字段，免得你跟着翻车。下面这条是示意，跑通后请换成你本地真实的命令：
```
# 示意，确切写法以 QUICKSTART.md 为准
everos memory add --user-id alice "Alice 偏好用 TypeScript，讨厌 any 类型"
```
写完这一下，EverOS 在后台做了三件事：把这句话抽取成结构化记忆，落盘成 Markdown，同步进 SQLite 和 LanceDB 的本地索引。
现在换个会话，假装是"第二天"，用大白话把它搜回来：
```
# 同样以 QUICKSTART.md 为准
everos memory search --user-id alice "Alice 写代码有什么偏好？"
```
跑通后，把你本地真实搜回来的那条结果贴在这——它该命中刚才那条偏好，还带着相关度。
这背后是一套混合检索：BM25 抓关键词，向量 ANN 抓语义，标量过滤按 user_id 这类维度精确切片，三路由 LanceDB 统一撑着。所以你哪怕换个问法，它照样能搜回来。
跑到这，你的 Agent 已经有跨会话记忆了。但 EverOS 最让我上头的，是下一步。
## 第五步：掀开黑箱，看看记忆长啥样（约 5 分钟）⭐
还记得开头那句"大脑就是一堆文件"吗？现在咱去把这堆文件翻出来。
打开 ~/.everos：
```
~/.everos/
└── default_app/ # app_id
└── default_project/ # project_id
├── users/alice/
│ ├── user.md # Alice 的画像（看得见）
│ ├── episodes/ # 按天记的情景日志（看得见）
│ ├── .atomic_facts/ # 原子事实（点文件，默认隐藏）
│ └── .foresights/ # 预测性记忆（点文件，默认隐藏）
└── agents/<agent_id>/
├── agent.md
└── .cases/ # Agent 的案例库
```
cat 一下 users/alice/user.md。你会发现刚才那条偏好，已经被结构化地写进了 Alice 的画像里，人能读，你也能直接改。
对，就是字面意思——你的 Agent 的记忆，是一份你随手能打开的笔记。
这就是"Markdown 作为唯一可信来源"的真正含义。
更带感的是，你可以直接拿 Obsidian 打开整个 ~/.everos 目录，把 Agent 的记忆当成一座可视化知识库来逛。
这个画面，强烈建议你截张图，它比任何一句文案都更能说明"透明记忆"是什么。
你大概也注意到目录里有两条线，users/ 和 agents/，
这正是 EverOS 的双轨记忆：用户轨记情景和画像（用户是谁、有啥偏好），Agent 轨记案例和技能（Agent 干过啥、学会了啥）。两条线分开抽取，互不污染。
## 再往前一步，它还能玩什么
这半小时咱只跑通了最核心那一圈，但 EverOS 能干的远不止这些，简单点几个方向，留给你接着探。
多模态摄取——一次 API 调用，就能把 PDF、图片、文档、表格、网页 URL 吃进记忆。
这里有个坑提前说：Office 文档的解析依赖系统装了 LibreOffice，没装的话 .docx/.pptx/.xlsx 会失败，但 PDF、图片、音频不受影响。
自我演化——每个完成的任务被记成一个 Case，那些反复成功的模式会自我提升成可复用的 Skill，在整个 Agent 团队间共享，不用你手动整理。
路线图上还有 Knowledge Wiki（把碎片记忆整理成可版本化的 wiki 页）和 Reflection（系统空闲时连接弱信号、压缩历史、改进画像）。
方向我挺期待，但毕竟还在路上，这里只当个预告。
## 几个容易翻车的点
最大的一个坑，必须单拎出来说。
网上很多"EverOS 教程"，其实讲的是它早期那个重型版本，要 docker-compose up 拉起 MongoDB、Elasticsearch、Redis 一整套。
你要是照着抄，从第一步就翻车。本文这个 1\.0\.0 轻量版的全部价值，恰恰就是不需要这些——命令认准 everos init / everos server start 这套 CLI 就对了。
剩下两个一句话带过：Office 文档解析记得装 LibreOffice；.env 一定进 .gitignore。
## 收尾：记忆这件事，值得你认真对待
半小时前，你的 Agent 每开一个会话都从零开始。
现在，它有了一层跨会话的持久记忆——而且这份记忆不是黑箱里一串你看不懂的向量，是你能打开、能读、能改、能用 Git 版本化的文件。
这正是我觉得它值得收藏的原因，它没把"记忆"做成一个玄乎的概念，而是给了开发者一套能跑、能看、能改的具体东西。
如果你手上正有需要长期记忆的 Agent、LLM 应用或者编程助手，现在就把这个仓库收藏了，下次开新项目你会想起它：
👉 https://github\.com/EverMind\-AI/EverOS
本文基于 EverOS 1\.0\.0 轻量本地版整理，跑分均为官方口径。仓库更新较快，发布前请核对最新版本号、默认端口，以及 QUICKSTART\.md 里写入/检索的权威示例，并把你本地真实跑出的命令和返回替换进正文。
## 相关链接
- [AYi](https://x.com/AYi_AInotes)
- [@AYi_AInotes](https://x.com/AYi_AInotes)
- [36K](https://x.com/AYi_AInotes/status/2069399806502453264/analytics)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [8:38 PM · Jun 23, 2026](https://x.com/AYi_AInotes/status/2069399806502453264)
- [36K Views](https://x.com/AYi_AInotes/status/2069399806502453264/analytics)
- [View quotes](https://x.com/AYi_AInotes/status/2069399806502453264/quotes)
---
*导出时间: 2026/6/24 17:49:55*