Memory Vault

Memory Vault

AI 应用的记忆数据库。 可自托管的 Postgres + pgvector，支持混合搜索、原生支持 MCP，并内置知识图谱。

你与 Claude 或 ChatGPT 的每次对话都从零开始。它们不记得你上周构建了什么、上个月做了哪些决定，也不记得你已经解决过哪些问题。你要么从头重新解释一切，要么粘贴一大段上下文，并希望它能放进窗口。

Memory Vault 是底层的持久化层。它会将你希望 AI 记住的内容——决策、对话、笔记、项目上下文——存储在一个支持语义 + 关键词混合搜索的 Postgres 数据库中。Claude 可在任何会话中通过 MCP 回忆和存储记忆；你可以通过本地 LLM 与自己的记忆聊天，也可以基于 REST API 构建自己的 AI 工具。

---

使用本地 LLM 与你的知识库对话。每个回答都会显示其依据的具体记忆——点击任意来源即可验证。

---

状态

v1.0 — 于 2026-05-07 发布。 Memory Vault 的首个稳定版本。M1-M7（混合搜索、Docker、MCP、REST API、仪表板、知识图谱、本地 LLM 聊天）均已发布并稳定。

完整的各版本更新记录请参阅 CHANGELOG.md，或在 GitHub Releases 查看平台原生页面。

从此版本起遵循 Semver——公共接口（REST API 端点、MCP 工具签名、DB 架构）保持稳定。只有在主版本号升级时才会进行破坏性更改。

---

快速开始（Docker）

git clone https://github.com/MihaiBuilds/memory-vault.git
cd memory-vault
docker compose up -d

就这么简单。PostgreSQL + pgvector + Memory Vault 已启动并就绪。首次启动时会自动运行迁移。

# Check it's working
docker compose exec app memory-vault status

# Ingest a file
docker compose exec app memory-vault ingest /path/to/file.md --space default

# Search
docker compose exec app memory-vault search "your query here"

数据会保存在 Docker 卷中——执行 docker compose down，再重新执行 up，你的记忆仍会保留。

在浏览器中打开 http://localhost:8000 使用仪表板（聊天、搜索、浏览、图谱、导入、统计）。

**Windows 用户：**请克隆到 WSL2 中，而不是 Windows 路径下；如果遇到行尾错误，请阅读 docs/windows.md。

---

不使用 Docker 快速开始

如果你更愿意在不使用 Docker 的情况下运行：

前置条件

• Python 3.11+
• PostgreSQL 16 和 pgvector 扩展
• uv（推荐）或 pip + venv

使用 uv 设置（推荐）

# Clone
git clone https://github.com/MihaiBuilds/memory-vault.git
cd memory-vault

# Create virtual environment and install dependencies
uv sync

# Install the spaCy language model
uv run python -m spacy download en_core_web_sm

# Configure
cp .env.example .env
# Edit .env with your PostgreSQL credentials

# Run migrations
uv run memory-vault migrate

# Verify
uv run memory-vault status

使用 pip + venv 设置（备用方案）

如果你不想安装 uv，也可以直接使用 pip + venv：

# Clone
git clone https://github.com/MihaiBuilds/memory-vault.git
cd memory-vault

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Install the spaCy language model
python -m spacy download en_core_web_sm

# Configure
cp .env.example .env
# Edit .env with your PostgreSQL credentials

# Run migrations
memory-vault migrate

# Verify
memory-vault status

使用方法

如果你使用 uv 设置，请在命令前加上 uv run（例如 uv run memory-vault search ...）。如果你使用 pip + venv，请先激活 venv（source .venv/bin/activate），然后直接运行命令：

# Ingest a file
memory-vault ingest notes.md --space default

# Search memories
memory-vault search "hybrid search architecture" --limit 5

# Check status
memory-vault status

---

功能

