1. 项目概述：为AI智能体“修剪”记忆，实现极致上下文优化

如果你正在运行一个拥有长期记忆的AI智能体，比如OpenClaw或其他基于文件存储记忆的框架，那么你很可能正面临一个日益严重的问题：每次会话启动，无论任务多么简单，你的智能体都需要将整个庞大的记忆文件（比如 MEMORY.md ）塞进上下文窗口。这就像每次打开电脑写邮件前，都必须先通读一遍你从出生到现在的所有日记——效率低下，成本高昂，而且会稀释智能体的思考焦点。

Bonsai Memory（盆景记忆）正是为了解决这个痛点而生。它的核心思想非常直观：将扁平的、线性的记忆文件，重构为一个精心修剪的、层次化的树状结构。这个项目借鉴了数据库索引（如B树）和“渐进式披露”的设计理念，旨在将AI智能体每次启动时需要加载的令牌（Token）数量减少70%到95%。它不是简单地压缩文本，而是通过智能地重组记忆的访问路径，让智能体在需要时“按需加载”相关知识，从而大幅提升响应速度、降低API调用成本，并改善推理质量。简单来说，它为你智能体的记忆做了一次“盆景修剪”，只保留必要的骨架，让养分（计算资源）更高效地输送到真正需要的地方。

2. 核心设计思路：从“通读全书”到“查阅目录”

要理解Bonsai Memory的价值，我们得先拆解当前AI智能体记忆管理的普遍困境。

2.1 扁平化记忆的三大原罪

目前，大多数具备持久化记忆的AI智能体框架，都采用一种简单粗暴的方式：将一个名为 MEMORY.md （或类似名称）的Markdown文件作为记忆库。这个文件包含了关于用户、业务、偏好和历史的所有信息。每次智能体启动一个新会话或处理一个新任务时，这个文件的全部内容都会被注入系统提示词（System Prompt）或上下文窗口。

这种设计带来了三个相互关联的严重问题：

1. 线性增长的启动成本（O(n) Boot Cost） ：这是最直接的财务和性能冲击。假设你的 MEMORY.md 文件有6000个令牌。那么，智能体在生成第一个回答之前，就已经消耗了6000个令牌的成本。无论你是问“今天天气如何”还是“帮我分析季度财报”，这个成本是固定的，且随着记忆内容的积累（n增长）而线性增加。

2. 上下文窗口污染（Context Window Pollution） ：LLM（大语言模型）的上下文窗口是宝贵的“工作记忆”区域。研究表明，当上下文窗口中充斥大量无关信息时，模型对关键信息的捕捉和处理能力会显著下降（即“迷失在中间”效应）。你的智能体在思考“天气”时，却被迫加载着“公司营收目标”和“服务器API密钥”，这无异于在嘈杂的菜市场里做微积分，其推理质量必然受损。

3. 不可持续的可扩展性 ：一个活跃的、不断学习的智能体，其记忆文件会像滚雪球一样越来越大。最终，它会触及上下文窗口的长度上限（例如128K），或者导致每次交互的延迟和成本高到无法接受。你不得不面临一个痛苦的选择：要么定期手动“修剪”记忆（可能丢失重要信息），要么忍受日益恶化的性能。

2.2 Bonsai Memory的解决方案：层次化索引与按需加载

Bonsai Memory的解决思路，与我们管理大型文档库或代码库的思路如出一辙：建立索引。

它不会删除任何记忆内容，而是对原始的 MEMORY.md 文件进行一次性的、智能的重组，将其从单个文件拆分为一个层次化的文件树。这个结构分为三层：

• 根索引（Trunk） ：这是新的、精简版的 MEMORY.md 。它不再包含具体细节，而是一个高级目录，概括了所有记忆领域（Domains）的摘要。大小通常固定在300-500个令牌。 每次会话启动，智能体只加载这个“树干” 。
• 分支索引（Branches） ：每个记忆领域（如“身份信息”、“业务”、“基础设施”）都有一个对应的文件夹（例如 memory/domains/business/ ），里面包含一个 _index.md 文件。这个文件列出了该领域下所有具体记忆“叶子”文件的摘要。
• 叶子文件（Leaves） ：这是原始记忆被拆分后的一个个独立Markdown文件，每个文件对应一个逻辑上独立的知识单元（通常由 ## 标题界定）。它们存储在各自的领域文件夹中。

当智能体需要访问特定信息时，它遵循一个确定的路径：先看根索引（已加载），找到相关领域，然后按需加载该领域的 _index.md ，最后定位并加载具体的叶子文件。最坏的情况下，查找一个具体事实也只需要3次读取（根→分支→叶子），总令牌数远低于加载整个原始文件。

