claude-journal-dev

Claude Journal - Claude Code Plugin

A lightweight journal/memory system for Claude Code with no ML dependencies. Uses simple SQLite for fast, local storage.

This is a full-featured Claude Code plugin with slash commands, skills, an agent, and auto-capture hooks.

Features

• ✅ Lightweight: No embeddings, no ML models, just SQLite
• ✅ Fast: Sub-millisecond queries on local database
• ✅ Smart Search: Advanced search with ID lookup, tag filtering, exact phrases, date ranges, and keywords
• ✅ Time Queries: Natural language like "last month", "yesterday"
• ✅ Project Tracking: Organize entries by repository/project
• ✅ Auto-Capture: Automatic periodic journaling via hooks
• ✅ Import/Export: Share journal between instances
• ✅ Flexible Tags: Organize with custom tags
• ✅ Slash Commands: 6 user-friendly commands for common operations
• ✅ Skills: 3 proactive AI skills for context recovery and smart capture
• ✅ Agent: Optional journal assistant for enhanced workflows

Requirements

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

Installation

Quick Start (Recommended)

1. Install uv (if not already installed):

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

2. Clone and install the plugin:

git clone https://github.com/chrismbryant/claude-journal-mcp.git
cd claude-journal-mcp
uv sync

3. Install as a Claude Code plugin:

# Option A: Direct install from current directory
claude /plugin install .

# Option B: Add marketplace first, then install
claude /marketplace add ./marketplace.json
claude /plugin install claude-journal

This automatically:

• Configures the MCP server (provides all 11 journal tools)
• Registers 6 slash commands (/journal-add, /journal-search, etc.)
• Enables 3 proactive skills (journal-capture, context-recovery, find-related-work)
• Sets up auto-capture hooks (triggers every 30 min or 3 messages)
• Prompts you to enable the journal-assistant agent (opt-in)

Alternative: Manual MCP Server Installation

If you prefer to install just the MCP server without the plugin features:

1. Install dependencies:

# With uv (recommended - faster)
uv sync

# Or with pip
pip install -e .

2. Add to ~/.claude/config.json or your project's .mcp.json:

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

Note: Manual installation only provides MCP tools. You won't get slash commands, skills, or the agent without installing as a plugin.

Database Location

Default: ~/.claude/journal.db

Override with environment variable:

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

Slash Commands

The plugin provides 6 slash commands for easy interaction:

/journal-add

Interactively create a new journal entry. Claude guides you through:

• Title
• Description
• Project (auto-detected from git)
• Tags (suggested based on content)

You: /journal-add
Claude: Let's create a journal entry. What's the title?
You: Implemented rate limiting
Claude: Great! Tell me more about it...

/journal-search

Search entries with advanced query syntax. Supports ID lookup, tag filtering, exact phrases, date ranges, and keywords.

You: /journal-search
Claude: What would you like to search for?
You: authentication
Claude: [Shows all auth-related entries]

Advanced search syntax:

• ID search: 42 or id:42 - Find specific entry by ID
• Tag filter: tag:bugfix or #bugfix - Filter by tag
• Exact phrase: "user authentication" - Match exact phrase
• Date range: last week authentication - Combine time with search
• Combined: tag:bugfix "login error" last month - Mix multiple filters

/journal-recent

Show recent entries to restore context (especially useful after /clear).

You: /clear
You: /journal-recent
Claude: Here's what you were working on:
[Lists recent entries with summaries]

/journal-time

Query entries using natural language time expressions.

You: /journal-time
You: last week
Claude: [Shows all entries from last week]

Supports: "yesterday", "last month", "january 2024", "last 3 days", etc.

/journal-stats

View statistics about your journal usage.

You: /journal-stats
Claude:
📊 247 entries across 5 projects
📅 Jan 15 - Jul 20, 2024 (6 months)
Most active: my-app (89 entries)

/journal-export

Export your journal for backup or sharing between machines.

You: /journal-export
Claude: Where should I save the export?
You: ~/backups/journal_2024.db
Claude: ✅ Exported to ~/backups/journal_2024.db

Skills

The plugin includes 3 proactive skills that Claude uses automatically:

journal-capture

Automatically captures significant work when you:

• Complete features or tasks
• Fix complex bugs
• Make technical decisions
• Solve challenging problems