使用说明
专用日志MCP服务器
一个全面的MCP（模型上下文协议）服务器，为Claude提供私人日志和语义搜索功能，用于处理想法、反思和见解。
特性
日志记录
- 多节日记：对反思、观察、项目笔记、用户背景、技术见解和世界知识进行单独分类
- 双存储器：项目笔记保存在项目中，个人想法保存在用户主目录中
- 带时间戳的条目：每个条目都以微秒精度自动标注日期
- YAML 前置元数据：每个条目的结构化元数据
搜索与发现
- 语义搜索：使用本地AI嵌入的自然语言查询
- 向量相似性：查找概念上相关的条目，而不仅仅是关键字匹配
- 本地AI处理：使用@xenova/transformers-不需要外部API调用
- 自动标引：为启动和正在进行的所有条目生成嵌入
隐私与性能
- 完全私密：所有处理都在本地进行，没有数据离开您的机器
- 快速操作：优化了文件结构和内存中的相似性计算
- 稳健的回退：跨平台的智能路径解析
安装
此服务器直接从GitHub运行，使用 npx -无需安装。
MCP配置
克劳德代码（单行）
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
具有以下可选类别的多节私人日记：
- 反思：综合思维——你注意到、感受到、理解或处理的东西
- 观察：简短、离散的通知——每句一句
- 项目注释：针对当前项目的技术见解
- 用户文本：关于与人类合作的说明
- 技术_景点：通用软件工程学习
- 世界知识：领域知识和有趣的发现
search_journal
跨所有日记账条目的语义搜索：
- 查询 （必填）：自然语言搜索查询
- 限制：最大结果（默认值：10）
- 类型：搜索范围-“项目”、“用户”或“两者”（默认值：“两者”）
- 章节：按特定类别筛选
read_journal_entry
阅读特定条目的完整内容：
- 路径 （必填）：搜索结果中的文件路径
list_recent_entries
按时间顺序浏览最近的条目：
- 限制：最大条目数（默认值：10）
- 类型：条目范围-“项目”、“用户”或“两者”（默认值：“两者”）
- 天：返回搜索的天数（默认值：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.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@fsck.com
阅读更多关于动机和设计的信息 博客文章.
许可证
麻省理工学院
