private-journal-mcp

An MCP server that stores journal entries in local files and searches them semantically with multilingual embeddings. Search and embedding inference run locally; the embedding model is downloaded and cached once on first use. Optionally, entries can be auto-synced to a Git remote.

Tools

• write_journal
  • Takes one or more of the six sections (reflections, observations, project_notes, user_context, technical_insights, world_knowledge) and stores an entry.
• search_journal
  • Performs semantic search with query.
  • Optional args: limit, sections
• read_journal
  • Reads a full individual Markdown entry by path.
• list_journal
  • Lists recent entries.
  • Optional args: limit, days

Storage Locations

Journal data

Priority order:

1. PRIVATE_JOURNAL_PATH
2. $XDG_DATA_HOME/private-journal
3. ~/.local/share/private-journal

Model cache

Priority order:

1. $XDG_CACHE_HOME/private-journal/models
2. ~/.cache/private-journal/models

The default embedding model is Xenova/multilingual-e5-small.

Install / Build

npm install
npm run build

Run locally:

node dist/index.js

The sync subcommand exits as a no-op when no Git remote is configured.

node dist/index.js sync

Install as a Plugin (recommended)

This repo is a plugin for both Claude Code (.claude-plugin/plugin.json) and Codex (.codex-plugin/plugin.json). Installing it registers the MCP server and the SessionStart sync hook in one step — no manual settings.json/config.toml edits, no absolute paths. The bundled hooks/hooks.json and .mcp.json resolve the plugin's own install path via ${CLAUDE_PLUGIN_ROOT} (Claude Code) / ${PLUGIN_ROOT} (Codex).

Build first so dist/ exists, then install:

npm install && npm run build

Claude Code:

/plugin install /absolute/path/to/private-journal-mcp

Codex:

codex plugin install /absolute/path/to/private-journal-mcp

Manual MCP registration (without the plugin)

claude mcp add private-journal -- node /absolute/path/to/private-journal-mcp/dist/index.js

Git Sync (optional)

Git sync is enabled only when PRIVATE_JOURNAL_GIT_REMOTE is set.

export PRIVATE_JOURNAL_GIT_REMOTE="git@github.com:youruser/my-journal.git"

Recommended prerequisites:

• You must already be authenticated for that remote via gh auth login or equivalent Git credentials.

Behavior:

• Right after a write_journal save, it attempts commit + pull --rebase + push on a best-effort basis.
• node dist/index.js sync handles pull and pushing any pending commits before a session starts.

SessionStart sync hook

When installed as a plugin, the SessionStart sync hook is registered automatically (see hooks/hooks.json) — nothing to configure. It exits as a no-op unless PRIVATE_JOURNAL_GIT_REMOTE is set.

To wire it up manually instead, add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/private-journal-mcp/dist/index.js sync"
          }
        ]
      }
    ]
  }
}

Conflict Handling

• Distinct entries mostly coexist automatically because filenames include a microsecond suffix.
• When two entries share a filename, the one with the larger frontmatter timestamp wins.
• If the timestamp is identical, the local version takes precedence.
• The .embedding file may be regenerated based on the adopted Markdown.