Basic Memory MCP 安装与配置指南

为 Claude Code 添加长期记忆与知识库语义检索能力安装版本：0.20.3 | 日期：2026-04-02

一、是什么

Basic Memory 是一个基于 MCP（Model Context Protocol）的本地知识库工具。

核心能力：

语义检索：用"意思"找内容，不需要精确关键词
混合检索：向量相似度 + 关键词全文，双重融合排序
本地优先：所有数据留在本地，Embedding 本地计算，不上云
实时同步：监听文件变更，索引自动更新

与 CLAUDE.md 的分工：CLAUDE.md 管"如何工作"，Basic Memory 管"知道什么"。

二、架构说明

你的 Markdown 文件（原地不动）
          ↓
   basic-memory sync
          ↓
  ~/.basic-memory/（SQLite + 向量索引）
          ↓
   Claude Code 通过 MCP 调用
          ↓
   语义检索 → 返回原文片段 + 来源路径

原始文件：原地不动，Basic Memory 不移动、不复制
索引库：存在 ~/.basic-memory/，只存向量和元数据
Embedding 模型：本地运行 FastEmbed，不需要 OpenAI API Key

三、安装步骤

1. 安装 uv（如未安装）

brew install uv

2. 安装 Basic Memory

uv tool install basic-memory

3. 接入 Claude Code MCP

claude mcp add basic-memory basic-memory mcp

配置写入 ~/.claude.json，路径：projects["/Users/robbin"].mcpServers.basic-memory。

4. 添加知识库目录

basic-memory project add workspace /Users/robbin/Workspace

5. 首次全量同步

basic-memory sync --project workspace

6. 验证安装

在 Claude Code 中输入 /mcp，看到 basic-memory 工具列表出现即成功。

四、配置 HuggingFace 国内镜像

问题

FastEmbed 的中文/多语言模型均需从 huggingface.co 下载 ONNX 文件，该域名在国内被墙，直连报错：

[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol

解决方案

Step 1 — 写入 .zshrc（终端永久生效）：

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.zshrc

Step 2 — 在 MCP 配置里也加上（关键！）。

Claude Code 启动的 MCP 子进程不继承 shell 环境变量，必须单独配置。手动编辑 ~/.claude.json，找到 basic-memory 的 MCP 配置：

"basic-memory": {
  "type": "stdio",
  "command": "basic-memory",
  "args": ["mcp"],
  "env": {
    "HF_ENDPOINT": "https://hf-mirror.com"
  }
}

五、Embedding 模型选择

默认模型 bge-small-en-v1.5 是英文模型，中文内容效果差，需替换。

FastEmbed 支持的中文/多语言模型

模型	维度	说明
`BAAI/bge-small-en-v1.5`	384	默认，英文，不适合中文
`BAAI/bge-small-zh-v1.5`	512	纯中文，轻量，推荐
`jinaai/jina-embeddings-v2-base-zh`	768	中文质量更好，但计算量大
`intfloat/multilingual-e5-large`	1024	中英混合最佳，体积最大

BGE-M3 不在 FastEmbed 支持列表中，无法直接使用。 Jina 768维在低性能机器上重建索引耗时极长（CPU 满载），不推荐笔记本使用。

修改配置

编辑 ~/.basic-memory/config.json：

"semantic_embedding_model": "BAAI/bge-small-zh-v1.5",
"semantic_embedding_dimensions": 512,
"semantic_embedding_cache_dir": "/Users/robbin/.basic-memory/models",

固定模型缓存路径

FastEmbed 默认把模型下载到 macOS 临时目录（/var/folders/.../T/fastembed_cache），系统重启后会被清空，需要重新下载。

建议设置固定路径，避免反复下载：

mkdir -p ~/.basic-memory/models

然后在 config.json 里设置 semantic_embedding_cache_dir（见上方配置）。

重建索引

换模型后必须重建向量索引：

export HF_ENDPOINT=https://hf-mirror.com && nohup basic-memory reindex --project workspace > /tmp/basic-memory-reindex.log 2>&1 &

查看进度：

tail -f /tmp/basic-memory-reindex.log

完成后重启 Claude Code 生效。

中断重建：

pkill -f "basic-memory reindex"

六、检索模式

search_notes 工具支持三种模式，可在对话中直接指定：

模式	说明	适合场景
`hybrid`（默认）	向量 + 关键词融合	大多数查询
`vector`	纯语义搜索	问法和写法完全不同时
`text`	纯关键词，支持 AND/OR	知道精确词语时

使用示例（在 Claude Code 对话中）：

搜索我的笔记里关于 AI 转型的内容
用纯向量搜索，找关于个人 IP 的笔记
用关键词精确匹配，找 JWT 相关记录
我上周关于内容策略做了什么决定？

七、关键文件路径速查

文件	说明
`~/.basic-memory/config.json`	主配置文件（模型、项目等）
`~/.basic-memory/memory.db`	SQLite 数据库（索引存储）
`~/.basic-memory/basic-memory.log`	运行日志
`~/.claude.json`	Claude Code 配置（含 MCP env）

八、多 Session 内存注意事项

每个 Claude Code session 会独立启动一个 basic-memory mcp 进程，每个进程都会把 Embedding Model 加载进内存——因为查询语句本身也需要做 Embedding，模型必须常驻。

模型	单进程内存占用	3 个 session
`bge-small-zh-v1.5`	~200-300MB	~600-900MB
`jina-embeddings-v2-base-zh`	~1.2GB	~3.6GB

结论： 习惯同时开多个 session 的用户，强烈建议用 bge-small-zh-v1.5，不要用 Jina。

九、注意事项

权重比例不可自定义调整（固定内部融合算法）
知识库规模较大时，首次 sync 耗时较长，属正常现象
import claude-json 命令在 0.20.3 已移除，Claude Code 本地 .jsonl 历史无法直接导入

十、常见问题

Q：搜索报 SSL 错误 A：检查 MCP 配置 ~/.claude.json 里 basic-memory.env.HF_ENDPOINT 是否已设置。

Q：换模型后搜索结果异常 A：执行 reindex 重建索引，新旧维度不匹配会导致结果错乱。

Q：重建索引 CPU 满载、风扇狂转 A：正常现象，Embedding 计算是 CPU 密集任务。低性能机器建议用 bge-small-zh-v1.5 而非 Jina。

十一、参考链接

官方文档：https://docs.basicmemory.com
GitHub：https://github.com/basicmachines-co/basic-memory
Claude Code 集成：https://docs.basicmemory.com/integrations/claude-code

robbin/basic_memory_mcp_install.md

Select an option

No results found