如果你用 AI Agent 写过稍微长一点的代码或者让它跨了好几个会话处理同一个项目多半会碰到同一个问题它记不住。同一个决策反复确认上一轮说好的技术选型下一轮它又给你一套完全相反的方案。这不是 Agent 变笨了而是它只活在上下文窗口里。每次新会话之前的结论、偏好和项目约束都会被清空。要解决这个问题就需要给 Agent 接一套能长期保存、随时召回的记忆系统。这次我们来看 Basic Memory 这个开源项目。Basic Memory 是一套面向 Claude Code、Claude Desktop 等场景的本地长期记忆方案。它不依赖中心化数据库也没有额外云服务而是把知识写成 Markdown 文件用 SQLite 做索引再通过 MCP 协议把记忆能力暴露给 AI Agent。换句话说它在本地维护一个可以搜索、可以版本管理的知识库同时让你能像用 Obsidian 一样查看和编辑这些记忆。核心卖点可以归纳成三点一是零云端依赖所有数据都在本机二是知识可见不是埋在一个向量数据库里的黑盒三是接口标准所有访问都走 MCP能和主流 Agent 工具直接对接。这篇文章会带你把整套流程走一遍从环境准备、安装部署、目录初始化到配置 Obsidian 可视化、注册 MCP 服务再到功能测试、批量导入、接口调用和常见问题排查。读完以后你至少能自己搭出一个能用的本地长期记忆系统并在 Claude Code 里实际验证“这个会话记住的东西下一个会话还能查到”。1. 核心能力速览先把最关键的信息放在前面。这个项目不像大模型那样吃 GPU它的硬件门槛很低更适合先看功能规格再决定要不要试。能力项说明项目类型开源本地长期记忆系统知识存储Markdown 文本文件 SQLite 索引核心协议MCPModel Context Protocol主要集成对象Claude Code、Claude Desktop、Obsidian 等数据隐私默认本地运行不对接外部云服务硬件门槛普通 CPU / 内存即可不依赖 GPU启动方式命令行 MCP 服务可视化入口Obsidian 仓库 / 文件系统直接查看API 能力通过 MCP 工具对外提供读写搜索能力批量能力支持批量导入 Markdown、脚本化写入适合读者AI Agent 开发者、Claude 用户、知识管理爱好者从公开资料和使用反馈来看Basic Memory 的定位不是“大数据量向量数据库”而是“可读、可搜索、可维护的 Agent 记忆目录”。如果你的诉求是给 Agent 补上持久记忆同时希望所有内容在自己手里这类方案比纯云端记忆服务更适合。2. 适用场景与使用边界Basic Memory 解决的是 Agent 的跨会话记忆问题。典型场景很明确你在 Claude Code 里做一个项目第一天确定用 Python 3.13第三天换了个新会话继续写Agent 又问你“这个项目用什么 Python 版本”。如果有了长期记忆Agent 会先检索本地记忆把项目约定拿出来之后的回答和操作都基于这些记录。这个过程和人打开笔记软件找历史决策是一样的。它适合下面几类读者AI Agent 开发者想给自己接的 Agent 增加“记性”又不想依赖远程数据库。Claude Code 深度用户希望让同一个项目的多次会话保持上下文一致。知识管理爱好者喜欢用 Markdown 维护笔记又想把这些笔记直接变成 Agent 的记忆。团队协作场景把项目约定、代码规范、用户偏好写进记忆库所有成员共享一套知识。使用边界也要说清楚。Basic Memory 不是为海量非结构化数据设计的它的优势是“可读、可维护、可审计”不是“超大容量检索”。如果你的知识库里有大量 PDF、数据库记录、音视频内容直接往 Basic Memory 里塞并不合适更应该考虑向量数据库或专业检索系统。其次Basic Memory 的完整能力依赖 MCP 客户端如果你的 Agent 工具不支持 MCP就需要通过 CLI 或文件系统间接使用体验会打折扣。涉及隐私和合规时建议把这些规则加入记忆库不写入密钥、Token、身份证号、手机号等敏感信息涉及第三方版权内容时不直接导入如果记忆库用于团队协作需确认成员对共享内容的授权范围。Basic Memory 的数据默认保存在本机比云端服务泄露面小但本机数据也要做好备份和访问控制。3. 环境准备与前置条件开始部署前先把环境条件捋一遍避免装到一半才发现缺东西。操作系统方面macOS 和 Linux 体验最顺Windows 下建议优先考虑 WSL 环境因为 Basic Memory 的命令行工具和文件路径规则与 Unix 体系更贴合。Python 版本建议准备 3.10 及以上具体以当前版本官方要求为准。项目本质是一个 Python 命令行工具安装时会带上依赖所以 Python 环境是整个部署的核心。还需要一个能编辑 Markdown 的工具。官方推荐 Obsidian因为 Basic Memory 生成的笔记结构天然适合 Obsidian 仓库。你也可以用 VS Code、Typora 等工具查看但 Obsidian 对双链、标签、目录树的支持最好。如果要跑完整的 MCP 集成还需要一个支持 MCP 的客户端例如 Claude Code、Claude Desktop 或兼容 MCP 的本地工具。磁盘空间和内存不用太担心。Basic Memory 本身只占几十 MB 到几百 MB 空间日常笔记通常都是纯文本增长很慢。如果你计划批量导入大量 Markdown再准备 1GB 以上磁盘空间就够了。端口方面Basic Memory 的 MCP 服务默认走本地进程通信不会像 WebUI 那样占一个明显端口。不过如果你的项目里已经跑了多个 MCP 服务器注意不同工具别互相冲突。4. 安装部署与启动方式4.1 安装 basic-memory安装方式就是 Python 包安装。先打开终端建议用虚拟环境或用户级安装避免污染系统 Python。python -m pip install --upgrade basic-memory如果你本地装了 uv也可以用 uv 安装速度更快uv tool install basic-memory安装完成后验证一下版本basic-memory --version如果提示command not found检查 Python 的 Scripts 目录是否在 PATH 中。macOS 和 Linux 通常位于~/Library/Python/3.x/bin或~/.local/binWindows 在%APPDATA%\Python\Scripts附近。把对应目录加入 PATH 后重新打开终端即可。4.2 初始化记忆目录安装好后先初始化。初始化命令会在你的用户目录下创建 Basic Memory 的默认数据目录一般是~/.basic-memory同时生成必要配置项。basic-memory init不同版本之间init 子命令可能会有差异。如果提示init不存在先执行basic-memory --help看一下当前版本支持哪些命令。初始化完成后可以确认目录结构ls -la ~/.basic-memory正常会出现类似下面的内容~/.basic-memory/ ├── index.db ├── notes/ ├── ...index.db 是 SQLite 索引文件notes 目录用于存放 Markdown 笔记。具体目录名和配置文件格式以你安装的版本实际生成为准这里给的是通用结构。4.3 关联 Obsidian 仓库可视化查看记忆最推荐的方式是把~/.basic-memory/notes目录直接作为 Obsidian 仓库打开。打开 Obsidian选择“Open folder as vault”选中~/.basic-memory/notes。打开后你会看到 Basic Memory 生成的 Markdown 文件按年月之类的结构分层。Agent 写入的记忆、项目决策、用户偏好都会以普通 Markdown 文件存在这里。这样做的最大好处是你随时能用 Obsidian 打开看、改、删不依赖任何命令行工具。而且你改完 Markdown 文件后SQLite 索引需要重新同步。不同版本的同步逻辑不一样有些会监听文件变化有些需要手动重建索引。建议在 Obsidian 里修改文件后运行一次basic-memory status或basic-memory reindex检查并更新索引。4.4 配置 MCP 服务MCP 是 Basic Memory 对外提供能力的关键接口。把 MCP 服务注册到 Claude Code 或 Claude Desktop 里Agent 才能在对话中直接调用记忆读写工具。如果是 Claude Code 新版客户端可以尝试用命令行注册claude mcp add basic-memory -- basic-memory mcp注册完成后Claude 会在启动时拉起 basic-memory 的 MCP 服务。如果你的 Claude Code 版本需要通过配置文件注册可以在对应的 MCP 配置里加一段{ mcpServers: { basic-memory: { command: basic-memory, args: [mcp], env: { BASIC_MEMORY_HOME: ~/.basic-memory } } } }这里BASIC_MEMORY_HOME指向实际的数据目录按你的环境调整。配置完成后重启 Claude Code 客户端在对话里搜索 MCP 工具名应该能看到 Basic Memory 注册的工具列表。4.5 启动与初步验证Basic Memory 没有独立的 Web 界面所谓“启动”其实是启动 MCP 进程。为了确认 MCP 服务能正常工作可以先在终端手动跑一下basic-memory mcp如果命令能持续执行不报错说明 MCP 服务进程本身是正常的。然后写一条测试记忆basic-memory write 项目约定Python 3.13代码注释使用中文执行完成后打开~/.basic-memory/notes目录应该能看到新生成的 Markdown 文件内容包含刚才写入的那句话。到这里安装和启动已经跑通了。5. 功能测试与效果验证部署只是第一步真正重要的是验证“Agent 到底能不能用上这些记忆”。下面按测试维度拆开讲。5.1 记忆写入测试先测最基本的写入。写一条记忆然后立刻用文件系统和日志确认它进库了。输入示例basic-memory write 2025-04-01项目 A 确定使用 FastAPI 作为后端框架成功标准命令退出码为 0~/.basic-memory/notes目录下新增了 Markdown 文件文件内容包含刚才写入的文本。如果命令没有创建文件很可能是用户目录权限不对或者配置里把 notes 路径指到了别处。失败排查先执行basic-memory status看是否能读取当前状态再执行basic-memory --help确认 write 子命令在当前版本存在。还有一些旧版本用remember而不是write这时候以 help 输出为准。5.2 搜索召回测试写入之后再验证关键词搜索能否召回。输入示例basic-memory search FastAPI成功标准搜索结果里能出现刚才写入的那条记忆并显示文件路径。如果搜索不到先检查写入的文件是否还在再手动跑一次索引重建。这个测试直接决定 Agent 后续能不能在对话中找到记忆属于核心链路。5.3 Obsidian 可视化测试打开 Obsidian 仓库把写入的笔记文件打开确认标题、正文、标签显示正常。再尝试在 Obsidian 里修改一条笔记内容保存后执行索引重建命令然后重新搜索看修改后的内容是否被索引到。成功标准Obsidian 中能看到 Agent 写的记忆手动修改后搜索能召回新内容。如果手动修改后搜索不到说明索引没有自动同步你需要把“修改后重建索引”写进自己的操作流程。5.4 MCP 端到端测试这一步是真正的 Agent 链路验证。在 Claude Code 中开启一个新会话直接问它“根据我的记忆项目 A 确定用什么后端框架”如果 MCP 配置成功Agent 会调用 Basic Memory 的搜索工具检索记忆并基于召回结果回答“FastAPI”。你也可以让 Agent 主动写一条记忆“请记住部署环境使用 Docker Compose容器名称统一加 -app 后缀。”然后打开 Obsidian 确认这条内容确实落盘。成功标准Agent 能读取到之前写入的记忆也能主动写入新记忆并且这些操作都发生在当前会话之外的持久存储中。注意如果 Agent 回答时没有调用 MCP 工具可能不是你配置错了而是它判断当前提问没必要查记忆。你可以把提问改成“先搜索你的记忆再回答”强制触发工具调用。5.5 批量导入测试如果你已经有一批 Markdown 笔记想批量导入先拿一个小目录测试basic-memory import --file ./memory_notes/*成功标准目录下的 Markdown 文件都被导入并且能搜索到。如果只导入了一部分先检查文件编码推荐统一为 UTF-8再检查文件头部是否有异常格式。批处理逻辑和排错细节后面在第 6 节单独展开。6. 接口 API 与批量任务很多同学关心“能不能把 Basic Memory 接到自己的 Agent 工具里”。这里的关键点是Basic Memory 的对外接口主要是 MCP 协议不是传统 REST API。MCP 服务启动后会暴露一组工具大致包括写入记忆把一段文本写入当前记忆库自动生成 Markdown 文件并建立索引。搜索记忆根据关键词或语义查询本地记忆返回相关笔记片段。列出笔记按目录或标签列出当期笔记方便快速浏览。读取笔记根据文件路径或笔记 ID 读取完整内容。更新索引重新扫描磁盘上的 Markdown 文件把新增或修改的内容同步到索引。不同版本暴露的工具名有差别实际使用前先看客户端的 MCP 工具列表再按工具名调用。如果你要写自动化脚本可以直接调用 CLI不需要经过 MCP。CLI 的好处是便于 shell 脚本、cron 定时任务、CI 流程集成。一个最简单的批量写入示例# 批量写入多条记忆 basic-memory write 习惯代码提交信息使用 conventional commits basic-memory write 习惯分支命名用 feature/前缀 basic-memory write 约定线上环境禁止直接修改数据库如果要把一整批 Markdown 文件导入知识库优先用import命令# 导入单目录下所有 md 文件 basic-memory import --file ./memory_notes/*注意shell 的通配符*会被直接展开所以如果你的文件很多建议先拆成小批量跑一遍确认导入逻辑稳定之后再扩大范围。Python 脚本调用也是常见做法import subprocess notes [ 项目约定API 统一返回 {code, message, data} 格式, 项目约定错误码 2xx 表示正常4xx 表示参数错误, 项目约定测试环境域名使用 staging.example.com, ] for note in notes: result subprocess.run( [basic-memory, write, note], checkTrue, capture_outputTrue, textTrue ) print(result.stdout)这样可以把从数据库、Excel、问卷里整理出来的文本批量灌进 Basic Memory再由 Agent 在后续会话里检索使用。批量导入时建议加日志和失败重试避免一条失败导致整批中断#!/bin/bash # 批量导入失败重试示例 for f in ./memory_notes/*.md; do echo 导入 $f basic-memory import --file $f || echo 失败: $f import_errors.log done接口这块最稳的使用方式是先跑通 CLI再跑通 MCP。如果你要接入 n8n、Dify 这类平台通常需要通过 MCP 客户端或本地 HTTP 桥接。这个过程不同平台差异大建议先确认目标平台是否支持 MCP 工具调用再决定集成方案。7. 资源占用与性能观察Basic Memory 不跑大模型不依赖 GPU所以“显存占用”在这个项目里不适用。它更值得关注的是命令行启动时间、MCP 进程内存占用、搜索延迟、SQLite 索引增长速度。先看启动速度。执行basic-memory --help或basic-memory status如果命令能在 1 秒内返回说明环境正常。MCP 进程启动时会加载 SQLite 索引数据量不大时基本是瞬间完成。如果你发现启动了好几秒优先检查是不是磁盘 IO 慢或者配置文件里写了不存在的路径导致反复重试。再看查询延迟。搜索本地 Markdown 文件数据量在几千条笔记以内正常应该几十到几百毫秒返回结果。如果搜索变慢先看 SQLite 索引是否需要重建再看是不是有超长 Markdown 文件拖慢了全文扫描。内存占用方面Basic Memory 本身是轻量工具但有两个情况会导致内存升高一是单次导入超大 Markdown 文件解析过程会把全文载入内存二是索引里积累了大量重复文档没有及时清理。建议大文件先拆分再导入定期清理无效笔记重建索引后再做一次 VACUUM# 需要 sqlite3 命令行工具按实际数据库路径调整 sqlite3 ~/.basic-memory/index.db VACUUM;如果你在 Windows 上跑更推荐用 WSL 环境跑命令行文件路径和 MCP 进程的兼容性会更好。最后记得任何本地知识库都要备份。Basic Memory 的数据本质是 Markdown 文件直接对~/.basic-memory/notes做文件备份即可索引数据库丢了可以用笔记重建。8. 常见问题与排查方法问题现象可能原因排查方式解决方案basic-memory命令不存在Python Scripts 目录不在 PATH检查which basic-memory/where basic-memory添加 PATH 或重新安装init 命令执行报错用户目录权限不足查看错误日志改用用户目录安装避免 sudoMCP 服务连不上没有注册成功或进程未启动手动运行basic-memory mcp重新注册 MCP并在客户端检查工具列表Obsidian 打开后看不到笔记vault 路径指向错误检查~/.basic-memory/notes是否存在更换 vault 为正确目录写入成功但搜索不到索引未同步执行basic-memory status或重建索引手动重建索引中文内容搜索乱码文件编码非 UTF-8查看文件编码统一转为 UTF-8批量导入中途失败文件格式或编码不统一查看导入日志拆批导入加失败重试MCP 工具总是超时数据量过大或索引损坏查看 MCP 日志重建索引精简记忆条目同一句话重复写入没有去重策略搜索确认再写入写入前先检查是否存在相似条目一个最常见的坑是MCP 配置写好了但 Claude 并不知道要用 Basic Memory。遇到这种情况不要反复改配置先在客户端里打开 MCP 工具面板确认 basic-memory 工具确实出现在工具列表里。如果工具列表为空说明服务注册有问题手动执行basic-memory mcp看有无报错。另一个典型问题是修复索引目录后旧文件仍然被搜索到。这种情况下建议先把索引重建跑一遍basic-memory reindex如果当前版本没有 reindex 子命令用 help 查看是否有 reindex、sync、refresh 之类的替代命令。以你本地版本实际输出为准。9. 最佳实践与使用建议长期记忆系统最怕的不是“没存进去”而是“存了一堆垃圾后来根本不想看”。所以从第一天就建立规范比事后整理省力得多。第一给记忆分类。写入时尽量包含主题词和日期例如“项目A-2025-04-01-后端框架决策”。这让搜索命中率更高也让 Obsidian 里的文件树更好看。不要所有记忆都写成“记住 xxx”没有上下文时间一长根本搜不到。第二保持记忆库精简。Basic Memory 的价值是“精确召回”不是“备份归档”。那些已经过时、被推翻的决策要主动删掉或标记为废弃不要留在库里面干扰后续回答。可以定期清理一次把彻底无效的笔记移出记忆目录然后重建索引。第三建立写前检查习惯。让 Agent 在写入之前先搜索一次如果已经存在冲突结论先确认保留哪条。这个“先查再写”的流程比事后清理更有效。你还应该在 CLAUDE.md 或系统提示词里明确告诉 Agent“在回答问题或写入记忆前先使用 Basic Memory 工具搜索相关内容。”第四做好备份和版本管理。通过 Git 管理~/.basic-memory/notes目录是最简单可靠的方案。每次记忆变更后提交一次既能追溯历史又能随时回滚错误写入。很多“记忆被覆盖”的问题靠版本管理就能解决。第五注意合规边界。不要往记忆库里写入明文密码、Token、身份证号、银行卡号等敏感信息。涉及客户资料、版权内容、内部系统信息时先确认是否有权存、有权用。Basic Memory 默认本地存储但如果你把笔记目录同步到了云端网盘风险范围就扩大了权限控制要做得更严格。10. 总结与下一步Basic Memory 最值得试的点是它把 Agent 记忆从“黑盒向量数据库”变成了“你可以用 Obsidian 打开看的 Markdown 文件”。这对调试非常友好。Agent 到底记住了什么、遗忘什么打开文件一眼就能看到不需要查数据库、看 embedding。第一次部署建议按这个顺序验证先安装并初始化再写一条记忆并搜索然后配置 Obsidian 打开目录最后注册 MCP在 Claude Code 里做端到端测试。跑通这条链路后再考虑批量导入历史笔记和接入 n8n、Dify 等自动化平台。最容易踩的坑是 MCP 配置后没有确认工具列表就盲目使用以及 Obsidian 修改笔记后没有重建索引。把这两点检查好基本能覆盖 80% 的“记忆失效”问题。后续可以扩展的方向很多给记忆库加标签体系和自动归档规则用 Git 做多端同步在团队里共享一套记忆库或者把 Basic Memory 接入 n8n 工作流让 Agent 在处理完任务后自动把关键结论写入记忆。从“让 Agent 记住”到“让 Agent 记住得更好”还有不少可以打磨的空间。建议先跑通基础链路再逐步把知识管理流程吸收进来。
AI Agent记不住？用Basic Memory打造本地长期记忆系统
如果你用 AI Agent 写过稍微长一点的代码或者让它跨了好几个会话处理同一个项目多半会碰到同一个问题它记不住。同一个决策反复确认上一轮说好的技术选型下一轮它又给你一套完全相反的方案。这不是 Agent 变笨了而是它只活在上下文窗口里。每次新会话之前的结论、偏好和项目约束都会被清空。要解决这个问题就需要给 Agent 接一套能长期保存、随时召回的记忆系统。这次我们来看 Basic Memory 这个开源项目。Basic Memory 是一套面向 Claude Code、Claude Desktop 等场景的本地长期记忆方案。它不依赖中心化数据库也没有额外云服务而是把知识写成 Markdown 文件用 SQLite 做索引再通过 MCP 协议把记忆能力暴露给 AI Agent。换句话说它在本地维护一个可以搜索、可以版本管理的知识库同时让你能像用 Obsidian 一样查看和编辑这些记忆。核心卖点可以归纳成三点一是零云端依赖所有数据都在本机二是知识可见不是埋在一个向量数据库里的黑盒三是接口标准所有访问都走 MCP能和主流 Agent 工具直接对接。这篇文章会带你把整套流程走一遍从环境准备、安装部署、目录初始化到配置 Obsidian 可视化、注册 MCP 服务再到功能测试、批量导入、接口调用和常见问题排查。读完以后你至少能自己搭出一个能用的本地长期记忆系统并在 Claude Code 里实际验证“这个会话记住的东西下一个会话还能查到”。1. 核心能力速览先把最关键的信息放在前面。这个项目不像大模型那样吃 GPU它的硬件门槛很低更适合先看功能规格再决定要不要试。能力项说明项目类型开源本地长期记忆系统知识存储Markdown 文本文件 SQLite 索引核心协议MCPModel Context Protocol主要集成对象Claude Code、Claude Desktop、Obsidian 等数据隐私默认本地运行不对接外部云服务硬件门槛普通 CPU / 内存即可不依赖 GPU启动方式命令行 MCP 服务可视化入口Obsidian 仓库 / 文件系统直接查看API 能力通过 MCP 工具对外提供读写搜索能力批量能力支持批量导入 Markdown、脚本化写入适合读者AI Agent 开发者、Claude 用户、知识管理爱好者从公开资料和使用反馈来看Basic Memory 的定位不是“大数据量向量数据库”而是“可读、可搜索、可维护的 Agent 记忆目录”。如果你的诉求是给 Agent 补上持久记忆同时希望所有内容在自己手里这类方案比纯云端记忆服务更适合。2. 适用场景与使用边界Basic Memory 解决的是 Agent 的跨会话记忆问题。典型场景很明确你在 Claude Code 里做一个项目第一天确定用 Python 3.13第三天换了个新会话继续写Agent 又问你“这个项目用什么 Python 版本”。如果有了长期记忆Agent 会先检索本地记忆把项目约定拿出来之后的回答和操作都基于这些记录。这个过程和人打开笔记软件找历史决策是一样的。它适合下面几类读者AI Agent 开发者想给自己接的 Agent 增加“记性”又不想依赖远程数据库。Claude Code 深度用户希望让同一个项目的多次会话保持上下文一致。知识管理爱好者喜欢用 Markdown 维护笔记又想把这些笔记直接变成 Agent 的记忆。团队协作场景把项目约定、代码规范、用户偏好写进记忆库所有成员共享一套知识。使用边界也要说清楚。Basic Memory 不是为海量非结构化数据设计的它的优势是“可读、可维护、可审计”不是“超大容量检索”。如果你的知识库里有大量 PDF、数据库记录、音视频内容直接往 Basic Memory 里塞并不合适更应该考虑向量数据库或专业检索系统。其次Basic Memory 的完整能力依赖 MCP 客户端如果你的 Agent 工具不支持 MCP就需要通过 CLI 或文件系统间接使用体验会打折扣。涉及隐私和合规时建议把这些规则加入记忆库不写入密钥、Token、身份证号、手机号等敏感信息涉及第三方版权内容时不直接导入如果记忆库用于团队协作需确认成员对共享内容的授权范围。Basic Memory 的数据默认保存在本机比云端服务泄露面小但本机数据也要做好备份和访问控制。3. 环境准备与前置条件开始部署前先把环境条件捋一遍避免装到一半才发现缺东西。操作系统方面macOS 和 Linux 体验最顺Windows 下建议优先考虑 WSL 环境因为 Basic Memory 的命令行工具和文件路径规则与 Unix 体系更贴合。Python 版本建议准备 3.10 及以上具体以当前版本官方要求为准。项目本质是一个 Python 命令行工具安装时会带上依赖所以 Python 环境是整个部署的核心。还需要一个能编辑 Markdown 的工具。官方推荐 Obsidian因为 Basic Memory 生成的笔记结构天然适合 Obsidian 仓库。你也可以用 VS Code、Typora 等工具查看但 Obsidian 对双链、标签、目录树的支持最好。如果要跑完整的 MCP 集成还需要一个支持 MCP 的客户端例如 Claude Code、Claude Desktop 或兼容 MCP 的本地工具。磁盘空间和内存不用太担心。Basic Memory 本身只占几十 MB 到几百 MB 空间日常笔记通常都是纯文本增长很慢。如果你计划批量导入大量 Markdown再准备 1GB 以上磁盘空间就够了。端口方面Basic Memory 的 MCP 服务默认走本地进程通信不会像 WebUI 那样占一个明显端口。不过如果你的项目里已经跑了多个 MCP 服务器注意不同工具别互相冲突。4. 安装部署与启动方式4.1 安装 basic-memory安装方式就是 Python 包安装。先打开终端建议用虚拟环境或用户级安装避免污染系统 Python。python -m pip install --upgrade basic-memory如果你本地装了 uv也可以用 uv 安装速度更快uv tool install basic-memory安装完成后验证一下版本basic-memory --version如果提示command not found检查 Python 的 Scripts 目录是否在 PATH 中。macOS 和 Linux 通常位于~/Library/Python/3.x/bin或~/.local/binWindows 在%APPDATA%\Python\Scripts附近。把对应目录加入 PATH 后重新打开终端即可。4.2 初始化记忆目录安装好后先初始化。初始化命令会在你的用户目录下创建 Basic Memory 的默认数据目录一般是~/.basic-memory同时生成必要配置项。basic-memory init不同版本之间init 子命令可能会有差异。如果提示init不存在先执行basic-memory --help看一下当前版本支持哪些命令。初始化完成后可以确认目录结构ls -la ~/.basic-memory正常会出现类似下面的内容~/.basic-memory/ ├── index.db ├── notes/ ├── ...index.db 是 SQLite 索引文件notes 目录用于存放 Markdown 笔记。具体目录名和配置文件格式以你安装的版本实际生成为准这里给的是通用结构。4.3 关联 Obsidian 仓库可视化查看记忆最推荐的方式是把~/.basic-memory/notes目录直接作为 Obsidian 仓库打开。打开 Obsidian选择“Open folder as vault”选中~/.basic-memory/notes。打开后你会看到 Basic Memory 生成的 Markdown 文件按年月之类的结构分层。Agent 写入的记忆、项目决策、用户偏好都会以普通 Markdown 文件存在这里。这样做的最大好处是你随时能用 Obsidian 打开看、改、删不依赖任何命令行工具。而且你改完 Markdown 文件后SQLite 索引需要重新同步。不同版本的同步逻辑不一样有些会监听文件变化有些需要手动重建索引。建议在 Obsidian 里修改文件后运行一次basic-memory status或basic-memory reindex检查并更新索引。4.4 配置 MCP 服务MCP 是 Basic Memory 对外提供能力的关键接口。把 MCP 服务注册到 Claude Code 或 Claude Desktop 里Agent 才能在对话中直接调用记忆读写工具。如果是 Claude Code 新版客户端可以尝试用命令行注册claude mcp add basic-memory -- basic-memory mcp注册完成后Claude 会在启动时拉起 basic-memory 的 MCP 服务。如果你的 Claude Code 版本需要通过配置文件注册可以在对应的 MCP 配置里加一段{ mcpServers: { basic-memory: { command: basic-memory, args: [mcp], env: { BASIC_MEMORY_HOME: ~/.basic-memory } } } }这里BASIC_MEMORY_HOME指向实际的数据目录按你的环境调整。配置完成后重启 Claude Code 客户端在对话里搜索 MCP 工具名应该能看到 Basic Memory 注册的工具列表。4.5 启动与初步验证Basic Memory 没有独立的 Web 界面所谓“启动”其实是启动 MCP 进程。为了确认 MCP 服务能正常工作可以先在终端手动跑一下basic-memory mcp如果命令能持续执行不报错说明 MCP 服务进程本身是正常的。然后写一条测试记忆basic-memory write 项目约定Python 3.13代码注释使用中文执行完成后打开~/.basic-memory/notes目录应该能看到新生成的 Markdown 文件内容包含刚才写入的那句话。到这里安装和启动已经跑通了。5. 功能测试与效果验证部署只是第一步真正重要的是验证“Agent 到底能不能用上这些记忆”。下面按测试维度拆开讲。5.1 记忆写入测试先测最基本的写入。写一条记忆然后立刻用文件系统和日志确认它进库了。输入示例basic-memory write 2025-04-01项目 A 确定使用 FastAPI 作为后端框架成功标准命令退出码为 0~/.basic-memory/notes目录下新增了 Markdown 文件文件内容包含刚才写入的文本。如果命令没有创建文件很可能是用户目录权限不对或者配置里把 notes 路径指到了别处。失败排查先执行basic-memory status看是否能读取当前状态再执行basic-memory --help确认 write 子命令在当前版本存在。还有一些旧版本用remember而不是write这时候以 help 输出为准。5.2 搜索召回测试写入之后再验证关键词搜索能否召回。输入示例basic-memory search FastAPI成功标准搜索结果里能出现刚才写入的那条记忆并显示文件路径。如果搜索不到先检查写入的文件是否还在再手动跑一次索引重建。这个测试直接决定 Agent 后续能不能在对话中找到记忆属于核心链路。5.3 Obsidian 可视化测试打开 Obsidian 仓库把写入的笔记文件打开确认标题、正文、标签显示正常。再尝试在 Obsidian 里修改一条笔记内容保存后执行索引重建命令然后重新搜索看修改后的内容是否被索引到。成功标准Obsidian 中能看到 Agent 写的记忆手动修改后搜索能召回新内容。如果手动修改后搜索不到说明索引没有自动同步你需要把“修改后重建索引”写进自己的操作流程。5.4 MCP 端到端测试这一步是真正的 Agent 链路验证。在 Claude Code 中开启一个新会话直接问它“根据我的记忆项目 A 确定用什么后端框架”如果 MCP 配置成功Agent 会调用 Basic Memory 的搜索工具检索记忆并基于召回结果回答“FastAPI”。你也可以让 Agent 主动写一条记忆“请记住部署环境使用 Docker Compose容器名称统一加 -app 后缀。”然后打开 Obsidian 确认这条内容确实落盘。成功标准Agent 能读取到之前写入的记忆也能主动写入新记忆并且这些操作都发生在当前会话之外的持久存储中。注意如果 Agent 回答时没有调用 MCP 工具可能不是你配置错了而是它判断当前提问没必要查记忆。你可以把提问改成“先搜索你的记忆再回答”强制触发工具调用。5.5 批量导入测试如果你已经有一批 Markdown 笔记想批量导入先拿一个小目录测试basic-memory import --file ./memory_notes/*成功标准目录下的 Markdown 文件都被导入并且能搜索到。如果只导入了一部分先检查文件编码推荐统一为 UTF-8再检查文件头部是否有异常格式。批处理逻辑和排错细节后面在第 6 节单独展开。6. 接口 API 与批量任务很多同学关心“能不能把 Basic Memory 接到自己的 Agent 工具里”。这里的关键点是Basic Memory 的对外接口主要是 MCP 协议不是传统 REST API。MCP 服务启动后会暴露一组工具大致包括写入记忆把一段文本写入当前记忆库自动生成 Markdown 文件并建立索引。搜索记忆根据关键词或语义查询本地记忆返回相关笔记片段。列出笔记按目录或标签列出当期笔记方便快速浏览。读取笔记根据文件路径或笔记 ID 读取完整内容。更新索引重新扫描磁盘上的 Markdown 文件把新增或修改的内容同步到索引。不同版本暴露的工具名有差别实际使用前先看客户端的 MCP 工具列表再按工具名调用。如果你要写自动化脚本可以直接调用 CLI不需要经过 MCP。CLI 的好处是便于 shell 脚本、cron 定时任务、CI 流程集成。一个最简单的批量写入示例# 批量写入多条记忆 basic-memory write 习惯代码提交信息使用 conventional commits basic-memory write 习惯分支命名用 feature/前缀 basic-memory write 约定线上环境禁止直接修改数据库如果要把一整批 Markdown 文件导入知识库优先用import命令# 导入单目录下所有 md 文件 basic-memory import --file ./memory_notes/*注意shell 的通配符*会被直接展开所以如果你的文件很多建议先拆成小批量跑一遍确认导入逻辑稳定之后再扩大范围。Python 脚本调用也是常见做法import subprocess notes [ 项目约定API 统一返回 {code, message, data} 格式, 项目约定错误码 2xx 表示正常4xx 表示参数错误, 项目约定测试环境域名使用 staging.example.com, ] for note in notes: result subprocess.run( [basic-memory, write, note], checkTrue, capture_outputTrue, textTrue ) print(result.stdout)这样可以把从数据库、Excel、问卷里整理出来的文本批量灌进 Basic Memory再由 Agent 在后续会话里检索使用。批量导入时建议加日志和失败重试避免一条失败导致整批中断#!/bin/bash # 批量导入失败重试示例 for f in ./memory_notes/*.md; do echo 导入 $f basic-memory import --file $f || echo 失败: $f import_errors.log done接口这块最稳的使用方式是先跑通 CLI再跑通 MCP。如果你要接入 n8n、Dify 这类平台通常需要通过 MCP 客户端或本地 HTTP 桥接。这个过程不同平台差异大建议先确认目标平台是否支持 MCP 工具调用再决定集成方案。7. 资源占用与性能观察Basic Memory 不跑大模型不依赖 GPU所以“显存占用”在这个项目里不适用。它更值得关注的是命令行启动时间、MCP 进程内存占用、搜索延迟、SQLite 索引增长速度。先看启动速度。执行basic-memory --help或basic-memory status如果命令能在 1 秒内返回说明环境正常。MCP 进程启动时会加载 SQLite 索引数据量不大时基本是瞬间完成。如果你发现启动了好几秒优先检查是不是磁盘 IO 慢或者配置文件里写了不存在的路径导致反复重试。再看查询延迟。搜索本地 Markdown 文件数据量在几千条笔记以内正常应该几十到几百毫秒返回结果。如果搜索变慢先看 SQLite 索引是否需要重建再看是不是有超长 Markdown 文件拖慢了全文扫描。内存占用方面Basic Memory 本身是轻量工具但有两个情况会导致内存升高一是单次导入超大 Markdown 文件解析过程会把全文载入内存二是索引里积累了大量重复文档没有及时清理。建议大文件先拆分再导入定期清理无效笔记重建索引后再做一次 VACUUM# 需要 sqlite3 命令行工具按实际数据库路径调整 sqlite3 ~/.basic-memory/index.db VACUUM;如果你在 Windows 上跑更推荐用 WSL 环境跑命令行文件路径和 MCP 进程的兼容性会更好。最后记得任何本地知识库都要备份。Basic Memory 的数据本质是 Markdown 文件直接对~/.basic-memory/notes做文件备份即可索引数据库丢了可以用笔记重建。8. 常见问题与排查方法问题现象可能原因排查方式解决方案basic-memory命令不存在Python Scripts 目录不在 PATH检查which basic-memory/where basic-memory添加 PATH 或重新安装init 命令执行报错用户目录权限不足查看错误日志改用用户目录安装避免 sudoMCP 服务连不上没有注册成功或进程未启动手动运行basic-memory mcp重新注册 MCP并在客户端检查工具列表Obsidian 打开后看不到笔记vault 路径指向错误检查~/.basic-memory/notes是否存在更换 vault 为正确目录写入成功但搜索不到索引未同步执行basic-memory status或重建索引手动重建索引中文内容搜索乱码文件编码非 UTF-8查看文件编码统一转为 UTF-8批量导入中途失败文件格式或编码不统一查看导入日志拆批导入加失败重试MCP 工具总是超时数据量过大或索引损坏查看 MCP 日志重建索引精简记忆条目同一句话重复写入没有去重策略搜索确认再写入写入前先检查是否存在相似条目一个最常见的坑是MCP 配置写好了但 Claude 并不知道要用 Basic Memory。遇到这种情况不要反复改配置先在客户端里打开 MCP 工具面板确认 basic-memory 工具确实出现在工具列表里。如果工具列表为空说明服务注册有问题手动执行basic-memory mcp看有无报错。另一个典型问题是修复索引目录后旧文件仍然被搜索到。这种情况下建议先把索引重建跑一遍basic-memory reindex如果当前版本没有 reindex 子命令用 help 查看是否有 reindex、sync、refresh 之类的替代命令。以你本地版本实际输出为准。9. 最佳实践与使用建议长期记忆系统最怕的不是“没存进去”而是“存了一堆垃圾后来根本不想看”。所以从第一天就建立规范比事后整理省力得多。第一给记忆分类。写入时尽量包含主题词和日期例如“项目A-2025-04-01-后端框架决策”。这让搜索命中率更高也让 Obsidian 里的文件树更好看。不要所有记忆都写成“记住 xxx”没有上下文时间一长根本搜不到。第二保持记忆库精简。Basic Memory 的价值是“精确召回”不是“备份归档”。那些已经过时、被推翻的决策要主动删掉或标记为废弃不要留在库里面干扰后续回答。可以定期清理一次把彻底无效的笔记移出记忆目录然后重建索引。第三建立写前检查习惯。让 Agent 在写入之前先搜索一次如果已经存在冲突结论先确认保留哪条。这个“先查再写”的流程比事后清理更有效。你还应该在 CLAUDE.md 或系统提示词里明确告诉 Agent“在回答问题或写入记忆前先使用 Basic Memory 工具搜索相关内容。”第四做好备份和版本管理。通过 Git 管理~/.basic-memory/notes目录是最简单可靠的方案。每次记忆变更后提交一次既能追溯历史又能随时回滚错误写入。很多“记忆被覆盖”的问题靠版本管理就能解决。第五注意合规边界。不要往记忆库里写入明文密码、Token、身份证号、银行卡号等敏感信息。涉及客户资料、版权内容、内部系统信息时先确认是否有权存、有权用。Basic Memory 默认本地存储但如果你把笔记目录同步到了云端网盘风险范围就扩大了权限控制要做得更严格。10. 总结与下一步Basic Memory 最值得试的点是它把 Agent 记忆从“黑盒向量数据库”变成了“你可以用 Obsidian 打开看的 Markdown 文件”。这对调试非常友好。Agent 到底记住了什么、遗忘什么打开文件一眼就能看到不需要查数据库、看 embedding。第一次部署建议按这个顺序验证先安装并初始化再写一条记忆并搜索然后配置 Obsidian 打开目录最后注册 MCP在 Claude Code 里做端到端测试。跑通这条链路后再考虑批量导入历史笔记和接入 n8n、Dify 等自动化平台。最容易踩的坑是 MCP 配置后没有确认工具列表就盲目使用以及 Obsidian 修改笔记后没有重建索引。把这两点检查好基本能覆盖 80% 的“记忆失效”问题。后续可以扩展的方向很多给记忆库加标签体系和自动归档规则用 Git 做多端同步在团队里共享一套记忆库或者把 Basic Memory 接入 n8n 工作流让 Agent 在处理完任务后自动把关键结论写入记忆。从“让 Agent 记住”到“让 Agent 记住得更好”还有不少可以打磨的空间。建议先跑通基础链路再逐步把知识管理流程吸收进来。