• 混合搜索 — 结合语义相似度和关键词匹配，即使不记得确切措辞，也能找到正确的记忆
• MCP 集成 — 提供四个工具（recall、remember、forget、memory_status），Claude 可在任何会话中原生使用
• 本地 LLM 聊天 — 通过 LM Studio 查询自己的记忆，无需向云端发送任何内容，并为每个回答显示来源
• 知识图谱 — 自动提取实体和关系，事物之间的联系会随着时间逐渐显现
• 记忆空间 — 为不同项目或领域创建独立命名空间
• REST API — 将 AI 记忆集成到任何应用中
• 一条命令即可设置 — 运行 docker compose up 即可启动
• 可自托管 — 数据始终保留在自己的设备上

---

架构

核心是 Postgres + pgvector。同一记忆层可通过 MCP（Claude）、仪表板聊天页面、REST API，以及你基于此构建的任何应用访问。

这个技术栈有三点是经过刻意设计的：

• 一个数据库，而非两个。 向量嵌入、全文索引和关系数据都存储在 Postgres 中。无需另设向量数据库并保持同步。
• 与前端无关。 仪表板只是 API 的一个使用方，而不是 API 本身。MCP、REST、CLI 和你自己的应用都是同等的一等客户端。
• 默认仅使用 CPU。 无需 GPU。嵌入（sentence-transformers）和实体提取（spaCy）都能在普通笔记本电脑上运行。

---

技术栈

• PostgreSQL 16 + pgvector — 在一个数据库中实现向量存储和混合搜索
• Python 3.11+ — 使用 psycopg 3 的异步后端
• sentence-transformers — all-MiniLM-L6-v2 嵌入（384 维，可在 CPU 上运行）
• spaCy — 使用 en_core_web_sm 进行实体提取（仅使用 CPU，不调用 LLM）
• FastAPI — 提供 REST API，支持 bearer 身份验证、速率限制和 OpenAPI 文档
• React 19 + Vite + TanStack Query — Web 仪表板，已打包到主 Docker 镜像中
• Cytoscape.js + cose-bilkent — 在仪表板上渲染力导向知识图谱
• Docker — 运行 docker compose up 即可一条命令完成部署
• MCP — 通过 FastMCP 集成 Claude（stdio 传输）

---

MCP 集成（Claude Desktop 和 Claude Code）

Memory Vault 通过 Model Context Protocol 提供六个工具，让 Claude 能在任何对话中读取和写入记忆。

工具

工具	描述
recall	使用混合搜索（向量 + 全文 + RRF）搜索记忆
remember	存储新记忆 — 自动分类并生成嵌入
forget	按区块 ID 软删除记忆
purge_forgotten	永久删除被遗忘超过 N 天的记忆
move_memory	将记忆移至其他空间，并重建其图谱条目
memory_status	数据库健康状态、区块数量和嵌入模型信息

资源

资源	描述
memory://spaces	列出所有记忆空间及其区块数量
memory://stats	当前系统统计信息

设置 — Claude Code

请确保已完成上文的无 Docker 快速入门（执行 uv sync 或 pip install，并下载 spaCy 模型），以安装 memory_vault 包。

项目级作用域 — 将以下内容添加到项目的 .mcp.json 中：

{
  "mcpServers": {
    "memory-vault": {
      "command": "/path/to/memory-vault/.venv/bin/python",
      "args": ["-m", "memory_vault.mcp"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "memory_vault",
        "DB_USER": "memory_vault",
        "DB_PASSWORD": "memory_vault"
      }
    }
  }
}

全局作用域 — 若要让 memory-vault 在每个 Claude Code 会话中都可用，请将相同的服务配置块添加到 ~/.claude/.mcp.json，然后将 memory-vault 添加到 ~/.claude/settings.json 中的 enabledMcpjsonServers：

{
  "enabledMcpjsonServers": ["memory-vault"]
}

运行 claude mcp list 进行验证 — memory-vault 应显示为 connected。

设置 — Claude Desktop

将相同的服务配置块添加到 Claude Desktop 的配置中（Settings → Developer → Edit Config），然后重启 Claude Desktop。

Docker 用户

