开源项目第178期：OptMem — 426 个 token 的提示词，给 AI Agent 跨会话的持久记忆

引言

"AI Agent 记性不好不是模型的问题，是没有给它一个地方存东西。"

这是「每日一个开源项目」系列的第 178 篇。今天的项目是 OptMem —— Victor Taelin（HigherOrderCO 创始人）写的一个极简 AI Agent 持久记忆工具，核心是：一个 Python 脚本 + 一段 426-token 的提示词，让你的 AI Agent 在会话结束后还能记住上次发生了什么。

Claude Code、Codex、Cursor 这类 AI 编程助手有一个共同局限：每次新会话都从零开始，上次讨论的架构决策、踩过的坑、记住的偏好，全部消失。你不得不反复在新会话里解释背景。OptMem 解决的就是这件事：给 Agent 一个可持久化的记忆存储，让它真的能"记住"。

整个方案的复杂度：一个无依赖的 Python 脚本，加上把一段提示词粘贴到你的 AGENTS.md 里。

1,100 颗 Star，Victor Taelin 的个人项目。

你会学到什么

AI Agent 为什么没有跨会话记忆，OptMem 的解法是什么
二叉树摘要结构：怎么在 O(1) 读取的同时控制 token 消耗
memo wake / memo note / memo nap：六个命令的工作原理
426-token 提示词块里写了什么，为什么是 426 个 token
OptMem 和向量数据库的本质差异，适合什么规模的场景
在 Claude Code 里的完整配置流程

前提知识

使用过 Claude Code 或类似的 AI 编程工具
了解 AGENTS.md / CLAUDE.md 的概念
会基础 Python 环境操作

问题背景：AI Agent 的健忘症

你用 Claude Code 开发一个项目，在某次会话里：

确定了认证方案用 magic link 而不是密码
发现了一个特定 API 的速率限制
记住了你的测试数据库连接字符串

然后会话结束。下次打开 Claude Code，它什么都不记得了。你要重新解释上下文，重新告诉它那些背景信息，有时候还会重复踩同一个坑。

这个问题有几种常见的解法：

方案	做法	问题
CLAUDE.md	手动把重要信息写进去	需要人工维护，容易忘
上下文压缩	每次会话开始复制上次的内容	麻烦，不自动化
向量数据库	语义搜索存储历史	需要服务器、嵌入模型，复杂
OptMem	Agent 自己记，自动管理	—

OptMem 的思路：让 Agent 自己负责记忆，而不是靠人工维护。Agent 在会话开始时加载历史记忆，在工作过程中遇到值得保存的信息就自动记录，记忆跨会话持久化在本地文件里。

核心架构：append-only 日志 + 二叉树摘要

OptMem 的所有数据存在 ~/.optmem/memory/ 下，结构极简：

~/.optmem/memory/
├── LOG.txt      ← 所有原始记忆，每行一条，只追加，从不修改
├── TREE/        ← 二叉树摘要节点（缓存，可从 LOG.txt 完整重建）
└── config       ← 配置（WAKE_LINES 等）

LOG.txt：不可变的事实记录

每次 memo note "某件事" 都把一行追加到 LOG.txt 末尾。这个文件从不被修改或删除，只追加。固定宽度的记录格式，使得每条记忆的位置本身就是它的标识，查找是 O(1) 的一次寻址，而不是全文扫描。

0000000001 | 2026-08-03T10:23:11 | auth flow uses magic links, no passwords
0000000002 | 2026-08-03T10:45:33 | stripe API rate limit is 100 req/min per key
0000000003 | 2026-08-03T11:02:55 | postgres on localhost:5432, db=dev_app
...

TREE/：二叉树摘要（一个缓存）

随着记忆增多，每次 wake 把所有原始记忆都展示给 Agent 会消耗大量 token。OptMem 用二叉树摘要解决这个问题：

原始记忆：                    摘要树结构：
 
#0: magic links              #0-3（4条的摘要）
#1: stripe rate limit    →       #0-1（0和1的摘要）
#2: postgres port            #2-3（2和3的摘要）
#3: test user email              #2-3
...
#0-63（64条的摘要）
    #0-31（32条的摘要）
    #32-63（32条的摘要）
        ...

记忆 #0 和 #1 合并为节点 #0-1（两条的摘要）
节点 #0-1 和 #2-3 合并为节点 #0-3（四条的摘要）
以此类推，形成二叉树

关键点：TREE/ 里的所有摘要都是缓存，可以从 LOG.txt 完整重建。真正的数据只有 LOG.txt。

wake 时展示什么

memo wake 读取这个树，输出一个分层视图：

## Memory
 
