{
  "markdown": "# Private Journal MCP Server\n\n[![Test Coverage](https://github.com/2389-research/journal-mcp/actions/workflows/coverage.yml/badge.svg)](https://github.com/2389-research/journal-mcp/actions/workflows/coverage.yml)\n[![Coverage](https://img.shields.io/badge/coverage-86.8%25-brightgreen)](https://github.com/2389-research/journal-mcp/actions)\n\nA comprehensive MCP (Model Context Protocol) server that provides Claude with private journaling and semantic search capabilities for processing thoughts, feelings, and insights.\n\n## Features\n\n### Journaling\n- **Multi-section journaling**: Separate categories for feelings, project notes, user context, technical insights, and world knowledge\n- **Dual storage**: Project notes stay with projects, personal thoughts in user home directory\n- **Timestamped entries**: Each entry automatically dated with microsecond precision\n- **YAML frontmatter**: Structured metadata for each entry\n\n### Search & Discovery\n- **Semantic search**: Natural language queries using local AI embeddings\n- **Vector similarity**: Find conceptually related entries, not just keyword matches\n- **Local AI processing**: Uses @xenova/transformers - no external API calls required\n- **Automatic indexing**: Embeddings generated for all entries on startup and ongoing\n\n### Privacy & Performance\n- **Completely private**: All processing happens locally, no data leaves your machine\n- **Fast operation**: Optimized file structure and in-memory similarity calculations\n- **Robust fallbacks**: Intelligent path resolution across platforms\n\n## Tech Stack\n\n### Core Technologies\n- **Node.js 18+** - Runtime environment with modern JavaScript features\n- **TypeScript 5.0+** - Type-safe development with strict configuration\n- **MCP SDK 0.4.0** - Official Model Context Protocol implementation\n- **@xenova/transformers** - Local AI models for semantic embeddings (no external APIs)\n\n### AI & Search\n- **Semantic Embeddings** - Multiple model options (MiniLM, DistilRoBERTa, MPNet)\n- **Vector Similarity** - Local cosine similarity calculations\n- **Natural Language Search** - Query understanding without external services\n\n### Development & Quality\n- **Jest** - Comprehensive testing framework with mocks\n- **Biome** - Modern linting and formatting\n- **Oxlint** - Additional code quality checks\n- **GitHub Actions** - Continuous integration and testing\n\n### Storage & Architecture\n- **Markdown + YAML** - Human-readable entries with structured metadata\n- **Hierarchical File System** - Date-based organization with microsecond precision\n- **Cross-Platform** - Windows, macOS, and Linux support\n\nFor detailed architectural decisions, see [ARCHITECTURE.md](ARCHITECTURE.md).\n\n## Installation\n\n```bash\nnpm install -g private-journal-mcp\n```\n\nOr install locally:\n\n```bash\nnpm install private-journal-mcp\n```\n\n## Usage\n\n### Basic Usage\n```bash\nprivate-journal-mcp\n```\n\nThis creates journal entries in `.private-journal/` in the current working directory.\n\n### Custom Journal Path\n```bash\nprivate-journal-mcp --journal-path /path/to/my/journal\n```\n\n### Embedding Model Configuration\n\nYou can customize the AI model used for generating semantic embeddings:\n\n```bash\nexport JOURNAL_EMBEDDING_MODEL=\"Xenova/all-distilroberta-v1\"\n```\n\n**Available Models:**\n- `Xenova/all-MiniLM-L6-v2` (default) - Fast, 384 dimensions, good general performance\n- `Xenova/all-distilroberta-v1` - Larger, 768 dimensions, better accuracy\n- `Xenova/paraphrase-MiniLM-L6-v2` - Optimized for paraphrase detection\n- `Xenova/all-mpnet-base-v2` - High quality, 768 dimensions, slower but more accurate\n\nThe embedding model affects:\n- **Local search quality** - More sophisticated models provide better semantic understanding\n- **Vector dimensions** - Impacts remote server storage and search capabilities\n- **Processing speed** - Larger models are slower but more accurate\n- **Memory usage** - Bigger models require more RAM\n\n### Remote Server Integration\n\nTo enable optional remote posting of journal entries to a team server, set these environment variables:\n\n```bash\nexport REMOTE_JOURNAL_SERVER_URL=\"https://api.yourteam.com\"\nexport REMOTE_JOURNAL_TEAMID=\"your-team-id\"\nexport REMOTE_JOURNAL_APIKEY=\"your-api-key\"\n```\n\nWhen 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.\n\n#### Remote-Only Mode\n\nFor teams using a backend server as the single source of truth, enable remote-only mode to skip local file storage entirely:\n\n```bash\nexport REMOTE_JOURNAL_ONLY=\"true\"\n```\n\nIn remote-only mode:\n- **No local storage** - entries go directly to the backend server\n- **Server-side search** - all search queries use the backend API\n- **Error handling** - journal operations fail if server is unavailable\n- **Team collaboration** - automatic sharing across team members\n- **Centralized AI** - semantic search powered by backend infrastructure\n\n#### Remote Payload Format\n\nThe server sends JSON payloads with this structure:\n\n**For simple entries:**\n```json\n{\n  \"team_id\": \"your-team-id\",\n  \"timestamp\": 1717160645123,\n  \"content\": \"Journal entry text\",\n  \"embedding\": [0.1, 0.2, 0.3, 0.4, 0.5, \"...\"]\n}\n```\n\n**For structured thoughts:**\n```json\n{\n  \"team_id\": \"your-team-id\",\n  \"timestamp\": 1717160645123,\n  \"sections\": {\n    \"feelings\": \"I feel great about this feature\",\n    \"project_notes\": \"Architecture is solid\",\n    \"technical_insights\": \"TypeScript provides great type safety\",\n    \"user_context\": \"Harper prefers concise responses\",\n    \"world_knowledge\": \"Semantic search is powerful\"\n  },\n  \"embedding\": [0.1, 0.2, 0.3, 0.4, 0.5, \"...\"]\n}\n```\n\n#### Embedding Vectors\n\nEach journal entry includes a semantic embedding vector generated using local AI models (@xenova/transformers). These vectors enable:\n- **Semantic search** on the remote server\n- **Similarity matching** across team entries\n- **Content clustering** and analysis\n- **AI-powered insights** without exposing raw content\n\nThe 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).\n\nThe remote server should expect POST requests to `/journal/entries` with `x-api-key` and `x-team-id` headers.\n\n### Claude Code Plugin\n\nThis repository is configured as a Claude Code Plugin. To use it:\n\n#### Quick Install (Recommended)\n```bash\nclaude mcp add-json private-journal '{\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"github:2389-research/journal-mcp\"]}' -s user\n```\n\nOr install directly from GitHub:\n```bash\nclaude mcp install github:2389-research/journal-mcp\n```\n\n#### What's Included\n\nThe plugin provides:\n- **Tools**: `process_thoughts`, `search_journal`, `read_journal_entry`, `list_recent_entries`\n- **Resources**: Access to journal entries as discoverable resources\n- **Prompts**: Guided templates for daily reflection, project retrospectives, and learning capture\n\n### MCP Configuration (Other Clients)\n\n#### Manual Configuration\nFor Claude Desktop or other MCP clients, add to your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"private-journal\": {\n      \"command\": \"npx\",\n      \"args\": [\"github:2389-research/journal-mcp\"]\n    }\n  }\n}\n```\n\nThe server will automatically find a suitable location for the journal files.\n\n## MCP Tools\n\nThe server provides comprehensive journaling and search capabilities:\n\n### `process_thoughts`\nMulti-section private journaling with these optional categories:\n- **feelings**: Private emotional processing space\n- **project_notes**: Technical insights specific to current project\n- **user_context**: Notes about collaborating with humans\n- **technical_insights**: General software engineering learnings\n- **world_knowledge**: Domain knowledge and interesting discoveries\n\n### `search_journal`\nSemantic search across all journal entries:\n- **query** (required): Natural language search query\n- **limit**: Maximum results (default: 10)\n- **type**: Search scope - 'project', 'user', or 'both' (default: 'both')\n- **sections**: Filter by specific categories\n\n### `read_journal_entry`\nRead full content of specific entries:\n- **path** (required): File path from search results\n\n### `list_recent_entries`\nBrowse recent entries chronologically:\n- **limit**: Maximum entries (default: 10)\n- **type**: Entry scope - 'project', 'user', or 'both' (default: 'both')\n- **days**: Days back to search (default: 30)\n\n## File Structure\n\n### Project Journal (per project)\n```\n.private-journal/\n├── 2025-05-31/\n│   ├── 14-30-45-123456.md          # Project notes entry\n│   ├── 14-30-45-123456.embedding   # Search index\n│   └── ...\n```\n\n### User Journal (global)\n```\n~/.private-journal/\n├── 2025-05-31/\n│   ├── 14-32-15-789012.md          # Personal thoughts entry\n│   ├── 14-32-15-789012.embedding   # Search index\n│   └── ...\n```\n\n### Entry Format\nEach markdown file contains YAML frontmatter and structured sections:\n\n```markdown\n---\ntitle: \"2:30:45 PM - May 31, 2025\"\ndate: 2025-05-31T14:30:45.123Z\ntimestamp: 1717160645123\n---\n\n## Feelings\n\nI'm excited about this new search feature...\n\n## Technical Insights\n\nVector embeddings provide semantic understanding...\n```\n\n## Development\n\n### Building\n\n```bash\nnpm run build\n```\n\n### Testing\n\n```bash\nnpm test\n```\n\n### Development Mode\n\n```bash\nnpm run dev\n```\n\n### Improving Claude's Performance\n\nTo help Claude learn and improve over time, consider adding journal usage guidance to your `~/.claude/CLAUDE.md` file:\n\n```markdown\n## Learning and Memory Management\n\n- YOU MUST use the journal tool frequently to capture technical insights, failed approaches, and user preferences\n- Before starting complex tasks, search the journal for relevant past experiences and lessons learned\n- Document architectural decisions and their outcomes for future reference\n- Track patterns in user feedback to improve collaboration over time\n- 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\n```\n\nThis enables Claude to build persistent memory across conversations, leading to better engineering decisions and collaboration patterns.\n\n## Documentation\n\n### Comprehensive Guides\n- **[Architecture & Design Decisions](ARCHITECTURE.md)** - Technical architecture, design patterns, and key decisions\n- **[Contributing Guidelines](CONTRIBUTING.md)** - Development setup, code style, testing, and contribution process\n- **[Roadmap & Development Priorities](ROADMAP.md)** - Current status, planned features, and future direction\n\n### API Reference\n- **[docs/spec.md](docs/spec.md)** - Original MCP server specification\n- **[docs/backend-api-spec.md](docs/backend-api-spec.md)** - Remote server API documentation\n- **[docs/implementation-plan.md](docs/implementation-plan.md)** - Development history and implementation details\n\n### Getting Help\n- **Issues**: [GitHub Issues](https://github.com/2389-research/journal-mcp/issues) for bugs and feature requests\n- **Discussions**: [GitHub Discussions](https://github.com/2389-research/journal-mcp/discussions) for questions and community chat\n- **MCP Protocol**: [Model Context Protocol Documentation](https://modelcontextprotocol.io/)\n\n## Author\n\nJesse Vincent <jesse@fsck.com>\n\nRead 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/).\n\n## License\n\nMIT\n\n---\n\nIf journaling gave your Claude some clarity, a ⭐ helps us know it's landing.\n\nBuilt by [2389](https://2389.ai) · Part of the [Claude Code plugin marketplace](https://github.com/2389-research/claude-plugins)\n",
  "bytes": 11631,
  "sha": "51d74afe7a418b3f8509570a8c62fae064aaa016013b4e771e266b801136ee7f",
  "repo_slug": "2389-research/journal-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_2389_research_journal_mcp_private_journa_85a21804/readme"
}