内容
<p align="center">
<img src="assets/readme/pixel-memory.svg" alt="Semi-Pervault像素记忆横幅" width="100%" />
</p>
<h1 align="center">Semi-Pervault内存服务器</h1>
<p align="center">
<strong>为AI智能体提供本地优先的长期记忆</strong>
<br />
为Claude Desktop、Cursor以及任何兼容MCP的客户端提供私有记忆层
</p>
<p align="center">
<a href="https://modelcontextprotocol.io/"><img alt="MCP" src="https://img.shields.io/badge/MCP-ready-38bdf8?style=for-the-badge" /></a>
<img alt="Python" src="https://img.shields.io/badge/Python-3.11%2B-34d399?style=for-the-badge" />
<img alt="存储" src="https://img.shields.io/badge/SQLite-local--first-fbbf24?style=for-the-badge" />
<a href="LICENSE"><img alt="许可证" src="https://img.shields.io/badge/许可证-MIT-a78bfa?style=for-the-badge" /></a>
</p>
<p align="center">
<a href="#快速入门">快速入门</a>
·
<a href="#为什么选择Semi-Pervault">为什么选择Semi-Pervault</a>
·
<a href="#使用场景">使用场景</a>
·
<a href="#MCP工具">MCP工具</a>
·
<a href="#架构">架构</a>
·
<a href="docs/launch-kit.md">启动套件</a>
·
<a href="#开发">开发</a>
</p>
<br />
Semi-Pervault MCP是一个围绕Pervault四层记忆架构构建的本地记忆服务器。它在本地SQLite数据库中存储重要事实、偏好、决策、项目上下文和关系笔记，然后将这些记忆作为MCP工具暴露给代理工作流。
目标很简单：让您的AI工具在不需要将私有记忆存储发送到托管服务的情况下，记住跨会话的有用上下文。
<br />
## 为什么存在
大多数AI工具在当时非常出色，但设计上却容易遗忘。Semi-Pervault MCP为它们提供了一个持久、可检查的记忆表面：
| 需求 | Semi-Pervault提供的内容 |
|---|---|
| 跨会话记住我 | 事实、偏好、决策和进展的长期本地存储 |
| 调用正确的上下文 | 跨事实、全文、嵌入和图上下文的混合检索 |
| 保持记忆可解释 | 证据链、录取分数和修订审计历史 |
| 默认保持私密 | 机器上的SQLite，具有仅回环守护进程 |
| 避免MCP进程脆弱性 | 一个薄的MCP桥接器转发到拥有后台工作的驻留守护进程 |
<br />
## 功能
- **存储长期记忆**，包括事实、偏好、决策、事件、关系和项目状态。
- **通过混合搜索检索**，跨结构化事实、全文搜索、嵌入和图上下文。
- **构建稳定的人物上下文**，基于重复的偏好和高置信度的特征。
- **提取知识图链接**，在人、项目、主题和事件之间。
- **通过后台整合循环生成反思**。
- **通过支持的记忆、置信度、录取分数和审计轨迹解释信念**。
- **保持数据本地优先**，使用SQLite存储和回环守护进程。
<br />
## 为什么选择Semi-Pervault
Semi-Pervault不仅仅是一个带有记忆表的stdio进程。它是一个通过MCP公开的本地记忆守护进程。
| 常见的MCP内存模式 | Semi-Pervault的不同之处 |
|---|---|
| MCP服务器进程拥有所有内容 | MCP只是一个插件。驻留守护进程拥有存储、后台作业和检索。 |
| 平面笔记、JSON或仅向量召回 | 四层记忆：原始记忆、结构化事实、稳定人物和更高层次的反思。 |
| 检索返回匹配的片段 | 混合召回结合事实、全文搜索、向量搜索、图上下文、人物和反思。 |
| 记忆难以审计 | `memory_why`返回证据、置信度、录取分数和修订历史。 |
| 后台工作在客户端关闭时停止 | 守护进程保持丰富、整合、衰减和睡眠代理工作。 |
| 隐私依赖于外部服务 | SQLite保留在您的机器上；提供者是可选的，仅用于丰富。 |
简而言之：Semi-Pervault的设计适用于需要记忆才能变得持久、结构化、可解释和私有的代理，而不是仅仅可搜索。
<br />
## 使用场景
Semi-Pervault MCP在您的AI助手需要连续性时最有用：
| 使用场景 | 示例记忆 |
|---|---|
| 个人助理上下文 | "我更喜欢简洁的技术解释，并附有具体下一步骤。" |
| 项目连续性 | "Semi-Pervault MCP使用薄的MCP桥和驻留的FastAPI守护进程。" |
| 研究和学习笔记 | "我正在香港大学学习数据科学和工程。" |
| 决策跟踪 | "我们选择了SQLite优先存储，以保持记忆本地化和可检查。" |
| 关系和协作上下文 | "Alice拥有项目X的后端可靠性决策。" |
尝试询问您的MCP客户端：
```text
记住我正在构建一个名为Semi-Pervault的本地优先内存MCP服务器。
```
然后再问：
```text
您还记得我的内存MCP项目吗？为什么？
```
第二个问题可以使用`memory_search`、`persona_get`或`memory_why`，具体取决于上下文。
<br />
## 架构
架构比看起来更简单：
> MCP是连接器。守护进程是记忆引擎。SQLite是真相的本地源。
Semi-Pervault分为三个边界：
| 区域 | 角色 |
|---|---|
| `apps/mcp_host/` | 薄的MCP桥接器。它通过stdio公开工具并将调用转发到本地守护进程。 |
| `backend/` | 驻留的FastAPI守护进程。它拥有HTTP API、身份验证、后台作业和所有写入`data.db`的操作。 |
| `packages/memory_core/` | 无框架的记忆内核：模式、模型、写入管道、检索、图、人物、反思和整合。 |
### 1. 运行时边界
这是用户首先需要了解的部分。Claude、Codex、Cursor、OpenClaw、Hermes等客户端不与SQLite通信。它们与MCP通信。MCP转发到守护进程。守护进程是唯一的写入者。
```mermaid
flowchart LR
Client["AI客户端或本地运行时<br/>Claude / Codex / Cursor<br/>OpenClaw / Hermes"] -->|"MCP stdio"| Bridge["MCP主机<br/>apps/mcp_host/server.py<br/>薄桥接器"]
Bridge -->|"127.0.0.1 /core/*<br/>X-Pervault-Token"| Daemon["内存守护进程<br/>backend/main.py<br/>唯一DB写入者"]
UI["可选本地UI<br/>或未来浏览器适配器"] -->|"HTTP"| Daemon
Daemon -->|"读取/写入"| DB["SQLite<br/>~/.pervault/data.db"]
Daemon -->|"启动一次"| Runtime["MemoryRuntime<br/>作业 + 整合<br/>衰减 + 睡眠代理"]
Runtime --> DB
Daemon -.-> Providers["可选LLM / 嵌入式API<br/>仅用于丰富"]
```
### 2. 记忆引擎
在守护进程内部，记忆并不存储为一个平面块。新记忆作为原始事件出现，然后后台作业将它们丰富为事实、图边、人物特征和反思。
```mermaid
flowchart TB
Store["memory_store / memory_update"] --> Raw["第1层<br/>memory_items<br/>原始事件记忆"]
Store --> Jobs["后台作业<br/>持久性丰富队列"]
Jobs --> Admission["录取 + 重要性<br/>这以后会很重要吗？"]
Jobs --> Facts["第2层<br/>结构化事实<br/>持久性事实"]
Jobs --> Graph["图记忆<br/>graph_nodes + graph_edges"]
Jobs --> Persona["第3层<br/>user_persona<br/>稳定特征"]
Jobs --> Reflection["第4层<br/>memory_reflection<br/>更高层次的洞察"]
Jobs --> Index["检索索引<br/>memory_fts + vec_items"]
Query["memory_search / persona_get<br/>memory_graph / memory_why"] --> Retrieval["混合检索<br/>意图路由 + 排名 + 来源"]
Retrieval --> Raw
Retrieval --> Facts
Retrieval --> Graph
Retrieval --> Persona
Retrieval --> Reflection
Retrieval --> Index
```
### 设计不变性
| 不变性 | 原因 |
|---|---|
| 单一写入者 | 守护进程是唯一写入SQLite的进程，因此MCP客户端重启不会损坏后台工作。 |
| 薄MCP桥接器 | `apps/mcp_host/server.py`仅读取`~/.pervault/core_token`并将工具调用转发到`127.0.0.1:8000/core/*`。 |
| 持久后台队列 | 丰富作业存在于SQLite中，因此图/人物/反思工作不受短生命周期MCP进程的影响。 |
| 可解释的记忆 | 重要信念可以通过源记忆、录取分数、置信度和修订日志追溯。 |
| 提供者可选的本地核心 | 基本存储和非向量召回在本地工作；LLM和嵌入式密钥提高丰富和检索质量。 |
### 数据模型
| 层 | SQLite表 | 目的 |
|---|---|---|
| 第1层：事件记忆 | `memory_items` | 原始记忆、源标签、权重、录取分数、修订状态。 |
| 第2层：结构化事实 | `structured_facts` | 从持久记忆中提取的规范化事实。 |
| 第3层：人物 | `user_persona` | 由源记忆证据支持的稳定用户特征。 |
| 第4层：反思 | `memory_reflection` | 由睡眠代理生成的更高层次的洞察。 |
| 图上下文 | `graph_nodes`、`graph_edges` | 人、项目、主题和事件的实体和关系记忆。 |
| 检索索引 | `memory_fts`、`vec_items` | 用于混合召回的全文和向量搜索表面。 |
| 证据和审计 | `memory_admission_log`、`preference_revision_log` | 录取证据、置信度历史和修正轨迹。 |
| 异步编排 | `background_jobs`、调度器日志 | 丰富、整合和睡眠代理工作的持久队列和运行历史。 |
写入路径故意很简单：工具和UI调用守护进程，守护进程调用`memory_core`，`memory_core`持久化到本地SQLite。这种分离使得MCP进程可替换，而记忆引擎保持活跃。
<br />
## MCP工具
| 工具 | 目的 |
|---|---|
| `memory_store` | 存储长期记忆项。 |
| `memory_search` | 使用混合搜索检索相关记忆。 |
| `memory_graph` | 查询某个主题的图上下文。 |
| `memory_update` | 修订现有记忆。 |
| `persona_get` | 读取稳定的人物特征。 |
| `reflections_list` | 读取后台代理生成的更高层次的反思。 |
| `memory_why` | 用支持的记忆、分数和审计轨迹解释信念。 |
| `memory_stats` | 显示记忆计数和录取统计。 |
<br />
## 快速入门
### 重要：模型/API设置
Semi-Pervault MCP是一个记忆层，而不是模型提供者。您仍然需要一个可以调用MCP工具的AI客户端或运行时。
有两个独立的API层：
| 层 | 您需要的内容 |
|---|---|
| **AI客户端/模型运行时** | Claude Desktop、Codex和类似的云模型客户端必须在使用此MCP服务器之前配置自己的帐户或API访问权限。OpenClaw / Hermes风格的本地运行时如果本地模型已安装并运行，则不需要云API进行客户端侧。 |
| **Semi-Pervault丰富** | `OPENAI_API_KEY`和嵌入式密钥对于基本存储是可选的，但对于LLM丰富、嵌入、更强的混合检索和一些后台智能是必要的。没有它们，守护进程仍然存储记忆并回退到非向量检索路径。 |
如果MCP客户端无法调用模型，Semi-Pervault将无法修复该部分。首先启动您的客户端/运行时，然后连接此记忆服务器。
### 要求
- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/getting-started/)
### 1. 启动本地守护进程
从项目根目录，双击`RUN.command`，或运行：
```bash
cd backend
cp .env.example .env
uv run python -m uvicorn main:app --host 127.0.0.1 --port 8000
```
守护进程仅绑定到`127.0.0.1`。
在首次使用时，它会在以下位置创建本地配对令牌：
```text
~/.pervault/core_token
```
默认数据库路径是：
```text
~/.pervault/data.db
```
如果您想将数据库存储在其他位置，请设置`PERVAULT_DB_PATH`。
### 2. 连接MCP客户端
Claude Desktop示例：
```json
{
"mcpServers": {
"pervault-memory": {
"command": "<uv的绝对路径>",
"args": [
"--directory",
"<绝对项目路径>/apps/mcp_host",
"run",
"python",
"server.py"
]
}
}
}
```
使用以下命令查找您的`uv`路径：
```bash
which uv
```
在编辑MCP客户端的配置后重启它。
特定于桥的详细信息位于[`apps/mcp_host/README.md`](apps/mcp_host/README.md)。
<br />
## 配置
后端配置模板位于[`backend/.env.example`](backend/.env.example)。
对于第一次本地测试，您可以保留提供者密钥为空并使用基本内存路径。在您需要丰富、向量检索、人物提取、图提取和更强的反射时添加LLM和嵌入式密钥。
| 变量 | 描述 |
|---|---|
| `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`LLM_MODEL` | 丰富和路由使用的LLM设置。 |
| `GEMINI_API_KEY`、`EMBEDDING_MODEL`、`EMBEDDING_BASE_URL`、`EMBEDDING_DIM` | 向量检索的嵌入设置。 |
| `PERVAULT_DB_PATH` | SQLite数据库位置。守护进程使用时默认为`~/.pervault/data.db`。 |
| `AUTH_PASSWORD`、`API_KEY`、`SESSION_SECRET` | HTTP路由的后端身份验证/会话设置。 |
| `CONSOLIDATION_SCHEDULER_ENABLED`、`WEIGHT_DECAY_SCHEDULER_ENABLED`、`SLEEP_AGENT_ENABLED` | 后台维护切换。 |
如果未配置嵌入式凭证，检索将回退到非向量搜索路径。
<br />
## 项目地图
```text
.
├── apps/mcp_host/ # MCP stdio桥
├── backend/ # FastAPI守护进程和HTTP路由
├── packages/memory_core/ # 无框架的记忆内核
├── docs/ # 架构和规划笔记
├── RUN.command # macOS助手启动守护进程
└── README.md
```
<br />
## 开发
在每个包目录中运行检查：
```bash
# 内存内核
cd packages/memory_core
env PYTHONPYCACHEPREFIX=/tmp/pervault-pycache uv run python -m pytest tests/ -q
# 后端守护进程
cd backend
env PYTHONPYCACHEPREFIX=/tmp/pervault-pycache uv run python -m pytest tests/ -q
# MCP桥
cd apps/mcp_host
uv run python -m pytest -q --ignore=tests/e2e_roundtrip.py
```
<br />
## 设计笔记
- 守护进程是本地优先和SQLite优先的。
- MCP桥故意设计得薄且无状态。
- `memory_core`是无框架的，并防止Web框架导入。
- 长期副作用由守护进程处理，而不是MCP stdio进程。
- 默认情况下数据是私有的，但外部LLM或嵌入式提供者可能会接收您通过配置的API密钥发送给它们的文本。
进一步阅读：
- [`docs/derivative/01-架构改造方案.md`](docs/derivative/01-架构改造方案.md)
- [`docs/plan/four-memory-architecture-integration-plan.md`](docs/plan/four-memory-architecture-integration-plan.md)
- [`packages/memory_core/README.md`](packages/memory_core/README.md)
- [`docs/launch-kit.md`](docs/launch-kit.md)
<br />
## 许可证
MIT。参见[`LICENSE`](LICENSE)。
