5分钟给AI编程Agent装上持久记忆memsearch零配置本地安装完整教程免API Key【免费下载链接】memsearchA persistent, unified memory layer for all your AI agents (e.g. Claude Code, Codex, DSH), backed by Markdown and Milvus.项目地址: https://gitcode.com/gh_mirrors/mem/memsearchmemsearch 是一个为 Claude Code、Codex、OpenCode 等 AI 编程 Agent 提供持久记忆层的开源项目它把每次对话自动沉淀为 Markdown 文件并通过本地向量索引实现跨会话的语义检索。整个过程零配置、免 API Key、数据完全落在你自己的电脑上。这篇完整教程将带你用 5 分钟完成 memsearch 本地安装给你的 Agent 装上过目不忘的记忆能力。一、为什么 AI 编程 Agent 需要持久记忆用过 Claude Code 或 Codex 的开发者都体会过这种尴尬明明上周刚修过一个 Redis 缓存的坑今天新开会话Agent 又从零开始问起。memsearch 的解决思路很克制也是它最大的亮点Markdown 是唯一事实来源记忆就是.md文件人能读、能改、能进 git不绑定任何私有格式️Milvus 只是影子索引向量库可随时从 Markdown 完整重建随时可迁移跨平台共享一份记忆Claude Code 里聊过的内容Codex 里也能搜到一套记忆全平台通用混合检索 渐进召回BM25 关键词检索 稠密向量检索 RRF 融合排序按搜索 → 展开 → 原始对话三层取用架构细节可以参考 docs/architecture.md 和设计理念文档 docs/design-philosophy.md。二、安装前准备只需 3 个前提前提条件要求说明Python3.10 及以上memsearch 的硬性要求包管理器uv推荐/ pipx / pip 三选一uv 速度最快磁盘空间约 600 MB用于 ONNX 嵌入模型不需要安装数据库服务器也不需要申请任何 API Key——这是本教程免 Key路线的关键。三、一条命令安装 memsearch免 API Key 路径执行下面任意一条命令安装带ONNX 嵌入的完整版本uv tool install memsearch[onnx] # 推荐 pipx install memsearch[onnx] # 或用 pipx pip install memsearch[onnx] # 或用原生 pip这里的[onnx]是重点它让 memsearch 默认使用bge-m3int8 量化嵌入模型纯 CPU 本地运行不消耗任何 token、不依赖任何云端接口。⏳ 首次启动时系统会自动从 HuggingFace 下载约 558 MB 的嵌入模型。如果你在国内网络环境下下载很慢可以先设置镜像再运行export HF_ENDPOINThttps://hf-mirror.com四、零配置快速上手索引并搜索你的第一条记忆memsearch 默认使用Milvus Lite作为向量后端——数据就是一个本地文件~/.memsearch/milvus.db无需安装、无需端口开箱即用。创建一个目录写两份简单的记忆文件然后索引、搜索mkdir -p my-agent/memory # 在 my-agent/MEMORY.md 中写长期事实在 my-agent/memory/ 下放每日记录 memsearch index . # 索引 Markdown 文件 memsearch search 缓存方案我们用的什么 # 语义搜索 memsearch stats # 查看已索引的块数如果看到带相似度分数的记忆片段返回说明本地记忆链路已经完全打通。更多命令细节见 docs/cli.md。五、给主流 AI 编程 Agent 装上记忆插件装好 CLI 后给各平台安装官方插件Agent 会自动在每轮对话后捕获并总结记忆全程无需你动手。1. Claude Code市场一键安装在 Claude Code 中执行/plugin marketplace add zilliztech/memsearch /plugin install memsearch然后重启 Claude Code 即可。插件源码与钩子逻辑位于 plugins/claude-code/官方说明见 docs/platforms/claude-code/。2. Codex克隆仓库执行安装脚本git clone https://gitcode.com/gh_mirrors/mem/memsearch bash memsearch/plugins/codex/scripts/install.sh脚本会自动完成三件事把 memory-recall 技能安装到~/.agents/skills/、写入~/.codex/hooks.json钩子、开启 Codex 的 hooks 开关。首次运行需要联网下载 ONNX 模型因此建议用全权限模式启动codex --dangerously-bypass-approvals-and-sandbox安装说明详见 docs/platforms/codex/。3. DSH / OpenClaw / OpenCode一条命令接入这三个平台同样提供官方插件分别安装后即可自动捕获对话并在需要时注入记忆。各平台的差异对比与安装细节可查阅官方平台对照文档 docs/platforms/。六、记忆如何工作写入、检索与质量memsearch 的记忆流分为写入和召回两条链路写入每轮对话结束后插件解析对话 → LLM 总结 → 追加到.memsearch/memory/YYYY-MM-DD.md→ 自动增量索引。SHA-256 内容哈希保证未变化的内容绝不重复嵌入召回先做混合检索拿排序结果需要上下文时用memsearch expand展开完整章节还要原始对话时再回溯到会话 transcript。三层按需取用token 花得刚刚好上图是官方评估数据在 2172 个中英文测试问题上启用 Jev 重排序后 Top-5 证据召回率从 0.747 提升到 0.794MRR10 从 0.637 提升到 0.688——而且重排序成本每千次查询不到 0.2 美元。重排序评估的完整数据见 evaluation/reranking-evaluation.md 与 evaluation/reranking-results.json。日常使用中你可以直接在 Agent 里输入/memory-recall 我们之前 Redis 的 TTL 定的是多少或者更自然地问一句之前讨论 Redis 缓存时 TTL 定的多少Agent 会自动调用召回技能。七、memsearch 常用命令速查表命令作用memsearch config init交互式配置向导Milvus、嵌入、分块参数一次配好memsearch index .索引当前目录的 Markdown 文件memsearch index . --force强制全量重新嵌入memsearch search 关键词混合检索--top-k可调数量memsearch expand chunk_id展开某个结果块的完整章节memsearch watch .文件监听改动自动增量索引memsearch stats查看已索引块数memsearch reset --yes丢弃向量索引保留 Markdown后重建完整参数说明见 docs/cli.md配置项全集见 docs/home/configuration.md。八、常见问题装好了但搜不到怎么办首次索引很慢之后却飞快这是设计使然。块 ID 基于内容寻址二次索引只嵌入新增或变更的内容冷索引新机器、换嵌入模型才会全量嵌入属于一次性成本。详见 docs/faq.md。换了嵌入模型后报错 dimension mismatch旧索引维度不匹配重建即可Markdown 原文毫发无损memsearch reset --yes memsearch index .Windows 上本地后端不稳定原生 Windows 的 Milvus Lite 目前是尽力支持建议走 WSL2或使用 Docker 自建 Milvus Server。排查步骤见 docs/troubleshooting.md。 学到这里你的 Agent 已经拥有了跨会话、跨平台的持久记忆。下一步建议阅读快速上手与后端选型docs/getting-started.mdPython API 自定义集成docs/python-api.md核心引擎源码src/memsearch/各平台插件目录plugins/【免费下载链接】memsearchA persistent, unified memory layer for all your AI agents (e.g. Claude Code, Codex, DSH), backed by Markdown and Milvus.项目地址: https://gitcode.com/gh_mirrors/mem/memsearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考