OptMem：极简的 Agent 跨会话记忆

“AI Agent 之所以会忘记，不是因为模型出了问题，而是因为没人给它们一个记东西的地方。”

这是「每天一个开源项目」系列的第 140 篇文章。今天介绍的项目是 OptMem——由 HigherOrderCO 创始人 Victor Taelin 开发的一套极简 AI Agent 持久化记忆系统。其核心设计是：一个 Python 脚本，加上一段仅 426 个 token 的 prompt，就能让你的 AI Agent 记住上一次 session 中发生的事情。

Claude Code、Codex、Cursor——这些工具都有一个共同的局限：每次新 session 都从零开始。上一次 session 中做出的架构决策、发现的坑、记住的偏好，全都消失了。你不得不反复解释上下文，有时甚至会在同一个问题上栽两次。OptMem 直接解决了这个问题：为 Agent 提供一个持久化的本地记忆存储，让它真正拥有记忆。

整个方案的复杂度只有：一个零依赖的 Python 脚本，再把一段 prompt 粘贴进你的 AGENTS.md。

1,100 Stars。Victor Taelin 的个人项目。

本文将介绍：

• 为什么 AI Agent 没有跨 session 记忆，以及 OptMem 如何解决这个问题
• 二叉树摘要：在控制 token 消耗的同时，实现 O(1) 查找
• memo wake / memo note / memo nap：六条命令如何工作
• 这段 426-token prompt 到底写了什么，以及为什么是 426 个 token
• OptMem 与向量数据库之间的真正区别，以及各自适合什么规模
• Claude Code 的完整配置流程

阅读本文前，你最好具备：

• 使用 Claude Code 或类似 AI 编程工具的经验
• 熟悉 AGENTS.md / CLAUDE.md 的概念
• 具备基本的 Python 环境使用能力

问题：AI Agent 没有记忆

在一个项目中使用 Claude Code 完成一次 session，可能会产生这些信息：

• 决定使用 magic links，而不是密码
• 发现某个特定 API 的 rate limit
• 开发数据库的连接字符串

session 结束。下一次打开 Claude Code 时，这些信息全都没有保留下来。你需要重新解释上下文、重新提供背景资料，有时还会再次遇到同一个问题。

解决这个问题的常见方式：

OptMem 的做法是：让 Agent 自己管理记忆，而不是依赖人工维护。Agent 在 session 开始时加载之前的记忆，在工作过程中记录值得保留的信息，而这些记忆会持久化保存在本地，跨 session 继续存在。

核心架构：只追加日志 + 二叉树摘要

OptMem 将所有内容存储在 ~/.optmem/memory/ 下：

~/.optmem/memory/
├── LOG.txt      ← All raw memories, one per line, append-only, never modified
├── TREE/        ← Binary tree summary nodes (cache, rebuildable from LOG.txt)
└── config       ← Configuration (WAKE_LINES, etc.)

LOG.txt：不可变的事实

每次执行 memo note "something"，都会向 LOG.txt 追加一行。这个文件永远不会被修改或删除，只会不断追加。定宽记录格式意味着每条记忆在文件中的位置就是它的身份，因此可以通过 O(1) 的 seek 完成查找，而不需要全文扫描。

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 的解决方案是一棵由摘要组成的二叉树。

Raw memories:                 Tree structure:

#0: magic links               #0-3 (summary of 4)
#1: stripe rate limit    →        #0-1 (summary of 0 and 1)
#2: postgres port             #2-3 (summary of 2 and 3)
#3: test user email               #2-3
...
#0-63 (summary of 64)
    #0-31 (summary of 32)
    #32-63 (summary of 32)
        ...

• 记忆 #0 和 #1 合并成节点 #0-1，也就是两条记忆的摘要
• 节点 #0-1 和 #2-3 合并成 #0-3，也就是四条记忆的摘要
• 依此类推，不断向树的上层合并

这里有一条关键不变量：TREE/ 中的一切都只是缓存，都可以完全根据 LOG.txt 重建。LOG.txt 才是唯一的事实来源。

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

在 session 开始时运行。它会加载记忆树，并输出供 Agent 阅读的 ## Memory 区块。

memo wake
# Output: layered memory summary, fed into context

memo note