[#0-1023] Summary: Auth uses magic links. Stripe rate 100/min. DB on localhost:5432...
[#1024-2047] Summary: Switched to pnpm. Tests run on port 3001. Error handling...
...
[#4095] 2026-08-03T14:22:11 | updated homepage hero copy to focus on "10x faster"
[#4096] 2026-08-03T14:35:44 | user prefers tabs not spaces in this repo
[#4097] 2026-08-03T15:01:22 | production deploy requires manual approval step

最近的记忆以原始形式展示（精确），较早的记忆以逐级摘要形式展示（压缩）。WAKE_LINES 配置控制展示多少行，默认 96 行约 8k token。

六个命令

`memo wake`

每次会话开始时运行，加载记忆树，输出 ## Memory 块供 Agent 读取。

memo wake
# 输出：分层的记忆摘要，贴入上下文

`memo note "..."`

记录一条事实，最多 280 字节（类 Twitter 设计，保持记忆原子性）。

memo note "decided to use Redis for session storage after testing Postgres was too slow"

`memo nap`

处理积累的合并请求——对二叉树节点执行摘要合并。由于没有后台进程，压缩任务在 Agent 工作时内联执行。

`memo recall <regex>`

对所有记忆做全文正则搜索。

memo recall "redis|session"
# 找到所有提到 redis 或 session 的记忆

`memo zoom <lo>-<hi>`

展开一个摘要节点，看它下面的两个子节点，层层向下直到原始记忆。

memo zoom 0-1023
# 展开：[0-511] 摘要 和 [512-1023] 摘要
memo zoom 0-511
# 继续展开...

`memo forget <lo>-<hi>`

删除一个质量差的摘要节点，下次 nap 时从原始记忆重建。

426-token 提示词块

整个 OptMem 对 Agent 的集成，就是把下面这段提示词粘贴到 AGENTS.md 或 CLAUDE.md：

## Memory
 
You have persistent memory via the `memo` command at ~/.optmem/memo.
 
**At session start:** run `memo wake` before any other tool call.
**During work:** run `memo note "..."` whenever you learn something worth keeping.
  - Decisions made, facts discovered, user preferences, pitfalls found
  - Max 280 chars per note. Be specific.
**On compression requests:** answer them before proceeding with other work.
**Subagent rule:** if you are a subagent, do NOT run any memo commands.
 
Commands:
- `memo wake` — load memory
- `memo note "..."` — record a fact (≤280 chars)
- `memo nap` — process pending merges
- `memo recall <regex>` — search memories
- `memo zoom <lo>-<hi>` — expand a tree node
- `memo forget <lo>-<hi>` — drop a bad summary
 
Never directly edit files under ~/.optmem/memory/.

这段提示词做了几件重要的事：

强制顺序：wake 必须是 Agent 做的第一件事
触发时机：明确告诉 Agent 什么情况下该记——决策、发现、偏好、坑
子 Agent 保护：并行子 Agent 不能运行 memo，防止重复写入错误
不可直接编辑：Agent 只通过命令操作记忆，不直接写文件

安装和配置

安装（一行命令）

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/install.sh | bash
 
# Windows 见 WINDOWS.md

安装后 memo 命令可用，数据目录在 ~/.optmem/。

集成到 Claude Code

# 1. 运行 memo wake，获取提示词块
memo wake
 
# 2. 把输出的 ## Memory 块粘贴到你的 AGENTS.md 或 ~/.claude/CLAUDE.md
# 3. 之后每次 Claude Code 会话，它会自动执行 memo wake 加载记忆

配置记忆目录

# 把记忆存到 Dropbox/iCloud/git 仓库里，跨机器同步
export MEMORY_DIR=~/Dropbox/optmem-memory

OptMem vs 向量数据库

维度	OptMem	向量数据库（Chroma、Pinecone 等）
检索方式	正则全文搜索	语义模糊搜索
搭建成本	粘贴一段提示词	搭建服务器 + 嵌入模型
可检查性	纯文本，用编辑器直接打开	不透明的向量
每次会话成本	wake 加载固定 token 预算	仅查询时消耗
百万条记忆速度	wake: 0.03 秒	取决于服务器
语义检索	无（只有精确词匹配）	支持
适合规模	个人 / 单项目	企业级大规模

OptMem 的核心优势：透明度。你可以打开 LOG.txt，一行行看 Agent 记住了什么、相不相信它。向量数据库里存的是你读不懂的浮点数。

OptMem 的检索局限：正则搜索要求精确词匹配。如果记忆写的是"登录改用 magic link"，但你后来问"认证方案是什么"，正则找不到。二叉树摘要部分弥补了这个问题——wake 把摘要加载进上下文，模型做语义匹配——但每次会话都需要花固定 token 预算，不管用不用到那些旧记忆。

适合的场景：一个人 + 一台机器 + 一个项目的 AI Agent，需要记住上周做了什么决定，可以打开文本文件看 Agent 记住了什么，比检索精度更看重可控性和透明度。

项目地址与资源

🌟 GitHub: VictorTaelin/OptMem
👤 作者: Victor Taelin（HigherOrderCO 创始人，也做 Bend 语言和 HVM 运行时）

总结

OptMem 代表了一种"够用就好"的工程哲学：解决一个真实问题，不过度设计。

AI Agent 的跨会话记忆是一个实际痛点。向量数据库、RAG 管道、嵌入模型——这些方案技术上更完整，但搭建成本和复杂度对个人开发者来说往往是过度工程。OptMem 的方案：一个 Python 脚本，零依赖，追加写文件，二叉树做摘要压缩，整个集成只需粘贴一段提示词。

这个架构做对了一件事：LOG.txt 是唯一的真相来源，TREE/ 只是缓存。不管摘要质量如何，原始记忆永远完整，随时可以重建。这让系统在最坏情况下也只是"慢一点"，而不是"丢数据"。

如果你每天用 Claude Code 工作，OptMem 能解决的是一个具体的日常痛点。装好之后，它在后台静默工作，你只需要偶尔留意 Agent 有没有记录重要决策。

探索 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。