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)
- Install uv (if not already installed):
curl -LsSf https://astral.sh/uv/install.sh | sh
- Clone and install the plugin:
git clone https://github.com/chrismbryant/claude-journal-mcp.git
cd claude-journal-mcp
uv sync
- 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:
- Install dependencies:
# With uv (recommended - faster)
uv sync
# Or with pip
pip install -e .
- 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
