跨代理记忆库zilliztech/memsearch

 
memsearch

面向 AI 编程代理的跨平台语义记忆。

📰 最新动态

- 支持 DeepSeek Harness — MemSearch 现为 DeepSeek Harness (DSH) 带来自动捕获、步骤前记忆注入、基于原生技能的召回、后台维护以及只读记忆浏览器。
- 来自记忆的技能 — MemSearch 现在会将你重复的工作流程提炼为可复用、可安装的智能体技能（第三层“程序性记忆”），并在后台保持其更新。参见 来自记忆的技能。
- 高级记忆维护 — 可选的后台任务可让持久的 PROJECT.md 和 USER.md 笔记跨会话保持最新。参见 高级记忆维护。

为什么选择 memsearch？

- 🌐 所有平台，一份记忆 — 记忆可在 Claude Code、Codex、DeepSeek Harness、OpenClaw 和 OpenCode 之间流转。在一个智能体中的对话会成为所有其他智能体中可搜索的上下文——无需额外设置
- 👥 面向智能体用户，安装插件即可零成本获得持久记忆；面向智能体开发者，可使用完整的 CLI 和 Python API，将记忆与 harness 工程构建到你自己的智能体中
- 📄 Markdown 是唯一事实来源 — 灵感来自 OpenClaw。你的记忆只是 .md 文件——人类可读、可编辑、可版本控制。Milvus 是一个“影子索引”：一个派生的、可重建的缓存
- 🔍 渐进式检索、混合搜索、智能去重、实时同步 — 三层召回（搜索 → 扩展 → 转录）；稠密向量 + BM25 稀疏 + RRF 重排序；SHA-256 内容哈希跳过未更改的内容；文件监听器实时自动索引

🧑‍💻 面向智能体用户

选择你的平台，安装插件，就完成了。每个插件都会自动捕获对话，并提供零配置的语义召回。

面向 Claude Code 用户

Install
/plugin marketplace add zilliztech/memsearch
/plugin install memsearch
Restart Claude Code to activate the plugin

重启后，像往常一样与 Claude Code 聊天即可。插件会自动捕获每一轮对话。

验证其是否正常工作 — 经过几次对话后，检查你的记忆文件：

ls .memsearch/memory/          # you should see daily .md files
cat .memsearch/memory/$(date +%Y-%m-%d).md

召回记忆 — 两种触发方式：

/memory-recall what did we discuss about Redis?
或者自然地提问——当 Claude 察觉到问题需要历史记录时，会自动调用该技能：
We discussed Redis caching before, what was the TTL we chose?

📖 Claude Code 插件文档 · 故障排除

面向 Codex 用户

Install
git clone --depth 1 https://github.com/zilliztech/memsearch.git
bash memsearch/plugins/codex/scripts/install.shbash
codex --yolo  # 访问 ONNX 模型网络所需

安装后，像往常一样聊天。钩子会捕获并总结每一轮对话。

验证是否正常工作：
bash
ls .memsearch/memory/

回忆记忆 —— 使用该技能：

$memory-recall 我们之前讨论过关于部署的什么内容？

📖 Codex 插件文档

适用于 DeepSeek Harness 用户
bash
将已发布的插件安装到你的 DSH 配置文件中
uv tool install "memsearch[onnx]"
dsh plugin --profile web add @zilliz/memsearch-dsh
重启该 DSH 配置文件，或启动一个新会话

安装后，正常使用 DSH。已完成的对话轮次会被自动捕获，相关记忆仅在有用时才会在第一个模型步骤之前注入。

验证是否正常工作：
bash
ls .memsearch/memory/

回忆记忆 —— 自然地提问，或告诉 DSH 使用已注册的 memory-recall 技能：

使用 memory-recall 找出我们关于部署架构所做的决定。

Web 配置文件还添加了一个紧凑的 MemSearch 停靠栏，你可以在其中查看技能候选项，并浏览 .memsearch/ 下受支持的文件，而无需编辑它们。

📖 DeepSeek Harness 插件文档

适用于 OpenClaw 用户
bash
从 ClawHub 安装
openclaw plugins install --force clawhub:memsearch
openclaw config set plugins.entries.memsearch.hooks.allowConversationAccess true
openclaw config set plugins.entries.memsearch.hooks.allowPromptInjection true
openclaw gateway restart

安装后，像往常一样在 TUI 中聊天。该插件会自动捕获每一轮对话。

验证是否正常工作 —— 记忆文件存储在智能体的工作区中：
bash
对于主智能体：
ls ~/.openclaw/workspace/.memsearch/memory/
对于其他智能体（例如 work）：
ls ~/.openclaw/workspace-work/.memsearch/memory/