如果您通过 Docker 运行 Memory Vault，请使用 DB_HOST: "127.0.0.1"，并确保在 docker-compose.yml 中公开端口 5432：

{
  "mcpServers": {
    "memory-vault": {
      "command": "/path/to/memory-vault/.venv/bin/python",
      "args": ["-m", "memory_vault.mcp"],
      "env": {
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "5432",
        "DB_NAME": "memory_vault",
        "DB_USER": "memory_vault",
        "DB_PASSWORD": "memory_vault"
      }
    }
  }
}

MCP 服务运行在主机上（而非 Docker 内部），并通过公开的端口连接 PostgreSQL 容器。

验证是否正常运行

配置完成后，Claude 就可以使用记忆工具。试试：

“使用 memory_status 检查记忆系统。”

“记住，我们为会话缓存选择了 Redis。”

“回想一下关于混合搜索的所有内容。”

故障排除

• 启动时出现 ModuleNotFoundError — 尚未安装虚拟环境；请在仓库目录中重新运行 uv sync（或 pip install -e .）。
• 启动时出现 OSError: [E050] — 尚未安装 spaCy 语言模型；请重新运行 python -m spacy download en_core_web_sm。
• 服务器在 Claude Code 中显示为 failed — 运行 claude --debug mcp 查看服务器的错误输出。
• 服务器已连接，但 Claude Code 中没有可用工具 — 确认 memory-vault 已列在 ~/.claude/settings.json 的 enabledMcpjsonServers 中。
• Docker 正在运行，但连接被拒绝 — 使用 DB_HOST: "127.0.0.1"，而不是 "localhost"。

通过 HTTP 远程访问

以上配置都通过 stdio 运行 MCP，前提是客户端和服务器位于同一台机器上。如果客户端位于其他位置——例如另一台机器上的 Claude Desktop，或另一个容器中的 Agent 运行框架——Memory Vault 也可以通过 SSE 使用 HTTP 提供 MCP 服务。

默认情况下，此功能处于关闭状态。 记忆存储不应在未经请求的情况下开始监听端口：

MCP_HTTP_ENABLED=true

之后，传输端点会挂载在 REST API 所用的同一端口上的 /api/mcp，因此客户端可连接到 http://<host>:8000/api/mcp/sse。

每个请求都需要令牌，令牌的创建方式与 REST API 相同：

memory-vault token create my-remote-client

不同客户端声明远程 MCP 服务的方式各不相同，但它们都需要相同的三项内容——SSE 传输、URL 和令牌。大多数客户端使用的配置格式如下：

{
  "mcpServers": {
    "memory-vault": {
      "type": "sse",
      "url": "http://192.168.1.50:8000/api/mcp/sse",
      "headers": { "Authorization": "Bearer mv_your-token-here" }
    }
  }
}

指定您的主机名

Memory Vault 只响应您声明过的主机名，对其他主机名则返回 HTTP 421。这项检查可以防止浏览器中的页面将自己的域名解析到 127.0.0.1，进而通过您的机器访问记忆存储。

默认设置适用于同一台机器上的客户端（任意端口上的 localhost 和 127.0.0.1）。如果通过其他名称访问——例如局域网地址、容器名称或反向代理后面的主机名——则需要显式声明：

MCP_HTTP_ALLOWED_HOSTS=memory.internal:8000,192.168.1.50:8000

此列表会替换默认值，而不是在其基础上添加，因此如果仍要允许本地客户端，请包含 localhost:*。host:* 条目会匹配该主机的任意端口。

如果客户端收到 421 Misdirected Request，原因就在这里：它使用的名称不在列表中。

安全性

API_AUTH_ENABLED=false 不会开放 MCP 传输。 此设置是 REST API 的本地开发便利选项，并且有意仅限于此——在自己的笔记本电脑上使用无需身份验证的 REST API 很方便，而让监听端口上的记忆存储无需身份验证，则可能导致实例暴露到公网。关闭此标志后，/api/spaces 无需令牌即可响应，而 /api/mcp/sse 仍会返回 401。

公开端口前，有两点值得注意：

