memsearch

跨平台语义记忆，专为AI编码代理设计。

为什么选择 memsearch？

• 🌐 全平台，一内存 — 记忆可在 Claude Code、OpenClaw、OpenCode 和 Codex CLI 之间无缝流转。在一个代理中的对话内容会成为其他所有代理中可搜索的上下文——无需额外配置。
• 👥 对于代理用户而言，只需安装插件即可获得持久化记忆，几乎零操作；对于代理开发者而言，可以使用完整的 CLI 和 Python API 来构建记忆系统，并将其集成到自己的代理中。
• 📄 Markdown 是唯一可信的数据源 — 受 OpenClaw 启发。你的记忆以 .md 文件形式存储，既人类可读、可编辑，又能进行版本控制。Milvus 则是一个“影子索引”：一个派生且可重建的缓存。
• 🔍 渐进式检索、混合搜索、智能去重、实时同步 — 三层召回机制（搜索 → 扩展 → 转录）；稠密向量 + BM25 稀疏向量 + RRF 重排序；通过 SHA-256 内容哈希跳过未更改的内容；文件监听器可实时自动索引。

🧑‍💻 对于代理用户

选择你的平台，安装相应的插件，一切就绪。每个插件都会自动捕获对话，并提供语义化的记忆检索功能，无需任何配置。

对于 Claude Code 用户

# 安装
/plugin marketplace add zilliztech/memsearch
/plugin install memsearch
# 重启 Claude Code 以激活插件

重启后，你只需像往常一样与 Claude Code 对话即可。插件会自动记录每一轮对话。

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

ls .memsearch/memory/          # 应该能看到每日生成的 .md 文件
cat .memsearch/memory/$(date +%Y-%m-%d).md

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

/memory-recall 我们之前讨论过 Redis 的哪些内容？

或者直接自然地提问——当 Claude 感知到问题需要历史背景时，会自动调用该技能：

我们之前讨论过 Redis 缓存，当时选择的 TTL 是多少？

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

对于 OpenClaw 用户

# 从 ClawHub 安装
openclaw plugins install clawhub:memsearch
openclaw gateway restart

安装完成后，你可以像往常一样在 TUI 中进行对话。插件会自动记录每一回合的交流。

验证是否正常工作 — 记忆文件会保存在你的代理工作目录中：

# 对主代理：
ls ~/.openclaw/workspace/.memsearch/memory/
# 对其他代理（如工作代理）：
ls ~/.openclaw/workspace-work/.memsearch/memory/

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

/memory-recall 我们设置的批量大小上限是多少？

或者直接自然地提问——当 LLM 感知到问题需要历史信息时，会自动调用记忆工具：

我们之前讨论过批量大小限制，最终决定的是什么？

📖 OpenClaw 插件文档

// 在 ~/.config/opencode/opencode.json 中添加
{ "plugin": ["@zilliz/memsearch-opencode"] }

ls .memsearch/memory/    # 经过几次对话后，会生成每日的 .md 文件

/memory-recall 我们之前讨论过身份验证的哪些内容？

我们之前讨论过身份验证流程，具体采用了哪种方式？

# 安装
bash memsearch/plugins/codex/scripts/install.sh
codex --yolo  # 用于 ONNX 模型网络访问

ls .memsearch/memory/

$memory-recall 我们之前讨论过部署的哪些内容？

⚙️ 配置（所有平台）

所有插件共享同一个 memsearch 后端。只需配置一次，即可在所有地方使用。

嵌入模型

默认为 ONNX bge-m3 — 在本地 CPU 上运行，无需 API 密钥，不产生费用。首次启动时，模型文件（约 558 MB）将从 HuggingFace Hub 下载。

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（默认）— 无需配置，单文件部署。非常适合快速上手：

# 开箱即用，无需任何设置
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"

memsearch config set milvus.uri http://localhost:19530

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

🛠️ 适用于智能体开发者

除了开箱即用的插件之外，memsearch 还提供了完整的 CLI 和 Python API，用于将记忆功能集成到您自己的智能体中。无论您是为自定义智能体添加持久化上下文、构建基于记忆增强的 RAG 流程，还是一些框架相关的工程工作，驱动插件的核心引擎都可以作为库直接使用。

🏗️ 架构概览