这种设计带来了根本性的复杂度转变：

操作	扁平文件模式	Bonsai Memory模式
启动加载	O(n) – 加载整个文件	O(1) – 仅加载根索引 (~400令牌)
已知类别查找	O(n) – 扫描整个文件	O(1) – 最多3次读取 (~750令牌)
跨领域搜索	O(n) – 语义搜索整个文件	O(n) – 语义搜索所有叶子文件（不变）
写入新记忆	O(1) – 追加到文件末尾	O(1) – 写入对应叶子文件并更新索引
迁移成本	无	O(n) – 一次性，约2分钟

关键在于， 会话启动 这一最高频、最影响用户体验和成本的操作，从与记忆大小相关的 O(n) 优化为了固定的 O(1) 。而跨领域搜索（通常通过向量相似性搜索实现）的性能保持不变，因为它本来就需要扫描所有内容。

2.3 为何选择文件树而非向量数据库？

你可能会问，为什么不直接用向量数据库来管理记忆？这是一个很好的问题。向量数据库擅长的是基于语义相似性的模糊检索，但它解决的是“搜索”问题。Bonsai Memory解决的是“启动加载”和“结构化访问”问题。

文件树方案有几个不可替代的优势：

• 零依赖与可移植性 ：不需要运行任何额外的服务（如ChromaDB、Pinecone），没有连接字符串，没有模式迁移。就是普通的文件和文件夹，在任何地方都能工作。
• 完全透明与可调试 ：你可以直接用任何文本编辑器打开、阅读、修改这些 .md 文件。可以用 grep 命令瞬间搜索关键词。所有记忆都以人类可读的形式存在。
• 完美的版本控制 ：整个 memory/ 目录可以直接用Git管理，你可以清晰地看到每一次记忆增删改的差异，轻松回滚到任何历史版本。
• 与现有搜索兼容 ：像OpenClaw的 memory_search 功能，是基于对 memory/ 目录下所有 .md 文件进行嵌入（Embedding）和检索的。Bonsai Memory的树状结构对此是完全透明的，搜索功能无需任何修改即可正常工作。

Bonsai Memory和向量搜索是互补的。前者优化了确定性的、已知类别的信息访问路径（通过索引），后者处理非确定性的、模糊的关联查询（通过语义）。两者结合，为智能体提供了高效且全面的记忆访问能力。

3. 迁移流程深度解析与实操要点

了解了“为什么”之后，我们来看看Bonsai Memory具体“怎么做”。整个迁移过程是完全自动化的，但理解其内部机制有助于你信任它，并在出现意外时知道如何应对。

3.1 步骤一：章节提取与解析

迁移脚本首先会读取你的 MEMORY.md 文件。它的解析逻辑基于一个简单的假设：在Markdown中， ## （二级标题）通常用于划分主要的主题或章节。因此，它会以 ## 为分隔符，将整个文件切割成多个独立的“章节块”。每个章节块，从它的 ## 标题 开始，到下一个 ## 标题之前结束，被视为一个基本的知识单元。

注意 ：这意味着你的原始记忆文件最好有清晰的二级标题结构。如果整个文件是一个没有标题的大段落，迁移虽然仍能进行（整个文件会被视为一个章节），但会失去分类的优势。建议在迁移前，花几分钟用 ## 整理一下你的记忆文件。

3.2 步骤二：基于关键词的确定性领域分类

这是整个流程中最关键的一步。每个被提取出来的章节，需要被归入一个特定的“领域”（Domain），比如 identity （身份）、 business （业务）、 infrastructure （基础设施）等。

Bonsai Memory采用了一种 确定性关键词匹配 算法，而不是依赖LLM进行分类。这是经过深思熟虑的设计决策：

• 稳定性与幂等性 ：确定性意味着每次运行迁移，同一个章节都会被分到同一个领域。如果使用LLM，由于其概率性，同一章节在两次运行中可能被分到不同领域，这会导致迁移结果不一致，破坏“幂等性”（多次运行结果相同）这一重要特性。
• 速度与零成本 ：关键词匹配是本地字符串操作，瞬间完成，不产生任何API调用成本。
• 透明与可预测 ：分类规则是明确的（一个关键词查找表），你可以轻松理解为什么某个章节被分到某个领域，甚至可以自定义这个关键词表。

分类器会扫描章节的标题（ ## 后面的内容），寻找预定义的关键词。例如：

