← All skills 2389 Research · Agent Skills
Strategy & Reflection · MCP SERVER

journal

v1.0.0

A lightweight MCP server that provides Claude with a private journaling capability to process feelings and thoughts

#journal #journaling #thoughts #feelings #processing #private
Install — Claude Code
/plugin install journal@2389-research
★ Star on GitHub · 9

Private Journal MCP Server

![Test Coverage](https://github.com/2389-research/journal-mcp/actions/workflows/coverage.yml)
![Coverage](https://github.com/2389-research/journal-mcp/actions)

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

Features

Journaling

Search & Discovery

Privacy & Performance

Tech Stack

Core Technologies

AI & Search

Development & Quality

Storage & Architecture

For detailed architectural decisions, see ARCHITECTURE.md.

Installation

npm install -g private-journal-mcp

Or install locally:

npm install private-journal-mcp

Usage

Basic Usage

private-journal-mcp

This creates journal entries in .private-journal/ in the current working directory.

Custom Journal Path

private-journal-mcp --journal-path /path/to/my/journal

Embedding Model Configuration

You can customize the AI model used for generating semantic embeddings:

export JOURNAL_EMBEDDING_MODEL="Xenova/all-distilroberta-v1"

Available Models:

The embedding model affects:

Remote Server Integration

To enable optional remote posting of journal entries to a team server, set these environment variables:

export REMOTE_JOURNAL_SERVER_URL="https://api.yourteam.com"
export REMOTE_JOURNAL_TEAMID="your-team-id"
export REMOTE_JOURNAL_APIKEY="your-api-key"

When configured, journal entries will be posted to your remote server in addition to being saved locally. Local journaling always takes priority - if the remote posting fails, the local entry is still saved.

#### Remote-Only Mode

For teams using a backend server as the single source of truth, enable remote-only mode to skip local file storage entirely:

export REMOTE_JOURNAL_ONLY="true"

In remote-only mode:

#### Remote Payload Format

The server sends JSON payloads with this structure:

For simple entries:

{
  "team_id": "your-team-id",
  "timestamp": 1717160645123,
  "content": "Journal entry text",
  "embedding": [0.1, 0.2, 0.3, 0.4, 0.5, "..."]
}

For structured thoughts:

{
  "team_id": "your-team-id",
  "timestamp": 1717160645123,
  "sections": {
    "feelings": "I feel great about this feature",
    "project_notes": "Architecture is solid",
    "technical_insights": "TypeScript provides great type safety",
    "user_context": "Harper prefers concise responses",
    "world_knowledge": "Semantic search is powerful"
  },
  "embedding": [0.1, 0.2, 0.3, 0.4, 0.5, "..."]
}

#### Embedding Vectors

Each journal entry includes a semantic embedding vector generated using local AI models (@xenova/transformers). These vectors enable:

The embedding is a numeric array representing the semantic meaning of the journal entry content. Vector dimensions depend on the model used (typically 384 or 512 dimensions).

The remote server should expect POST requests to /journal/entries with x-api-key and x-team-id headers.

Claude Code Plugin

This repository is configured as a Claude Code Plugin. To use it:

#### Quick Install (Recommended)

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

Or install directly from GitHub:

claude mcp install github:2389-research/journal-mcp

#### What's Included

The plugin provides:

MCP Configuration (Other Clients)

#### Manual Configuration
For Claude Desktop or other MCP clients, add to your MCP settings:

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

Multi-section private journaling with these optional categories:

search_journal

Semantic search across all journal entries:

read_journal_entry

Read full content of specific entries:

list_recent_entries

Browse recent entries chronologically:

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: 
---
title: "2:30:45 PM - May 31, 2025"
date: 2025-05-31T14:30:45.123Z
timestamp: 1717160645123
---

## Feelings

I'm excited about this new search feature...

## Technical Insights

Vector embeddings provide semantic understanding...

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.

Documentation

Comprehensive Guides

API Reference

Getting Help

Author

Jesse Vincent

Read more about the motivation and design in the blog post.

License

MIT

---

If journaling gave your Claude some clarity, a ⭐ helps us know it's landing.

Built by 2389 · Part of the Claude Code plugin marketplace

More from Strategy & Reflection