┌──────────────────────────────────────────────────────────────┐
│                  🧑‍💻 适用于智能体用户（插件）                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────┐ │
│  │ Claude   │ │ OpenClaw │ │ OpenCode │ │ Codex  │ │ Your │ │
│  │ Code     │ │ Plugin   │ │ Plugin   │ │ Plugin │ │ App  │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ └──┬───┘ │
│       └─────────────┴────────────┴───────────┴────────┘     │
├────────────────────────────┬─────────────────────────────────┤
│  🛠️ 适用于智能体开发者   │  使用 ↓ 自行构建                 │
│  ┌─────────────────────────┴──────────────────────────────┐  │
│  │           memsearch CLI / Python API                   │  │
│  │      index · search · expand · watch · compact         │  │
│  └─────────────────────────┬──────────────────────────────┘  │
│  ┌─────────────────────────┴──────────────────────────────┐  │
│  │           核心：分块器 → 嵌入模型 → Milvus            │  │
│  │        混合搜索（BM25 + 稠密向量 + RRF）              │  │
│  └────────────────────────────────────────────────────────┘  │
├──────────────────────────────────────────────────────────────┤
│  📄 Markdown 文件（事实来源）                         │
│  memory/2026-03-27.md · memory/2026-03-26.md · ...           │
└──────────────────────────────────────────────────────────────┘

插件位于 CLI/API 层之上。API 负责索引、搜索以及与 Milvus 的同步。Markdown 文件始终是事实来源——Milvus 是一个可重建的影子索引。插件层以下的部分，正是智能体开发者所使用的部分。

插件的工作原理（以 Claude Code 为例）

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

用户提问 → 智能体回复 → 停止钩子触发
                                          │
                     ┌────────────────────┘
                     ▼
              解析最后一轮对话
                     │
                     ▼
         大语言模型总结（俳句风格）
         "- 用户询问了 X。"
         "- Claude 回答了 Y。"
                     │
                     ▼
         追加到 memory/2026-03-27.md
         并附带 <!-- session:UUID --> 标记
                     │
                     ▼
         memsearch 索引 → Milvus

召回 — 三层渐进式搜索：

用户：“我们之前讨论过批处理大小吗？”
                     │
                     ▼
  L1  memsearch 搜索“批处理大小”    → 排序后的文本片段
                     │ （还需要更多吗？）
                     ▼
  L2  memsearch 展开 <chunk_hash>    → 整个 .md 片段
                     │ （需要原始内容吗？）
                     ▼
  L3  解析转录本 <session.jsonl> → 原始对话记录

📄 Markdown 作为事实来源

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

📦 安装

# 作为全局 CLI 工具安装 — 当您主要使用 `memsearch` 命令，或者使用任何智能体插件（Claude Code、Codex、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           # 安装到已激活的虚拟环境中

# 作为 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 — 为您的代理赋予记忆能力

