jarvis-mcp

# Jarvis MCP Jarvis MCP is a local-first memory and productivity server for AI coding agents. Codex or Claude supplies the reasoning, while durable memory remains ordinary Markdown on your computer. It gives an MCP-compatible AI client a durable work context, reminders, searchable memories, and bounded proactive check-ins without a database, cloud account, or model lock-in. Read [VISION.md](VISION.md) for the product direction: a proactive, explainable productivity assistant that can eventually be accessed securely from anywhere. ## What It Does - Keeps the active work session in `~/.jarvis/NOW.md`. - Maintains `~/.jarvis/INDEX.md` as a compact map of all durable knowledge and includes it in every context bootstrap. - Stores pending and completed tasks in `~/.jarvis/REMINDERS.md`. - Appends simple interaction summaries to `~/.jarvis/daily/YYYY-MM-DD.md`. - Saves durable memories under `~/.jarvis/memories/`. - Consolidates local Codex conversations every five hours into evidence-linked memory candidates. - Creates client-side encrypted daily backups and verifies remote restoration weekly. - Prevents exact duplicate reminders and can consolidate existing repeated tasks without deleting audit history. - Searches the Markdown vault without a database. - Exposes everything to MCP-compatible clients through a local STDIO server. - Optionally sends bounded morning, due-task, stale-work, and evening desktop check-ins on Linux. It does not yet sync devices or provide voice and dedicated UI features. ## Requirements - Node.js 20 or newer - `git`, `gh`, `tar`, `zstd`, and `age` for encrypted backups - An MCP client such as Codex CLI, Codex desktop, the Codex IDE extension, or Claude Code - For proactive Linux notifications: systemd and `notify-send` ## Install And Connect ### Easiest setup with Codex Your friend can install a new private Jarvis instance without copying your memories or editing configuration by hand: ```bash git clone https://github.com/ash25082003/jarvis-mcp.git cd jarvis-mcp codex ``` Then tell Codex: > Set up Jarvis for me. The repository's `AGENTS.md` directs Codex to run the idempotent setup script. It installs exact dependencies, builds Jarvis, creates a new empty vault with governance and recovery documentation, adds global Jarvis guidance without replacing unrelated instructions, registers the local MCP server, and installs a `jarvis` launcher. Codex then offers consent-driven setup for five-hour dream consolidation, desktop check-ins, and a dedicated encrypted backup. After setup finishes, restart Codex and run: ```bash jarvis ``` The cloned repository must remain at the same path because the MCP configuration starts Jarvis from that installation. To check prerequisites without changing anything, run `npm run setup:codex:check`. To repair or rerun the installation directly, run `npm run setup:codex`. See [docs/CODEX_SETUP.md](docs/CODEX_SETUP.md) for the complete walkthrough and [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for every path, variable, schedule, and privacy boundary. ### Easiest setup with Claude Code Your friend can install Jarvis without editing any configuration by hand: ```bash git clone https://github.com/ash25082003/jarvis-mcp.git cd jarvis-mcp claude ``` Then tell Claude Code: > Set up Jarvis for me. The repository's `CLAUDE.md` tells Claude to run the idempotent setup script. The script installs dependencies, builds Jarvis, creates a new empty vault for that user, registers Jarvis at Claude Code's user scope, and installs the conversation behavior for all of that user's Claude Code projects. It never copies another user's memories or credentials. After setup finishes, exit and restart Claude Code. The cloned repository must remain at the same path because the local MCP configuration starts Jarvis from that installation. To rerun or repair the setup directly: ```bash npm run setup:claude ``` ### Manual setup Clone the repository and build the server: ```bash git clone https://github.com/ash25082003/jarvis-mcp.git cd jarvis-mcp npm ci npm run build ``` Jarvis stores its vault in `~/.jarvis` by default. To use another folder, replace the value of `JARVIS_HOME` in the commands below. The MCP client starts the server when it needs it. You do not need to run `npm start` in a separate terminal. ### Codex The recommended installer performs all of these steps and preserves existing global guidance: ```bash npm run setup:codex ``` For a manual connection from the project directory: ```bash codex mcp add jarvis --env JARVIS_HOME="$HOME/.jarvis" -- node "$(pwd)/dist/src/index.js" ``` On Windows PowerShell, use absolute paths for both values: ```powershell codex mcp add jarvis --env JARVIS_HOME="C:\Users\YOUR_NAME\.jarvis" -- node "C:\path\to\jarvis-mcp\dist\src\index.js" ``` Verify the connection: ```bash codex mcp get jarvis ``` ### Claude Code Connect Jarvis from the project directory: ```bash claude mcp add --transport stdio --scope user jarvis --env JARVIS_HOME="$HOME/.jarvis" -- node "$(pwd)/dist/src/index.js" ``` Verify the connection: ```bash claude mcp list ``` On Windows, use absolute paths for `JARVIS_HOME` and `dist/src/index.js`. After connecting, restart the client and verify that Jarvis appears in its MCP server list. In Claude Code, use `/mcp` to inspect the connection. ## Conversation Style Jarvis keeps its conversation behavior separate from the MCP server: - [`prompts/JARVIS.md`](prompts/JARVIS.md) is the provider-independent conversation contract. - [`prompts/CODEX.md`](prompts/CODEX.md) is the Codex adapter used by the personal launcher. - [`prompts/CLAUDE.md`](prompts/CLAUDE.md) is the Claude Code adapter to add to the relevant `CLAUDE.md` instructions. This separation matters: MCP supplies facts and actions, while the AI client is responsible for turning them into natural conversation. The contract tells Jarvis to keep internal terms such as MCP, tools, and raw Markdown paths out of ordinary replies. ## First Conversation Start Codex or Claude Code and say: > Use Jarvis. Show my current context, then help me choose one concrete work objective and start a work session. Ask me for a definition of done if it is unclear. During work: > Log that I finished the first six evaluation tasks. Evidence: `results/`. At the end: > Finish this work session honestly as completed, partial, or blocked, and summarize what remains. To save something durable: > Save this as a Jarvis memory: Markdown is the canonical source of truth, and model providers must remain replaceable. To create a reminder: > Remind me to review the Jarvis roadmap at 11:00 tomorrow. ## Proactive Check-ins On Linux, install the optional user-level timers: ```bash npm run checkins:install ``` The default schedule is: - Morning planning at 09:00. - Due-task and stale-work checks once per hour. - Evening review at 18:00. - Quiet hours from 20:00 through 08:00. - At most three notifications per day. Settings live in `~/.config/jarvis/check-ins.env`. After changing them, the next check uses the new values. Preview a check-in without sending or recording it: ```bash npm run check-in -- --kind morning --dry-run ``` Disable the timers while keeping your settings: ```bash npm run checkins:uninstall ``` Proactive Check-ins v1 uses deterministic local rules, not unattended model calls. This makes each notification explainable and avoids background token usage. ## Dream Consolidation Jarvis can run an optional five-hour “dream cycle” over local Codex transcripts. Each cycle: 1. Reads only user-originated CLI and VS Code threads from the completed five-hour window; internal subagent threads are excluded. 2. Redacts common credential formats, bounds large messages and tool output, and treats transcript content as untrusted data. 3. Uses an ephemeral, read-only Codex run with a strict JSON output schema. 4. Stores an immutable cycle report with session IDs, timestamps, and brief supporting quotes. 5. Automatically promotes only non-sensitive candidates with confidence of at least 0.90, importance of at least 3, and direct evidence. 6. Sends sensitive, conflicting, or uncertain candidates to a review queue. Detected tasks are surfaced but never become reminders automatically. Install the exact five-hour user timer: ```bash npm run dream:install ``` Preview transcript coverage without calling the model or writing data: ```bash npm run dream -- --dry-run ``` Run the first cycle immediately, inspect status, and inspect logs: ```bash npm run dream -- --force npm run dream -- --status systemctl --user status jarvis-dream-cycle.timer journalctl --user -u jarvis-dream-cycle.service ``` Settings live in `~/.config/jarvis/dream-cycle.env`. The timer catches up bounded five-hour windows after downtime, uses a two-minute settlement delay to avoid partially written transcript records, and advances its checkpoint only after a complete successful cycle. Disable background runs without deleting memories or reports: ```bash npm run dream:uninstall ``` The MCP tools `get_dream_status`, `list_dream_candidates`, and `review_dream_candidate` expose the latest consolidation and let a user approve or reject queued candidates. Approval writes a canonical `auto-*.md` memory; original cycle evidence remains unchanged. ## Encrypted Backups Jarvis keeps the live Markdown vault readable locally and stores only client-side `age` ciphertext in the private backup repository. The remote contains a compressed encrypted snapshot, public recipient, and integrity manifest; it never receives plaintext vault files or the private identity. The backup path performs these checks in order: 1. Verify the configured GitHub repository is private. 2. Scan every text file for common credentials without printing matched values. 3. Build a deterministic `tar.zst` archive and compare its plaintext hash with the last valid snapshot. 4. Skip both encryption and commit creation when content is unchanged. 5. Encrypt changed content locally, commit only the ciphertext and manifest, and push non-interactively. 6. Once per week, clone the remote into a temporary directory, verify both checksums, decrypt and extract it, check required vault files, rerun the credential scan, record success, and delete the temporary restore. Commands: ```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 ``` The default timers run the backup daily around 03:15 and restoration verification every Sunday around 04:15, with a randomized delay. Settings and the private identity live under `~/.config/jarvis/`; stable runtime copies live under `~/.local/lib/jarvis-backup/`; the dedicated backup checkout and verification status live under `~/.local/share/jarvis/` and `~/.local/state/jarvis/`. The identity at `~/.config/jarvis/backup-age-key.txt` must be copied to an offline password manager. Losing that identity makes remote snapshots unrecoverable. ## Where Your Data Lives ```text ~/.jarvis/ ├── AGENTS.md # Vault governance and privacy rules ├── README.md # Structure, ownership, and recovery guidance ├── INDEX.md # Generated knowledge map included in every context bootstrap ├── NOW.md # Active work session ├── REMINDERS.md # Pending and completed reminders ├── daily/YYYY-MM-DD.md # Concise work and check-in history ├── memories/*.md # Explicit and approved/automatic durable memories └── dreams/ ├── LATEST.md # Latest cycle and review summary ├── state.json # Successful-window checkpoint ├── review-queue.json # Hybrid human review queue └── cycles/ # Immutable JSON and Markdown cycle reports ``` The index lists every durable memory by path and title, recent daily logs, and counts for immutable dream-cycle records. Jarvis regenerates it from the vault before composing current context, so the map cannot silently drift when files are added or removed. Detailed memory contents stay on disk until they are relevant and can be retrieved with `search_memory`, avoiding an ever-growing prompt. These are ordinary Markdown files. You can open, edit, back up, or move them without Jarvis. ## MCP Tools - `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` ## Development ```bash npm test ``` The next feature should be added only after using this basic work-session loop in real work. ## How It Works ```text You -> Codex or Claude -> Jarvis MCP tools -> Markdown files on your computer ^ systemd timers -> relevance rules -> desktop notifications local Codex transcripts -> dream consolidation -> evidence-backed memories ``` The model decides when to call a Jarvis tool. Jarvis only validates the request and reads or writes the Markdown vault. Your memory remains usable without Jarvis because the files are plain text. ## Roadmap - Learn from real use of the work-session and proactive check-in loops. - Add a context composer, dialogue director, and response-quality evaluation layer. - Add reminder feedback, snooze controls, and configurable schedules. - Learn from dream-consolidation review decisions and improve candidate ranking. - Add authenticated remote access and multi-device use without giving up local ownership. - Adopt MCP Apps and Tasks after the `2026-07-28` specification and target clients support them. ## Privacy Jarvis does not operate its own cloud service. Your MCP client or model provider may process text returned by tools. When dream consolidation is enabled, the relevant bounded transcript window and existing Jarvis context are sent through your authenticated Codex account for analysis. Raw source transcripts remain in Codex storage, and Jarvis stores only structured reports and brief evidence excerpts. Encrypted backups are protected before upload, but repository privacy and the offline encryption identity still matter. Protect `~/.codex`, `~/.jarvis`, and `~/.config/jarvis/backup-age-key.txt` as sensitive data. ## License MIT