• 绑定到合适的地址。 将容器端口发布到 0.0.0.0 会让整个网络都能访问。请绑定到局域网地址，或将其置于反向代理或隧道之后。
• 传输不加密。 令牌会通过标头传输，因此对于任何跨越不受您控制的网络的连接，都应在其前面配置 TLS——使用反向代理或隧道。

令牌的行为与 REST API 中完全相同：使用 memory-vault token revoke <prefix> 撤销令牌后，该令牌会立即在两种接口上同时失效，因为二者检查的是同一张表。

stdio 仍可照常使用。 这是一种额外的接入方式，而非替代方案；启用它不会影响现有客户端。

---

本地大模型聊天

Memory Vault 包含一个聊天页面，让你使用本地大模型与自己的记忆对话——无需云服务、OpenAI 密钥或遥测。仪表板会对你的知识库执行混合搜索，根据排名靠前的结果构建上下文块，并将本机运行的模型生成的回答流式传回。

每个回答都会显示来源。 每条回复都会包含大模型使用的确切文本块，以及相似度分数和内容预览。点击任意来源，即可验证回答是否基于你的数据，而非凭空编造。这是它区别于不透明的文档聊天工具的关键——你始终知道模型看到了什么。

设置

Memory Vault 在 v1.0 中使用 LM Studio 作为本地大模型提供方。

1. 下载并安装 LM Studio。
2. 加载一个非思考型模型——Qwen2.5（7B+）、Llama 3（8B+）或类似模型。避免使用 Qwen3、DeepSeek-R1 和 o1 风格的推理模型——它们会将思维链输出到回答中，破坏 RAG 工作流。
3. 启动本地服务（LM Studio → Developer 选项卡 → Start Server）。默认地址：http://localhost:1234。
4. 打开 Memory Vault 仪表板 → Chat 页面 → ⚙️ Settings → 确认 Local LLM URL 指向你的 LM Studio 实例。系统会自动检测模型。

完成。提出问题后，仪表板会检索相关文本块，将它们与你的问题一起发送给 LM Studio，并将回答流式传回。

工作原理

1. 混合搜索会为你的问题检索排名靠前的文本块（与 /api/search 和 MCP recall 使用相同的引擎）
2. 排名靠前的结果会被打包到 6,000-token 的上下文预算中——先移除最早的历史记录，然后移除相似度最低的文本块
3. LM Studio 会通过 Server-Sent Events 逐个 token 地流式生成回答
4. 来源会在数据流中最先到达，因此 UI 会在 token 开始传输前显示“基于 N 条记忆”

为什么优先使用 LM Studio

LM Studio 的原生 API 支持 reasoning="off"，这是在 RAG 工作流中抑制思考型模型思维链的唯一可靠方式。Memory Vault 默认使用原生 API；如果原生 API 不可用，则回退到 OpenAI 兼容接口（/v1/chat/completions），并移除 `` 内容。

---

REST API

每个 MCP 工具也都通过 HTTP 端点开放，因此你可以将 Memory Vault 集成到任何应用、脚本或语言中。运行 docker compose up 时，API 由 FastAPI 在 http://localhost:8000 上提供。

• 交互式文档： http://localhost:8000/docs
• OpenAPI 架构： http://localhost:8000/openapi.json

自动生成的 /docs 页面是权威的 API 参考文档，始终与代码保持同步。以下摘要仅供快速了解。

身份验证

除 /api/health 外，所有端点都需要 Bearer 令牌。通过命令行创建令牌：

docker compose exec app memory-vault token create my-app

明文令牌只显示一次——请立即复制。然后将它作为请求头发送：

curl -H "Authorization: Bearer mv_..." http://localhost:8000/api/spaces

管理令牌：

memory-vault token list
memory-vault token revoke mv_abc1234

若要完全禁用身份验证（仅限本地开发），请设置 API_AUTH_ENABLED=false。

端点

