这次我们来看一个有点反常识的结论在一组 Agent Memory 产品的基准测试里干掉那些专用记忆框架的不是什么复杂架构而是一个普通的 Markdown Wiki。先说清楚背景。Agent Memory 产品这几年很火很多人把它理解成“给大模型接一个长期记忆系统”常见做法是对话切片 - 嵌入向量 - 写入向量库 - 检索增强。听起来很完美真正落地时却经常掉链子召回不准、上下文漂移、跨会话一致性差、成本还高。而这个 Markdown Wiki 方案却把问题简化到了极致用纯文本的 Markdown 文件组织记忆用双链和组织结构表达关系检索的时候直接读文件、做关键词匹配必要时才让 LLM 参与整理和生成。结果从准确性、可维护性、成本和可解释性四个维度看都明显优于那些“看起来更聪明”的专用方案。这篇文章会做三件事第一拆解为什么 Agent Memory 产品会输给 Markdown Wiki第二给你一套可以直接照抄的 Markdown Wiki Agent Memory 搭建方法第三给出检索、接口调用、批量任务和问题排查的完整工程化思路。适合正在做 Agent 应用、被记忆功能折磨过、或者想给团队搭一套低成本知识库的读者。1. 核心能力速览先把两组方案的差异放在一张表里后面展开都围绕这张表。能力项Markdown Wiki 方案专用 Agent Memory 产品存储形式纯文本 Markdown 文件向量库 关系数据库混合存储检索方式文件名/标题/正文关键词、双链遍历、可选 BM25向量相似度检索 混合检索语义理解依赖 LLM 抽取整理检索阶段不依赖向量依赖嵌入模型检索阶段依赖向量相似度可读性人类直接打开编辑器阅读修改通常需要工具可视化无法直接编辑底层记忆可解释性每次回答都能溯源到具体文件溯源依赖召回结果可能关联到错误片段硬件门槛纯 CPU 即可零 GPU 需求嵌入模型和向量库可跑 CPU但大规模检索有内存压力成本存储成本接近 0向量存储、嵌入 API 或自建模型都有持续成本维护难度低Markdown 文件可交给普通编辑器管理需要运维向量库、定时任务、索引重建多模型适配不绑定模型任何 LLM 都能读取部分产品绑定自家模型或指定的嵌入模型适合场景个人知识库、小团队 Agent 记忆、可控性要求高的场景海量碎片化记忆、超大规模多租户场景从表里能看出来Markdown Wiki 的核心优势不是“某个技术指标特别强”而是“没有多余的复杂度”。在 Agent Memory 这个场景里多余复杂度通常是错误的来源。2. 为什么专用 Agent Memory 产品会被反超要理解这个结果先看一个常见误区很多人把 Agent Memory 等同于向量检索。但向量检索解决的是“语义相似”不等于“事实正确”。举个例子。用户十天前告诉 Agent“我住在杭州公司在滨江区通勤坐地铁 1 号线。” 今天问 Agent“我每天怎么上班”一个依赖向量召回的记忆系统可能会把这条记忆切成若干片段再经过嵌入模型转换。如果嵌入模型对“通勤”“上班”“地点”这三个概念的语义编码有偏差召回结果可能就是“杭州”或者“滨江区”而不是完整的通勤方式描述。Markdown Wiki 不会这样。它把这条记忆写成一个结构化的条目# 用户通勤信息 - 居住地杭州 - 公司地址滨江区 - 通勤方式地铁 1 号线 - 更新时间2025-06-01检索的时候直接按“通勤”“上班”等关键词匹配到这个文件然后把整个文件内容注入上下文。没有嵌入环节没有语义偏移召回的就是完整事实。这个差异在评测时会放大因为大多数 Agent Memory 基准测试的真实场景都包含“事实必须精确回忆起”的题目。比如用户之前指定的偏好、截止日期、会议结论、项目约定。语义相似召回在这种场景下会返回“看起来相关但细节对不上”的结果。另一个被忽略的原因是专用 Agent Memory 产品通常不会让你直接编辑记忆。产品内部的记忆结构是黑盒用户无法修改一段错误记忆。而 Markdown Wiki 是文件系统用户随时可以打开文件修正一个错误日期、删除一条过期信息、合并两个重复条目。这种“人类可干预能力”对长期可用性影响极大因为 Agent 记忆一定会积累错误关键是纠正错误成不成本。还有一个维度和性能无关是成本。专用记忆方案每写入一条记忆至少经过一次嵌入每检索一次又要做一次向量化。如果 Agent 每天有上万个会话片段嵌入 API 的费用会非常可观。自建嵌入模型则要额外维护 GPU 推理服务。Markdown Wiki 的写入就是写文件检索就是 grep 或者 BM25成本几乎可以忽略。这不是说向量检索一无是处。在模糊语义搜索、跨语言检索、推荐系统里它仍然有价值。但对于 Agent Memory 这种需要“精确记忆、双向校验、可修正”的场景传统方案反而更稳。3. Benchmark测什么才有说服力要得出“Markdown Wiki 超过所有产品”的结论评测维度必须覆盖真实使用场景。这里给出一套可复现的 Agent Memory 评测框架包含七个维度。3.1 事实准确率模拟一个 Agent 连续和用户对话多天对话中包含了明确的个人信息、截止日期、约定事项。结束后问 Agent 具体事实检查回答是否精确。测试题示例用户上周提到的客户的英文名是什么用户的项目演示定在几点用户对 PPT 的配色偏好是什么这类题目不允许 Agent 说“我记不清了”必须给出精确答案评测标准是字段级精确匹配。3.2 跨会话一致性同一件事在多轮对话中以不同方式被提及。评测时看 Agent 最终记忆是否合并正确。比如第一次说“下周三发布”第二次说“发布时间提前到周二”第三次问“什么时候发布”正确答案是“周二”。这个维度经常暴露专用记忆产品的结构性问题旧记忆和新记忆同时存在于向量库语义相近但答案矛盾检索时无法判断哪条是对的。Markdown Wiki 的优势在于AI 整理记忆时可以直接改写原文件旧的矛盾条目会被删除或标记失效。3.3 更新与遗忘能力验证 Agent 能否正确处理“记忆被更新”的情况。比如用户说“我不喜欢咖啡了改成喝茶”之后问“用户的饮品偏好是什么”。评测标准是新记忆必须完全覆盖旧记忆不能出现“用户可能喜欢咖啡或茶”这类骑墙回答。3.4 交叉引用能力Agent 记忆中有大量跨主题关联比如“项目 A 的负责人是张三”和“张三的邮箱是 zhangexample.com”。评测时问“项目 A 负责人的邮箱是什么”必须能通过两次跳转得到答案。Markdown Wiki 用双链语法能天然支持这种跳转向量检索则经常在这一步因为实体关联丢失而失败。3.5 检索延迟从用户提问到 Agent 做出回答记忆检索环节的耗时。专用产品通常包含多个服务调用Markdown Wiki 基本都是毫秒级文件读取延迟。评测时重点观察 P95 延迟因为峰值延迟往往被向量召回的不稳定性拖高。3.6 可解释性评分每次回答后要求 Agent 给出记忆来源。能明确指向具体文件条目的得高分只能给出“来自历史对话”的得低分。Markdown Wiki 天然具备这个能力因为答案是直接从某个文件注入的。3.7 综合成本包括存储成本、算力成本、维护成本、人工修正成本。按每万条记忆估算或者按 30 天连续运行统计。这套评测框架可以在自己的测试环境跑。不用迷信任何“官方榜单”把上述场景用脚本写清楚任何团队都能验证自己的 Agent 记忆到底行不行。4. Markdown Wiki 作为 Agent Memory 的设计原则如果决定采用 Markdown Wiki 方案设计上有几个原则要守住。4.1 一份记忆只写在一个文件里Agent 记忆最怕的是同一事实分散在多个文件。比如用户偏好写在“用户介绍.md”又在“对话记录/6月.md”里重复出现。将来检索时可能拿到两个版本无法判断新旧。建议的规则是同一实体、同一事件、同一偏好只允许出现在一个 canonical 文件中。AI 在做记忆整理时第一优先是“找到已有文件并更新”第二才是“新建文件”。4.2 文件名和标题就是检索索引Markdown Wiki 没有向量索引文件名和标题就是最重要的检索入口。文件名要使用稳定的实体名比如用户-张三.md 项目-产品发布.md 会议-2025-06-01-需求评审.md不要用对话 ID 或者无名的时间戳否则检索时找不到文件。4.3 双链比目录更重要双链语法[[项目-产品发布]]是 Markdown Wiki 的核心能力。每一份记忆文件里凡是涉及其他实体的地方都要用双链写出。这样检索时可以沿着链接做二级跳转。# 会议-2025-06-01-需求评审 - 参与人[[用户-张三]]、李四 - 关联项目[[项目-产品发布]] - 结论功能范围缩减优先保证登录模块4.4 YAML Frontmatter 记录元数据在 Markdown 文件头部加入 YAML Frontmatter用于记录更新时间、类型、重要度。这样后续写脚本处理时可以直接用程序读元数据。--- type: user-profile entity: 张三 updated: 2025-06-01 importance: high ---4.5 建立 MOC内容地图MOC 是 Wiki 的导航首页负责组织记忆的总体结构。每个 Agent 至少需要一个 MOC# Agent Memory Index ## 用户相关 - [[用户-张三]] ## 项目相关 - [[项目-产品发布]] ## 会议记录 - [[会议-2025-06-01-需求评审]]MOC 文件是 Agent 每次启动对话时最先注入的上下文帮助 LLM 快速定位记忆入口。5. 本地搭建从零开始建一个 Agent Memory Wiki下面给出一个具体的搭建流程不依赖任何特定商业产品纯开源和本地文件即可完成。5.1 创建目录结构mkdir -p agent-memory/{users,projects,meetings,daily,archive}建议目录users用户档案一人一个文件projects项目状态、决策记录meetings会议结论按日期命名daily每日对话摘要AI 每天生成archive过期记忆归档避免删除后无法回溯5.2 使用 Obsidian 作为可视化前端Obsidian 可以直接打开这个目录自动识别双链和 MOC。Obsidian 的优点是完全基于本地文件不锁定数据支持图谱视图移动端也能访问。也可以使用 VSCode 加 Markdown 插件适合纯命令行习惯的用户。5.3 写一个基础的记忆写入脚本Agent 在对话过程中需要把新信息写入 Wiki。下面是一个 Python 脚本示例用于把一条结构化记忆写入指定文件import os import datetime import hashlib MEMORY_ROOT ./agent-memory def write_memory(memory_type, content, entityNone): if memory_type user and entity: path os.path.join(MEMORY_ROOT, users, f{entity}.md) mode append elif memory_type meeting: today datetime.date.today().isoformat() path os.path.join(MEMORY_ROOT, meetings, f{today}.md) mode append else: file_id hashlib.md5(content.encode()).hexdigest()[:8] path os.path.join(MEMORY_ROOT, daily, f{datetime.date.today().isoformat()}-{file_id}.md) mode write os.makedirs(os.path.dirname(path), exist_okTrue) if mode append: with open(path, a, encodingutf-8) as f: f.write(content \n) else: with open(path, w, encodingutf-8) as f: f.write(content \n) print(fmemory written: {path}) return path这个脚本没有涉及任何向量模型只是纯文件操作因此任何机器上都能跑。5.4 AI 辅助整理把碎片对话变成结构化记忆真正完整的 Agent Memory 不能只靠人工写文件需要让 AI 每天把对话日志整理成结构化的 Markdown 条目。该整理任务的 Prompt 可以这样设计你是一个记忆整理助手。请阅读下面的对话记录提取需要长期保存的信息用 Markdown 格式输出。 输出要求 1. 用户明确表达的个人信息、偏好、计划、截止日期必须提取 2. 项目相关的决策、变更、任务分配必须提取 3. 每个条目使用一二级标题组织 4. 如果一条信息在更早的对话中出现过请标注已存在需更新 5. 不要输出与用户无关的通用事实。 对话记录 {{对话内容}}把 AI 整理后的 Markdown 文本交给上述写入脚本保存即可。6. 检索与注入把 Wiki 变成 LLM 的长期记忆搭建好 Wiki 之后核心问题变为Agent 在回答问题时如何从 Wiki 中找到相关记忆这里不采用向量检索而是采用“关键词 双链遍历 BM25”的组合方案。6.1 BM25 检索器实现BM25 是传统的文本检索算法对长文本召回非常稳定依赖少CPU 上毫秒级响应。下面的 Python 代码使用 rank_bm25 库实现pip install rank-bm25import os import re from rank_bm25 import BM25Okapi class MarkdownWikiRetriever: def __init__(self, wiki_root): self.wiki_root wiki_root self.docs [] # 全文 self.paths [] # 对应的文件路径 self.bm25 None def load_documents(self): for root, dirs, files in os.walk(self.wiki_root): for fname in files: if not fname.endswith(.md): continue path os.path.join(root, fname) with open(path, r, encodingutf-8) as f: content f.read() self.paths.append(path) self.docs.append(content) tokenized [self._tokenize(doc) for doc in self.docs] self.bm25 BM25Okapi(tokenized) print(floaded {len(self.docs)} markdown files) def _tokenize(self, text): return re.findall(r[\w\u4e00-\u9fa5], text.lower()) def search(self, query, top_k3): tokens self._tokenize(query) scores self.bm25.get_scores(tokens) ranked sorted(range(len(scores)), keylambda i: scores[i], reverseTrue) results [] for idx in ranked[:top_k]: if scores[idx] 0: continue results.append({ path: self.paths[idx], score: scores[idx], content: self.docs[idx][:2000], }) return results写完后先建一个索引retriever MarkdownWikiRetriever(./agent-memory) retriever.load_documents() results retriever.search(用户通勤方式, top_k2) for r in results: print(ffile: {r[path]}, score: {r[score]})6.2 双链遍历增强BM25 返回的文件中如果包含双链[[项目-产品发布]]可以额外加载这些被链接的文件让 LLM 获得二级上下文。这种“一跳扩展”能明显提升交叉引用问题的回答质量。import re def expand_wiki_links(contents, max_hops1): linked_docs [] for content in contents: links re.findall(r\[\[([^\]])\]\], content) for link in links: target_path find_markdown_file(link) if target_path: with open(target_path, r, encodingutf-8) as f: linked_docs.append(f.read()) return linked_docs6.3 注入到 LLM 上下文最终把检索到的内容格式化为可注入的上下文。以下是你可以参考的长期记忆片段来自本地 Wiki --- 记忆 1 / 来源: users/张三.md --- # 用户-张三 - 居住地杭州 - 通勤方式地铁 1 号线 --- 记忆 2 / 来源: meetings/2025-06-01.md --- # 需求评审结论 - 功能范围缩减优先登录模块 请基于以上记忆回答用户问题如果记忆与用户当前说法冲突以用户当前说法为准。将这段文本拼接到系统 Prompt 或对话历史中即可。6.4 无 GPU 也能跑整个检索链路只有 Python、文件系统、BM25 三个环节不需要 CUDA、不需要嵌入模型、不需要向量数据库。这意味着在一台 2 核 4G 内存的轻量服务器上就能运行一个完整的 Agent Memory 后端。7. 接口 API 与自动化批量任务如果你要把 Wiki 接入到自建的 Agent 框架或者团队其他人需要调用记忆服务建议封装一层轻量 API。7.1 FastAPI 接口示例from fastapi import FastAPI, HTTPException from pydantic import BaseModel import MarkdownWikiRetriever app FastAPI() retriever MarkdownWikiRetriever(./agent-memory) retriever.load_documents() class SearchRequest(BaseModel): query: str top_k: int 3 class MemoryWriteRequest(BaseModel): memory_type: str entity: str None content: str app.get(/health) def health(): return {status: ok, wiki_files: len(retriever.docs)} app.post(/api/retrieve) def retrieve(req: SearchRequest): results retriever.search(req.query, top_kreq.top_k) return {results: results} app.post(/api/write) def write_memory(req: MemoryWriteRequest): path write_memory(req.memory_type, req.content, req.entity) retriever.load_documents() return {path: path, status: ok}启动uvicorn wiki_memory_api:app --host 127.0.0.1 --port 88007.2 批量任务设计常见批量任务包括每日 0 点整理前一天对话日志每周扫描所有 Markdown 文件检查双链断裂每月归档超过 180 天未更新的低优先级记忆每次写入后重建 BM25 索引一个简单的定时任务示例0 0 * * * cd /path/to/project python scripts/daily_summary.py logs/daily_summary.log 21 0 2 * * * cd /path/to/project python scripts/rebuild_index.py logs/rebuild_index.log 217.3 失败重试建议如果某个批量任务处理到一半失败建议先把处理进度记录在.progress文件重启后从上次位置继续写入 Wiki 是幂等操作重复执行不会造成数据损坏BM25 索引重建很快即使每次写入都重建压力也可接受8. 资源占用与性能观察从典型运行情况看Markdown Wiki 方案的资源占用极低但这取决于 Wiki 文件数量和单次检索返回的文本量建议在自己的环境里做一次量化观察。8.1 观察方法如果你使用 Linux可以用htop看内存用du -sh看 Wiki 目录体积用time python test_query.py看检索耗时。du -sh ./agent-memory time python query_test.py8.2 性能特征500 个 Markdown 文件内BM25 检索耗时通常是毫秒级5000 个文件时内存占用仍很低主要耗时来自文件遍历和 tokenize双链跳转扩展一次最多增加几个文件的读取耗时仍可控相比向量检索不需要网络调用也不需要为召回结果做后处理8.3 降低资源占用的方法大批量写入后只在整点重建 BM25 索引而不是每次都重建文件数量增长到几千个后可以把 Archive 目录排除在索引外检索时限制返回文本长度例如content[:2000]如果同时有大量并发请求在 API 层加一个进程级缓存8.4 避免端口冲突和进程残留API 服务如果出现端口被占用可以先查端口lsof -i :8800 kill pid然后再重启服务。批量任务建议用日志文件记录每次运行结果避免重复启动多个实例同时写入文件。9. 常见问题与排查方法问题现象可能原因排查方式解决方案检索结果相关性差文件名和正文没有包含目标关键词检查目标文件是否存在、关键词是否写全补全标题和双链统一命名规范双链跳转找不到文件双链文本与文件名不一致在 Obsidian 中查看链接是否变灰统一实体命名使用索引脚本校验更新记忆后旧信息仍被召回Wiki 中存在多个同事实文件搜索关键词检查重复文件合并文件只保留 canonical 文件Agent 回答出现记忆矛盾新旧记忆没有正确覆盖查看 AI 整理结果是否做了更新操作调整整理 Prompt要求显式标记“已更新”API 服务响应慢向量检索不存在通常是文件过多或每次重建索引检查 stdout 日志和 CPU 占用分批重建检索结果截断批量任务重复写入没有记录处理进度检查日志和文件更新时间添加.progress文件机制Markdown 文件不小心被改乱没有版本管理查看文件修改时间为 Wiki 目录初始化 Git提交版本快照多线程同时写一个文件并发任务没有加锁观察文件内容是否出现交错覆盖写入用单 Worker 或加文件锁排查时最常用的定位手段是直接打开 Markdown 文件人工查看。因为所有记忆都是纯文本问题很容易暴露。这也是这个方案比黑盒记忆产品好排查的核心原因。10. 最佳实践与使用建议10.1 第一次先小规模验证不要一开始就把所有历史对话灌进 Wiki。先跑一周用真实的 50 条记忆测试召回准确率再逐步扩大。10.2 保留最小可运行配置建议把以下内容固定下来目录结构固定为 users/projects/meetings/daily/archive双链命名规则固定为“实体类型 名称”如项目-产品发布所有文件头部必须有 YAML Frontmatter每日 AI 整理任务必须有日志10.3 目录、脚本、数据分层管理agent-memory/ # 记忆数据纳入 Git scripts/ # 整理、检索、索引脚本 logs/ # 运行日志不纳入 Git tests/ # 测试脚本和样例数据10.4 批量任务要加日志和失败重试每个定时任务至少输出一行日志记录开始时间、处理数量、结束状态。失败时能在日志中看到卡在哪一步。10.5 接口服务限制访问范围API 如果部署在服务器上建议只监听127.0.0.1或使用防火墙限制来源 IP。如果需要在局域网共享应增加简单的 Token 校验。10.6 涉及隐私数据时先确认边界Wiki 里如果记录了用户个人信息、公司内部项目或对话内容无论是个人使用还是团队使用都要注意数据的存储位置和访问控制。如果期望长期保存建议定期检查映射关系和 Git 历史确保边界清晰。10.7 先用 Git 做记忆版本管理Git 是 Markdown Wiki 天然的配套工具支持回溯任意历史版本cd agent-memory git init git add . git commit -m init memory每次 AI 整理后提交一次可随时回滚。这里要提醒的是如果记忆库中包含非常敏感的文本请确保 Git 仓库保存在可信环境里不推送到公共远程仓库。10.8 发布或商用前做效果复核如果有任何输出会面向外部用户展示发布前应该复核记忆来源是否准确、是否有过时信息。不要完全依赖自动整理结果。11. 结论什么时候该用 Markdown Wiki回到标题为什么一个 Markdown Wiki 能在 benchmark 里超过所有 AI agent memory 产品最直接的原因是这个方案没有把简单问题复杂化。Agent Memory 的核心目标是“准确地记住并调用事实”而不是“存储海量语义信息”。Markdown Wiki 用纯文本、结构化的方式存储事实用关键词和双链来定位事实用 LLM 来做整理和生成。每一步都可解释、可修正、可测试。这个方案也有边界。如果你的场景是处理亿级非结构化记忆或者需要跨语言的模糊语义检索向量库仍然是必要组件。到时可以考虑混合方案Markdown Wiki 作为权威记忆层向量库作为模糊发现层最终以 Markdown Wiki 的结果为准。最容易踩的坑有两个一是文件命名不规范导致检索不到二是 AI 整理记忆时重复建文件而不是更新旧文件。这两个坑只要在前两步用规则和 Prompt 约束好后面的运行会非常省心。如果你正在被 Agent 记忆的准确率折磨或者想给团队上一套低成本、可控的知识库建议从今天开始建一个 Markdown Wiki每天让 LLM 帮你整理几段对话连续跑一周再对比效果。这个方案的每一个环节都能自己验证也适合长期积累。 Markdown Wiki 如何超越专用 Agent Memory 产品？
这次我们来看一个有点反常识的结论在一组 Agent Memory 产品的基准测试里干掉那些专用记忆框架的不是什么复杂架构而是一个普通的 Markdown Wiki。先说清楚背景。Agent Memory 产品这几年很火很多人把它理解成“给大模型接一个长期记忆系统”常见做法是对话切片 - 嵌入向量 - 写入向量库 - 检索增强。听起来很完美真正落地时却经常掉链子召回不准、上下文漂移、跨会话一致性差、成本还高。而这个 Markdown Wiki 方案却把问题简化到了极致用纯文本的 Markdown 文件组织记忆用双链和组织结构表达关系检索的时候直接读文件、做关键词匹配必要时才让 LLM 参与整理和生成。结果从准确性、可维护性、成本和可解释性四个维度看都明显优于那些“看起来更聪明”的专用方案。这篇文章会做三件事第一拆解为什么 Agent Memory 产品会输给 Markdown Wiki第二给你一套可以直接照抄的 Markdown Wiki Agent Memory 搭建方法第三给出检索、接口调用、批量任务和问题排查的完整工程化思路。适合正在做 Agent 应用、被记忆功能折磨过、或者想给团队搭一套低成本知识库的读者。1. 核心能力速览先把两组方案的差异放在一张表里后面展开都围绕这张表。能力项Markdown Wiki 方案专用 Agent Memory 产品存储形式纯文本 Markdown 文件向量库 关系数据库混合存储检索方式文件名/标题/正文关键词、双链遍历、可选 BM25向量相似度检索 混合检索语义理解依赖 LLM 抽取整理检索阶段不依赖向量依赖嵌入模型检索阶段依赖向量相似度可读性人类直接打开编辑器阅读修改通常需要工具可视化无法直接编辑底层记忆可解释性每次回答都能溯源到具体文件溯源依赖召回结果可能关联到错误片段硬件门槛纯 CPU 即可零 GPU 需求嵌入模型和向量库可跑 CPU但大规模检索有内存压力成本存储成本接近 0向量存储、嵌入 API 或自建模型都有持续成本维护难度低Markdown 文件可交给普通编辑器管理需要运维向量库、定时任务、索引重建多模型适配不绑定模型任何 LLM 都能读取部分产品绑定自家模型或指定的嵌入模型适合场景个人知识库、小团队 Agent 记忆、可控性要求高的场景海量碎片化记忆、超大规模多租户场景从表里能看出来Markdown Wiki 的核心优势不是“某个技术指标特别强”而是“没有多余的复杂度”。在 Agent Memory 这个场景里多余复杂度通常是错误的来源。2. 为什么专用 Agent Memory 产品会被反超要理解这个结果先看一个常见误区很多人把 Agent Memory 等同于向量检索。但向量检索解决的是“语义相似”不等于“事实正确”。举个例子。用户十天前告诉 Agent“我住在杭州公司在滨江区通勤坐地铁 1 号线。” 今天问 Agent“我每天怎么上班”一个依赖向量召回的记忆系统可能会把这条记忆切成若干片段再经过嵌入模型转换。如果嵌入模型对“通勤”“上班”“地点”这三个概念的语义编码有偏差召回结果可能就是“杭州”或者“滨江区”而不是完整的通勤方式描述。Markdown Wiki 不会这样。它把这条记忆写成一个结构化的条目# 用户通勤信息 - 居住地杭州 - 公司地址滨江区 - 通勤方式地铁 1 号线 - 更新时间2025-06-01检索的时候直接按“通勤”“上班”等关键词匹配到这个文件然后把整个文件内容注入上下文。没有嵌入环节没有语义偏移召回的就是完整事实。这个差异在评测时会放大因为大多数 Agent Memory 基准测试的真实场景都包含“事实必须精确回忆起”的题目。比如用户之前指定的偏好、截止日期、会议结论、项目约定。语义相似召回在这种场景下会返回“看起来相关但细节对不上”的结果。另一个被忽略的原因是专用 Agent Memory 产品通常不会让你直接编辑记忆。产品内部的记忆结构是黑盒用户无法修改一段错误记忆。而 Markdown Wiki 是文件系统用户随时可以打开文件修正一个错误日期、删除一条过期信息、合并两个重复条目。这种“人类可干预能力”对长期可用性影响极大因为 Agent 记忆一定会积累错误关键是纠正错误成不成本。还有一个维度和性能无关是成本。专用记忆方案每写入一条记忆至少经过一次嵌入每检索一次又要做一次向量化。如果 Agent 每天有上万个会话片段嵌入 API 的费用会非常可观。自建嵌入模型则要额外维护 GPU 推理服务。Markdown Wiki 的写入就是写文件检索就是 grep 或者 BM25成本几乎可以忽略。这不是说向量检索一无是处。在模糊语义搜索、跨语言检索、推荐系统里它仍然有价值。但对于 Agent Memory 这种需要“精确记忆、双向校验、可修正”的场景传统方案反而更稳。3. Benchmark测什么才有说服力要得出“Markdown Wiki 超过所有产品”的结论评测维度必须覆盖真实使用场景。这里给出一套可复现的 Agent Memory 评测框架包含七个维度。3.1 事实准确率模拟一个 Agent 连续和用户对话多天对话中包含了明确的个人信息、截止日期、约定事项。结束后问 Agent 具体事实检查回答是否精确。测试题示例用户上周提到的客户的英文名是什么用户的项目演示定在几点用户对 PPT 的配色偏好是什么这类题目不允许 Agent 说“我记不清了”必须给出精确答案评测标准是字段级精确匹配。3.2 跨会话一致性同一件事在多轮对话中以不同方式被提及。评测时看 Agent 最终记忆是否合并正确。比如第一次说“下周三发布”第二次说“发布时间提前到周二”第三次问“什么时候发布”正确答案是“周二”。这个维度经常暴露专用记忆产品的结构性问题旧记忆和新记忆同时存在于向量库语义相近但答案矛盾检索时无法判断哪条是对的。Markdown Wiki 的优势在于AI 整理记忆时可以直接改写原文件旧的矛盾条目会被删除或标记失效。3.3 更新与遗忘能力验证 Agent 能否正确处理“记忆被更新”的情况。比如用户说“我不喜欢咖啡了改成喝茶”之后问“用户的饮品偏好是什么”。评测标准是新记忆必须完全覆盖旧记忆不能出现“用户可能喜欢咖啡或茶”这类骑墙回答。3.4 交叉引用能力Agent 记忆中有大量跨主题关联比如“项目 A 的负责人是张三”和“张三的邮箱是 zhangexample.com”。评测时问“项目 A 负责人的邮箱是什么”必须能通过两次跳转得到答案。Markdown Wiki 用双链语法能天然支持这种跳转向量检索则经常在这一步因为实体关联丢失而失败。3.5 检索延迟从用户提问到 Agent 做出回答记忆检索环节的耗时。专用产品通常包含多个服务调用Markdown Wiki 基本都是毫秒级文件读取延迟。评测时重点观察 P95 延迟因为峰值延迟往往被向量召回的不稳定性拖高。3.6 可解释性评分每次回答后要求 Agent 给出记忆来源。能明确指向具体文件条目的得高分只能给出“来自历史对话”的得低分。Markdown Wiki 天然具备这个能力因为答案是直接从某个文件注入的。3.7 综合成本包括存储成本、算力成本、维护成本、人工修正成本。按每万条记忆估算或者按 30 天连续运行统计。这套评测框架可以在自己的测试环境跑。不用迷信任何“官方榜单”把上述场景用脚本写清楚任何团队都能验证自己的 Agent 记忆到底行不行。4. Markdown Wiki 作为 Agent Memory 的设计原则如果决定采用 Markdown Wiki 方案设计上有几个原则要守住。4.1 一份记忆只写在一个文件里Agent 记忆最怕的是同一事实分散在多个文件。比如用户偏好写在“用户介绍.md”又在“对话记录/6月.md”里重复出现。将来检索时可能拿到两个版本无法判断新旧。建议的规则是同一实体、同一事件、同一偏好只允许出现在一个 canonical 文件中。AI 在做记忆整理时第一优先是“找到已有文件并更新”第二才是“新建文件”。4.2 文件名和标题就是检索索引Markdown Wiki 没有向量索引文件名和标题就是最重要的检索入口。文件名要使用稳定的实体名比如用户-张三.md 项目-产品发布.md 会议-2025-06-01-需求评审.md不要用对话 ID 或者无名的时间戳否则检索时找不到文件。4.3 双链比目录更重要双链语法[[项目-产品发布]]是 Markdown Wiki 的核心能力。每一份记忆文件里凡是涉及其他实体的地方都要用双链写出。这样检索时可以沿着链接做二级跳转。# 会议-2025-06-01-需求评审 - 参与人[[用户-张三]]、李四 - 关联项目[[项目-产品发布]] - 结论功能范围缩减优先保证登录模块4.4 YAML Frontmatter 记录元数据在 Markdown 文件头部加入 YAML Frontmatter用于记录更新时间、类型、重要度。这样后续写脚本处理时可以直接用程序读元数据。--- type: user-profile entity: 张三 updated: 2025-06-01 importance: high ---4.5 建立 MOC内容地图MOC 是 Wiki 的导航首页负责组织记忆的总体结构。每个 Agent 至少需要一个 MOC# Agent Memory Index ## 用户相关 - [[用户-张三]] ## 项目相关 - [[项目-产品发布]] ## 会议记录 - [[会议-2025-06-01-需求评审]]MOC 文件是 Agent 每次启动对话时最先注入的上下文帮助 LLM 快速定位记忆入口。5. 本地搭建从零开始建一个 Agent Memory Wiki下面给出一个具体的搭建流程不依赖任何特定商业产品纯开源和本地文件即可完成。5.1 创建目录结构mkdir -p agent-memory/{users,projects,meetings,daily,archive}建议目录users用户档案一人一个文件projects项目状态、决策记录meetings会议结论按日期命名daily每日对话摘要AI 每天生成archive过期记忆归档避免删除后无法回溯5.2 使用 Obsidian 作为可视化前端Obsidian 可以直接打开这个目录自动识别双链和 MOC。Obsidian 的优点是完全基于本地文件不锁定数据支持图谱视图移动端也能访问。也可以使用 VSCode 加 Markdown 插件适合纯命令行习惯的用户。5.3 写一个基础的记忆写入脚本Agent 在对话过程中需要把新信息写入 Wiki。下面是一个 Python 脚本示例用于把一条结构化记忆写入指定文件import os import datetime import hashlib MEMORY_ROOT ./agent-memory def write_memory(memory_type, content, entityNone): if memory_type user and entity: path os.path.join(MEMORY_ROOT, users, f{entity}.md) mode append elif memory_type meeting: today datetime.date.today().isoformat() path os.path.join(MEMORY_ROOT, meetings, f{today}.md) mode append else: file_id hashlib.md5(content.encode()).hexdigest()[:8] path os.path.join(MEMORY_ROOT, daily, f{datetime.date.today().isoformat()}-{file_id}.md) mode write os.makedirs(os.path.dirname(path), exist_okTrue) if mode append: with open(path, a, encodingutf-8) as f: f.write(content \n) else: with open(path, w, encodingutf-8) as f: f.write(content \n) print(fmemory written: {path}) return path这个脚本没有涉及任何向量模型只是纯文件操作因此任何机器上都能跑。5.4 AI 辅助整理把碎片对话变成结构化记忆真正完整的 Agent Memory 不能只靠人工写文件需要让 AI 每天把对话日志整理成结构化的 Markdown 条目。该整理任务的 Prompt 可以这样设计你是一个记忆整理助手。请阅读下面的对话记录提取需要长期保存的信息用 Markdown 格式输出。 输出要求 1. 用户明确表达的个人信息、偏好、计划、截止日期必须提取 2. 项目相关的决策、变更、任务分配必须提取 3. 每个条目使用一二级标题组织 4. 如果一条信息在更早的对话中出现过请标注已存在需更新 5. 不要输出与用户无关的通用事实。 对话记录 {{对话内容}}把 AI 整理后的 Markdown 文本交给上述写入脚本保存即可。6. 检索与注入把 Wiki 变成 LLM 的长期记忆搭建好 Wiki 之后核心问题变为Agent 在回答问题时如何从 Wiki 中找到相关记忆这里不采用向量检索而是采用“关键词 双链遍历 BM25”的组合方案。6.1 BM25 检索器实现BM25 是传统的文本检索算法对长文本召回非常稳定依赖少CPU 上毫秒级响应。下面的 Python 代码使用 rank_bm25 库实现pip install rank-bm25import os import re from rank_bm25 import BM25Okapi class MarkdownWikiRetriever: def __init__(self, wiki_root): self.wiki_root wiki_root self.docs [] # 全文 self.paths [] # 对应的文件路径 self.bm25 None def load_documents(self): for root, dirs, files in os.walk(self.wiki_root): for fname in files: if not fname.endswith(.md): continue path os.path.join(root, fname) with open(path, r, encodingutf-8) as f: content f.read() self.paths.append(path) self.docs.append(content) tokenized [self._tokenize(doc) for doc in self.docs] self.bm25 BM25Okapi(tokenized) print(floaded {len(self.docs)} markdown files) def _tokenize(self, text): return re.findall(r[\w\u4e00-\u9fa5], text.lower()) def search(self, query, top_k3): tokens self._tokenize(query) scores self.bm25.get_scores(tokens) ranked sorted(range(len(scores)), keylambda i: scores[i], reverseTrue) results [] for idx in ranked[:top_k]: if scores[idx] 0: continue results.append({ path: self.paths[idx], score: scores[idx], content: self.docs[idx][:2000], }) return results写完后先建一个索引retriever MarkdownWikiRetriever(./agent-memory) retriever.load_documents() results retriever.search(用户通勤方式, top_k2) for r in results: print(ffile: {r[path]}, score: {r[score]})6.2 双链遍历增强BM25 返回的文件中如果包含双链[[项目-产品发布]]可以额外加载这些被链接的文件让 LLM 获得二级上下文。这种“一跳扩展”能明显提升交叉引用问题的回答质量。import re def expand_wiki_links(contents, max_hops1): linked_docs [] for content in contents: links re.findall(r\[\[([^\]])\]\], content) for link in links: target_path find_markdown_file(link) if target_path: with open(target_path, r, encodingutf-8) as f: linked_docs.append(f.read()) return linked_docs6.3 注入到 LLM 上下文最终把检索到的内容格式化为可注入的上下文。以下是你可以参考的长期记忆片段来自本地 Wiki --- 记忆 1 / 来源: users/张三.md --- # 用户-张三 - 居住地杭州 - 通勤方式地铁 1 号线 --- 记忆 2 / 来源: meetings/2025-06-01.md --- # 需求评审结论 - 功能范围缩减优先登录模块 请基于以上记忆回答用户问题如果记忆与用户当前说法冲突以用户当前说法为准。将这段文本拼接到系统 Prompt 或对话历史中即可。6.4 无 GPU 也能跑整个检索链路只有 Python、文件系统、BM25 三个环节不需要 CUDA、不需要嵌入模型、不需要向量数据库。这意味着在一台 2 核 4G 内存的轻量服务器上就能运行一个完整的 Agent Memory 后端。7. 接口 API 与自动化批量任务如果你要把 Wiki 接入到自建的 Agent 框架或者团队其他人需要调用记忆服务建议封装一层轻量 API。7.1 FastAPI 接口示例from fastapi import FastAPI, HTTPException from pydantic import BaseModel import MarkdownWikiRetriever app FastAPI() retriever MarkdownWikiRetriever(./agent-memory) retriever.load_documents() class SearchRequest(BaseModel): query: str top_k: int 3 class MemoryWriteRequest(BaseModel): memory_type: str entity: str None content: str app.get(/health) def health(): return {status: ok, wiki_files: len(retriever.docs)} app.post(/api/retrieve) def retrieve(req: SearchRequest): results retriever.search(req.query, top_kreq.top_k) return {results: results} app.post(/api/write) def write_memory(req: MemoryWriteRequest): path write_memory(req.memory_type, req.content, req.entity) retriever.load_documents() return {path: path, status: ok}启动uvicorn wiki_memory_api:app --host 127.0.0.1 --port 88007.2 批量任务设计常见批量任务包括每日 0 点整理前一天对话日志每周扫描所有 Markdown 文件检查双链断裂每月归档超过 180 天未更新的低优先级记忆每次写入后重建 BM25 索引一个简单的定时任务示例0 0 * * * cd /path/to/project python scripts/daily_summary.py logs/daily_summary.log 21 0 2 * * * cd /path/to/project python scripts/rebuild_index.py logs/rebuild_index.log 217.3 失败重试建议如果某个批量任务处理到一半失败建议先把处理进度记录在.progress文件重启后从上次位置继续写入 Wiki 是幂等操作重复执行不会造成数据损坏BM25 索引重建很快即使每次写入都重建压力也可接受8. 资源占用与性能观察从典型运行情况看Markdown Wiki 方案的资源占用极低但这取决于 Wiki 文件数量和单次检索返回的文本量建议在自己的环境里做一次量化观察。8.1 观察方法如果你使用 Linux可以用htop看内存用du -sh看 Wiki 目录体积用time python test_query.py看检索耗时。du -sh ./agent-memory time python query_test.py8.2 性能特征500 个 Markdown 文件内BM25 检索耗时通常是毫秒级5000 个文件时内存占用仍很低主要耗时来自文件遍历和 tokenize双链跳转扩展一次最多增加几个文件的读取耗时仍可控相比向量检索不需要网络调用也不需要为召回结果做后处理8.3 降低资源占用的方法大批量写入后只在整点重建 BM25 索引而不是每次都重建文件数量增长到几千个后可以把 Archive 目录排除在索引外检索时限制返回文本长度例如content[:2000]如果同时有大量并发请求在 API 层加一个进程级缓存8.4 避免端口冲突和进程残留API 服务如果出现端口被占用可以先查端口lsof -i :8800 kill pid然后再重启服务。批量任务建议用日志文件记录每次运行结果避免重复启动多个实例同时写入文件。9. 常见问题与排查方法问题现象可能原因排查方式解决方案检索结果相关性差文件名和正文没有包含目标关键词检查目标文件是否存在、关键词是否写全补全标题和双链统一命名规范双链跳转找不到文件双链文本与文件名不一致在 Obsidian 中查看链接是否变灰统一实体命名使用索引脚本校验更新记忆后旧信息仍被召回Wiki 中存在多个同事实文件搜索关键词检查重复文件合并文件只保留 canonical 文件Agent 回答出现记忆矛盾新旧记忆没有正确覆盖查看 AI 整理结果是否做了更新操作调整整理 Prompt要求显式标记“已更新”API 服务响应慢向量检索不存在通常是文件过多或每次重建索引检查 stdout 日志和 CPU 占用分批重建检索结果截断批量任务重复写入没有记录处理进度检查日志和文件更新时间添加.progress文件机制Markdown 文件不小心被改乱没有版本管理查看文件修改时间为 Wiki 目录初始化 Git提交版本快照多线程同时写一个文件并发任务没有加锁观察文件内容是否出现交错覆盖写入用单 Worker 或加文件锁排查时最常用的定位手段是直接打开 Markdown 文件人工查看。因为所有记忆都是纯文本问题很容易暴露。这也是这个方案比黑盒记忆产品好排查的核心原因。10. 最佳实践与使用建议10.1 第一次先小规模验证不要一开始就把所有历史对话灌进 Wiki。先跑一周用真实的 50 条记忆测试召回准确率再逐步扩大。10.2 保留最小可运行配置建议把以下内容固定下来目录结构固定为 users/projects/meetings/daily/archive双链命名规则固定为“实体类型 名称”如项目-产品发布所有文件头部必须有 YAML Frontmatter每日 AI 整理任务必须有日志10.3 目录、脚本、数据分层管理agent-memory/ # 记忆数据纳入 Git scripts/ # 整理、检索、索引脚本 logs/ # 运行日志不纳入 Git tests/ # 测试脚本和样例数据10.4 批量任务要加日志和失败重试每个定时任务至少输出一行日志记录开始时间、处理数量、结束状态。失败时能在日志中看到卡在哪一步。10.5 接口服务限制访问范围API 如果部署在服务器上建议只监听127.0.0.1或使用防火墙限制来源 IP。如果需要在局域网共享应增加简单的 Token 校验。10.6 涉及隐私数据时先确认边界Wiki 里如果记录了用户个人信息、公司内部项目或对话内容无论是个人使用还是团队使用都要注意数据的存储位置和访问控制。如果期望长期保存建议定期检查映射关系和 Git 历史确保边界清晰。10.7 先用 Git 做记忆版本管理Git 是 Markdown Wiki 天然的配套工具支持回溯任意历史版本cd agent-memory git init git add . git commit -m init memory每次 AI 整理后提交一次可随时回滚。这里要提醒的是如果记忆库中包含非常敏感的文本请确保 Git 仓库保存在可信环境里不推送到公共远程仓库。10.8 发布或商用前做效果复核如果有任何输出会面向外部用户展示发布前应该复核记忆来源是否准确、是否有过时信息。不要完全依赖自动整理结果。11. 结论什么时候该用 Markdown Wiki回到标题为什么一个 Markdown Wiki 能在 benchmark 里超过所有 AI agent memory 产品最直接的原因是这个方案没有把简单问题复杂化。Agent Memory 的核心目标是“准确地记住并调用事实”而不是“存储海量语义信息”。Markdown Wiki 用纯文本、结构化的方式存储事实用关键词和双链来定位事实用 LLM 来做整理和生成。每一步都可解释、可修正、可测试。这个方案也有边界。如果你的场景是处理亿级非结构化记忆或者需要跨语言的模糊语义检索向量库仍然是必要组件。到时可以考虑混合方案Markdown Wiki 作为权威记忆层向量库作为模糊发现层最终以 Markdown Wiki 的结果为准。最容易踩的坑有两个一是文件命名不规范导致检索不到二是 AI 整理记忆时重复建文件而不是更新旧文件。这两个坑只要在前两步用规则和 Prompt 约束好后面的运行会非常省心。如果你正在被 Agent 记忆的准确率折磨或者想给团队上一套低成本、可控的知识库建议从今天开始建一个 Markdown Wiki每天让 LLM 帮你整理几段对话连续跑一周再对比效果。这个方案的每一个环节都能自己验证也适合长期积累。