回忆记忆 —— 两种触发方式：

/memory-recall 我们设置的批量大小限制是多少？
或者直接自然地提问 —— 当 LLM 察觉到问题需要历史记录时，会自动调用记忆工具：
我们之前讨论过批量大小限制，我们决定了什么？

📖 OpenClaw 插件文档 · 在 ClawHub 上浏览

适用于 OpenCode 用户
json
// 在 ~/.config/opencode/opencode.json 中
{ "plugin": ["@zilliz/memsearch-opencode"] }

安装后，像往常一样在 TUI 中聊天。后台守护进程会捕获对话。

验证是否正常工作：
bash
ls .memsearch/memory/    # 几次对话后会出现每日 .md 文件

回忆记忆 —— 两种触发方式：

/memory-recall 我们之前讨论过关于身份验证的什么内容？
或者直接自然地提问 —— 当 LLM 察觉到问题需要历史记录时，会自动调用记忆工具：
我们之前讨论过认证流程，当时的方法是什么？

📖 OpenCode 插件文档

⚙️ 配置（所有平台）

所有插件共享同一个 memsearch 后端。配置一次，处处可用。

嵌入

默认使用 ONNX bge-m3 —— 在 CPU 上本地运行，无需 API 密钥，零成本。首次启动时，模型（约 558 MB）会从 HuggingFace Hub 下载。
bash
memsearch config set embedding.provider onnx     # 默认 — 本地，免费
memsearch config set embedding.provider openai   # 需要 OPENAI_API_KEY
memsearch config set embedding.provider ollama   # 本地，任意模型

所有提供商和模型：配置 — 嵌入提供商

Milvus 后端

只需更改 milvus_uri（以及可选的 milvus_token）即可在部署模式之间切换：

Milvus Lite（默认）—— 零配置，单文件。非常适合入门：
bash
开箱即用，无需设置
memsearch config get milvus.uri   # → ~/.memsearch/milvus.db

⭐ Zilliz Cloud（推荐）—— 全托管，提供免费套餐 —— 注册 👇：
bash
memsearch config set milvus.uri "https://in03-xxx.api.gcp-us-west1.zillizcloud.com"
memsearch config set milvus.token "your-api-key"

⭐ 注册免费的 Zilliz Cloud 集群

你可以在 Zilliz Cloud 上注册以获得免费集群和 API 密钥。

注册并获取 API 密钥

自托管 Milvus 服务器（Docker）—— 面向高级用户

适用于拥有专用 Milvus 实例的多用户或团队环境。需要 Docker。请参阅官方安装指南。
bash
memsearch config set milvus.uri http://localhost:19530

📖 完整配置指南：配置 · 平台对比

捕获摘要路由

除非你显式覆盖，否则每个插件都会保留其原生捕获摘要器：
bash
memsearch config set plugins.codex.summarize.model gpt-5.1-codex-mini
memsearch config set plugins.opencode.summarize.model anthropic/claude-haiku

高级用户可以通过 memsearch 管理的 API 提供商来路由插件摘要：
bash
memsearch config set llm.providers.openai.type openai
memsearch config set llm.providers.openai.model gpt-5-mini
memsearch config set llm.providers.openai.api_key env:OPENAI_API_KEY
memsearch config set plugins.codex.summarize.provider openai

将 plugins..summarize.provider 留空可保留平台的默认行为。Claude Code、Codex、OpenClaw 和 OpenCode 也接受 native；当未设置 provider 时，DSH 会选择其无头代理后端。插件专属的 summarize 设置不会回退到 llm.model。

你也可以在保留插件安装的情况下，为某个平台全局禁用自动捕获：

memsearch config set plugins.codex.summarize.enabled false

高级记忆维护

你的代理可以在后台维护两份更高层级的笔记：PROJECT.md —— 持久的项目状态（活跃线程、决策、风险、后续步骤）—— 以及 USER.md —— 你可复用的偏好、工作风格和反复出现的目标。它们仅在日志发生变化且已过最小间隔时间后，于会话结束后刷新，并且默认关闭。

通过向你的代理提出请求来开启它们——“启用 MemSearch 的 PROJECT.md 和 USER.md 维护”——它会通过 memory-config 技能进行配置，该技能还可以选择模型/provider、间隔时间和自定义提示词，或诊断当前设置。更喜欢直接编辑文件？这些设置位于 MemSearch 配置中的 [plugins..project_review] 和 [plugins..user_profile] 下（两者默认读取 .memsearch/memory，并写入 .memsearch/PROJECT.md / .memsearch/USER.md）。

