Jarvis Markdown

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.
• 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/.
• 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 reorganize memory, run AI reasoning in the background, monitor files, sync devices, or provide voice and UI features.

Requirements

• Node.js 20 or newer
• 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 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

Connect Jarvis 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 list

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.

Where Your Data Lives

~/.jarvis/
├── NOW.md                 # Active work session
├── REMINDERS.md           # Pending and completed reminders
├── daily/YYYY-MM-DD.md    # Concise work and check-in history
└── memories/*.md          # Durable memories you explicitly save

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
• save_memory
• search_memory

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

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.
• Add optional memory organization and consolidation.
• 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 send your vault anywhere. Your MCP client or model provider may process text returned by tools, so use the privacy settings appropriate for that client.

License

MIT