方法	路径	说明
GET	/api/health	服务和数据库运行状况（无需身份验证）
GET	/api/spaces	列出记忆空间及文本块数量
POST	/api/search	混合搜索（向量 + 全文 + RRF）
GET	/api/search/quality	查看近期搜索的匹配效果
GET	/api/chunks	分页并按筛选条件列出文本块
GET	/api/chunks/{id}	获取单个文本块
DELETE	/api/chunks/{id}	软删除（遗忘）文本块
POST	/api/ingest/text	将一段文本作为文本块导入
POST	/api/ingest/file	通过导入流程上传文件
POST	/api/chat	基于混合搜索的 RAG 聊天（非流式）
POST	/api/chat/stream	以逐个 token 的方式通过 SSE 流式传输 RAG 聊天

示例 — 搜索

curl -X POST http://localhost:8000/api/search \
  -H "Authorization: Bearer $MV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does hybrid search work",
    "spaces": ["default"],
    "limit": 5
  }'

示例 — 搜索质量

curl http://localhost:8000/api/search/quality \
  -H "Authorization: Bearer $MV_TOKEN"

{
  "queries": 42,
  "window_hours": 24,
  "avg_top_similarity": 0.51,
  "weak_matches": 6,
  "empty_results": 0,
  "weak_threshold": 0.35
}

这些数据汇总自已运行过的搜索——查询不花费任何资源，也不会自行运行查询。它报告的是每次搜索的最佳命中，而不是前 K 个结果的平均值，因为搜索返回的行数取决于你请求的数量以及知识库中的内容；对排名进行平均，衡量的不仅是匹配质量，也包括你的 limit。

weak_matches 是值得关注的数字。即使搜索找不到相关内容，也会返回最接近的猜测，因此即便没有给出令人满意的回答，empty_results 也会接近零。弱匹配数偏高，通常意味着答案从未被存储，而不是搜索未能找到答案。

Web UI 中的 Stats 页面会显示相同的数据。

示例 — 导入文本

curl -X POST http://localhost:8000/api/ingest/text \
  -H "Authorization: Bearer $MV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Decided to use RRF for hybrid merging", "space": "default"}'

示例 — 上传文件

curl -X POST http://localhost:8000/api/ingest/file \
  -H "Authorization: Bearer $MV_TOKEN" \
  -F "[email protected]" \
  -F "space=default"

配置

变量	默认值	描述
API_HOST	0.0.0.0	绑定地址
API_PORT	8000	端口
API_AUTH_ENABLED	true	设置为 false 可禁用 bearer 身份验证（仅限本地开发）
API_CORS_ORIGINS	*	允许的来源，以逗号分隔；也可以设为 *
API_RATE_LIMIT_PER_MIN	120	每个 IP 每分钟的请求限制

---

仪表板

Memory Vault 自带 Web UI，与 API 一同打包在同一个 Docker 镜像中——无需单独部署，也无需额外端口。运行 docker compose up 后，在浏览器中打开 http://localhost:8000。

共有六个页面：

• Chat — 使用本地大模型与知识库对话，每个回答都会显示来源（默认首页）
• Search — 混合搜索，支持空间筛选、相似度评分和展开查看命中内容
• Browse — 可分页的分块列表，支持空间和排序筛选，以及两步内联删除
• Graph — 力导向知识图谱（Cytoscape.js），支持平移/缩放；点击节点可查看其提及内容和相关实体，并可按空间 / 类型 / 最少提及次数 / 最大节点数筛选
• Ingest — 粘贴文本或上传文件（v1.0 中一次只能处理一个文件），显示每个文件的状态和批次摘要
• Stats — 系统运行状况、分块总数、带可视化分布的空间表格，每 30 秒自动刷新

访问

仪表板使用与 API 相同的 bearer 令牌。创建一个令牌并粘贴到仪表板的令牌界面中：

docker compose exec app memory-vault token create dashboard

明文令牌只显示一次——请立即复制。打开 http://localhost:8000，将令牌粘贴到提示框中，仪表板会将其存储在 localStorage 的 memory-vault-token 下。此后，在该浏览器中不会再提示你输入。