如果某个后台维护任务似乎悄无声息，请检查 .memsearch/.maintenance-state.json，或让 memory-config 技能检查它；失败的运行会记录 last_error，并在下一次到期运行时重试，因为失败的输入摘要不会被标记为成功。

来自记忆的技能

除了情景日志和语义化的 PROJECT.md / USER.md 笔记之外，MemSearch 还发展出第三层记忆——程序性记忆：你的代理会把你重复执行的工作流转化为可复用、可安装的技能。你完全通过代理以自然语言来驱动它——无需记忆任何内容：

- “把我们刚才做的事做成一个技能。” —— 代理会从本次会话中起草一个技能（读取原始记录，以确保步骤准确而非猜测），将其保存为候选，并提议安装它。
- “我有哪些技能候选？安装部署那个。” —— 代理会列出候选，并将你选中的那个安装到它自己的技能目录中，在那里它会成为一个真正的 / 命令。

在底层，候选技能存放在一个由 git 跟踪的 .memsearch/skill-candidates/ 存储中——可进行差异对比和回滚，并且在你安装之前处于惰性状态（这一步始终由你完成）。一个可选的后台流程还可以自行从你的历史记录中挖掘重复出现的工作流。提炼出的技能遵循 Agent Skills 开放标准，因此一次捕获即可在 Claude Code、Codex、DSH、OpenClaw、OpenCode 以及其他兼容的 agent 之间移植。

启用它也只需一句话： 让你的 agent “enable MemSearch skill distillation”（或 “make it more eager”），它就会通过 memory-config 技能进行配置——该功能默认关闭。更喜欢编辑文件？相同的设置位于你的 MemSearch 配置中的 [plugins..memory_to_skill] 下。完整指南：Skills from Memory。

你可以用它做什么？

- 恢复调试线程 —— 询问上次类似的 Redis、Docker、数据库或部署问题是如何修复的。
- 找回决策依据 —— 找出项目为何选择某个架构、库、迁移路径或 API 设计，而非另一个。
- 追溯功能历史 —— 了解某个功能如何跨会话演变，包括更改的文件和讨论过的权衡。
- 进行代码考古 —— 在再次改动某个模块、配置或工作流之前，询问它是何时以及为何被更改的。
- 找到要恢复的正确会话 —— 询问之前哪次对话涵盖了某个主题，恢复相关上下文，并从那里继续。
- 跨 agent 携带上下文 —— 让 Claude Code、Codex、DeepSeek Harness、OpenClaw 和 OpenCode 基于相同的项目记忆协同工作。

🛠️ 面向 Agent 开发者

除了开箱即用的插件之外，memsearch 还提供了一套完整的 CLI 和 Python API，用于将记忆构建到你自己的 agent 中。无论你是在为自定义 agent 添加持久化上下文、构建记忆增强的 RAG 流水线，还是进行 harness 工程——驱动这些插件的同一核心引擎都可以作为库使用。

🏗️ 架构概览

┌──────────────────────────────────────────────────────────────┐
│                  🧑‍💻 For Agent Users (Plugins)                │
│ Claude Code · Codex · DSH · OpenClaw · OpenCode · Your App   │
│                              │                               │
├────────────────────────────┬─────────────────────────────────┤
│  🛠️ For Agent Developers   │  Build your own with ↓          │
│  ┌─────────────────────────┴──────────────────────────────┐  │
│  │           memsearch CLI / Python API                   │  │
│  │      index · search · expand · watch · compact         │  │
│  └─────────────────────────┬──────────────────────────────┘  │
│  ┌─────────────────────────┴──────────────────────────────┐  │
│  │           Core: Chunker → Embedder → Milvus            │  │
│  │        Hybrid Search (BM25 + Dense + RRF)              │  │
│  └────────────────────────────────────────────────────────┘  │
├──────────────────────────────────────────────────────────────┤
│  📄 Markdown 文件（唯一事实来源）                              │
│  memory/2026-03-27.md · memory/2026-03-26.md · ...           │
└──────────────────────────────────────────────────────────────┘

插件位于 CLI/API 层之上。API 负责索引、搜索和 Milvus 同步。Markdown 文件始终是唯一事实来源——Milvus 是可重建的影子索引。插件层以下的所有内容都是你作为智能体开发者所使用的东西。

插件如何工作（以 Claude Code 为例）

捕获——在每一轮对话之后：

用户提问 → 智能体响应 → Stop 钩子触发
│
┌────────────────────┘
▼
解析最后一轮对话
│
▼
LLM 进行总结（haiku）
"- 用户询问了关于 X 的问题。"
"- Claude 做了 Y。"
│
▼
追加到 memory/2026-03-27.md
并带有  锚点
│
▼
memsearch index → Milvus

