30分钟给Agent搭好永久记忆 - 保姆级教程

共计 4364 个字符，预计需要花费 11 分钟才能阅读完成。

30 分钟给你的 Agent 搭好永久记忆：能 cat 能 git 能直接编辑

我最近搭 Agent 工作流有一个很深的感受：OpenClaw、Hermes、Claude Code、Codex 这些 Agent，不需要更大的上下文窗口，它需要更好的记忆能力。

于是我花了 30 分钟，给常用的编码 Agent 接上持久记忆——没开 Docker，没搭向量库集群，而且这次，它的大脑就是一堆我能直接打开、直接编辑的 Markdown 文件。

为什么不用向量库？

向量库适合大规模语义检索，但个人 Agent 工作流的核心是 可控和可观测。Markdown 文件你能 cat、能 git diff、能手动编辑，哪一步出问题一眼就能定位。

一、你的 Agent，每天醒来都失忆

用过 Agent 的朋友大概都受过这个委屈：昨天它刚陪你定位完一个磨人的 bug，今天开个新会话，它对昨天发生的一切一无所知。

你那些决策、工作流、好不容易踩明白的坑，没有一样跟着它走。上下文被锁在上一段对话里，关掉就蒸发了。

我们的第一反应，通常是把 prompt 塞得更满。把历史记录、用户偏好、项目背景一股脑灌进上下文窗口，然后祈祷模型别忘。

但这条路很快撞墙。窗口有上限，token 要花钱，更要命的是——你塞进去的那点 "记忆" 是一次性的，关掉窗口就没了。

说到底，你缺的不是更大的 prompt，是一层持久记忆。

这篇我会带你用大约半小时，给一个 Agent 接上 EverOS，一个开源、本地优先的记忆操作系统。

不用搭 MongoDB，不用 Elasticsearch，也不用一整套向量数据库集群。

最妙的一点是，它把记忆存成你能直接打开、阅读、甚至手动改的 Markdown 文件。跟着走完，你的 Agent 就有了跨会话的长期记忆，而这份记忆是透明的，是你的。

二、为什么是 EverOS，而不是再自己搓一个向量库

动手前，先花一分钟说清它跟 "再写一个向量库" 差在哪，因为这决定了这半小时值不值。

大多数记忆方案是个黑箱，你把文本喂进去，它吐一串向量存进数据库，检索时再还你一堆相似度分数。

那么问题来了：出错的时候，你根本不知道它到底 "记住" 了什么、为什么这么记，调试基本靠猜

EverOS 走的是另一条路：它的存储是一套本地三件套：Markdown 当唯一可信来源，SQLite 管状态和处理队列，LanceDB 管向量、BM25 全文索引和标量过滤。

组件	干的活
Markdown	唯一可信来源，所有记忆落成可读、可 grep、可 Git 版本化、可 Obsidian 打开的 . md
SQLite	管理状态和处理队列
LanceDB	管理向量、BM25 全文索引、标量过滤

关键在第一件，你想知道 Agent 记住了什么？cat 一下就行，想改掉一条记错的？编辑器打开删掉就行，这种可检视性，是黑箱向量库怎么都给不了的。

顺一句佐证，官方那几个跑分也不难看：LoCoMo 93\.05%、LongMemEval\(\-S\) 83\.00%、HaluMem 大约 90%\+，都是官方口径，你自己掂量，但真正打动我的肯定不只是分数。

说白了，我们的 Agent 的大脑，就是一堆能打开的文件。

第一步：环境准备

一共三样东西。

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，完全可以换掉默认那两家，下一步配置我会讲怎么改。

第二步：安装与初始化

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

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

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         # 源码安装方式下可跑测试套件

第三步：启动服务并验证

everos server start

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

curl http://127.0.0.1:8000/health

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

{"status":"ok"}

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

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

第四步：第一条记忆——写进去，再搜回来

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 最让我上头的，是下一步。

第五步：看看永久记忆长啥样

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

打开 ~/.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。

为什么说 AI 记忆值得认真对待

半小时前，你的 Agent 每开一个会话都从零开始。

现在，它有了一层跨会话的持久记忆——而且这份记忆不是黑箱里一串你看不懂的向量，是你能打开、能读、能改、能用 Git 版本化的文件。

这正是我觉得它值得收藏的原因，它没把 "记忆" 做成一个玄乎的概念，而是给了开发者一套能跑、能看、能改的具体东西。

如果你手上正有需要长期记忆的 Agent、LLM 应用或者编程助手，现在就把这个仓库收藏了，下次开新项目你会想起它：

开源项目地址：

👉 https://github\.com/EverMind\-AI/EverOS