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 [email protected]

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

License

MIT