召回——3 层渐进式搜索：

用户："我们之前关于 batch size 讨论了什么？"
│
▼
L1  memsearch search "batch size"    → 排序后的分块
│ （需要更多？）
▼
L2  memsearch expand     → 完整的 .md 章节
│ （需要原始内容？）
▼
L3  parse-transcript  → 原始对话

📄 Markdown 作为唯一事实来源

插件追加 ──→  .md 文件  ←── 可人工编辑
│
▼
memsearch watch（实时监视器）
│
检测到文件变更
│
▼
对变更的 .md 重新分块
│
对每个分块进行哈希（SHA-256）
│
┌───────────┴───────────┐
▼                       ▼
哈希未变？              哈希是新的/已变更？
→ 跳过（无 API 调用）    → 嵌入 → 更新插入到 Milvus
│                       │
└───────────┬───────────┘
▼
┌──────────────────┐
│  Milvus（影子）   │
│  始终保持同步     │
│  可重建           │
└──────────────────┘

📦 安装

安装为全局 CLI 工具——当你主要使用
memsearch 命令或任何智能体插件（Claude Code、Codex、
DSH、OpenClaw、OpenCode）时推荐使用，它们都会调用 CLI。
uv tool install memsearch       # 通过 uv
pipx install memsearch          # 通过 pipx
pip install memsearch           # 直接使用 pip
作为项目依赖安装 — 如果你想从自己的 Python 代码中导入
memsearch（例如通过 MemSearch 类），请使用此方式。
uv add memsearch                # 通过 uv，添加到 pyproject.toml
pip install memsearch           # 安装到已激活的 venv 中

可选的嵌入提供程序
bash
作为 CLI 工具（推荐 — 本地 ONNX，无需 API 密钥）
uv tool install "memsearch[onnx]"
pipx install "memsearch[onnx]"
pip install "memsearch[onnx]"

作为项目依赖
uv add "memsearch[onnx]"

其他选项：[openai]、[google]、[voyage]、[jina]、[mistral]、[ollama]、[local]、[all]

🐍 Python API — 为你的 Agent 赋予记忆
python
from memsearch import MemSearch

mem = MemSearch(paths=["./memory"])

await mem.index()                                      # 索引 markdown 文件
results = await mem.search("Redis config", top_k=3)    # 语义搜索
scoped = await mem.search("pricing", top_k=3, source_prefix="./memory/product")
print(results[0]["content"], results[0]["score"])       # 内容 + 相似度

完整示例 — 带记忆的 Agent（OpenAI） — 点击展开
python
import asyncio
from datetime import date
from pathlib import Path
from openai import OpenAI
from memsearch import MemSearch

MEMORY_DIR = "./memory"
llm = OpenAI()                                        # 你的 LLM 客户端
mem = MemSearch(paths=[MEMORY_DIR])                    # memsearch 处理其余部分

def save_memory(content: str):
"""将一条笔记追加到今天的记忆日志中（OpenClaw 风格的每日 markdown）。"""
p = Path(MEMORY_DIR) / f"{date.today()}.md"
p.parent.mkdir(parents=True, exist_ok=True)
with open(p, "a") as f:
f.write(f"\n{content}\n")

async def agent_chat(user_input: str) -> str:
1. 回忆 — 搜索过去的记忆以获取相关上下文
memories = await mem.search(user_input, top_k=3)
context = "\n".join(f"- {m['content'][:200]}" for m in memories)

2. 思考 — 携带记忆上下文调用 LLM
resp = llm.chat.completions.create(
model="gpt-5-mini",
messages=[
{"role": "system", "content": f"You have these memories:\n{context}"},
{"role": "user", "content": user_input},
],
)
answer = resp.choices[0].message.content

3. 记住 — 保存这次交流并为其建立索引
save_memory(f"## {user_input}\n{answer}")
await mem.index()

return answer

async def main():
预置一些知识
save_memory("## Team\n- Alice: frontend lead\n- Bob: backend lead")
save_memory("## Decision\nWe chose Redis for caching over Memcached.")
await mem.index()  # 或者用 mem.watch() 在后台自动建立索引

Agent 现在可以回忆起这些记忆
print(await agent_chat("Who is our frontend lead?"))
print(await agent_chat("What caching solution did we pick?"))

asyncio.run(main())

Anthropic Claude 示例 — 点击展开
bash
pip install memsearch anthropic
python
import asyncio
from datetime import date
from pathlib import Path
from anthropic import Anthropic
from memsearch import MemSearch