• 标题 ## My Family and Personal Preferences 包含关键词 “personal”，因此被分类到 identity 领域。
• 标题 ## Company Revenue and Growth Targets 包含关键词 “revenue”，因此被分类到 business 领域。
• 标题 ## AWS EC2 Configuration and Backup 包含关键词 “configuration”，因此被分类到 infrastructure 领域。

如果标题中没有匹配任何预定义关键词，该章节会被放入 general （通用）领域作为兜底。预定义的领域和关键词映射可以在迁移脚本的配置部分找到，你也可以根据自己记忆的特点进行调整。

3.3 步骤三：生成文件树与叶子文件

分类完成后，系统会为每个领域在 memory/domains/ 下创建对应的文件夹（如 memory/domains/business/ ）。然后，为每个章节创建一个独立的Markdown文件（即“叶子”）。

文件名通过对章节标题进行“Slug化”生成：转换为小写，移除特殊字符，将空格替换为连字符，并截断到合理长度（如60字符）。例如：

• ## Monthly SEO Performance Report (March 2024)
• → 文件名： monthly-seo-performance-report-march-2024.md
• → 存储路径： memory/domains/business/monthly-seo-performance-report-march-2024.md

文件的内容就是原始章节的完整Markdown文本。至此，你的记忆已经从“一本书”变成了“一个图书馆”，书被拆成了单篇文章，并分门别类放到了不同的书架上。

3.4 步骤四：自底向上生成索引

仅有叶子文件还不够，我们需要创建高效的“图书目录”。Bonsai Memory采用自底向上的方式生成两级索引：

1. 分支索引（Branch _index.md ） ：在每个领域文件夹（如 memory/domains/business/ ）内，脚本会遍历所有叶子文件，为每个文件生成一个简短的摘要（通常是文件的第一段或前几行），并估算其令牌数。然后，它创建一个 _index.md 文件，列出该领域下所有叶子文件的标题、估算令牌数和一句话摘要。

   # Business Index
   _Last indexed: 2024-05-27T10:30:00+08:00_
   _Estimated tokens: ~850_
   
   ### company-overview.md (~400 tokens)
   Our company is a SaaS provider founded in 2020, focusing on developer tools.
   
   ### monthly-seo-performance-report-march-2024.md (~250 tokens)
   March 2024 SEO report shows a 15% increase in organic traffic.
   
   ### q1-2024-revenue-targets.md (~200 tokens)
   Q1 revenue target set at $500K, currently at 90% achievement.
   

2. 根索引/主干（Root _index.md ） ：这是最终将替换原有 MEMORY.md 的文件。脚本会汇总所有分支索引的信息，生成一个更高级别的目录。它通常只包含各个领域的名称、估算总令牌数和一句顶级摘要。

   # Memory Index
   _Last indexed: 2024-05-27T10:30:00+08:00_
   _Estimated tokens: ~2,950_
   
   ## Domains
   
   ### Identity (~600 tokens)
   Personal background, contact preferences, and family information.
   _Also: personal-details, communication-prefs_
   
   ### Business (~850 tokens)
   Company overview, financial targets, and operational reports.
   _Also: company-overview, seo-reports_
   
   ### Infrastructure (~1,500 tokens)
   Server configurations, API keys, and deployment setups.
   _Also: aws-config, database-backup-plan_
   

   这个只有几百个令牌的根索引文件，就是智能体未来每次启动时加载的全部“记忆”。令牌估算采用 ceil(字符数 / 4) 的经验公式，对于英文文本，其准确度在GPT和Claude的令牌化器下误差通常在±10%以内。

3.5 步骤五：安全替换与回滚准备

在生成全新的文件树和索引后，迁移脚本不会立即删除你的原始 MEMORY.md 。标准操作流程是：

1. 将原始的 MEMORY.md 重命名为 MEMORY.md.bak （备份文件）。
2. 将新生成的根索引 _index.md 复制并重命名为 MEMORY.md ，放置在原来的位置。

这样，你的智能体框架在下次启动时，会自动加载这个新的、精简的 MEMORY.md 。整个迁移过程是原子的、可逆的。如果出现任何问题，你只需要删除新的 MEMORY.md ，并将 MEMORY.md.bak 重命名回去，就能瞬间恢复原状。

实操心得 ：在运行迁移命令前， 务必 确保你的工作目录已用Git提交或已有其他备份。虽然Bonsai Memory会自动备份，但多一份保障总是好的。迁移完成后，第一时间验证智能体是否能正常启动，并用几个简单问题测试其记忆检索是否准确。

4. 集成与使用指南

Bonsai Memory的设计目标是“开箱即用”，尤其是与OpenClaw框架深度集成。以下是几种主要的安装和使用方式。

