跨代理记忆库 zilliztech/memsearch

memsearch

跨平台语义记忆，专为 AI 编程智能体打造。

📰 最新动态

- 可选的 Jev 重排序 —— 通过 TypeSafe API 用 Jev 对记忆搜索结果重排序，无需下载本地模型。详见配置与中英文评测。
- 支持 DeepSeek Harness — MemSearch 现在为 DeepSeek Harness（DSH） 带来自动捕获、回忆提示、原生技能回忆、后台维护和只读记忆浏览器。
- 从记忆中提炼技能 — MemSearch 现在把你重复的工作流提炼成可复用、可安装的智能体技能（第三层「程序性记忆」），并在后台保持更新。见 从记忆中提炼技能。
- 高级记忆维护 — 可选的后台任务让持久的 PROJECT.md 和 USER.md 笔记跨会话保持最新。见 高级记忆维护。

为什么选 memsearch？

- 🌐 全平台，一份记忆 — 记忆在 Claude Code、Codex、DeepSeek Harness、OpenClaw 和 OpenCode 之间流动。在一个智能体里的对话，会成为所有其他智能体里可搜索的上下文——无需额外配置
- 👥 智能体用户，装个插件就能零成本获得持久记忆；智能体开发者，用完整的 命令行 和 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.sh
codex --yolo # needed for ONNX model network access

安装完成后，照常聊天即可。钩子会捕获每一轮对话并做摘要。

验证是否生效：

ls .memsearch/memory/

召回记忆 —— 使用技能：

$memory-recall what did we discuss about deployment?

📖 Codex 插件文档

DeepSeek Harness 用户

Install the published plugin into your DSH profile
uv tool install "memsearch[onnx]"
dsh plugin --profile web add @zilliz/memsearch-dsh
Restart that DSH profile, or start a new session

安装完成后，照常使用 DSH。已完成的对话轮次会自动捕获；只有在确实有用时，相关记忆才会在模型第一步之前注入。

验证是否生效：

ls .memsearch/memory/

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

Use memory-recall to find what we decided about the deployment architecture.

web 配置档还会加一个紧凑的 MemSearch 停靠面板，你可以在里面查看技能候选、浏览 .memsearch/ 下支持的文件，但不能编辑它们。

📖 DeepSeek Harness 插件文档

OpenClaw 用户

Install from 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 里照常聊天。插件会自动捕获每一轮对话。

验证是否生效 —— 记忆文件存放在智能体的工作区里：

For the main agent:
ls ~/.openclaw/workspace/.memsearch/memory/
For other agents (e.g. work):
ls ~/.openclaw/workspace-work/.memsearch/memory/

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

/memory-recall what was the batch size limit we set?
或者直接自然提问 —— 当 LLM 察觉问题需要历史信息时，会自动调用记忆工具： We discussed batch size limits before, what did we decide?

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

OpenCode 用户

MemSearch 让 OpenCode 拥有跨会话的持久记忆。安装插件：

opencode plugin add @zilliz/memsearch-opencode

已完成的回合会汇总到 .memsearch/memory/，并建立索引供后续召回。中断后，未完成的工作会继续。

问起之前的决策或调试会话，OpenCode 能搜索记忆、展开相关笔记，并查回原始对话。内置 memory-recall、memory-config、memory-to-skill 技能。

📖 OpenCode 插件文档

⚙️ 配置（所有平台）

所有插件共用同一套 memsearch 后端。配置一次，处处生效。

嵌入

用 ONNX bge-m3 做本地 CPU 嵌入，无需 API key。首次启动会从 HuggingFace Hub 下载模型（约 558 MB）。

memsearch config set embedding.provider onnx # local, free
memsearch config set embedding.provider openai # needs OPENAI_API_KEY
memsearch config set embedding.provider ollama # local, any model

全部服务商与模型：配置 — 嵌入服务商

Milvus 后端

只需改 milvus_uri（可选改 milvus_token），就能在部署模式之间切换：

Milvus Lite（默认）— 零配置，单文件。适合上手：

Works out of the box, no setup needed
memsearch config get milvus.uri # → ~/.memsearch/milvus.db

⭐ Zilliz Cloud（推荐）— 全托管，有免费套餐 — 注册 👇：

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 key。

Sign up and get API key

自托管 Milvus Server（Docker）— 面向进阶用户

适合多用户或团队环境，使用独立 Milvus 实例。需要 Docker。见官方安装指南。

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.<platform>.summarize.provider 留空，就保留平台默认行为。Claude Code、Codex、OpenClaw、OpenCode 也接受 native；DSH 在服务商未设置时选用自己的 headless-agent 后端。插件专属的 summarize 设置不会回退到 llm.model。

