内容
# Persyst
**本地优先、合规级别的MCP内存层，为受监管的企业编码团队使用AI助手。**
Persyst 为 AI 编码代理（Claude Code、Cursor、VS Code、Aider、Windsurf、Antigravity）提供跨会话的持久内存。它将内存存储在本地 SQLite 数据库中，采用混合关键字 + 语义搜索 — 100% 离线运行，零云 egress。
---
## 合规安全功能
Persyst 从头到尾为高度受监管的企业环境（金融、医疗保健、国防）而构建，符合 **SOC 2**、**HIPAA** 和 **欧盟 AI 法案**：
* **100% 数据驻留（零 egress）**：所有矢量计算、全文本搜索和模型推理都在开发人员的工作站上本地运行。数据库记录或上下文数据永远不会离开本地机器。绕过 HIPAA 的商业关联协议（BAA）复杂性。
* **加密托管链**：每次上下文检索都会生成一个 Ed25519 加密签名，密封查询和检索的内存哈希。每个证明都通过 SHA-256 哈希链与前一个证明链接，创建一个防篡改审计账本，可由安全团队验证。
* **自动机密信息删除**：扫描传入的日志文件和文本写入，以删除高熵机密（API 密钥、JWT、数据库字符串、私钥），然后再将其写入持久数据库。
* **事件驱动的文件监视**：集成了 `chokidar`，用于立即扫描代理转录文件夹，确保在每次代理交互后立即同步您的内存。
* **工作区项目隔离**：支持 `PERSYST_PROJECT` 环境分区，防止跨项目上下文泄漏，同时允许共享企业合规规则。
*在我们的合规映射指南中了解更多：*
- [SOC 2 Type II 控制](compliance/SOC2-controls.md)
- [HIPAA 映射和 PHI 边界](compliance/HIPAA-mapping.md)
- [欧盟 AI 法案第 13 条透明度](compliance/EU-AI-Act-Article13.md)
- [合规审计轨迹样本](compliance/audit-trail-sample.md)
---
## 快速入门和自动 IDE 设置
您不需要手动配置 MCP 文件。Persyst 包含一个自动设置 CLI，可以检测已安装的编辑器并在几秒钟内配置规则包装器和全局设置。
### 自动一键设置
在目标项目目录中运行设置向导：
```bash
npx persyst-mcp init
```
此命令自动：
1. 在 `~/.persyst` 中生成本地加密 Ed25519 密钥对。
2. 创建工作区规则文件（`.cursorrules`、`.windsurfrules`、`.clinerules`、`.persystrules.md`），以指示代理进行内存检索。
3. 自动为 **Cursor**、**Claude Code**、**Aider** 和 **Continue.dev** 编写全局 MCP 服务器配置，并带有项目范围的环境参数（`PERSYST_PROJECT`）。
---
## 手动 MCP 配置
如果您更喜欢手动配置代理，请将 MCP 服务器定义添加到您的编辑器：
### Claude Code (`~/.claude.json`) & Claude Desktop
```json
{
"mcpServers": {
"persyst": {
"command": "npx",
"args": ["-y", "persyst-mcp"],
"env": {
"PERSYST_PROJECT": "my-project"
}
}
}
}
```
### VS Code (Cline / Roo Code)
将以下内容添加到您的用户设置下的 `cline_mcp_settings.json`：
```json
{
"mcpServers": {
"persyst": {
"command": "npx",
"args": ["-y", "persyst-mcp"],
"env": {
"PERSYST_PROJECT": "my-project"
}
}
}
}
```
### Cursor
在 **设置 → 功能 → MCP** 下：
1. 点击 **+ 添加新 MCP 服务器**
2. 名称：`persyst`
3. 类型：`stdio`
4. 命令：`npx -y persyst-mcp`
### Aider
追加到您的 `.aider.conf.yml` 项目文件：
```yaml
mcp-server:
- name: persyst
command: npx -y persyst-mcp
env:
PERSYST_PROJECT: my-project
```
---
## 被动记录 vs. 主动检索
> **代理集成说明**：Persyst 以两种互补的模式运行：
> 1. **被动记录**：文件监视器自动从代理对话记录中提取并保存内存。
> 2. **主动检索**：AI 代理调用 `search_memories` 或 `get_optimized_context` 以获取相关上下文。
>
> 除非通过工作区规则（例如 `.cursorrules`、`.windsurfrules`、`.clinerules`）或自定义系统提示构建器配置，否则 IDE 本身不会自动将检索到的内存注入到提示输入中。
---
## 可用工具（19 个 MCP 端点）
| 工具 | 描述 | 关键参数 |
|------|-------------|----------------|
| `add_memory` | 存储新的内存，带有秘密删除和矛盾检查 | `content`，`importance`（0-1），`agent_id`，`shared` |
| `search_memories` | 带有证明的混合关键字 + 语义搜索 | `query`，`limit`，`agent_id` |
| `get_memory` | 通过 ID 检索特定的内存（提高重要性） | `id`，`agent_id` |
| `update_memory` | 更新内容并存档以前的版本 | `id`，`content`，`agent_id` |
| `delete_memory` | 永久删除内存并清理知识图谱边缘 | `id` |
| `get_recent_memories` | 获取按创建时间排序的最新内存 | `limit`，`agent_id` |
| `get_important_memories` | 获取按重要性评分排序的内存 | `limit`，`agent_id` |
| `get_optimized_context` | 在令牌预算内编译图跳跃上下文提示 | `query`，`max_tokens`，`agent_id`，`intent` |
| `ingest_git_commits` | 解析并导入最近的 git 提交记录为结构化内存 | `repo_path`，`count` |
| `watch_git_repo` | 轮询仓库以获取更改并自动导入新提交记录 | `repo_path` |
| `consolidate_memories` | 语义重复扫描，合并相似的内存 | — |
| `get_memory_history` | 检索完整的版本历史记录和语义差异 | `query` |
| `get_agent_stats` | 查看代理声誉评分和矛盾指标 | — |
| `export_audit_log` | 导出加密证明审计日志（JSON/Markdown） | `start_date`，`end_date` |
| `verify_attestation` | 验证 Ed25519 签名和 SHA-256 链完整性 | `attestation_id` |
| `add_entity` | 将命名实体添加到知识图谱 | `name`，`type` |
| `link_entity_memory` | 在知识图谱实体和内存之间创建边缘 | `entity_id`，`memory_id`，`relation` |
| `search_by_entity` | 通过知识图谱遍历查询链接的内存 | `entity_name` |
---
## 本地 HTTP 网关和 Swarm 集成
除了 STDIO 传输外，Persyst 还会自动在端口 `4321`（`http://127.0.0.1:4321`）启动高吞吐量本地 HTTP 网关。
- **`/health`**：健康检查和数据库状态
- **`/stats`**：全局内存和代理声誉统计数据
- **`/system-prompt`**：格式化提示上下文注入
- **`/compliance/export`**：加密合规审计报告导出（支持 `format=markdown`）
- **`/events`**：代理群组的实时服务器发送事件（SSE）流
---
## 混合搜索工作原理
Persyst 结合了两种互补的搜索策略：
1. **关键字搜索（SQLite FTS5）** — 使用 BM25 排名的快速精确字符串匹配。
2. **语义搜索（sqlite-vec）** — 使用本地 `all-MiniLM-L6-v2` 嵌入的基于深层含义的匹配。
结果会动态合并。关键字匹配会获得分数提升，以便精确匹配排在顶部，而语义相似性会使概念相关的内存出现在使用不同措辞时。
---
## 技术栈
- **运行时：** Node.js 18+
- **数据库：** SQLite via `better-sqlite3`（同步，WAL 模式）
- **矢量搜索：** `sqlite-vec`（进程内，零云 egress）
- **全文搜索：** SQLite FTS5
- **嵌入：** `@huggingface/transformers` + `all-MiniLM-L6-v2`（384-dim，本地 ONNX）
- **监视器：** `chokidar` 事件驱动文件监视
- **协议：** MCP over stdio + HTTP 网关
---
## 备份和迁移
Persyst 包含内置的 JSONL 导出/导入命令，用于可移植的内存备份和跨机器迁移：
```bash
# 导出所有内存到 JSONL 文件
npx persyst-mcp export
# 导出到特定文件
npx persyst-mcp export my-backup.jsonl
# 预览导入（干运行）
npx persyst-mcp import my-backup.jsonl --dry-run
# 导入内存（自动重复数据删除）
npx persyst-mcp import my-backup.jsonl
```
---
## 许可证
MIT 许可证。详情请参见 [LICENSE](LICENSE)。