4.1 推荐方式：通过你的AI智能体安装（最安全）

这是最符合“智能体原生”理念的方式。你不需要手动运行任何命令，只需将以下指令粘贴到你的OpenClaw智能体对话中：

Review and install this OpenClaw skill: https://github.com/felixsim/bonsai-memory

Before installing, read the repo's SKILL.md, README, and LICENSE. Tell me what it does, what files it will create or modify in my workspace, and whether it needs any API keys or external services.

Check for conflicts — do I already have a skill with the same name or similar purpose? Will it modify files I depend on (MEMORY.md, AGENTS.md, anything in memory/)? Are there any commands in SKILL.md that look risky (network calls, credential access, file deletions without backups)?

If anything looks wrong, stop and show me the exact lines. Otherwise, give me your assessment and wait for my approval before installing.

Install only — do NOT run or activate the skill yet. I'll decide when to use it.

你的智能体会执行以下安全检查：

1. 读取与理解 ：分析技能仓库的文档，理解其功能。
2. 安全审计 ：检查 SKILL.md 中的命令，识别任何潜在风险（如网络调用、凭据访问、无备份删除等）。
3. 冲突检查 ：查看你的工作空间是否已存在同名技能，或是否会修改关键文件。
4. 报告与等待 ：向你汇报它的评估结果，并等待你的明确批准。

只有在你回复“批准安装”后，它才会将技能文件下载到你的 skills/ 目录。之后，当你决定迁移记忆时，只需对智能体说：“ Restructure your memory using the bonsai-memory skill. ” 智能体便会激活该技能并执行迁移流程。

这种方式将控制权完全交给了你，避免了“盲装”可能带来的风险。

4.2 手动安装方式

如果你更喜欢手动控制，或者使用的不是OpenClaw框架，可以通过命令行一键安装：

# 为OpenClaw安装
mkdir -p ~/.openclaw/workspace/skills/bonsai-memory && \
curl -sL https://raw.githubusercontent.com/felixsim/bonsai-memory/main/SKILL.md \
  -o ~/.openclaw/workspace/skills/bonsai-memory/SKILL.md

安装后，技能会被OpenClaw自动发现。你可以在智能体对话中通过名称调用它。

4.3 通用框架使用方式

Bonsai Memory的核心逻辑是框架无关的。如果你使用其他AI智能体框架（只要它使用文件存储记忆），你可以：

1. 直接克隆或下载GitHub仓库。
2. 阅读并理解其核心脚本（通常是Python或Shell脚本）。
3. 根据你的框架的目录结构，调整脚本中的路径配置。
4. 手动运行迁移脚本，或者将其集成到你的框架的插件/技能系统中。

项目的 SKILL.md 文件本身就是一个自包含的、可执行的说明文档，智能体可以直接解析并执行其中的步骤。

4.4 迁移后的日常工作流

迁移完成后，你的智能体工作流会发生细微但重要的变化：

• 启动 ：智能体加载 MEMORY.md （现在是根索引），仅消耗~400令牌。
• 执行任务 ：
  • 如果任务明确涉及某个领域（如“查看Q1营收”），智能体可以遵循“根索引→业务分支索引→具体营收文件”的路径加载记忆。这需要智能体具备基本的逻辑来解析任务并匹配领域。在OpenClaw中，这可以通过提示词工程或技能调用来实现。
  • 如果任务模糊或需要跨领域信息（如“找出所有与‘安全’相关的事项”），智能体会直接调用原有的 memory_search 功能。该功能会递归扫描整个 memory/domains/ 目录下的所有 .md 文件进行语义搜索， 完全不受文件树结构影响 。
• 添加新记忆 ：最佳实践是直接在与内容相关的领域文件夹内创建新的 .md 文件。为了保持索引的时效性，你可以定期（例如每周）或在新增大量记忆后，重新运行一次索引生成步骤（非完整迁移），以更新分支索引和根索引中的令牌估算和摘要。Bonsai Memory技能通常也提供了单独的“更新索引”命令。

5. 性能实测、问题排查与进阶技巧

理论再完美，也需要实际数据支撑。下面我们结合实测结果和常见问题，来看看Bonsai Memory在真实场景下的表现。

5.1 实测性能数据解读

根据项目提供的测试数据，在9个不同角色的生产级智能体上进行的迁移，取得了显著的效果：

智能体角色	令牌减少比例	具体变化 (前 → 后)
首席助理	94%	6,400 → 385
运营助理	87%	2,764 → 367
SEO助理	87%	2,732 → 373
内容助理	86%	1,945 → 271
学校助理	80%	1,450 → 296
代码助理	75%	1,012 → 249
研究助理	66%	939 → 316
LinkedIn助理	76%	899 → 218