你也可以在保留插件安装的前提下，全局关闭某个平台的自动捕获： bash memsearch config set plugins.codex.summarize.enabled false

进阶记忆维护

你的智能体可以在后台维护两份更高层的笔记：PROJECT.md —— 项目长期状态（进行中的事项、决策、风险、下一步）；USER.md —— 你可复用的偏好、工作风格和反复出现的目标。只有日志发生变化、且已过最小间隔时，它们才会在会话结束后刷新，并且默认关闭。

想开启，直接对智能体说 —— “enable MemSearch's PROJECT.md and USER.md maintenance” —— 它会通过 memory-config 技能完成配置。这个技能还能选择模型/服务商、间隔和自定义提示词，或诊断当前设置。更想直接改文件？相关设置位于 MemSearch 配置的 [plugins.<agent>.project_review] 和 [plugins.<agent>.user_profile] 下（两者默认读取 .memsearch/memory，写入 .memsearch/PROJECT.md / .memsearch/USER.md）。

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

从记忆中生成技能

除了情景日志和语义笔记 PROJECT.md / USER.md，MemSearch 还生长出第三层记忆 —— 程序性记忆：智能体把你重复的工作流变成可复用、可安装的技能。你完全通过智能体、用自然语言驱动，不需要记任何东西：

- “Make a skill out of what we just did.” —— 智能体根据本次会话起草技能（读取原始记录，确保步骤准确而非猜测），存为候选，并询问是否安装。
- “What skill candidates do I have? Install the deploy one.” —— 智能体列出候选，把你选中的那个安装到自己的技能目录，它随即成为真正的 / 命令。

底层实现上，候选技能存放在 git 跟踪的 .memsearch/skill-candidates/ 存储里——可 diff、可回滚，并且在你安装之前始终处于惰性状态（安装这一步永远由你来做）。可选的背景任务还能自行从你的历史记录里挖掘反复出现的工作流。蒸馏出的技能遵循 Agent Skills 开放标准，因此一次捕获就能在 Claude Code、Codex、DSH、OpenClaw、OpenCode 以及其他兼容智能体之间通用。

开启它同样只需一句话： 对你的智能体说 “enable MemSearch skill distillation”（或 “make it more eager”），它就会通过 memory-config 技能完成配置——该功能默认关闭。更想直接改文件？同样的设置位于 MemSearch 配置里的 [plugins.<agent>.memory_to_skill] 下。完整指南：Skills from Memory。

你能用它做什么？

- 续接调试线索 —— 问上次类似的 Redis、Docker、数据库或部署问题是怎么修好的。
- 还原决策依据 —— 找出项目当初为什么选某个架构、库、迁移路径或 API 设计，而不是另一个。
- 追溯功能历史 —— 了解某个功能跨会话如何演进，包括改动了哪些文件、讨论过哪些取舍。
- 做代码考古 —— 再次改动某个模块、配置或工作流之前，先问清它何时被改、为什么被改。
- 找到该续接的会话 —— 问哪个之前的对话聊过某个话题，找回相关上下文，然后接着往下做。
- 跨智能体传递上下文 —— 让 Claude Code、Codex、DeepSeek Harness、OpenClaw 和 OpenCode 共用同一份项目记忆。

🛠️ 面向智能体开发者

除了开箱即用的插件，memsearch 还提供完整的 命令行和 Python API，用来把记忆能力构建进你自己的智能体。无论你是给自定义智能体加上持久上下文、搭建带记忆增强的 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 Files (Source of Truth) │ │ memory/2026-03-27.md · memory/2026-03-26.md · ... │ └──────────────────────────────────────────────────────────────┘

插件位于 CLI/API 层之上。API 负责索引、搜索和 Milvus 同步。Markdown 文件始终是唯一事实来源，Milvus 只是可重建的影子索引。插件层以下的部分，就是智能体开发者会用到的内容。

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

捕获 —— 每轮对话结束后：

User asks question → Agent responds → Stop hook fires
│
┌────────────────────┘
▼
Parse last turn
│
▼
LLM summarizes (haiku)
"- User asked about X."
"- Claude did Y."
│
▼
Append to memory/2026-03-27.md
with anchor
│
▼
memsearch index → Milvus

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

User: "What did we discuss about batch size?"
│
▼
L1 memsearch search "batch size" → ranked chunks
│ (need more?)
▼
L2 memsearch expand <chunk_hash> → full .md section
│ (need original?)
▼
L3 parse-transcript <session.jsonl> → raw dialogue

