Skip to content
Back to search

private-journal-mcp

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/obra--private-journal-mcp/badge.svg)](/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
  1. {
  2. "name": "private-journal-mcp",
  3. "description": "A lightweight MCP server that provides Claude with a private journaling and reflection capability",
  4. "version": "2.0.2",
  5. "author": {
  6. "name": "Jesse Vincent",
  7. "email": "jesse@fsck.com"
  8. },
  9. "homepage": "https://github.com/obra/private-journal-mcp",
  10. "repository": "https://github.com/obra/private-journal-mcp",
  11. "license": "MIT",
  12. "keywords": [
  13. "mcp",
  14. "journal",
  15. "private",
  16. "claude",
  17. "ai"
  18. ]
  19. }
README.md · README · 196 lines
  1. # Private Journal MCP Server
  2. A comprehensive MCP (Model Context Protocol) server that provides Claude with private journaling and semantic search capabilities for processing thoughts, reflections, and insights.
  3. ## Features
  4. ### Journaling
  5. - **Multi-section journaling**: Separate categories for reflections, observations, project notes, user context, technical insights, and world knowledge
  6. - **Dual storage**: Project notes stay with projects, personal thoughts in user home directory
  7. - **Timestamped entries**: Each entry automatically dated with microsecond precision
  8. - **YAML frontmatter**: Structured metadata for each entry
  9. ### Search & Discovery
  10. - **Semantic search**: Natural language queries using local AI embeddings
  11. - **Vector similarity**: Find conceptually related entries, not just keyword matches
  12. - **Local AI processing**: Uses @xenova/transformers - no external API calls required
  13. - **Automatic indexing**: Embeddings generated for all entries on startup and ongoing
  14. ### Privacy & Performance
  15. - **Completely private**: All processing happens locally, no data leaves your machine
  16. - **Fast operation**: Optimized file structure and in-memory similarity calculations
  17. - **Robust fallbacks**: Intelligent path resolution across platforms
  18. ## Installation
  19. This server is run directly from GitHub using `npx` - no installation required.
  20. ## MCP Configuration
  21. #### Claude Code (One-liner)
  22. ```bash
  23. claude mcp add-json private-journal '{"type":"stdio","command":"npx","args":["github:obra/private-journal-mcp"]}' -s user
  24. ```
  25. #### Manual Configuration
  26. Add to your MCP settings (e.g., Claude Desktop configuration):
  27. ```json
  28. {
  29. "mcpServers": {
  30. "private-journal": {
  31. "command": "npx",
  32. "args": ["github:obra/private-journal-mcp"]
  33. }
  34. }
  35. }
  36. ```
  37. The server will automatically find a suitable location for the journal files.
  38. ### Configuration
  39. #### `PRIVATE_JOURNAL_PATH` environment variable
  40. 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:
  41. ```json
  42. {
  43. "mcpServers": {
  44. "private-journal": {
  45. "command": "npx",
  46. "args": ["github:obra/private-journal-mcp"],
  47. "env": {
  48. "PRIVATE_JOURNAL_PATH": "/data/journals"
  49. }
  50. }
  51. }
  52. }
  53. ```
  54. When set, both project and user journals are written to the specified path, bypassing all fallback resolution logic.
  55. #### `--journal-path` CLI argument
  56. You can also set the project journal path via CLI argument:
  57. ```bash
  58. npx github:obra/private-journal-mcp --journal-path /path/to/journals
  59. ```
  60. This only overrides the project journal path. The user journal path still resolves via `PRIVATE_JOURNAL_PATH` or the default home directory logic.
  61. ## MCP Tools
  62. The server provides comprehensive journaling and search capabilities:
  63. ### `process_thoughts`
  64. Multi-section private journaling with these optional categories:
  65. - **reflections**: Integrated thinking — what you noticed, felt, understood, or processed
  66. - **observations**: Short, discrete noticings — one or two sentences each
  67. - **project_notes**: Technical insights specific to current project
  68. - **user_context**: Notes about collaborating with humans
  69. - **technical_insights**: General software engineering learnings
  70. - **world_knowledge**: Domain knowledge and interesting discoveries
  71. ### `search_journal`
  72. Semantic search across all journal entries:
  73. - **query** (required): Natural language search query
  74. - **limit**: Maximum results (default: 10)
  75. - **type**: Search scope - 'project', 'user', or 'both' (default: 'both')
  76. - **sections**: Filter by specific categories
  77. ### `read_journal_entry`
  78. Read full content of specific entries:
  79. - **path** (required): File path from search results
  80. ### `list_recent_entries`
  81. Browse recent entries chronologically:
  82. - **limit**: Maximum entries (default: 10)
  83. - **type**: Entry scope - 'project', 'user', or 'both' (default: 'both')
  84. - **days**: Days back to search (default: 30)
  85. ## File Structure
  86. ### Project Journal (per project)
  87. ```
  88. .private-journal/
  89. ├── 2025-05-31/
  90. │ ├── 14-30-45-123456.md # Project notes entry
  91. │ ├── 14-30-45-123456.embedding # Search index
  92. │ └── ...
  93. ```
  94. ### User Journal (global)
  95. ```
  96. ~/.private-journal/
  97. ├── 2025-05-31/
  98. │ ├── 14-32-15-789012.md # Personal thoughts entry
  99. │ ├── 14-32-15-789012.embedding # Search index
  100. │ └── ...
  101. ```
  102. ### Entry Format
  103. Each markdown file contains YAML frontmatter and structured sections:
  104. ```markdown
  105. ---
  106. title: "2:30:45 PM - May 31, 2025"
  107. date: 2025-05-31T14:30:45.123Z
  108. timestamp: 1717160645123
  109. ---
  110. ## Reflections
  111. I'm excited about this new search feature...
  112. ## Technical Insights
  113. Vector embeddings provide semantic understanding...
  114. ```
  115. ## Development
  116. ### Building
  117. ```bash
  118. npm run build
  119. ```
  120. ### Testing
  121. ```bash
  122. npm test
  123. ```
  124. ### Development Mode
  125. ```bash
  126. npm run dev
  127. ```
  128. ### Improving Claude's Performance
  129. To help Claude learn and improve over time, consider adding journal usage guidance to your `~/.claude/CLAUDE.md` file:
  130. ```markdown
  131. ## Learning and Memory Management
  132. - YOU MUST use the journal tool frequently to capture technical insights, failed approaches, and user preferences
  133. - Before starting complex tasks, search the journal for relevant past experiences and lessons learned
  134. - Document architectural decisions and their outcomes for future reference
  135. - Track patterns in user feedback to improve collaboration over time
  136. - 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
  137. ```
  138. This enables Claude to build persistent memory across conversations, leading to better engineering decisions and collaboration patterns.
  139. ## Author
  140. Jesse Vincent <jesse@fsck.com>
  141. 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/).
  142. ## License
  143. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.