private-journal-mcp

Private Journal MCP Server

A comprehensive MCP (Model Context Protocol) server that provides Claude with private journaling and semantic search capabilities for processing thoughts, feelings, and insights.

Features

Journaling

• Multi-section journaling: Separate categories for feelings, project notes, user context, technical insights, and world knowledge
• Dual storage: Project notes stay with projects, personal thoughts in user home directory
• Timestamped entries: Each entry automatically dated with microsecond precision
• YAML frontmatter: Structured metadata for each entry

Search & Discovery

• Semantic search: Natural language queries using local AI embeddings
• Vector similarity: Find conceptually related entries, not just keyword matches
• Local AI processing: Uses @xenova/transformers - no external API calls required
• Automatic indexing: Embeddings generated for all entries on startup and ongoing

Privacy & Performance

• Completely private: All processing happens locally, no data leaves your machine
• Fast operation: Optimized file structure and in-memory similarity calculations
• Robust fallbacks: Intelligent path resolution across platforms

Installation

npm install -g private-journal-mcp

Or install locally:

npm install private-journal-mcp

Usage

Basic Usage

private-journal-mcp

This creates journal entries in .private-journal/ in the current working directory.

Custom Journal Path

private-journal-mcp --journal-path /path/to/my/journal

MCP Configuration

Claude Code (One-liner)

claude mcp add-json private-journal '{"type":"stdio","command":"npx","args":["github:obra/private-journal-mcp"]}' -s user

Manual Configuration

Add to your MCP settings (e.g., Claude Desktop configuration):

{
  "mcpServers": {
    "private-journal": {
      "command": "npx",
      "args": ["github:obra/private-journal-mcp"]
    }
  }
}

The server will automatically find a suitable location for the journal files.

MCP Tools

The server provides comprehensive journaling and search capabilities:

process_thoughts

Multi-section private journaling with these optional categories:

• feelings: Private emotional processing space
• project_notes: Technical insights specific to current project
• user_context: Notes about collaborating with humans
• technical_insights: General software engineering learnings
• world_knowledge: Domain knowledge and interesting discoveries

search_journal

Semantic search across all journal entries:

• query (required): Natural language search query
• limit: Maximum results (default: 10)
• type: Search scope - 'project', 'user', or 'both' (default: 'both')
• sections: Filter by specific categories

read_journal_entry

Read full content of specific entries:

• path (required): File path from search results

list_recent_entries

Browse recent entries chronologically:

• limit: Maximum entries (default: 10)
• type: Entry scope - 'project', 'user', or 'both' (default: 'both')
• days: Days back to search (default: 30)

File Structure

Project Journal (per project)

.private-journal/
├── 2025-05-31/
│   ├── 14-30-45-123456.md          # Project notes entry
│   ├── 14-30-45-123456.embedding   # Search index
│   └── ...

User Journal (global)

~/.private-journal/
├── 2025-05-31/
│   ├── 14-32-15-789012.md          # Personal thoughts entry
│   ├── 14-32-15-789012.embedding   # Search index
│   └── ...

Entry Format

Each markdown file contains YAML frontmatter and structured sections:

---
title: "2:30:45 PM - May 31, 2025"
date: 2025-05-31T14:30:45.123Z
timestamp: 1717160645123
---

## Feelings

I'm excited about this new search feature...

## Technical Insights

Vector embeddings provide semantic understanding...

Development

Building

npm run build

Testing

npm test

Development Mode

npm run dev

Improving Claude's Performance

To help Claude learn and improve over time, consider adding journal usage guidance to your ~/.claude/CLAUDE.md file:

## Learning and Memory Management

- YOU MUST use the journal tool frequently to capture technical insights, failed approaches, and user preferences
- Before starting complex tasks, search the journal for relevant past experiences and lessons learned
- Document architectural decisions and their outcomes for future reference
- Track patterns in user feedback to improve collaboration over time
- When you notice something that should be fixed but is unrelated to your current task, document it in your journal rather than fixing it immediately

This enables Claude to build persistent memory across conversations, leading to better engineering decisions and collaboration patterns.

Author

Jesse Vincent

Read more about the motivation and design in the blog post.

License

MIT