Private Journal MCP Server

私人日志 MCP 服务

一个功能全面的 MCP（Model Context Protocol）服务，为 Claude 提供私人日志记录和语义搜索能力，用于处理想法、反思和见解。

功能

日志记录

• 多分区日志记录：为反思、观察、项目笔记、用户背景、技术见解和世界知识设置独立分类
• 双重存储：项目笔记随项目保存，个人想法保存在用户主目录中
• 带时间戳的条目：每个条目都会自动记录日期，精确到微秒
• YAML frontmatter：为每个条目提供结构化元数据

搜索与发现

• 语义搜索：使用本地 AI 嵌入进行自然语言查询
• 向量相似度：查找概念相关的条目，而不仅仅是关键词匹配
• 本地 AI 处理：使用 @xenova/transformers，无需调用外部 API
• 自动索引：启动时及运行期间为所有条目生成嵌入

隐私与性能

• 完全私密：所有处理都在本地进行，不会有数据离开你的设备
• 运行快速：优化文件结构和内存中的相似度计算
• 可靠的回退机制：支持跨平台的智能路径解析

安装

此服务通过 npx 直接从 GitHub 运行，无需安装。

MCP 配置

Claude Code（一行命令）

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

手动配置

添加到你的 MCP 设置中（例如 Claude Desktop 配置）：

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

服务会自动为日志文件找到合适的位置。

配置

PRIVATE_JOURNAL_PATH 环境变量

设置 PRIVATE_JOURNAL_PATH，可将所有日志存储位置覆盖为单个目录。这适用于容器化部署，因为默认主目录解析方式可能不适用：

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

设置后，项目日志和用户日志都会写入指定路径，并跳过所有回退解析逻辑。

--journal-path CLI 参数

也可以通过 CLI 参数设置项目日志路径：

npx github:obra/private-journal-mcp --journal-path /path/to/journals

此参数仅覆盖项目日志路径。用户日志路径仍通过 PRIVATE_JOURNAL_PATH 或默认主目录逻辑解析。

MCP 工具

此服务提供全面的日志记录和搜索功能：

process_thoughts

使用以下可选分类进行多分区私人日志记录：

• reflections：整合思考——你注意到、感受到、理解或处理的内容
• observations：简短、独立的观察——每条一到两句话
• project_notes：针对当前项目的技术见解
• user_context：关于与人协作的笔记
• technical_insights：通用软件工程经验
• world_knowledge：领域知识和有趣的发现

search_journal

对所有日志条目进行语义搜索：

• query（必填）：自然语言搜索查询
• limit：最多返回的结果数（默认：10）
• type：搜索范围——'project'、'user' 或 'both'（默认：'both'）
• sections：按特定分类筛选

read_journal_entry

读取特定条目的完整内容：

• path（必填）：搜索结果中的文件路径

list_recent_entries

按时间顺序浏览最近的条目：

• limit：最多显示的条目数（默认：10）
• type：条目范围——'project'、'user' 或 'both'（默认：'both'）
• days：向前搜索的天数（默认：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
│   └── ...

条目格式

每个 Markdown 文件都包含 YAML frontmatter 和结构化分区：

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

开发

构建

npm run build

测试

npm test

开发模式

npm run dev

提升 Claude 的性能

为了帮助 Claude 随着时间推移不断学习和改进，可以考虑在 ~/.claude/CLAUDE.md 文件中添加日志使用指南：

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

这样 Claude 就能在不同对话之间构建持久记忆，从而做出更好的工程决策，并形成更有效的协作模式。

作者

Jesse Vincent [email protected]

在博客文章中进一步了解其动机和设计。

许可证

MIT