用memsearch Python API打造带记忆的Agent：Recall-Think-Remember三步实战教程-平芜编程栈

用memsearch Python API打造带记忆的Agent：Recall-Think-Remember三步实战教程

【免费下载链接】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 Agent 总是"金鱼记忆"，聊过的决定换个会话就忘了？memsearch Python API正是解决这个痛点的捷径——memsearch 是一个面向所有 AI Agent（Claude Code、Codex、DSH 等）的持久统一记忆层，以人类可读的 Markdown 文件为记忆载体，用 Milvus 向量数据库做可重建的"影子索引"。本教程带你用三步Recall-Think-Remember模式，十几行代码就给你的 AI 加上持久记忆。

一、准备工作：30 秒完成 memsearch 安装配置

pip install memsearch

默认使用 OpenAI 作为嵌入（向量化）后端，需要OPENAI_API_KEY；想完全本地运行、零 API 费用的话，选 ONNX 或 local 提供方：

pip install "memsearch[onnx]" # 本地 CPU 推理，无需 API Key

开始之前记住两个设计要点：

📄Markdown 是唯一事实来源：记忆就是普通的.md文件，可读、可编辑、可用 git 管理；
🗄️Milvus 是可重建的影子索引：默认使用单文件 Milvus Lite 数据库（~/.memsearch/milvus.db），开箱即用，无需部署服务。

二、第一步 Recall：用语义搜索召回相关记忆

创建MemSearch实例后，一次search调用即可完成"回忆"：

from memsearch import MemSearch mem = MemSearch(paths=["./memory"]) await mem.index() # 增量索引目录下的 Markdown 文件 results = await mem.search("Redis 配置", top_k=3) print(results[0]["content"], results[0]["score"])

memsearch 在幕后执行混合搜索（稠密向量 + BM25 全文）并用 RRF 融合重排，比纯关键词匹配更懂语义。每条结果还带source（来源文件）、heading（所属章节标题）、score（相关度）等元数据，方便溯源。核心实现在 MemSearch 主类。

三、第二步 Think：把记忆作为上下文交给大模型

"Think" 的关键，是把召回的记忆注入 LLM 的系统提示词，让模型基于历史上下文作答：

memories = await mem.search(user_input, top_k=3) context = "\n".join(f"- {m['content'][:200]}" for m in memories) answer = llm.chat.completions.create( # llm 为你的任意 LLM 客户端 model="gpt-5-mini", messages=[ {"role": "system", "content": f"你有这些记忆：\n{context}"}, {"role": "user", "content": user_input}, ], ).choices[0].message.content

有了这一步，Agent 才能回答"前端负责人是谁？""我们上次给 Redis 设的 TTL 是多少？"这类依赖历史的问题。

四、第三步 Remember：把本次对话写回记忆库

memsearch 推荐"每日日志"风格：把新记忆追加到按日期命名的 Markdown（如memory/2026-02-12.md），然后重新索引：

from pathlib import Path from datetime import date def save_memory(content: str): p = Path("./memory") / f"{date.today()}.md" p.parent.mkdir(parents=True, exist_ok=True) with open(p, "a") as f: f.write(f"\n{content}\n") # 保存本轮问答并增量索引 save_memory(f"## {user_input}\n{answer}") await mem.index()

index()默认是增量的（源码）：内容通过 SHA-256 哈希去重，只有新增/变更的片段会重新向量化，成本极低；被删除的内容也会在下次索引时自动清理。

五、把三步串起来：一个完整的记忆循环

步骤	做什么	关键调用
🔍 Recall	语义搜索，召回最相关的历史记忆	`mem.search()`
🧠 Think	记忆注入系统提示词，LLM 生成回答	你的 LLM 客户端
📝 Remember	问答写入每日 Markdown 并增量索引	`save_memory()`+`mem.index()`

每聊一轮，Agent 的记忆就更丰富一分，跨会话也能追溯完整决策脉络。OpenAI / Claude / Ollama 本地版三种完整可运行示例，见官方 Python API 文档。

六、进阶技巧：让记忆系统自己"保鲜"

⏱️实时同步：mem.watch()启动后台文件监听，Markdown 一改就自动重新索引（默认 1.5 秒防抖），不用再手动调index()：
```
watcher = mem.watch(on_event=lambda t, s, p: print(f"[{t}] {s}"))
```
🗜️记忆压缩：mem.compact()用 LLM 把大量记忆片段压缩成摘要，并自动写回每日日志（源码），让记忆库保持精简而不失重点。
🎯可选重排序：设置reranker_model="jev:jev-latest"可对搜索候选做远程重排序，进一步提升头部命中率。下图是官方评估中 Jev 重排序 vs 原始排序 vs Voyage 的对比（Recall@5、MRR@10、NDCG@10 及每千次查询成本）：

七、小结与延伸阅读

用Recall-Think-Remember三步模式，你只需要index/search加一个简单的save_memory，就能让任意 Python Agent 拥有持久记忆——而且所有记忆数据都是 Markdown 文件，可读、可编辑、git 友好，向量索引随时可重建。

继续学习：

📖 Python API 完整参考：全部参数说明与三种 LLM 完整示例
🚀 快速上手指南：无 API Key 的本地最快配置
🏗️ 架构说明：搜索、索引、压缩的完整数据流
🛠️ 面向 Agent 开发者：CLI 与 Python API 双入口
📦 核心源码：MemSearch 主类 · 混合搜索 · 文件监听

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

用memsearch Python API打造带记忆的Agent：Recall-Think-Remember三步实战教程