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 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.

Related MCP server: Codex Memory

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:

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:

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 for the complete walkthrough and 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:

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:

npm run setup:claude

Manual setup

Clone the repository and build the server:

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:

npm run setup:codex

For a manual connection from the project directory:

codex mcp add jarvis --env JARVIS_HOME="$HOME/.jarvis" -- node "$(pwd)/dist/src/index.js"

On Windows PowerShell, use absolute paths for both values:

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:

codex mcp get jarvis

Claude Code

Connect Jarvis from the project directory:

claude mcp add --transport stdio --scope user jarvis --env JARVIS_HOME="$HOME/.jarvis" -- node "$(pwd)/dist/src/index.js"

Verify the connection:

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 is the provider-independent conversation contract.

• prompts/CODEX.md is the Codex adapter used by the personal launcher.

• 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:

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:

npm run check-in -- --kind morning --dry-run

Disable the timers while keeping your settings:

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:

npm run dream:install

Preview transcript coverage without calling the model or writing data:

npm run dream -- --dry-run

Run the first cycle immediately, inspect status, and inspect logs:

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:

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:

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

~/.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

npm test

The next feature should be added only after using this basic work-session loop in real work.

How It Works

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