30 分钟给你的 Agent 搭好永久记忆：能 cat 能 git 能直接编辑，保姆级教程零门槛上手

我最近搭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 全文索引和标量过滤。

组件干的活Markdown唯一可信来源，所有记忆落成可读、可 grep、可 Git 版本化、可 Obsidian 打开的 .mdSQLite管理状态和处理队列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 没装的话，一行搞定：

key 这块先交个底：EverOS 兼容所有走 OpenAI 协议的端点。

所以你手上要是已经有 OpenAI、自建 vLLM 或者本地 Ollama，完全可以换掉默认那两家，下一步配置我会讲怎么改。

第二步：安装与初始化（约 5 分钟）

两种装法，按目的二选一：

想顺手读读代码、做点改造，从源码装：

只想把它接进自己项目，直接装包：

两种方式装完，用同一条命令初始化：

它会生成一个起始 .env。打开，填进你那两个 key：

这里插一句，别手滑：.env 里装着你的 key，记得先把它加进 .gitignore。

提交进仓库这种事，翻一次车够你后悔半天。

填完跑这两条确认没问题：

第三步：启动服务并验证（约 3 分钟）

起服务：

让它在这个终端保持运行。新开一个终端，做次健康检查：

一切正常的话，你会看到：

看到这行 ok，你的本地记忆服务就活了。

小提醒：文档写的默认端口是 8000，但你本地起来后亲眼确认一下，别想当然。接下来是这篇的核心。

第四步：第一条记忆——写进去，再搜回来（约 8 分钟）⭐

EverOS 最值钱的就一件事，我给它起了个名，叫核心循环：写入一条事实 → 落盘成持久的 Markdown → 通过本地索引搜回来。咱完整跑一遍。

先写一条关于用户的事实。注意带上 user_id，它决定这条记忆归谁——这也是 EverOS 能在多用户、多 Agent 场景下不串味的关键。

这里我得说句实在话。1.0.0 本地版写入/检索的确切调用方式（是 CLI 子命令还是 REST 请求体），请你一定以仓库根目录的 QUICKSTART.md 为准，README 自己也把权威示例指到了那儿。我不照搬旧版的接口字段，免得你跟着翻车。下面这条是示意，跑通后请换成你本地真实的命令：

写完这一下，EverOS 在后台做了三件事：把这句话抽取成结构化记忆，落盘成 Markdown，同步进 SQLite 和 LanceDB 的本地索引。

现在换个会话，假装是“第二天“，用大白话把它搜回来：

跑通后，把你本地真实搜回来的那条结果贴在这——它该命中刚才那条偏好，还带着相关度。

这背后是一套混合检索：BM25 抓关键词，向量 ANN 抓语义，标量过滤按 user_id 这类维度精确切片，三路由 LanceDB 统一撑着。所以你哪怕换个问法，它照样能搜回来。

跑到这，你的 Agent 已经有跨会话记忆了。但 EverOS 最让我上头的，是下一步。

第五步：掀开黑箱，看看记忆长啥样（约 5 分钟）⭐

还记得开头那句“大脑就是一堆文件“吗？现在咱去把这堆文件翻出来。

打开 ~/.everos：

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 里写入/检索的权威示例，并把你本地真实跑出的命令和返回替换进正文。