DOCSEARCHbyAlgolia
Submit Docs

Private Journal MCP Server

repository·main·Indexed 19 days ago

https://github.com/obra/private-journal-mcp

A Model Context Protocol (MCP) server version 2.0.1 that provides Claude with private journaling and reflection capabilities. It enables structured thought processing and semantic search using local AI embeddings, ensuring data remains on the user's machine. Features include tools for processing thoughts and feelings, listing recent entries, and reading specific journal entries across project-local and user-global storage paths.

Tokens
10.8K
Snippets
36
Records
50
Agent score
64%

What's inside private-journal-mcp

  1. Understand the Journal file structure and entry format

    main

    The server uses two distinct storage locations:

    • Project Journal: Stored in .private-journal/ within the current project directory.
    • User Journal: Stored in ~/.private-journal/ in the user's home directory.

    Each entry is a Markdown file containing YAML frontmatter and structured sections.

    Entry Format Example:

    ---
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...

  2. Understand the journal file structure and format

    main

    The server organizes journal entries in a hierarchical directory structure based on dates, with individual files named by precise timestamps.

    Directory Structure

    Entries are stored in daily subdirectories:

    [journal-path]/
├── YYYY-MM-DD/
│   ├── HH-MM-SS-μμμμμμ.md
│   └── ...
└── ...

    Filename Format

    Files use the pattern HH-MM-SS-μμμμμμ.md (e.g., 14-30-45-123456.md) to ensure uniqueness via microsecond precision.

    File Content Format

    Each entry is a Markdown file with a header containing the timestamp:

    # HH:MM:SS AM/PM - Month Day, Year

[diary entry content]

  3. Understand storage routing for journal entries

    main

    The process_thoughts tool automatically routes content to different storage locations based on the field provided:

    Project-Local Journal (.private-journal/)

    • project_notes only.

    User-Global Journal (~/.private-journal/)

    • reflections
    • observations
    • user_context
    • technical_insights
    • world_knowledge

    If you provide both project_notes and reflections, the server will create/update two separate files: one in the project directory and one in the user's global directory.

  4. How the `process_thoughts` tool works

    main

    The process_thoughts MCP tool is the primary interface for writing timestamped journal entries. It accepts an object containing optional named fields. Each field is rendered as a specific ## Section in a markdown file.

    Routing Logic:

    • Project-local: Fields like project_notes are written to a .private-journal/ directory in the current working directory.
    • User-global: All other fields (e.g., feelings, observations, user_context, technical_insights, world_knowledge) are routed to the user's global journal located at ~/.private-journal/.

    Every write operation produces both a .md file for human reading and an .embedding file for semantic search.

  5. Understand the journal file structure

    main

    The server organizes journal entries using a date-based directory structure. Each entry is written as a markdown file with microsecond precision in its timestamp.

    Directory Pattern: .private-journal/YYYY-MM-DD/

    Entry Logic:

    • Entries are stored as markdown files.
    • Files include proper headers and timestamps.
    • The system ensures directory existence for the specific date before writing.

  6. Verify `process_thoughts` schema and field routing

    main

    To manually verify that the process_thoughts tool correctly accepts new fields and rejects old ones (like the deprecated feelings field), you can use a verification script.

    When using JournalManager.writeThoughts, the following routing occurs:

    • observations and reflections are stored in the user journal.
    • project_notes, user_context, technical_insights, and world_knowledge are stored in the project journal.

    If an unrecognized field like feelings is passed, the journal layer will silently drop it.

    # Build the project
npm run build

# Run a verification script (example logic)
# 1. Initialize JournalManager with project and user paths
# 2. Call writeThoughts with valid fields (reflections, observations, etc.)
# 3. Verify markdown headers in the resulting files match the expected order:
#    ## Reflections
#    ## Observations
#    ## Project Notes
#    ...

  9. Add the `observations` field to `process_thoughts`

    main

    To implement the observations field (intended for short, atomic noticings), you must update the type definitions, the journal logic, and the MCP server schema to ensure the field is not silently dropped during structural comparison.

    Implementation Steps:

    1. Update src/types.ts: Add observations?: string; to the ProcessThoughtsRequest interface.
    2. Update src/journal.ts:
      • Add observations?: string; to the three inline type declarations in writeThoughts, writeThoughtsToLocation, and formatThoughts.
      • Update the userThoughts object in writeThoughts to include the new field.
      • Update formatThoughts to emit the ## Observations section.
    3. Update src/server.ts:
      • Add the observations property to the inputSchema.properties in the tool advertisement.
      • Map args.observations to the thoughts object in the request handler.
    4. Verify: Run npm test and npm run build to ensure type safety and functional correctness.
    npm test
npm run build

  10. Configure the Private Journal MCP Server manually

    main

    To manually add the server to your MCP settings (such as Claude Desktop configuration), use the following JSON structure:

    {
  "mcpServers": {
    "private-journal": {
      "command": "npx",
      "args": ["github:obra/private-journal-mcp"]
    }
  }
}

  11. Improve Claude's performance with journal guidance

    main

    To ensure Claude uses the journal effectively for persistent memory, add usage instructions to your ~/.claude/CLAUDE.md file. This encourages Claude to capture insights, search for past experiences before starting tasks, and document architectural decisions.

    Example CLAUDE.md snippet:

    ## 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

  12. Install the Private Journal MCP Server

    main

    The server can be run directly from GitHub using npx without a manual installation process. You can add it to Claude Code using a one-liner or configure it manually in your MCP settings.

    # Claude Code one-liner
claude mcp add-json private-journal '{"type":"stdio","command":"npx","args":["github:obra/private-journal-mcp"]}' -s user