# 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](https://github.com/obra/private-journal-mcp) by Jesse Vincent. Read the original motivation and design in his [blog post](https://blog.fsck.com/2025/05/28/dear-diary-the-user-asked-me-if-im-alive/). 

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)
```bash
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):

```json
{
  "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:

```markdown
---
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

```bash
npm run build
```

### Testing

```bash
npm test
```

### Development Mode

```bash
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:

```markdown
## 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](https://github.com/obra) — [obra/private-journal-mcp](https://github.com/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.