📄 Markdown 作为唯一事实来源

Plugins append ──→ .md files ←── human editable
│
▼
memsearch watch (live watcher)
│
detects file change
│
▼
re-chunk changed .md
│
hash each chunk (SHA-256)
│
┌───────────┴───────────┐
▼ ▼
hash unchanged? hash is new/changed?
→ skip (no API call) → embed → upsert to Milvus
│ │
└───────────┬───────────┘
▼
┌──────────────────┐
│ Milvus (shadow) │
│ always in sync │
│ rebuildable │
└──────────────────┘

📦 安装 bash

Install as a global CLI tool — recommended when you mainly use the

memsearch command or any of the agent plugins (Claude Code, Codex,

DSH, OpenClaw, OpenCode), which all shell out to the CLI.

uv tool install memsearch # via uv
pipx install memsearch # via pipx
pip install memsearch # plain pip

Install as a project dependency — use this if you want to import memsearch from your own Python code (e.g. via the MemSearch class).
uv add memsearch # via uv, adds to pyproject.toml
pip install memsearch # into an activated venv

可选嵌入服务商

Install local ONNX support for the CLI
uv tool install "memsearch[onnx]"
pipx install "memsearch[onnx]"
pip install "memsearch[onnx]"

As a project dependency
uv add "memsearch[onnx]"

Other options: [openai], [google], [voyage], [jina], [mistral], [ollama], [local], [all]

🐍 Python API — 给你的智能体加上记忆

Python API 默认使用 OpenAI（OPENAI_API_KEY）。要用本地嵌入，传 embedding_provider="onnx"。

from memsearch import MemSearch

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

await mem.index() # index markdown files
results = await mem.search("Redis config", top_k=3) # semantic search
scoped = await mem.search("pricing", top_k=3, source_prefix="./memory/product")
print(results[0]["content"], results[0]["score"]) # content + similarity

完整示例 — 带记忆的智能体（OpenAI） — 点击展开

import asyncio
from datetime import date
from pathlib import Path
from openai import OpenAI
from memsearch import MemSearch

MEMORY_DIR = "./memory"
llm = OpenAI() # your LLM client
mem = MemSearch(paths=[MEMORY_DIR]) # memsearch handles the rest

def save_memory(content: str):
"""Append a note to today's memory log (OpenClaw-style daily 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. Recall — search past memories for relevant context
memories = await mem.search(user_input, top_k=3)
context = "\n".join(f"- {m['content'][:200]}" for m in memories)

2. Think — call LLM with memory context
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. Remember — save this exchange and index it
save_memory(f"## {user_input}\n{answer}")
await mem.index()

return answer

async def main():
Seed some knowledge
save_memory("## Team\n- Alice: frontend lead\n- Bob: backend lead")
save_memory("## Decision\nWe chose Redis for caching over Memcached.")
await mem.index() # or mem.watch() to auto-index in the background

智能体现在能回忆起那些记忆了

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 key） — 点击展开 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 文档

⌨️ 命令行用法

初始化： bash memsearch config init # interactive setup wizard memsearch config set embedding.provider onnx # switch embedding provider memsearch config set milvus.uri http://localhost:19530 # switch Milvus backend

索引与搜索： bash memsearch index ./memory/ # index markdown files memsearch index ./memory/ ./notes/ --force # re-embed everything memsearch index . --ignore-file .gitignore # opt in to repository ignore rules memsearch search "Redis caching" # hybrid search (BM25 + vector) memsearch search "auth flow" --top-k 10 --json-output # JSON for scripting memsearch expand <chunk_hash> # show full section around a chunk

实时同步与维护： bash memsearch watch ./memory/ # live file watcher (auto-index on change) memsearch compact # LLM-powered chunk summarization memsearch stats # show indexed chunk count memsearch reset --yes # drop all indexed data and rebuild

📖 完整命令行参考（含全部参数）：命令行文档

⚙️ 配置

嵌入与 Milvus 后端设置 → 配置（全平台）

集合优先级：集成默认值 → ~/.memsearch/config.toml → .memsearch.toml → 显式指定 --collection 或 Python 参数。没有集成默认值时，使用内置集合。

📖 完整配置指南：配置

🔗 链接

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

🤝 参与贡献

欢迎提交 Bug 报告、功能请求和 pull request！开发环境搭建、测试与插件开发说明见贡献指南。有问题或想讨论，来 Discord 找我们。

📄 许可证

MIT