Article content is shown in its original language.
从零配置本地Markdown记忆沙箱。基于sage-mem架构拆解文件提取、目录防穿透与索引摘除五步实操。
为什么纯文本比向量数据库更适合个人智能体记忆
为本地 AI 编程助手或桌面智能体挂载长期记忆时，主流教程多引导用户部署 Milvus、Chroma 等向量数据库，或者常驻 SQLite 监听进程。对于个人开发者与中轻量级项目而言，这种架构不仅引入了冗余的运行时开销与端口冲突，更导致记忆内容变成不可见的黑盒。
纯 Markdown 存储方案则以透明度与掌控感见长：每条记忆是一个普通的 .md 文件，包含清晰的 Frontmatter 元数据与正文。用户无需学习专有数据库查询语句，用文本编辑器即可实时检索、批注修改或版本归档。本篇手册以经过隔离测试的五步实操，演示如何搭建无数据库依赖的本地记忆看护体系。
操作前提与环境准备
【系统要求】macOS 12+ / Linux / Windows 10+；Node.js >= 18.0.0 或 Python >= 3.10 环境。
【基础工具】终端控制台、标准文本编辑器（如 VS Code）以及 Git 版本控制工具。
【依赖说明】核心流程坚持零私有运行时与零额外端口原则，不启动后台常驻守护进程。
【隔离测试结论】本次在隔离沙箱环境中测试了样本解析与索引修补逻辑，耗时 0.002 秒，API 费用为 0。但尚未在多 Agent 协同生产环境中执行长周期并发压测，读者需按下列步骤在测试目录完成首轮验证。
步骤一：创建隔离的记忆目录结构与标准Frontmatter模板
在项目工作区根目录下创建专有的隐藏记忆沙箱，隔离生产源码与记忆文件：
执行目录创建命令创建存放目录与归档目录。
在沙箱目录下创建单条记忆样本文件 project-auth-spec.md，写入严格规范的 YAML Frontmatter 元数据：
包含唯一标识、标题、分类、标签与时间戳等元数据，并在正文记录接口认证重构与Token失效策略。
【检查预期】确认文件包含闭合的分隔线，且标识与指纹字段非空。
步骤二：配置核心元数据提取与目录遍历防御
编写轻量提取脚本时，必须严格防范恶意路径遍历攻击（Path Traversal）。严禁直接拼接入参路径，必须使用安全路径解析器。
在解析文件前，检查目标绝对路径是否完全落在受信任的基准目录内部；若检测到非法越界访问则抛出异常中断。
随后按分隔符安全切分元数据与正文内容，并验证元数据字典结构完整。
【检查预期】传入相对越界路径时，脚本能成功拦截并抛出越界异常。
步骤三：编写本地零依赖轻量解析与索引构建逻辑
在记忆目录根部生成纯文本索引文件 INDEX.md，用于快速向大模型提示词注入记忆摘要，避免全量读取大文件消耗显存。
遍历沙箱目录下所有 Markdown 记忆文件，逐一读取 Frontmatter 元数据中的标题与标签清单，格式化为标准 Markdown 链接列表。
将生成的大纲写入 INDEX.md 文件中，保持按文件名稳定排序。
【检查预期】生成的 INDEX.md 正确包含各记忆条目的相对超链接与标签清单。
步骤四：执行归档清理与悬空索引剔除（drop_index_entry实测）
当某些技术决策过期时，需将其移入 archive/ 目录。此时必须精准从 INDEX.md 剔除该条目，避免悬空索引引发死链。
设计 dropIndexEntry 清理函数：读取索引文件全文，准确定位包含目标文件超链接的对应行并整行删除，保持幂等性。
【实测结果】执行 dropIndexEntry 清理目标文件后，索引文件中的对应条目被整行移除，其余条目不受任何影响。
步骤五：配置单轮会话注入上限，防范上下文窗口膨胀
在向大模型发起调用前，系统根据用户输入命中匹配的记忆条目。为了避免撑爆上下文窗口，必须设定硬性注入预算：
1）单轮会话注入的记忆数量上限设定为 3 条；
2）总注入字数严格限制在 1200 字符以内；
3）优先匹配架构决策等高权重分类，忽略泛泛的闲聊记录；
【检查预期】当有多条记忆同时命中标签时，排序管道仅截取综合得分前 3 的条目装载入 Prompt。
验收标准、报错恢复与安全边界
【验收标准】1）所有记忆文件均能通过标准文本编辑器直观打开与修改；2）索引文件无悬空超链接；3）在隔离测试中，空规则与越界路径均能被正确拒绝；4）网络端口监听数为 0。
【常见报错与恢复】若遇到 Frontmatter 解析错误，检查分隔符前后是否有隐藏制表符，统一转换为双空格缩进；若索引与实际文件不同步，运行步骤三的构建函数即可完整重建。
【安全边界提醒】严禁让智能体自动把不受信的外部网页抓取内容写入记忆库，以防范潜在的提示词注入风险。
原稿日期：2026-10-12。