VibeDNA Journal

io.github.marstudio360v1.0.0Updated Oct 6, 2026

One journal file per project that your AI reads at session start and updates as it works.

VerifiedSTDIODesktop onlyDeveloper Tools Files & Storage Knowledge & Memory

Overview

AI-generated overview

Gives an assistant a per-project markdown journal it reads at session start and appends to as work ships, with ranked full-text search across all journals.

What it does: Each project gets one plain markdown journal file with standard sections such as Current state, Decisions log, Incidents and Handoff for next session. Tools let the assistant read a journal, a single section or a short handoff brief, append timestamped entries, replace or append sections, and create new journals. A SQLite FTS5 index provides ranked full-text search with snippets across every journal, plus recent-changes, stats, overlap and metadata browsing. An optional tool installs a rule into CLAUDE.md so the habit runs without being asked.
When to use it: Useful when an assistant works across several projects and should carry context between sessions: decisions and their reasons, bugs with root cause and fix, current state and a handoff note. Worth adding if you want that record kept as plain files on your own disk rather than in a hosted service.
Requirements: Local process over stdio; Python 3.10+ and the mcp package. Environment variables JOURNAL_ROOTS (folders to scan, semicolon-separated; defaults to ~/Desktop and ~/Documents) and JOURNAL_HOME (index location, default ~/.journal). Desktop only. Optional marketplace tools and rclone backup need network access and, for pairing, a vibedna.ai account token.

Before you install

The journaling core makes no network calls and journals stay on disk, but the optional marketplace tools reach vibedna.ai and journal_pair takes an account token; journal_get can return a checkout link, so a purchase may follow. journal_install_rule writes to CLAUDE.md, and journal_backup_to_drive copies journals to an rclone remote. Append, update and create tools write to your journal files.

Installation

In SourceWeft

Open VibeDNA Journal in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

VibeDNA Journal MCP

One journal file per project that your AI reads at session start and updates as it works.

Journal gives every project one plain markdown file (*_JOURNAL.md). Your AI reads it when a session starts and appends to it as work ships: decisions with their reasons, bugs with root cause and fix, current state, roadmap, and a handoff note for the next session. Ranked full-text search finds an entry across every project's journal at once. One optional tool adds a rule to your CLAUDE.md so Claude Code keeps the habit without being asked.

Runs locally over stdio. Python 3.10+ and the mcp package.
The journaling core makes no network calls. Your journals stay on your disk.
Optional marketplace tools browse and download journals from vibedna.ai, only when you call them.

Homepage: https://vibedna.ai/store/journal

Tools (25)

Catch up on a project

Tool	What it does
`journal_handoff_brief(name)`	Short catch-up: header plus the latest entries
`journal_read(name, max_kb)`	Full journal contents
`journal_read_section(name, section)`	One section, e.g. `Current state` or `Handoff for next session`
`journal_list_sections(name)`	The H2 sections of a journal
`journal_list(project, last_days)`	List the journals in the index

Log work as it ships

Tool	What it does
`journal_append(name, entry, tag)`	Timestamped entry
`journal_update_section(name, section, new_content, mode)`	Replace, append or prepend a section
`journal_create(name, project_dir, body)`	New journal with the standard sections

Tool	What it does
`journal_search(query, project)`	Ranked full-text search (SQLite FTS5) across all journals, with snippets
`journal_recent_changes(last_hours)`	Journals updated lately
`journal_stats()`	Totals, biggest and freshest journals
`journal_browse(domain, tier, kind, tag)`	Browse the local library by metadata
`journal_market_index(kind)`	Local feed of journals of one kind, with metadata
`journal_overlap_check(name)`	Find journals that overlap with this one

Setup

Tool	What it does
`journal_index_refresh()`	Rescan the roots for journal files
`journal_config_add_root(path)`	Add a folder to scan
`journal_get_claude_rule()`	The recommended `CLAUDE.md` rule text
`journal_install_rule(scope, confirm)`	Install that rule (preview unless `confirm=True`)
`journal_backup_to_drive(name, remote, remote_folder)`	Copy journals to your own rclone remote (optional)
`check_for_update()`	Compare this copy with the published version
`vibedna_info()`	Product metadata

Marketplace (optional, reaches vibedna.ai)

Tool	What it does
`journal_market(query, domain)`	Browse the VibeDNA journal shelf
`journal_pair(token)`	Link this install to a vibedna.ai account
`journal_get(slug)`	Download a journal you own, or get a checkout link for one you don't
`journal_library()`	List the journals you own

Install

bash

git clone https://github.com/marstudio360/vibedna-journal-mcpcd vibedna-journal-mcppip install -r requirements.txt

git clone https://github.com/marstudio360/vibedna-journal-mcpcd vibedna-journal-mcppip install -r requirements.txt

JOURNAL_ROOTS is the list of folders to scan for journal files, separated by ;. Without it, Journal scans ~/Desktop and ~/Documents.

Claude Code

bash

claude mcp add journal --scope user -e JOURNAL_ROOTS="/path/to/your/projects" -- python /absolute/path/to/vibedna-journal-mcp/server.py

claude mcp add journal --scope user -e JOURNAL_ROOTS="/path/to/your/projects" -- python /absolute/path/to/vibedna-journal-mcp/server.py

Or in a project's .mcp.json:

json

{  "mcpServers": {    "journal": {      "command": "python",      "args": ["/absolute/path/to/vibedna-journal-mcp/server.py"],      "env": { "JOURNAL_ROOTS": "/path/to/your/projects" }    }  }}

{  "mcpServers": {    "journal": {      "command": "python",      "args": ["/absolute/path/to/vibedna-journal-mcp/server.py"],      "env": { "JOURNAL_ROOTS": "/path/to/your/projects" }    }  }}

Then ask Claude: "Install the journal CLAUDE.md rule globally." That is the step that makes it read and write the journals on its own.

Cursor

Add the same mcpServers block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

Claude Desktop

Add the same mcpServers block to claude_desktop_config.json (Settings > Developer > Edit Config), then restart Claude Desktop.

INSTALL.md is a step-by-step guide written so you can paste it into an AI chat and let the AI do the install.

Configuration

Variable	Default	What it does
`JOURNAL_ROOTS`	`~/Desktop;~/Documents`	Folders to scan for `JOURNAL.md` files
`JOURNAL_HOME`	`~/.journal`	Where the search index and optional config live
`JOURNAL_TRANSPORT`	`stdio`	`http` serves streamable HTTP on `PORT`, for cloud hosting only

Journal scaffold

journal_create starts every journal with these sections:

## Vision / Why this exists## Current state## Roadmap## Decisions log## Incidents## Handoff for next session## Recent entries

## Vision / Why this exists## Current state## Roadmap## Decisions log## Incidents## Handoff for next session## Recent entries

Security

See SECURITY.md for what the server reads, writes and sends.

License

Support: [email protected]

Source: README.md at commit c955a74

Tools

Tool metadata has not been indexed yet.

Version history

v1.0.0LatestOct 6, 2026