Private Journal MCP Server

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

Forked from obra/private-journal-mcp by Jesse Vincent. Read the original motivation and design in his blog post.

This fork restructures the journaling categories to focus on project-specific learning and drops the feelings/diary framing in favor of a technical notes approach.

Why project specificity

I often work on very different projects with different requirements and approaches. I don't want my agent to read about super critical stuff if we're working on an experiment. Hence, the changes to this server to reflect this need.

I also tried to focus the journal more on the collaboration and on the technical aspects of the job.

Features

Journaling

• Project-scoped journaling: All entries are written to the current project's .private-journal/ directory
• Structured categories: Separate sections for project notes, user context, technical insights, world knowledge, and WIP scraps
• 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
• Cross-journal search: Search covers both the project journal and ~/.private-journal/ (for compatibility with entries written by other tools)

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

This server is run directly from GitHub using npx - no installation required.

MCP Configuration

Claude Code (One-liner)

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

Manual Configuration

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

{
  "mcpServers": {
    "private-journal": {
      "command": "npx",
      "args": ["github:lock3r/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

Project-scoped journaling with these optional categories:

• project_notes: Technical insights specific to the current project
• user_context: Notes about collaborating with the human on this project
• technical_insights: General software engineering learnings
• world_knowledge: Domain knowledge and interesting discoveries
• wip_stuff: Work-in-progress scratchpad for loose ends and half-baked ideas

All entries are written to .private-journal/ in the current project directory.

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

Note: search covers both the project journal and ~/.private-journal/ so entries written by other tools or earlier versions are still findable.

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          # Journal entry
│   ├── 14-30-45-123456.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
---

## Project Notes

Discovered that the embedding model needs warm-up time on first run...

## WIP Stuff

Still need to investigate why the path resolution falls back to /tmp on WSL...

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.

Credits

Original project by Jesse Vincent — obra/private-journal-mcp.

License

GPL-3.0

The GPL-3.0 license applies to the source code of this MCP server only. It does not extend to the journal entries or any other content written by or through this tool — that content belongs solely to its authors.