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
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, yesterdaylast week, last month, last yearlast 3 days, last 2 weeksthis week, this month, this yearjanuary, january 20242024-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