MEMORY_DIR = "./memory"
llm = Anthropic()
mem = MemSearch(paths=[MEMORY_DIR])

def save_memory(content: str):
p = Path(MEMORY_DIR) / f"{date.today()}.md"
p.parent.mkdir(parents=True, exist_ok=True)
with open(p, "a") as f:
f.write(f"\n{content}\n")

async def agent_chat(user_input: str) -> str:
1. Recall
memories = await mem.search(user_input, top_k=3)
context = "\n".join(f"- {m['content'][:200]}" for m in memories)

2. Think — call Claude with memory context
resp = llm.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=f"You have these memories:\n{context}",
messages=[{"role": "user", "content": user_input}],
)
answer = resp.content[0].text

3. Remember
save_memory(f"## {user_input}\n{answer}")
await mem.index()
return answer

async def main():
save_memory("## Team\n- Alice: frontend lead\n- Bob: backend lead")
await mem.index()
print(await agent_chat("Who is our frontend lead?"))

asyncio.run(main())

Ollama（完全本地，无需 API 密钥） — 点击展开
bash
pip install "memsearch[ollama]"
ollama pull nomic-embed-text          # embedding model
ollama pull llama3.2                  # chat model
python
import asyncio
from datetime import date
from pathlib import Path
from ollama import chat
from memsearch import MemSearch

MEMORY_DIR = "./memory"
mem = MemSearch(paths=[MEMORY_DIR], embedding_provider="ollama")

def save_memory(content: str):
p = Path(MEMORY_DIR) / f"{date.today()}.md"
p.parent.mkdir(parents=True, exist_ok=True)
with open(p, "a") as f:
f.write(f"\n{content}\n")

async def agent_chat(user_input: str) -> str:
1. Recall
memories = await mem.search(user_input, top_k=3)
context = "\n".join(f"- {m['content'][:200]}" for m in memories)

2. Think — call Ollama locally
resp = chat(
model="llama3.2",
messages=[
{"role": "system", "content": f"You have these memories:\n{context}"},
{"role": "user", "content": user_input},
],
)
answer = resp.message.content

3. Remember
save_memory(f"## {user_input}\n{answer}")
await mem.index()
return answer

async def main():
save_memory("## Team\n- Alice: frontend lead\n- Bob: backend lead")
await mem.index()
print(await agent_chat("Who is our frontend lead?"))

asyncio.run(main())

📖 完整的 Python API 参考：Python API 文档

⌨️ CLI 用法

设置：
bash
memsearch config init                              # interactive setup wizard
memsearch config set embedding.provider onnx       # 切换嵌入提供程序
memsearch config set milvus.uri http://localhost:19530  # 切换 Milvus 后端

索引与搜索：
bash
memsearch index ./memory/                          # 索引 markdown 文件
memsearch index ./memory/ ./notes/ --force         # 重新嵌入所有内容
memsearch index . --ignore-file .gitignore         # 选择启用仓库忽略规则
memsearch search "Redis caching"                   # 混合搜索（BM25 + 向量）
memsearch search "auth flow" --top-k 10 --json-output  # 用于脚本编写的 JSON 输出
memsearch expand                       # 显示某个分块周围的完整章节

实时同步与维护：
bash
memsearch watch ./memory/                          # 实时文件监视器（变更时自动索引）
memsearch compact                                  # LLM 驱动的分块摘要
memsearch stats                                    # 显示已索引的分块数量
memsearch reset --yes                              # 删除所有已索引数据并重建

📖 包含所有标志的完整 CLI 参考：CLI 文档

⚙️ 配置

嵌入和 Milvus 后端设置 → 配置（所有平台）

集合优先级：集成派生的默认值 → ~/.memsearch/config.toml → .memsearch.toml → 显式的 --collection 或 Python 参数。如果没有集成派生的默认值，则使用内置集合。

📖 完整配置指南：配置

🔗 链接

- 📖 文档 — 完整指南、API 参考和架构细节
- 🔌 平台插件 — Claude Code、Codex、DeepSeek Harness、OpenClaw、OpenCode
- 💡 设计理念 — 为什么选择 markdown、为什么选择 Milvus、竞品对比
- 🦞 OpenClaw — 启发了 memsearch 的记忆架构
- 🗄️ Milvus | Zilliz Cloud — 为 memsearch 提供支持的向量数据库

🤝 贡献

欢迎提交错误报告、功能请求和拉取请求！有关开发环境搭建、测试和插件开发说明，请参阅贡献指南。如有问题和讨论，请加入我们的 Discord。

📄 许可证

MIT