Jarvis Markdown MCP

Jarvis is a small local-first memory server for AI coding agents. Codex or Claude supplies the reasoning, while durable memory remains ordinary Markdown on your computer.

This repository is the MVP: a dependable work-session loop with no 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

git clone https://github.com/ash25082003/jarvis-markdown-mcp.git
cd jarvis-markdown-mcp
npm ci
npm run build

The vault defaults to ~/.jarvis. To use another folder, set JARVIS_HOME before launching the server.

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-markdown-mcp\dist\src\index.js"

Verify the connection:

codex mcp list

Claude Code

Connect Jarvis from the project directory:

claude mcp add jarvis -e 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.

First Conversation

Start your AI client 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.

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