轮换或撤销

# See which tokens exist
docker compose exec app memory-vault token list

# Revoke by prefix (shown in list output)
docker compose exec app memory-vault token revoke mv_abc1234

# Create a new one
docker compose exec app memory-vault token create dashboard

撤销后，仪表板下次发出请求时会收到 401，并自动清除存储的令牌，要求你粘贴新令牌。

故障排除

• 每次重新加载都会提示输入令牌： 浏览器正在阻止 localStorage（隐私模式、严格的 Cookie 设置）。请使用普通窗口，或允许 localhost 使用存储。
• 每次请求都返回 401： 令牌已撤销，或 API_AUTH_ENABLED 已更改。请创建新令牌并粘贴到此处。
• 仪表板能显示，但 API 调用失败并出现 CORS 错误： 你访问的 API 与仪表板位于不同源。内置构建不会遇到此问题——请使用 http://localhost:8000，不要使用开发服务器，除非你清楚自己在做什么。
• 运行开发服务器： cd web && npm install && npm run dev 会在 http://localhost:5173 提供 UI，并将 API 调用代理到 :8000。仅供开发使用。
• Windows 特定问题： 请参阅 docs/windows.md。
• 报告错误： 运行 docker compose exec app memory-vault diagnose（或在主机上运行 memory-vault diagnose，以生成更完整的诊断包，其中包含 docker compose ps 和数据库日志）。该命令会生成 memory-vault-diagnostic-YYYY-MM-DD-HHMMSS.zip，其中包含应用日志、状态、操作系统信息和已脱敏的环境变量。Bearer 令牌、密码和 mv_ 令牌会自动清理——但请在将诊断包附加到公开的 GitHub 问题前检查一遍。
• 引用请求 ID： 每个 API 响应都带有一个 X-Request-ID 标头（UUID 十六进制）。请在错误报告中附上它——维护者可以据此在结构化 JSON 日志中查找同一请求。

---

工作原理

混合搜索

Memory Vault 将两种搜索方法结合起来，并合并搜索结果：

1. 向量搜索 — 将查询转换为嵌入向量，通过 HNSW 索引查找语义相似的文本块
2. 全文搜索 — 通过 PostgreSQL tsvector + GIN 索引进行关键词匹配
3. RRF 合并 — Reciprocal Rank Fusion 合并两个排序列表，避免任何一种方法占据主导

无论你记得的是确切措辞还是仅仅记得概念，都能找到合适的记忆。

查询扩展

搜索前，Memory Vault 会使用嵌入模型的 WordPiece 分词器提取关键技术术语，并生成最多 3 个查询变体。这样可以提高召回率，同时不损失精确度。

摄取流水线

基于异步队列的流水线，配有用于处理不同输入格式的适配器：

• Markdown — 按标题拆分，并保留结构
• 纯文本 — 按段落处理，并智能合并
• Claude JSON — 解析 Claude 对话导出文件

知识图谱

Memory Vault 会从每个已摄取的文本块中提取实体和关系，并将它们与记忆一同存储。点击仪表板中的 Graph 页面，即可查看已存储内容之间的关联。

提取方式：

• spaCy NER — 小型 en_core_web_sm 模型（约 15 MB，仅使用 CPU）会标注 PERSON、ORG 和 PRODUCT 实体，并分别映射为 Person、Project 和 Tool。
• 概念提取 — 在一个文本块中至少出现两次的多词名词短语会成为 Concept 实体。不使用大模型，也不调用 API。
• 共现关系 — 在同一文本块中找到的任意两个实体都会生成 related_to 关系。边的权重会随实体在多个文本块中的共现次数增加。
• 按空间去重 — 实体按 (lower(name), type, space) 去重，因此同一空间中的同一实体只保留一个节点，不会与无关项目中的实体合并。

整个流水线在摄取时同步运行，使用与嵌入计算相同的 CPU——无需额外服务，也没有外部 API 费用。

