claude-journal

Claude Journal is a lightweight SQLite-backed journal and memory system designed for Claude Code plugins. It provides 6 slash commands for quick journaling, powerful search capabilities, time-based queries, and project organization, along with 3 proactive skills and an optional assistant agent. Use it to capture work notes, index tasks by project, search through past entries with advanced filters, and quickly restore context before resuming work. The server exposes tools for writing and reading journal entries, time-aware queries, and export/import of journals for syncing across machines. This makes it ideal for personal knowledge management and code-related journaling within Claude Code workflows.

You can interact with the following MCP tools: journal_add to manually create an entry, journal_auto_capture to save progress automatically, journal_search for text-based search with filters like tags, IDs, and date ranges, journal_time_query for natural language time searches, journal_list_recent to retrieve recent entries, journal_list_projects to see projects with counts, and journal_stats to view usage statistics. There is also support for managing entries via journal_delete and journal_export/import for backups or transfers. The system uses optional auto-capture hooks every 30 minutes or after a set number of messages and can prompt to enable the Journal Assistant agent for enhanced workflows.

Prerequisites

• Python 3.12 or higher
• uv (recommended) or pip

Option A: Quick setup with uv (recommended)

1. Install uv if you don’t have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install and run the MCP server locally:

# Clone the repository (or download the MCP server package)
git clone https://github.com/chrismbryant/claude-journal-mcp.git
cd claude-journal-mcp
# Start uv sync if required by your setup (example depending on repo structure)
uv sync

3. Add the MCP server to Claude’s config (example shown in the repo)

{
  "mcpServers": {
    "journal": {
      "command": "python",
      "args": ["-m", "claude_journal.server"]
    }
  }
}

Option B: Install as a Python package (editable install)

1. Install dependencies and install the MCP server:

pip install -e .

2. Add to your MCP configuration (e.g., ~/.claude/config.json or your project’s .mcp.json):

{
  "mcpServers": {
    "journal": {
      "command": "python",
      "args": ["-m", "claude_journal.server"]
    }
  }
}

Notes

• By default the database is at ~/.claude/journal.db. You can override with JOURNAL_DB_PATH as an environment variable:

export JOURNAL_DB_PATH="/path/to/your/journal.db"

• The plugin supports auto-capture, 6 slash commands, and optional an agent for enhanced workflows once enabled.

Tips and caveats:

• Ensure Python 3.12+ is used to meet the server requirements.
• If you don’t enable the agent, the journal features still work with all MCP tools available.
• The Journal assistant agent is opt-in; enabling it can provide proactive capture and context recovery features.
• Adjust JOURNAL_DB_PATH if you want to keep your journal outside the default location or on a different drive.
• If you run into issues, verify that the MCP server is correctly registered in your Claude configuration and that the Python module claude_journal.server is importable from your environment.