内容
ome
**适用于 macOS 的本地优先的个人模型运行时。** Persome 观察您已经使用的应用程序，将跨应用程序活动转换为可检查的真实人员模型，并将该模型提供给 Chat 和 MCP 代理。
[](https://github.com/Persome-ai/persome-core/actions/workflows/ci.yml)
[](https://github.com/Persome-ai/persome-core/releases)
[](LICENSE)
[](#平台支持)
[](MCP.md)
**[在 GitHub 上点赞 Persome](https://github.com/Persome-ai/persome-core)**，关注运行时并帮助优先考虑下一个 MCP 集成。
_实际的 `/model` 截图由 `scripts/sample_demo.py` 生成：4 个合成点、2 条线、2 个面、1 个体积和 1 个根。它不包含任何个人数据。_
## 产品工作
Persome 在一台 Mac 上静默运行，执行四项工作：
1. **收集** 具有可选的设备上 OCR 回落的聚焦 macOS 无障碍（AX）上下文，适用于 AX 较差的表面。
2. **建模** 观察结果为来源事实，演化关系，稳定模式，跨域结构和当前根。
3. **提供** 本地内存和模型工具通过 MCP，以及可选的终端聊天，使用相同的工具。
4. **归还控制** 通过回执，时间旅行，纠正，导出和删除。
这是运行时，而不是托管帐户或单个助手的私有内存。 一个本地模型可由 Claude Code、Codex、Cursor 或另一个受信任的 MCP 客户端使用。
## 五分钟示例演示
在没有 API 密钥、Accessibility 权限或访问您真实的 `~/.persome` 数据的情况下查看整个模型。 此路径需要 Git 和 [`uv`](https://docs.astral.sh/uv/getting-started/installation/)：
```bash
git clone https://github.com/Persome-ai/persome-core.git
cd persome-core
uv run python scripts/sample_demo.py
```
脚本打开 `http://127.0.0.1:8743/model`，在 `http://127.0.0.1:8743/mcp`，并在您按 `Ctrl-C` 时删除其临时合成数据。 要检查确切的搜索、回执和快照有效载荷：
```bash
PERSOME_LLM_MOCK=1 uv run python scripts/sample_demo.py --json
```
在样本服务器仍运行时，从第二个终端验证实际的 MCP 传输：
```bash
uv run python scripts/verify_sample_mcp.py
```
此示例路径与下面的真实数据路径故意分开。
## 快速入门，包含您的数据
要求：macOS 13 或更高版本和 Xcode 命令行工具。安装程序查找或安装 `uv`，配置 Python 3.11-3.13，编译 Swift AX 助手，生成本地截图加密密钥，并提供注册检测到的 MCP 客户端。
```bash
git clone https://github.com/Persome-ai/persome-core.git
cd persome-core
bash install.sh
persome doctor
persome start
open http://127.0.0.1:8742/model
```
在 **系统设置 -> 隐私和安全 -> 无障碍** 中授予 **无障碍** 到启动 Persome 的终端或应用程序。 此权限对于读取聚焦的 AX 文本和结构是必需的。 仅在启用 OCR 回落或截图保留时授予 **屏幕录制**；它为本地 OCR 工作器提供像素。 Persome 不需要完全磁盘访问权限。
LLM 密钥对于收集和 BM25 召回是可选的，但对于实际语义建模是必需的。 `install.sh` 可以将 Anthropic 密钥或与 Anthropic 兼容的网关密钥保存到仅限所有者的 `~/.persome/env` 文件中。没有任何密钥随附。
```bash
# 如果安装程序未带有密钥：
printf 'ANTHROPIC_API_KEY=%s\n' 'your-provider-key' >> ~/.persome/env
chmod 600 ~/.persome/env
persome stop || true
persome start
```
默认情况下，每五分钟减少一次主动工作。因此，在有效捕获加上一个工作的语义提供者后，预计会有十分钟内的有用召回；`persome status`、`persome model status` 和查看器解释稀疏或降级状态，而不是构造几何。
## 证明点
### 本地优先
- 持久的 Markdown、SQLite/FTS5、模型快照和日志存放在 `~/.persome` 下，除非设置了 `PERSOME_ROOT`。
- AX 是默认信号。可选的 PP-OCRv6 在隔离的子进程中本地运行，带有捆绑的权重。
- HTTP/MCP 服务器默认绑定到 `127.0.0.1`，并且没有遥测数据。
- 只有配置的语义阶段将派生文本发送到您选择的 LLM 或嵌入端点。
### 跨应用
Swift 监视器读取原生和浏览器应用中聚焦的 AX 树。Persome 规范化聚焦元素、可见文本、窗口、应用程序、URL 和时间到一个捕获和会话管道。OCR 是一个回落，而不是一个并行的云记录器。
### 代理就绪
- 可流式的 HTTP MCP：`http://127.0.0.1:8742/mcp`
- stdio MCP：`persome mcp`
- 本地聊天：`persome chat`
- 稳定模型合约：`persome model export` 和 `GET /model/graph`
- 证据工具：`search`、`read_receipt`、`verify_fact` 和 `get_model_snapshot`
## 连接 MCP 客户端
首先启动 Persome，然后注册端点：
```bash
persome start
persome install claude-code
persome install codex
# 生成一个可以合并到 Cursor 的 MCP 配置中的 stdio 配置：
persome install mcp-json --filename persome-mcp.json
```
| 客户端 | 验证配置 | 检查 |
| --- | --- | --- |
| Claude Code | `persome install claude-code` | `claude mcp list` |
| Codex CLI / IDE | `persome install codex` | `codex mcp list` |
| Cursor | 将生成的 `mcpServers.persome` 对象合并到 `.cursor/mcp.json` 或 `~/.cursor/mcp.json` | Cursor 设置 -> MCP |
规范的 JSON 形状是：
```json
{
"mcpServers": {
"persome": {
"command": "persome",
"args": ["mcp"]
}
}
}
```
参见 [MCP 客户端设置和验证](docs/mcp-clients获取 HTTP 配置、卸载命令、测试的客户端版本和隐私边界。
## 具有引用答案的真实 MCP 查询
以下结果由提交的合成样本通过 MCP 公开的 `search` 和 `read_receipt` 实现生成text
工具：search
输入：{"query时更喜欢专注的写作？","top_k":2}
最佳结果：
id： 20260701-0800-d4e5f6
路径： project-work.md
时间戳： 2026-07-01T08:00
用户保留早晨进行专注的写作和：read_receipt
输入：{"entry_id":"20260701-0800-d4e5f6"}
```
然后，基础的客户端响应可以说：
> 用户更喜欢在早上进行专注的写作和审查。
> [project-work.md, 2026-07-01 08:00;
> 回执 `20260701-0800-d4e5f6`]
回执是可解析的，之前被取代的陈述仍然作为历史记录提供，答案不依赖于模型的不可支持的内存。
## 基准和验证状态
此存储库报告运行时工程证据，而不是论文质量的个性化基准。
| 门控 | 公共证据 | 当前状态 |
| --- | --- | --- |
| 新的根完整的几何形状 | `tests/test_runtime_model_e2 | 确定的 |
| MCP 回执 | `sample_demo.py` + `verify_sample_mcp.py` | 真实的流式 HTTP MCP，确定的合成通过 |
| 离线运行时行为 | `pytest -m "not macos and not integration"` | 完整的离线套件；无提供者密钥 |
性 | 轮子安装 + 捆绑的 Swift、Three.js 和 PP-OCR 检查 | CI/发布所需 |
| 机密数据安全性 | `secret_scan.py` + `_scan.py` |发布所需 |
| 内存质量 / 下一步预测 | 单独的基准 | **此处不报告样本使用合成夹具，无法在真实人员上建立召回质量。 不声称跨用户基准、后续行动准确性、位或比较胜利机器的三个隔离源安装具有 11.896 秒的中位数和一个温暖的 `uv` 缓存； 条件和限制记录在 [基准范围](docs/benchmarks.md) 中。
## 为什么是 Persome
这些项目解决了相邻但不同的工作：
| 系统 | 主要工作 | Persome 的不同之处 |
| --- | --- | --- |
| [screenpipe](https://github.com/screenpipe/screenpipe) | 可搜索的本地屏幕/音频历史记录和开发者平台 | Persome 以演变的点/线/面/体积/根的个人模型为中心，具有纠正和回执，供 MCP 代理使用。 |
| [Mem0](https://github.com/mem0ai/mem0) | 由应用程序或对话事件填充的内存层 | Persome 从环境 macOS 工作上下文开始，拥有本地捕获/会话管道，并公开可检查的模型，而不是仅内存 |
| 助手/平台内存 | 便利功能位于一个提供者或客户端内 | Persome 是一个本地运行时，跨受信任的 MCP 客户端共享；数据、导出、纠正和删除仍在用户的控制之下。 |
Persome 不是全屏存档向量内存或提供者的首选项功能的替代品。 当核心需求是多个代理可以查询的本地、跨应用、可审计的模型时，请选择它。
## 工作原理
```mermaid
flowchart LR
AX[macOS AX 监视器] --> S0[S0 去抖动]
OCR[可选的本地 OCR] --> S1[S1 归一化捕获]
S0 --> S1
S1 --> BUF[捕获缓冲区]
BUF --> TL[1 分钟时间线]
TL --> SES[确定性会话]
SES --> DELTA[5 分钟内存增量]
DELTA --> PL[点和线]
PL --> FV[面和体积]
FV --> ROOT[根]
PL --> RET[BM25 和可选的密集检索]
FV -->CP、聊天、导出、查看器]
MCP
RET --> MCP
```
每个建都保留源回执和双时间历史存储可以真实地包含点和线面、体积或根。 查看器显示该不完整状态而不是构造一个。
阅读 [运行时架构](ARCHITECTURE.md)、[模型合约](MODEL_FORMAT.md) 和详细的 [维护者架构](docs/architecture.md)。
## 检查、纠正、导出和删除
```bash
# 检查
persome status
persome model status
persome faces-report
persome contradictions
open http://127.0.0.1:8742/model
# 纠正或撤销一个记忆，同时保留其审计轨迹
persome correct --help
# 代理也可以调用 MCP correct_memory。
# 导出一个红化的仅限所有者的快照（0600）
persome model export
# 删除模型内存，或所有捕获/时间线/模型状态
persomepersome clean memory
persome clean all
保留个人数据的完整卸载：
```bash
bash uninstall.sh
# 显式删除剩余的数据、配置、环境、导出和日志：
bash uninstall.sh --delete-data --yes
```
客户端注册单独且幂等地删除：
```bash
persome uninstall claude-code
persome uninstall codex
pers claude-desktop
```
有关确切的备份建议、导出敏感性、重置行为和步骤，请参见 [操作和数据控制](operations.md)。
## 隐私边界
- 个人配置的模型阶段或连接的代理将选发送到其自己的提供者之前保持本地。
- MCP 捕获工具可以返回原始屏幕文本、标题、URL 和聚焦字段值。仅连接您信任的客户端。
- 默认情况下，截图在 MCP 中省略，当启用保留时，截图会加密存储。
- `persome model export` 默认情况下会进行删减； `--raw` 是一个明确的选择。
- 没有内置的远程帐户、同步服务、遥测、会议音频捕获、计算机使用激活或文件系统分析器。
在将真实个人数据投入使用之前，请阅读 [安全和隐私](SECURITY_PRIVACY.md)，并通过 [SECURITY.md](SECURITY.md) 报告漏洞。
## 平台支持
| 平台 | 捕获 | 本地 OCR | 运行时 / MCP |
| --- | --- | --- | --- |
| macOS 13+ on Apple Silicon (`arm64`) | 支持 | 捆绑的 PP-OCRv6 | 支持 |
| macOS 13+ on Intel (`x86_64`) | 支持的 AX 路径 Paddle 不提供所需的 Intel 轮子，因此不可用 | 支持 |
| Linux | 无实时的 macOS 捕获 | 未打包 | 仅限离线测试和开发 |
| Windows | 不支持 | 不支持 | 不支持 |
安装程序支持 Python 3-3.13。参见 [操作](docs/operations.md) 和 [故障排除](docs/troubleshooting.md)。
## Persome 和 Personome
**Persome** 是此和项目名称。ome** 是对一个人的学习模型的研发术语：一个由来源观察、关系、稳定模式和更高层次结构组成的动态状态。 产品名称在命令、软件包、路径、API 和文档中保持为 Persome。
## 论文和架构说明状态
此存储库提供了可执行的运行时和面向实施的架构说明。 架构文档不是同行评议的论文，运行时的综合门控不是出版基准。 论文、基准测试套件、数据声明和项目发布将作为具有独立许可的单独工件在发布前提供。 参见 [许可边界](LICENSE 和 [基准测试限制](docs/benchmarks.md)。
## 路线图
公共路线图是问题驱动的：
- 更多测试的 MCP 客户端集成；
- 更丰富的首次运行权限诊断；
- 显式导入/导出互操作性；
- Intel 和未来 macOS 兼容性证据；
-的、可复制的个人模型基准测试套件。
浏览 [入门问题](https://githubersome-ai/persome-core/issues) 或在 [讨论](https://github.com/Persome-ai/persome-core/discussions) 中提出设计问题。
## 贡献和社区
阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，遵循 [行为准则](CODE_OF_CONDUCT.md)，并使用 [SUPPORT.md](SUPPORT.md) 选择正确的渠道。 每个提交都需要 DCO 签名，CI 阻止已知机密、个人数据、非文本、合约漂移、lint 失败和回归。
### 支持 Persome
如果可检查的、用户拥有的个人模型对您的代理有用，请在 GitHub 上 [**点赞 Persome**](https://github.com/Persome-ai/persome-core)，并在 [讨论](https://github.com/Persome-ai/persome-core/discussions) 中分享您想要支持的 MCP 客户端或工作流。
## 许可证
运行时代码为 Apache-2.0。 论文、基准测试、项目说明、第三方和个人数据边界在 [LICENSES.md](LICENSES.md) 中解释。 所需的合并工作通知保留在 [NOTICE](NOTICE) 和 [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES) 中。
