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

Claude recognizes important moments and captures them without being asked.

context-recovery

Restores your working context from the journal:

• Automatically after /clear command
• When you ask "what was I working on?"
• At session start to resume past work

Brings back project context, recent changes, and next steps.

find-related-work

Searches for past work related to current tasks:

• Before implementing similar features
• When making architecture decisions
• During troubleshooting
• When you explicitly ask about past work

Helps avoid reinventing solutions and maintains consistency.

Agent

The plugin includes an optional Journal Assistant agent.

When you first use journal features, Claude will prompt:

Would you like to enable the Journal Assistant agent?

The agent helps by:
- Automatically capturing significant work
- Recovering context after /clear
- Finding related past work
- Suggesting when to journal

Enable now?

The agent is opt-in but recommended for the best experience.

Available MCP Tools

Write Operations

journal_add - Manually add entry

Add a journal entry:
- title: "Implemented auth system"
- description: "Built OAuth2 flow with JWT tokens"
- project: "my-app"
- tags: ["auth", "backend"]

journal_auto_capture - Auto-save progress

Automatically called by hooks or when Claude detects significant work

Read Operations

journal_search - Advanced text search

Search examples:
- "authentication" - Keyword search
- "42" or "id:42" - Find entry by ID
- "tag:bugfix" or "#bugfix" - Filter by tag
- "\"user authentication\"" - Exact phrase match
- "last week authentication" - Date range + keyword
- "tag:bugfix \"login error\" performance" - Combined filters

journal_time_query - Time-based search

What did I work on last week?
What did I do in January?
When did I implement feature X?

Supported time expressions:

• today, yesterday
• last week, last month, last year
• last 3 days, last 2 weeks
• this week, this month, this year
• january, january 2024
• 2024-01-15 (ISO date)

journal_list_recent - Recent entries

Show me the last 10 entries
Show recent work on project X

journal_list_projects - All projects

List all projects with entry counts

journal_stats - Statistics

Show journal statistics

Management Operations

journal_delete - Delete by ID

Delete entry 42

journal_delete_by_project - Delete all for project

Delete all entries for project "old-app"

journal_import - Import from file

Import from ~/other-machine/journal.db

journal_export - Export to file

Export to ~/backup/journal_2024.db

Usage Examples

Manual Journaling

You: Remember that we implemented rate limiting today

Claude: [Calls journal_add]
✅ Journal entry created (ID: 42)

Time-Based Queries

You: What did I work on last month?

Claude: [Calls journal_time_query with "last month"]
Shows all entries from last month

You: When did I add the auth system?

Claude: [Calls journal_time_query with search for "auth"]
Shows entries matching "auth" with dates

Context Recovery

You: /clear
You: What was I working on?

Claude: [Calls journal_list_recent]
Shows recent work to restore context

Project Organization

You: Show me everything I've done on my-app

Claude: [Calls journal_search with project filter]
Lists all my-app entries

Sharing Between Machines

Machine 1:

You: Export my journal

Claude: [Calls journal_export]
✅ Exported journal to journal_export_20241105.db

Machine 2:

You: Import journal from ~/Downloads/journal_export_20241105.db

Claude: [Calls journal_import]
✅ Imported 150 new entries

Auto-Capture Hook

The plugin includes an auto-capture hook that runs automatically when installed.

How it works:

• Monitors conversation activity
• Triggers every 30 minutes or when 3+ messages are sent (whichever comes first)
• Automatically creates journal entries via CLI
• Maintains state in ~/.claude/journal-capture-state.json
• Auto-enabled on plugin installation

Configuration:

The hook is defined in hooks/hooks.json and automatically enabled:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/journal-auto-capture.js"
          }
        ]
      }
    ]
  }
}

Behavior:

• Runs on every user prompt submission with visible logging (📊 Journal auto-capture hook running)
• Low overhead (checks timestamp and counter)
• When threshold reached (30 min or 3+ messages), prompts Claude to analyze the session
• Claude must respond - either creates a journal entry OR explains why not capturing
• Claude reviews the conversation and creates a meaningful journal entry with:
  • Goal (what we were trying to do)
  • Accomplishments (what was done)
  • Relevant tags and project information
• Claude can also proactively use journal tools to capture significant work at any time based on conversation context

CLI Interface

The plugin includes a minimal CLI that provides information about available MCP tools:

python -m claude_journal.cli
# Or: claude-journal

All journal operations are performed through the MCP server, not via CLI commands. The auto-capture hook triggers Claude to create entries using the journal_auto_capture MCP tool.

Database Schema

CREATE TABLE journal_entries (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    project TEXT,
    title TEXT NOT NULL,
    description TEXT NOT NULL,
    tags TEXT
);

CREATE INDEX idx_created_at ON journal_entries(created_at);
CREATE INDEX idx_project ON journal_entries(project);

Development

Running Tests

pytest tests/

Contributing Changes

Important: The main branch is protected and requires pull requests.

# Create a feature branch
git checkout -b your-feature-name

# Make your changes and commit
git add .
git commit -m "Description of changes"

# Push your branch
git push -u origin your-feature-name

# Create a pull request
gh pr create --title "Your PR title" --body "Description"

# After CI passes, merge the PR
gh pr merge <PR-number> --squash --delete-branch

Do not push directly to main - all changes must go through pull requests.

Project Structure

claude-journal-mcp/
├── .claude-plugin/
│   └── plugin.json         # Plugin manifest
├── agents/
│   └── journal-assistant.md # Journal assistant agent
├── commands/
│   ├── journal-add.md      # /journal-add command
│   ├── journal-export.md   # /journal-export command
│   ├── journal-recent.md   # /journal-recent command
│   ├── journal-search.md   # /journal-search command
│   ├── journal-stats.md    # /journal-stats command
│   └── journal-time.md     # /journal-time command
├── hooks/
│   ├── hooks.json          # Hook configuration
│   └── journal-auto-capture.js # Auto-capture hook
├── skills/
│   ├── journal-capture/
│   │   └── SKILL.md        # Proactive capture skill
│   ├── context-recovery/
│   │   └── SKILL.md        # Context recovery skill
│   └── find-related-work/
│       └── SKILL.md        # Related work finder skill
├── src/
│   └── claude_journal/
│       ├── __init__.py
│       ├── server.py       # MCP server
│       ├── database.py     # SQLite operations
│       └── time_parser.py  # Natural language time parsing
├── tests/
├── .mcp.json               # MCP server config
├── pyproject.toml
├── LICENSE
└── README.md

Why Not Embeddings?

Embeddings/Semantic Search:

• Pros: Find by meaning, not exact words
• Cons: 4GB+ dependencies, requires PyTorch/CUDA

This Approach (SQLite Full-Text):

• Pros: Lightweight (~10MB), instant queries, no ML deps
• Cons: Must use similar keywords to find entries

Trade-off: For a journal, exact keyword matching is usually sufficient. You remember rough terms like "auth", "bug", "deploy" better than abstract concepts.

License

MIT

Contributing

Pull requests welcome! Please ensure:

• Tests pass
• Code follows existing style
• Update README for new features