平均降低81%的启动令牌负载。

数据背后的洞察：

1. 收益与原始大小正相关 ：原始记忆文件越大，节省的绝对令牌数和比例通常越高（如首席助理从6400降至385）。这是O(n)到O(1)复杂度转变的直接体现。
2. 存在基础开销 ：无论原始文件多小，根索引本身有约300-500令牌的固定开销。因此，对于原本就很小（例如低于1000令牌）的记忆文件，迁移可能不会带来净收益，甚至可能因结构开销而略微增加。项目逻辑中也包含了对小文件的检查和建议跳过机制。
3. 分类质量影响索引大小 ：如果大量记忆被正确分类到少数几个领域，那么根索引会非常精简。如果记忆非常分散，导致领域很多，根索引就会稍大一些。因此，在迁移前花点时间优化原始记忆文件的标题清晰度，能让收益最大化。

5.2 常见问题与解决方案速查表

在实际部署和使用中，你可能会遇到以下情况。这里提供一个快速排查指南：

问题现象	可能原因	解决方案
迁移后智能体“失忆”	1. 智能体未适配新的索引加载逻辑。 2. 搜索功能未正确配置递归扫描。	1. 对于OpenClaw ：确保使用的是最新版，其 memory_search 默认支持递归扫描子目录。 2. 对于自定义框架 ：修改你的记忆加载函数，使其能理解并遍历 memory/domains/ 结构，或确保你的搜索函数是递归的。
分类不准确，文件放错领域	原始记忆标题缺乏明确关键词，或你的业务领域与预设关键词不匹配。	1. 迁移前 ：手动编辑 MEMORY.md ，为章节添加更明确的标题（如 ## [Infra] Server Backup Plan ）。 2. 迁移后 ：直接手动将 .md 文件移动到正确的 domains/ 子文件夹下，然后 重新运行索引生成 （非完整迁移）。
添加新记忆后索引未更新	新增了叶子文件，但分支和根索引还是旧的。	运行Bonsai Memory技能提供的“更新索引”或“重新索引”命令。这个命令只会重新生成 _index.md 文件，不会移动或修改已有的叶子文件。
回滚后智能体仍加载索引	备份文件恢复后，框架可能缓存了旧的上下文。	完全重启你的智能体进程或服务，确保它从磁盘重新读取 MEMORY.md 文件。
迁移脚本执行错误	1. 文件权限不足。 2. 原始 MEMORY.md 格式异常（如编码问题）。	1. 检查脚本对工作目录是否有读写权限。 2. 用文本编辑器检查 MEMORY.md 是否为有效的UTF-8编码，确保Markdown标题格式正确。

5.3 进阶技巧与自定义

当你熟悉了基本流程后，可以考虑以下优化：

• 自定义领域关键词 ：如果你发现默认的分类不符合你的记忆结构，可以直接修改迁移脚本中的 DOMAIN_KEYWORDS 映射字典。例如，如果你有很多关于“营销活动”的记忆，可以添加 "marketing": ["campaign", "promotion", "advertisement"] 到一个新的 marketing 领域。
• 混合记忆策略 ：对于极其重要、需要智能体在 任何 对话中都铭记于心的核心信息（例如核心身份、绝对禁忌规则），你可以选择不将它们迁移到树中，而是保留一小段在根索引 MEMORY.md 的开头部分。这样既能享受结构化的好处，又能确保关键信息永远在线。
• 定期索引维护 ：将“更新索引”命令设置为一个定期任务（例如每周日的定时任务）。这能确保你的索引摘要反映最新的内容，虽然智能体的语义搜索不依赖索引，但清晰的索引摘要有助于你在人工浏览时快速了解记忆库的全貌。
• 与版本控制结合 ：将整个 memory/ 目录纳入Git仓库。每次智能体学习新知识（新增叶子文件）都是一次提交，你可以清晰追溯记忆的演变历史。回滚到某个时间点的记忆状态变得轻而易举。

Bonsai Memory项目体现了一种务实而优雅的工程思维：在面对LLM上下文窗口这一稀缺资源时，通过引入简单的、符合计算机科学原理的层次化设计，就能获得数量级的性能提升。它不需要昂贵的向量数据库，不改变你现有的文件存储习惯，只是对信息的组织方式做了一次重新的思考。这种用“聪明”的软件架构来弥补硬件（这里指上下文窗口）限制的思路，在构建高效、可持续的AI应用过程中，是非常值得借鉴的。