内容
# Jarvis MCP
Jarvis MCP 是一个本地优先的记忆和生产力服务器，适用于 AI 编程代理。Codex 或 Claude 提供推理能力，而持久记忆则保留在计算机上的普通 Markdown 文件中。
它为兼容 MCP 的 AI 客户端提供持久的工作上下文、提醒、可搜索的记忆和有界的定期检查，无需数据库、云账户或模型锁定。
阅读 [VISION.md](VISION.md) 以了解产品方向：一个主动的、可解释的生产力助手，最终可以从任何地方安全访问。
## 功能
- 将活动工作会话保存在 `~/.jarvis/NOW.md` 中。
- 维护 `~/.jarvis/INDEX.md` 作为所有持久知识的紧凑映射，并在每次上下文启动时包含它。
- 将待处理和已完成的任务存储在 `~/.jarvis/REMINDERS.md` 中。
- 将简单的交互摘要追加到 `~/.jarvis/daily/YYYY-MM-DD.md` 中。
- 在 `~/.jarvis/memories/` 下保存持久记忆。
- 每五小时将本地 Codex 对话合并到证据链接的记忆候选者中。
- 创建客户端加密的每日备份，并每周验证远程恢复。
- 防止确切的重复提醒，并且可以在不删除审计历史的情况下合并现有的重复任务。
- 在没有数据库的情况下搜索 Markdown 保险库。
- 通过本地 STDIO 服务器将所有内容暴露给兼容 MCP 的客户端。
- 可选地在 Linux 上发送有界的晨间、到期任务、陈旧工作和晚间桌面检查。
它目前不具备同步设备或提供语音和专用 UI 功能。
## 要求
- Node.js 20 或更新版本
- `git`、`gh`、`tar`、`zstd` 和 `age` 用于加密备份
- MCP 客户端，例如 Codex CLI、Codex 桌面版、Codex IDE 扩展或 Claude Code
- 对于主动 Linux 通知：systemd 和 `notify-send`
## 安装和连接
### 使用 Codex 最简单的设置
您的朋友可以安装一个新的私有 Jarvis 实例，而无需复制您的记忆或手动编辑配置：
```bash
git clone https://github.com/ash25082003/jarvis-mcp.git
cd jarvis-mcp
codex
```
然后告诉 Codex：
> 为我设置 Jarvis。
存储库的 `AGENTS.md` 指导 Codex 运行幂等设置脚本。它安装确切的依赖项，构建 Jarvis，创建一个新的空保险库，并添加全局 Jarvis 指导，而不替换不相关的指令。Codex 然后提供五小时梦境整合、桌面检查和专用加密备份的同意驱动设置。
设置完成后，重启 Codex 并运行：
```bash
jarvis
```
克隆的存储库必须保持在相同的路径，因为 MCP 配置从该安装启动。要在不更改任何内容的情况下检查先决条件，请运行 `npm run setup:codex:check`。要修复或重新运行安装，请直接运行 `npm run setup:codex`。
参见 [docs/CODEX_SETUP.md](docs/CODEX_SETUP.md) 以获取完整的演练步骤，[docs/CONFIGURATION.md](docs/CONFIGURATION.md) 以获取每个路径、变量、计划和隐私边界的详细信息。
### 使用 Claude Code 最简单的设置
您的朋友可以安装 Jarvis，而无需手动编辑任何配置：
```bash
git clone https://github.com/ash25082003/jarvis-mcp.git
cd jarvis-mcp
claude
```
然后告诉 Claude Code：
> 为我设置 Jarvis。
存储库的 `CLAUDE.md` 告诉 Claude 运行幂等设置脚本。该脚本安装依赖项，构建 Jarvis，为该用户创建一个新的空保险库，在 Claude Code 的用户范围内注册 Jarvis，并为该用户的所有 Claude Code 项目安装对话行为。它永远不会复制其他用户的记忆或凭证。
设置完成后，退出并重启 Claude Code。克隆的存储库必须保持在相同的路径，因为本地 MCP 配置从该安装启动。
要重新运行或修复设置，请直接运行：
```bash
npm run setup:claude
```
### 手动设置
克隆存储库并构建服务器：
```bash
git clone https://github.com/ash25082003/jarvis-mcp.git
cd jarvis-mcp
npm ci
npm run build
```
Jarvis 默认情况下将其保险库存储在 `~/.jarvis` 中。要使用其他文件夹，请替换以下命令中的 `JARVIS_HOME` 值：
MCP 客户端在需要时启动服务器。您无需在单独的终端中运行 `npm start`。
### Codex
推荐的安装程序执行所有这些步骤，并保留现有的全局指导：
```bash
npm run setup:codex
```
从项目目录手动连接：
```bash
codex mcp add jarvis --env JARVIS_HOME="$HOME/.jarvis" -- node "$(pwd)/dist/src/index.js"
```
在 Windows PowerShell 上，请使用绝对路径：
```powershell
codex mcp add jarvis --env JARVIS_HOME="C:\Users\YOUR_NAME\.jarvis" -- node "C:\path\to\jarvis-mcp\dist\src\index.js"
```
验证连接：
```bash
codex mcp get jarvis
```
### Claude Code
从项目目录连接 Jarvis：
```bash
claude mcp add --transport stdio --scope user jarvis --env JARVIS_HOME="$HOME/.jarvis" -- node "$(pwd)/dist/src/index.js"
```
验证连接：
```bash
claude mcp list
```
在 Windows 上，请为 `JARVIS_HOME` 和 `dist/src/index.js` 使用绝对路径。
连接后，重启客户端并验证 Jarvis 是否出现在其 MCP 服务器列表中。在 Claude Code 中，使用 `/mcp` 检查连接。
## 对话风格
Jarvis 将其对话行为与 MCP 服务器分开：
- [`prompts/JARVIS.md`](prompts/JARVIS.md) 是与提供者无关的对话合同。
- [`prompts/CODEX.md`](prompts/CODEX.md) 是个人启动器使用的 Codex 适配器。
- [`prompts/CLAUDE.md`](prompts/CLAUDE.md) 是 Claude Code 适配器，用于添加到相关的 `CLAUDE.md` 指令中。
这种分离很重要：MCP 提供事实和行动，而 AI 客户端负责将它们转化为自然对话。对话合同告诉 Jarvis 保持内部术语（如 MCP、工具和原始 Markdown 路径）不出现在普通回复中。
## 首次对话
启动 Codex 或 Claude Code 并说：
> 使用 Jarvis。显示我的当前上下文，然后帮助我选择一个具体的工作目标并开始工作会话。如果不明确，请向我询问完成工作的定义。
在工作过程中：
> 记录我已经完成了前六个评估任务。证据：`results/`。
在结束时：
> 诚实地完成、部分完成或阻塞这个工作会话，并总结还剩下什么。
要保存某些内容：
> 将此内容保存为 Jarvis 记忆：Markdown 是真实性的规范来源，并且模型提供者必须保持可替换。
要创建提醒：
> 提醒我在明天 11:00 审查 Jarvis 路线图。
## 主动检查
在 Linux 上，安装可选的用户级计时器：
```bash
npm run checkins:install
```
默认计划是：
- 09:00 晨间规划。
- 每小时一次的任务到期和陈旧工作检查。
- 18:00 晚间审查。
- 20:00 至 08:00 静音时间。
- 每天最多三个通知。
设置位于 `~/.config/jarvis/check-ins.env`。更改设置后，下一次检查将使用新值。
预览检查而不发送或记录它：
```bash
npm run check-in -- --kind morning --dry-run
```
在保持设置不变的情况下禁用计时器：
```bash
npm run checkins:uninstall
```
主动检查 v1 使用确定性的本地规则，而不是无人值守的模型调用。这使得每个通知都是可解释的，并避免了后台令牌使用。
## 梦境整合
Jarvis 可以在本地 Codex 转录上运行一个可选的五小时“梦境循环”。每个循环：
1. 读取仅限用户发起的 CLI 和 VS Code 线程，来自已完成的五小时窗口；内部子代理线程被排除。
2. 删减常见的凭证格式，绑定大消息和工具输出，并将转录内容视为不受信任的数据。
3. 使用短暂的、只读的 Codex 运行，并具有严格的 JSON 输出模式。
4. 存储具有会话 ID、时间戳和简要支持引语的不可变循环报告。
5. 自动提升仅具有至少 0.90 置信度、至少 3 重要性且具有直接证据的非敏感候选者。
6. 将敏感、冲突或不确定的候选者发送到审查队列。检测到的任务被显示，但永远不会自动成为提醒。
安装确切的五小时用户计时器：
```bash
npm run dream:install
```
预览转录覆盖范围而不调用模型或写入数据：
```bash
npm run dream -- --dry-run
```
立即运行第一个循环，检查状态和日志：
```bash
npm run dream -- --force
npm run dream -- --status
systemctl --user status jarvis-dream-cycle.timer
journalctl --user -u jarvis-dream-cycle.service
```
设置位于 `~/.config/jarvis/dream-cycle.env`。计时器弥补了停机后的有界五小时窗口，使用两分钟的结算延迟来避免部分写入的转录记录，并在成功循环后仅推进其检查点。
禁用后台运行而不删除记忆或报告：
```bash
npm run dream:uninstall
```
MCP 工具 `get_dream_status`、`list_dream_candidates` 和 `review_dream_candidate` 公开最新的整合情况，并允许用户批准或拒绝排队的候选者。批准写入规范的 `auto-*.md` 记忆；原始循环证据保持不变。
## 加密备份
Jarvis 保持实时 Markdown 保险库可本地读取，并仅在私有备份存储库中存储客户端加密的 `age` 密文。远程存储压缩的加密快照、公共接收者和完整性清单；它永远不会接收纯文本保险库文件或私有身份。
备份路径按顺序执行以下检查：
1. 验证配置的 GitHub 存储库是私有的。
2. 扫描每个文本文件以获取常见的凭证，而不打印匹配的值。
3. 构建确定性的 `tar.zst` 存档，并将其纯文本哈希与上一个有效快照进行比较。
4. 如果内容未更改，则跳过加密和提交创建。
5. 当内容更改时，本地加密更改的内容，仅提交密文和清单，并非交互式地推送。
6. 每周一次，克隆远程存储库到临时目录，验证两个校验和，解密并提取它，检查所需的保险库文件，重新运行凭证扫描，记录成功，并删除临时恢复。
命令：
```bash
export JARVIS_BACKUP_REMOTE=https://github.com/YOUR_ACCOUNT/YOUR_PRIVATE_BACKUP.git
npm run backup:setup
npm run backup
npm run backup:verify
npm run backup:install
npm run backup:uninstall
```
默认计时器每天凌晨 03:15 运行备份，每周日凌晨 04:15 运行恢复验证，并带有随机延迟。设置和私有身份位于 `~/.config/jarvis/` 下；稳定的运行时副本位于 `~/.local/lib/jarvis-backup/` 下；专用备份检出和验证状态位于 `~/.local/share/jarvis/` 和 `~/.local/state/jarvis/` 下。
位于 `~/.config/jarvis/backup-age-key.txt` 的身份必须复制到离线密码管理器中。丢失此身份将使远程快照无法恢复。
## 数据存储位置
```text
~/.jarvis/
├── AGENTS.md # 保险库治理和隐私规则
├── README.md # 结构、所有权和恢复指南
├── INDEX.md # 每个上下文启动时包含的生成的知识地图
├── NOW.md # 活动工作会话
├── REMINDERS.md # 待处理和已完成的提醒
├── daily/YYYY-MM-DD.md # 简洁的工作和检查历史
├── memories/*.md # 显式和批准的/自动持久记忆
└── dreams/
├── LATEST.md # 最新周期和审查摘要
├── state.json # 成功窗口检查点
├── review-queue.json # 混合人工审查队列
└── cycles/ # 不变的 JSON 和 Markdown 周期报告
```
索引按路径和标题列出每个持久记忆，包含最近的每日日志和不可变的梦境循环记录。Jarvis 在编写当前上下文之前，从保险库中重新生成它，因此地图不会在添加或删除文件时悄悄更改。详细的记忆内容保留在磁盘上，直到它们相关，并且可以使用 `search_memory` 检索，从而避免不断增长的提示。
这些是普通的 Markdown 文件。您可以打开、编辑、备份或移动它们，而无需 Jarvis。
## MCP 工具
- `initialize_vault`
- `get_current_context`
- `start_work`
- `log_progress`
- `finish_work`
- `add_reminder`
- `list_reminders`
- `complete_reminder`
- `deduplicate_reminders`
- `save_memory`
- `search_memory`
- `get_dream_status`
- `list_dream_candidates`
- `review_dream_candidate`
## 开发
```bash
npm test
```
在实际工作中使用此基本工作会话循环后，应添加新功能。
## 工作原理
```text
您 -> Codex 或 Claude -> Jarvis MCP 工具 -> 计算机上的 Markdown 文件
^
systemd 计时器 -> 相关性规则 -> 桌面通知
本地 Codex 转录 -> 梦境整合 -> 基于证据的记忆
```
模型决定何时调用 Jarvis 工具。Jarvis 只验证请求并读取或写入 Markdown 保险库。您的记忆在没有 Jarvis 的情况下仍然可用，因为文件是纯文本。
## 路线图
- 从实际使用工作会话和主动检查循环中学习。
- 添加上下文编译器、对话导演和响应质量评估层。
- 添加提醒反馈、延迟控制和可配置的计划。
- 从梦境整合审查决策中学习并改进候选者排名。
- 添加身份验证的远程访问和多设备使用，而不放弃本地所有权。
- 在 2026-07-28 规范和目标客户端支持的 MCP 应用和任务之后采用。
## 隐私
Jarvis 不运营自己的云服务。您的 MCP 客户端或模型提供商可能会处理工具返回的文本。当启用梦境整合时，相关的有界转录窗口和现有的 Jarvis 上下文将通过您的身份验证的 Codex 帐户发送进行分析。原始源转录保留在 Codex 存储中，Jarvis 仅存储结构化报告和简要证据摘录。加密备份在上传前受到保护，但存储库隐私和离线加密身份仍然很重要。请保护 `~/.codex`、`~/.jarvis` 和 `~/.config/jarvis/backup-age-key.txt` 作为敏感数据。
## 许可证
MIT