这些取舍是有意为之。spaCy 加上共现分析速度快、免费，而且能以 0% 的大模型成本实现实用知识图谱 80% 的功能。相关的局限已在下方的局限性部分中如实说明。

---

性能调优

Memory Vault 在捆绑的 docker-compose.yml 中默认设置 maintenance_work_mem = 1 GB。PostgreSQL 的原生默认值为 64 MB；语料库增长到几千个文本块后，这会让 pgvector 上的 HNSW 索引构建慢得令人难以忍受。

如果你的主机有 16 GB 或更多 RAM，将其提高到 2 GB 可以显著加快索引重建，且没有任何负面影响。编辑 docker-compose.yml 中的 command: 块：

db:
  image: pgvector/pgvector:pg16
  command:
    - postgres
    - -c
    - maintenance_work_mem=2GB

如果你运行在小型设备上（总 RAM 不超过 4 GB，例如小型 VPS），可以考虑将其降回 256 MB，为系统其余部分留出余量。Memory Vault 在原生默认值 64 MB 下仍然可以运行，只是在大型索引重建时会更慢。

---

局限性

v1.0 的局限性（如实说明）

• 仅支持英语 NER。 en_core_web_sm 是针对英语训练的；对于非英语文本，几乎无法提取有用实体。混合搜索和聊天支持任何语言，只有自动提取的知识图谱受限于英语。
• NER 依赖上下文。 spaCy 会根据周围的句子判断实体属于 PERSON 还是 ORG。同一个名称可能会因句法角色不同而被识别为 Person 和 Project 实体。
• 不支持模糊实体匹配。 “PostgreSQL”和“Postgres”是独立实体。v1.0 不会合并别名。
• 编辑后不会重新提取。 如果你忘记了一个文本块，又重新摄取了修正后的版本，新实体会被添加；旧实体不会自动清理。
• 单实例。 不支持多用户／多租户。每次部署只能有一个知识库。团队功能属于 PRO。
• 聊天仅支持 LM Studio。 v1.0 不支持 Ollama 提供商。

---

PRO 版本（计划中）

团队功能、高级分析、托管版本。免费／开源核心将永久免费——采用开放核心模式，而非诱导后变卦。

---

常见问题

这与 claude-mem / cognee / Mem0 有什么不同？

它们处于技术栈的不同层级。基于文件系统的工具（claude-mem、claudesidian、obsidian-second-brain）会将 Markdown 笔记保存在磁盘上，并在检索时使用 grep/read。它们在知识库增长到几千条笔记之前都表现出色；之后 grep 会变慢，而且无法进行语义回忆。Memory Vault 是基于数据库的记忆层（Postgres + pgvector + tsvector + RRF），旨在实现扩展，并作为其他应用的构建基础。它与前端无关。你可以通过 MCP、REST、仪表板或自己的应用使用它，这些都是同等的一等客户端。

cognee 和 Mem0 在技术栈中的位置更接近，但它们优先面向云端或 SDK。Memory Vault 则以可自托管的基础设施为先。

我需要 GPU 吗？

不需要。默认的嵌入模型（all-MiniLM-L6-v2，384-d）和实体提取模型（en_core_web_sm）都在 CPU 上运行。本地 LLM 聊天使用 LM Studio，可运行在你现有的硬件上——配备 16 GB RAM 的现代机器可以轻松运行 7B 参数模型。

我的数据会发送到云端吗？

不会。Memory Vault 从头到尾都可自托管。嵌入在本地运行（sentence-transformers），实体提取在本地运行（spaCy），聊天使用你的本地 LM Studio 实例。没有遥测，也不会向 OpenAI / Anthropic / 任何人发起 API 调用。你的数据会一直留在自己的机器上，仅此而已。

不使用 Claude 也能用吗？

可以。MCP 集成只是三种接口之一。REST API 和仪表板可以独立运行。你可以使用任意本地 LLM（LM Studio 支持许多开放权重模型）访问聊天页面，也可以基于 API 构建自己的 AI 工具。

NER 支持哪些语言？

