A comprehensive MCP (Model Context Protocol) server that provides Claude with private journaling and semantic search capabilities for processing thoughts, feelings, and insights.
- Multi-section journaling: Separate categories for feelings, 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
- 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
- Vault sync: Store user journal in your Obsidian vault for cross-machine sync
- Auto-discovery: Automatically finds your vault from Obsidian's config
- Smart caching: Embeddings stored locally (not synced) for efficiency
- Rich frontmatter: Tags, project info, and agent metadata for Obsidian filtering
- 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
This server is run directly from GitHub using npx - no installation required.
claude mcp add-json private-journal '{"type":"stdio","command":"npx","args":["github:EnderRealm/private-journal-mcp"]}' -s userAdd to your MCP settings (e.g., Claude Desktop configuration):
{
"mcpServers": {
"private-journal": {
"command": "npx",
"args": ["github:EnderRealm/private-journal-mcp"]
}
}
}On Windows, use cmd /c to run npx:
{
"mcpServers": {
"private-journal": {
"type": "stdio",
"command": "cmd",
"args": ["/c", "npx", "github:EnderRealm/private-journal-mcp"]
}
}
}The server will automatically find a suitable location for the journal files.
To store your user journal in an Obsidian vault (for sync across machines):
{
"mcpServers": {
"private-journal": {
"command": "npx",
"args": ["github:EnderRealm/private-journal-mcp"],
"env": {
"AGENTIC_JOURNAL_VAULT": "your-vault-name"
}
}
}
}{
"mcpServers": {
"private-journal": {
"type": "stdio",
"command": "cmd",
"args": ["/c", "npx", "github:EnderRealm/private-journal-mcp"],
"env": {
"AGENTIC_JOURNAL_VAULT": "your-vault-name"
}
}
}
}The server will automatically discover your vault location from Obsidian's config. Journal entries will be stored in your-vault/agentic-journal/ with embeddings cached locally (not synced).
Environment Variables:
AGENTIC_JOURNAL_VAULT: Name of your Obsidian vault to use for user journalAGENTIC_JOURNAL_PATH: Explicit path override (ignores vault discovery)
The server provides comprehensive journaling and search capabilities:
Multi-section private journaling with these optional categories:
- feelings: Private emotional processing space
- 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
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 full content of specific entries:
- path (required): File path from search results
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)
.private-journal/
├── 2025-05-31/
│ ├── 14-30-45-123456.md # Project notes entry
│ ├── 14-30-45-123456.embedding # Search index
│ └── ...
~/.private-journal/
├── 2025-05-31/
│ ├── 14-32-15-789012.md # Personal thoughts entry
│ ├── 14-32-15-789012.embedding # Search index
│ └── ...
When AGENTIC_JOURNAL_VAULT is set, entries go to your vault and embeddings to local cache:
# Journal entries (synced via Obsidian)
your-vault/agentic-journal/
├── 2025-05-31/
│ ├── 14-32-15-789012.md
│ └── ...
# Embeddings (local cache, not synced)
~/.cache/private-journal/embeddings/ # macOS/Linux
%LOCALAPPDATA%/private-journal/embeddings/ # Windows
├── 2025-05-31--14-32-15-789012.embedding
└── ...
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
project: git@github.com:user/repo.git
agent: claude-code:1.0.0
tags:
- agentic-journal
- feelings
- technical-insights
---
## Feelings
I'm excited about this new search feature...
## Technical Insights
Vector embeddings provide semantic understanding...The project and agent fields are automatically captured. Tags include agentic-journal plus the sections present in each entry, making it easy to filter in Obsidian.
npm run buildnpm testnpm run devTo 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 immediatelyThis enables Claude to build persistent memory across conversations, leading to better engineering decisions and collaboration patterns.
Jesse Vincent jesse@fsck.com
Read more about the motivation and design in the blog post.
MIT