记录一条事实，最大长度为 280 字节。这个限制类似 Twitter，目的是让每条记忆保持原子性。

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

memo nap

处理待执行的合并请求——通过基于 LLM 的摘要，将二叉树节点合并起来。OptMem 没有后台进程，因此压缩操作会在 Agent 工作期间以内联方式完成。

memo recall

对全部记忆执行全文正则搜索。

memo recall "redis|session"
# Find all memories mentioning redis or session

memo zoom

将某个摘要节点向下展开为两个子节点，并且可以递归展开，直到看到原始记忆。

memo zoom 0-1023
# Expands to: [0-511] summary and [512-1023] summary
memo zoom 0-511
# Continue down...

memo forget <lo>-<hi>

丢弃一个质量较差的摘要节点；下一次执行 nap 时，会根据原始记忆重新构建它。

426-Token Prompt 区块

OptMem 的全部集成工作，就是把下面这段内容粘贴进 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/.

这段 prompt 处理了四件事：

• 强制执行顺序：wake 必须先于其他所有操作运行
• 触发标准：明确告诉 Agent 什么内容应该记录——决策、发现、偏好和踩过的坑
• Subagent 保护：并行 subagent 永远不会运行 memo，从而避免并发写入造成数据损坏
• 不可变约束：Agent 只能通过命令操作记忆，绝不能直接修改记忆文件

安装与配置

安装：只需一条命令

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

# Windows: see WINDOWS.md in the repo

安装完成后，memo 就可以从 PATH 中直接调用，同时会创建 ~/.optmem/ 目录。

与 Claude Code 集成

# 1. Run memo wake to get the prompt block
memo wake

# 2. Paste the ## Memory block output into your AGENTS.md or ~/.claude/CLAUDE.md
# 3. From now on, Claude Code automatically runs memo wake at the start of each session

配置记忆目录

# Store memories in Dropbox / iCloud / a git repo for cross-machine sync
export MEMORY_DIR=~/Dropbox/optmem-memory

OptMem 与向量数据库的对比

OptMem 的核心优势是透明。打开 LOG.txt，就能逐行阅读 Agent 记录的每一条内容，并自行决定是否信任这些记忆。向量数据库存储的则是你无法直接阅读的浮点数。

OptMem 在检索方面的局限是：正则搜索要求关键词精确匹配。如果一条记忆写的是“login switched to magic link”，但你之后搜索的是“what's the auth approach”，正则就无法找到它。二叉树摘要可以在一定程度上弥补这个问题——wake 会把这些摘要加载进上下文，再由模型进行语义匹配——但无论实际需要多少旧记忆，每个 session 都必须支付固定的 token 成本。

它适合的场景是：一个人、一台机器、一个项目中的 AI Agent，需要记住上周二做出的决策；你希望能打开文本文件，审查 Agent 到底记录了什么；与检索精度相比，你更看重可控性。

🌟 GitHub：VictorTaelin/OptMem

👤 作者：Victor Taelin（HigherOrderCO 创始人，同时也在开发 Bend 语言和 HVM runtime）

OptMem 代表了一种“足够好”的工程理念：解决一个真实问题，同时避免过度工程化。

AI Agent 的跨 session 记忆是每天都会遇到的真实痛点。向量数据库、RAG pipeline、embedding 模型——这些方案在技术上更加完整，但对个人开发者而言，配置成本确实不低。OptMem 给出的答案是：一个 Python 脚本、零依赖、只追加文件、二叉树压缩，再粘贴一段 prompt 即可完成集成。

它的架构有一点做得非常正确：LOG.txt 是唯一的事实来源，TREE/ 只是缓存。无论摘要效果如何，原始记忆都会完整保留下来，而且随时可以重建。最坏的情况只是“速度慢一点”，而不是“数据丢失”。

如果你每天都在使用 Claude Code，OptMem 能解决一个具体而且反复出现的痛点。安装完成后，它会悄无声息地在后台运行。你只需要偶尔检查一下，确认 Agent 确实记录了那些重要决策。

探索 PrimeSkills——一个精选 AI Agent 和 skills 的市场。每个产品都经过真实企业工作流的验证，剥去炒作，只保留真正有效的部分。

欢迎访问我的主页，获取更多实用洞见和有趣产品。

如需采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。