v1.0 仅支持英语。默认 spaCy 模型针对英语训练，对于非英语文本，几乎无法提取有用实体。v1.0 不支持多语言 NER。混合搜索和聊天支持任何语言；只有自动提取的知识图谱受限于英语。

需要多少磁盘空间和 RAM？

大致需要：2 GB 磁盘空间（Docker 镜像 + Postgres 数据 + spaCy + 嵌入模型），空闲时占用 1–2 GB RAM，活跃使用时建议 4 GB 或以上。捆绑的配置将 maintenance_work_mem=1GB 设为默认值，以加快 HNSW 索引构建；在小型 VPS 上可将其降至 256 MB。

我可以运行多个 Memory Vault 实例吗？

可以。每个实例都通过一次 docker compose up 启动。使用不同的 Compose 项目名称（docker compose -p mv-personal up、docker compose -p mv-work up）使它们彼此隔离，或者克隆到不同目录中。

后续更新会如何影响我的数据？

迁移采用版本控制，且只能向前执行。docker compose pull && docker compose up -d 会在启动时运行新的迁移。v1.x 内的架构变更只会新增内容——次要版本升级不会执行破坏性迁移。这是 v1.x 语义化版本承诺的一部分。

---

参与贡献

Memory Vault 基于 MIT 许可，欢迎提交 PR。请参阅：

• CONTRIBUTING.md — 如何报告 Bug、提出功能建议、设置开发环境，以及编码规范
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1
• SECURITY.md — 如何报告漏洞（发送邮件至 [email protected]，不要公开提交 issue）
• docs/threat-model.md — Memory Vault 防御什么、不防御什么，以及如何加固超出单机部署范围的部署
• Bug 报告模板 — 包含 memory-vault diagnose 操作说明
• 功能请求模板 — 提出解决方案前，先描述问题

这是由单人维护的项目。我有时间时会审查 PR。大型功能应先在 issue 中讨论。

---

许可证

核心部分采用 MIT 许可，永远免费。让 Memory Vault 成为实用个人记忆系统的一切功能（混合搜索、MCP 集成、知识图谱、仪表盘、本地 LLM 聊天、Docker 配置）都将始终免费且开源。

计划推出面向团队和高级功能的 PRO 版本。

---

致谢

• @rivestack — 提供了 Postgres + pgvector 调优建议，已纳入 v1.0（使用 maintenance_work_mem=1GB 加快 HNSW 构建）。他的更多建议也已列入计划。
• Beta 测试者 — 在 M1-M7 期间克隆、测试并报告问题的各位
• 本项目所基于的开源巨作 — PostgreSQL、pgvector、sentence-transformers、spaCy、FastAPI、FastMCP、React、Cytoscape.js

---

鸣谢

GitHub 贡献者列表 致谢了所有代码进入代码库的贡献者。本节则致谢那些提供洞见、帮助塑造已发布成果，但未出现在提交作者记录中的问题报告者和诊断者。

• Leonard Janke（lcjanke2020），与 GPT-5.6-Sol 通过 OpenAI Codex 合作（@lcj-codex-coder）——在 v1.0.7–v1.0.10 期间报告了 20 多个问题，涉及版本偏差、MCP 正确性、时区处理、嵌入维度验证，以及知识图谱软删除语义。诊断质量可与同行媲美；每份报告都附有一次性数据库复现方案。
• @git-pharos — 在 #74 中提交的诊断包揭示了三个底层问题，这些问题已在 v1.0.7 中修复。
• Rivestack — 每次查询的 ef_search 参数，以及启动时预热向量索引，两者均已在 v1.5.0 中发布。其 pgvector 运维经验带来了这样的实用默认设置：演示时没问题，规模扩大后却不合适。

安全报告和正确性问题发现始终会注明报告者的用户名，以及报告者指定的任何署名格式——包括其要求注明的工具归属。

---

关注开发进展

• 网站：mihaibuilds.com
• 博客：mihaibuilds.com/blog
• GitHub：@MihaiBuilds
• X：@mihaibuilds

关注此代码库，持续了解项目进展。