from memsearch import MemSearch

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

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

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-4o-mini",
        messages=[
            {"role": "system", "content": f"你有以下记忆：\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("## 团队\n- Alice：前端负责人\n- Bob：后端负责人")
    save_memory("## 决策\n我们选择了 Redis 作为缓存方案，而非 Memcached。")
    await mem.index()  # 或者使用 mem.watch() 在后台自动索引

    # 代理现在可以回忆起这些记忆
    print(await agent_chat("我们的前端负责人是谁？"))
    print(await agent_chat("我们选择了哪种缓存方案？"))

asyncio.run(main())

pip install memsearch anthropic

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. 回忆
    memories = await mem.search(user_input, top_k=3)
    context = "\n".join(f"- {m['content'][:200]}" for m in memories)

    # 2. 思考——调用 Claude 并结合记忆上下文
    resp = llm.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=1024,
        system=f"你有以下记忆：\n{context}",
        messages=[{"role": "用户", "内容": user输入}],
    )
    answer = resp.content[0].text

    # 3. 记住
    save_memory(f"## {user输入}\n{答案}")
    await mem.index()
    return answer

async def main():
    save_memory("## 团队\n- Alice：前端负责人\n- Bob：后端负责人")
    await mem.index()
    print(await agent_chat("我们的前端负责人是谁？"))

asyncio.run(main())

pip install "memsearch[ollama]"
ollama pull nomic-embed-text          # 嵌入模型
ollama pull llama3.2                  # 对话模型

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. 回忆
    memories = await mem.search(user_input, top_k=3)
    context = "\n".join(f"- {m['content'][:200]}" for m in memories)

    # 2. 思考——在本地调用 Ollama
    resp = chat(
        model="llama3.2",
        messages=[
            {"role": "系统", "内容": f"你有以下记忆：\n{context}"},
            {"role": "用户", "内容": user输入},
        ],
    )
    answer = resp.message.content

    # 3. 记住
    save_memory(f"## {user输入}\n{答案}")
    await mem.index()
    return answer

async def main():
    save_memory("## 团队\n- Alice：前端负责人\n- Bob：后端负责人")
    await mem.index()
    print(await agent_chat("我们的前端负责人是谁？"))

asyncio.run(main())

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

⌨️ CLI 使用方法

设置：

memsearch config init                              # 交互式设置向导
memsearch config set embedding.provider onnx       # 切换嵌入提供商
memsearch config set milvus.uri http://localhost:19530  # 切换 Milvus 后端

索引与搜索：

memsearch index ./memory/                          # 索引 Markdown 文件
memsearch index ./memory/ ./notes/ --force         # 重新嵌入所有内容
memsearch search "Redis 缓存"                   # 混合搜索（BM25 + 向量）
memsearch search "认证流程" --top-k 10 --json-output  # 输出 JSON 格式以便脚本处理
memsearch expand <chunk_hash>                      # 显示某个分块周围的完整段落

实时同步与维护：

memsearch watch ./memory/                          # 实时文件监视器（文件更改时自动索引）
memsearch compact                                  # 基于 LLM 的分块摘要
memsearch stats                                    # 显示已索引的分块数量
memsearch reset --yes                              # 清除所有已索引的数据并重新构建

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

⚙️ 配置

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

设置优先级：内置默认值 → ~/.memsearch/config.toml → .memsearch.toml → CLI 标志。

📖 完整配置指南：配置

🔗 链接

• 📖 文档 — 完整指南、API 参考和架构细节
• 🔌 平台插件 — Claude Code、OpenClaw、OpenCode、Codex CLI
• 💡 设计哲学 — 为什么使用 Markdown、为什么选择 Milvus、竞争对手对比
• 🦞 OpenClaw — 激发 memsearch 灵感的内存架构
• 🗄️ Milvus | Zilliz Cloud — 为 memsearch 提供支持的向量数据库

🤝 贡献

欢迎提交 bug 报告、功能请求和拉取请求！请参阅 贡献指南，了解开发环境搭建、测试以及插件开发的相关说明。如有疑问或想参与讨论，请加入我们的 Discord 社区。

📄 许可证

MIT

memsearch 快速上手指南

memsearch 是一款跨平台的 AI 编程助手语义记忆工具。它能让 Claude Code、OpenClaw、OpenCode 和 Codex CLI 等不同代理共享同一份记忆上下文，无需额外配置即可实现对话内容的自动捕获与语义检索。

环境准备

• 操作系统：支持 Windows、macOS、Linux（跨平台）。
• Python 版本：>= 3.10。
• 前置依赖：
  • 已安装你常用的 AI 代理工具（如 Claude Code、OpenClaw 等）。
  • 网络连接：首次运行时会自动从 HuggingFace 下载嵌入模型（约 558 MB），或使用本地/云端向量数据库。

安装步骤

根据你的使用场景选择以下一种方式：

方案 A：作为插件安装（推荐普通用户）

直接在你使用的 AI 代理中安装插件，即可自动启用记忆功能。

1. Claude Code 用户

/plugin marketplace add zilliztech/memsearch
/plugin install memsearch
# 安装后请重启 Claude Code 以激活插件

2. OpenClaw 用户

openclaw plugins install clawhub:memsearch
openclaw gateway restart

3. OpenCode 用户 在 ~/.config/opencode/opencode.json 中添加：

{ "plugin": ["@zilliz/memsearch-opencode"] }

4. Codex CLI 用户

bash memsearch/plugins/codex/scripts/install.sh
codex --yolo  # 需要此参数以允许 ONNX 模型访问网络

方案 B：独立安装（推荐开发者）

如果你需要直接使用 CLI 或 Python API 构建自己的代理：

pip install memsearch

基本使用

安装完成后，memsearch 会自动在后台运行，无需复杂配置。

1. 验证运行状态

进行几次正常的对话后，检查是否生成了记忆文件（Markdown 格式）：

# 查看生成的每日记忆文件
ls .memsearch/memory/
cat .memsearch/memory/$(date +%Y-%m-%d).md

2. 触发记忆检索

你可以通过两种方式让 AI 回顾历史上下文：

• 显式命令：直接调用记忆技能。

  /memory-recall 我们之前讨论过 Redis 的什么内容？
  

• 自然提问：直接询问历史细节，AI 会自动感知并调用记忆工具。

  我们之前讨论过 Redis 缓存，当时设置的 TTL 是多少？
  

3. 核心配置（可选）

所有插件共享同一套后端配置，修改一次即可全局生效。

切换嵌入模型提供者 (Embedding Provider) 默认使用本地免费的 ONNX bge-m3 模型。如需切换：

# 使用 OpenAI (需设置 OPENAI_API_KEY)
memsearch config set embedding.provider openai

# 使用本地 Ollama
memsearch config set embedding.provider ollama

切换向量数据库后端 (Milvus Backend) 默认使用 Milvus Lite（单文件模式，零配置）。如需使用云端或自建服务：

• 使用 Zilliz Cloud (推荐，有免费额度)

  memsearch config set milvus.uri "https://in03-xxx.api.gcp-us-west1.zillizcloud.com"
  memsearch config set milvus.token "your-api-key"
  

• 使用自建 Milvus (Docker)

  memsearch config set milvus.uri http://localhost:19530
  

提示：记忆数据以 .md 文件为唯一真实源（Source of Truth），Milvus 仅作为可重建的索引缓存，支持人工编辑和版本控制。