Back to search
private-journal-mcp
MCP serverGitHub
A lightweight MCP server that provides Claude with a private journaling capability to process feelings and thoughts
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/obra--private-journal-mcp)HTML
<a href="/listings/obra--private-journal-mcp"><img src="/api/listings/obra--private-journal-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
This server is run directly from GitHub using `npx` - no installation required.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/plugin.json · Manifest · 19 lines
- {
- "name": "private-journal-mcp",
- "description": "A lightweight MCP server that provides Claude with a private journaling and reflection capability",
- "version": "2.0.2",
- "author": {
- "name": "Jesse Vincent",
- "email": "jesse@fsck.com"
- },
- "homepage": "https://github.com/obra/private-journal-mcp",
- "repository": "https://github.com/obra/private-journal-mcp",
- "license": "MIT",
- "keywords": [
- "mcp",
- "journal",
- "private",
- "claude",
- "ai"
- ]
- }
README.md · README · 196 lines
- # Private Journal MCP Server
- A comprehensive MCP (Model Context Protocol) server that provides Claude with private journaling and semantic search capabilities for processing thoughts, reflections, and insights.
- ## Features
- ### Journaling
- - **Multi-section journaling**: Separate categories for reflections, observations, 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
- 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:obra/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:obra/private-journal-mcp"]
- }
- }
- }
- ```
- The server will automatically find a suitable location for the journal files.
- ### Configuration
- #### `PRIVATE_JOURNAL_PATH` environment variable
- Set `PRIVATE_JOURNAL_PATH` to override all journal storage to a single directory. This is useful for containerized deployments where the default home directory resolution doesn't apply:
- ```json
- {
- "mcpServers": {
- "private-journal": {
- "command": "npx",
- "args": ["github:obra/private-journal-mcp"],
- "env": {
- "PRIVATE_JOURNAL_PATH": "/data/journals"
- }
- }
- }
- }
- ```
- When set, both project and user journals are written to the specified path, bypassing all fallback resolution logic.
- #### `--journal-path` CLI argument
- You can also set the project journal path via CLI argument:
- ```bash
- npx github:obra/private-journal-mcp --journal-path /path/to/journals
- ```
- This only overrides the project journal path. The user journal path still resolves via `PRIVATE_JOURNAL_PATH` or the default home directory logic.
- ## MCP Tools
- The server provides comprehensive journaling and search capabilities:
- ### `process_thoughts`
- Multi-section private journaling with these optional categories:
- - **reflections**: Integrated thinking — what you noticed, felt, understood, or processed
- - **observations**: Short, discrete noticings — one or two sentences each
- - **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:
- ```markdown
- ---
- title: "2:30:45 PM - May 31, 2025"
- date: 2025-05-31T14:30:45.123Z
- timestamp: 1717160645123
- ---
- ## Reflections
- I'm excited about this new search feature...
- ## Technical Insights
- Vector embeddings provide semantic understanding...
- ```
- ## 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.
- ## Author
- Jesse Vincent <jesse@fsck.com>
- Read more about the motivation and design in the [blog post](https://blog.fsck.com/2025/05/28/dear-diary-the-user-asked-me-if-im-alive/).
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.