Claude Journal-克劳德代码插件
Claude Code的轻量级日志/内存系统，不依赖ML。使用简单的SQLite进行快速的本地存储。
这是一个功能齐全的Claude Code插件，具有斜线命令、技能、代理和自动捕获挂钩。
特性
- ✅ 轻量级：没有嵌入，没有ML模型，只有SQLite
- ✅ 快速：本地数据库上的亚毫秒级查询
- ✅ 智能搜索：具有ID查找、标签过滤、精确短语、日期范围和关键字的高级搜索
- ✅ 时间查询：自然语言，如“上个月”、“昨天”
- ✅ 项目跟踪：按存储库/项目组织条目
- ✅ 自动捕获：通过挂钩自动定期记录日志
- ✅ 导入/导出：在实例之间共享日志
- ✅ 灵活标签：使用自定义标签进行组织
- ✅ 斜杠命令：6个用户友好的常用操作命令
- ✅ 技能：3种主动的人工智能技能，用于上下文恢复和智能捕获
- ✅ 代理：可选日记助理，可增强工作流程
需求
- Python 3.12或更高版本
- 紫外线 （推荐）或pip
安装
快速入门（推荐）
- 安装uv （如果尚未安装）：
curl -LsSf https://astral.sh/uv/install.sh | sh- 克隆并安装插件：
git clone https://github.com/chrismbryant/claude-journal-mcp.git
cd claude-journal-mcp
uv sync- 安装为Claude Code插件：
# Option A: Direct install from current directory
claude /plugin install .
# Option B: Add marketplace first, then install
claude /marketplace add ./marketplace.json
claude /plugin install claude-journal这会自动：
- 配置MCP服务器（提供所有11个日志工具）
- 注册6个斜线命令（/journal add、/journals search等）
- 实现3种主动技能（日志捕获、上下文恢复、查找相关工作）
- 设置自动捕获挂钩（每30分钟或3条消息触发一次）
- 提示您启用日志助理代理（选择加入）
替代方案：手动安装MCP服务器
如果您更喜欢只安装MCP服务器而不安装插件功能：
- 安装依赖项：
# With uv (recommended - faster)
uv sync
# Or with pip
pip install -e .- 增添
~/.claude/config.json或者你的项目.mcp.json:
{
"mcpServers": {
"journal": {
"command": "python",
"args": ["-m", "claude_journal.server"]
}
}
}注： 手动安装仅提供MCP工具。如果不作为插件安装，您将无法获得斜线命令、技能或代理。
数据库位置
违约： ~/.claude/journal.db
用环境变量覆盖：
export JOURNAL_DB_PATH="/path/to/your/journal.db"斜杠命令
该插件提供了6个斜线命令，便于交互：
/journal-add
交互式创建新日记条目。Claude将指导您：
- 标题
- 描述
- 项目（从git自动检测到）
- 标签（根据内容建议）
You: /journal-add
Claude: Let's create a journal entry. What's the title?
You: Implemented rate limiting
Claude: Great! Tell me more about it.../journal-search
使用高级查询语法搜索条目。支持ID查找、标签过滤、精确短语、日期范围和关键字。
You: /journal-search
Claude: What would you like to search for?
You: authentication
Claude: [Shows all auth-related entries]高级搜索语法：
- ID搜索:
42或id:42-按ID查找特定条目 - 标签过滤器:
tag:bugfix或#bugfix-按标签筛选 - 精确短语:
"user authentication"-匹配精确短语 - 日期范围:
last week authentication-将时间与搜索相结合 - 组合的:
tag:bugfix "login error" last month-混合多个过滤器
/journal-recent
显示最近的条目以还原上下文（在以下情况下特别有用 /clear).
You: /clear
You: /journal-recent
Claude: Here's what you were working on:
[Lists recent entries with summaries]/journal-time
使用自然语言时间表达式查询条目。
You: /journal-time
You: last week
Claude: [Shows all entries from last week]支持：“昨天”、“上月”、“2024年1月”、“最近3天”等。
/journal-stats
查看有关日志使用情况的统计信息。
You: /journal-stats
Claude:
📊 247 entries across 5 projects
📅 Jan 15 - Jul 20, 2024 (6 months)
Most active: my-app (89 entries)/journal-export
导出日志以在机器之间进行备份或共享。
You: /journal-export
Claude: Where should I save the export?
You: ~/backups/journal_2024.db
Claude: ✅ Exported to ~/backups/journal_2024.db技能
该插件包括Claude自动使用的3种主动技能：
journal-capture
当您执行以下操作时，自动捕获重要工作：
- 完成功能或任务
- 修复复杂错误
- 做出技术决策
- 解决具有挑战性的问题
克劳德能够识别重要时刻，并在未被询问的情况下捕捉到它们。
context-recovery
从日志中恢复您的工作环境：
- 自动地 之后
/clear命令 - 当你问“我在做什么？”
- 在会议开始时继续过去的工作
带回项目背景、最近的更改和下一步。
find-related-work
搜索与当前任务相关的过去工作：
- 在实现类似功能之前
- 在做出架构决策时
- 故障排除期间
- 当你明确询问过去的工作时
有助于避免重新设计解决方案并保持一致性。
代理
该插件包括 可选的 期刊助理代理人。
当你第一次使用日记功能时，Claude会提示：
Would you like to enable the Journal Assistant agent?
The agent helps by:
- Automatically capturing significant work
- Recovering context after /clear
- Finding related past work
- Suggesting when to journal
Enable now?代理人是 选择进入 但建议获得最佳体验。
可用的MCP工具
写入操作
journal_add -手动添加条目
Add a journal entry:
- title: "Implemented auth system"
- description: "Built OAuth2 flow with JWT tokens"
- project: "my-app"
- tags: ["auth", "backend"]journal_auto_capture -自动保存进度
Automatically called by hooks or when Claude detects significant work读取操作
journal_search -高级文本搜索
Search examples:
- "authentication" - Keyword search
- "42" or "id:42" - Find entry by ID
- "tag:bugfix" or "#bugfix" - Filter by tag
- "\"user authentication\"" - Exact phrase match
- "last week authentication" - Date range + keyword
- "tag:bugfix \"login error\" performance" - Combined filtersjournal_time_query -基于时间的搜索
What did I work on last week?
What did I do in January?
When did I implement feature X?支持的时间表达式：
today,yesterdaylast week,last month,last yearlast 3 days,last 2 weeksthis week,this month,this yearjanuary,january 20242024-01-15（ISO日期）
journal_list_recent -最近的条目
Show me the last 10 entries
Show recent work on project Xjournal_list_projects -所有项目
List all projects with entry countsjournal_stats -统计数据
Show journal statistics管理操作
journal_delete -按ID删除
Delete entry 42journal_delete_by_project -删除项目的所有内容
Delete all entries for project "old-app"journal_import -从文件导入
Import from ~/other-machine/journal.dbjournal_export -导出到文件
Export to ~/backup/journal_2024.db用法示例
手动日记
You: Remember that we implemented rate limiting today
Claude: [Calls journal_add]
✅ Journal entry created (ID: 42)基于时间的查询
You: What did I work on last month?
Claude: [Calls journal_time_query with "last month"]
Shows all entries from last monthYou: When did I add the auth system?
Claude: [Calls journal_time_query with search for "auth"]
Shows entries matching "auth" with dates上下文恢复
You: /clear
You: What was I working on?
Claude: [Calls journal_list_recent]
Shows recent work to restore context项目组织机构
You: Show me everything I've done on my-app
Claude: [Calls journal_search with project filter]
Lists all my-app entries机器之间共享
机器1：
You: Export my journal
Claude: [Calls journal_export]
✅ Exported journal to journal_export_20241105.db机器2：
You: Import journal from ~/Downloads/journal_export_20241105.db
Claude: [Calls journal_import]
✅ Imported 150 new entries自动抓钩
该插件包含一个自动捕获挂钩，安装后会自动运行。
它是如何工作的：
- 监控对话活动
- 每30分钟触发一次 或 发送3+条消息时（以先到者为准）
- 通过CLI自动创建日记条目
- 保持状态
~/.claude/journal-capture-state.json - 插件安装时自动启用
配置：
钩子的定义见 hooks/hooks.json 并自动启用：
{
"hooks": {
"UserPromptSubmit": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/journal-auto-capture.js"
}
]
}
]
}
}行为：
- 在每次用户提示提交时运行，并显示日志(
📊 Journal auto-capture hook running) - 低开销（检查时间戳和计数器）
- 当达到阈值（30分钟或3条以上消息）时，提示Claude分析会话
- 克劳德必须回应 -要么创建日记条目，要么解释为什么不捕获
- Claude回顾了对话，并创建了一个有意义的日记条目：
- 目标（我们试图做的事情） - 成就（做了什么） - 相关标签和项目信息
- Claude还可以根据对话上下文随时主动使用日记工具来记录重要工作
CLI接口
该插件包括一个最小的CLI，提供有关可用MCP工具的信息：
python -m claude_journal.cli
# Or: claude-journal所有日志操作都是通过MCP服务器执行的，而不是通过CLI命令。自动捕获钩子触发Claude使用 journal_auto_capture MCP工具。
数据库模式
CREATE TABLE journal_entries (
id INTEGER PRIMARY KEY AUTOINCREMENT,
created_at TEXT NOT NULL DEFAULT (datetime('now')),
project TEXT,
title TEXT NOT NULL,
description TEXT NOT NULL,
tags TEXT
);
CREATE INDEX idx_created_at ON journal_entries(created_at);
CREATE INDEX idx_project ON journal_entries(project);发展
运行测试
pytest tests/促成变更
重要提示： 这 main 分支受到保护，需要拉取请求。
# Create a feature branch
git checkout -b your-feature-name
# Make your changes and commit
git add .
git commit -m "Description of changes"
# Push your branch
git push -u origin your-feature-name
# Create a pull request
gh pr create --title "Your PR title" --body "Description"
# After CI passes, merge the PR
gh pr merge
--squash --delete-branch不要直接推到main -所有更改都必须通过pull请求。
项目结构
claude-journal-mcp/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── agents/
│ └── journal-assistant.md # Journal assistant agent
├── commands/
│ ├── journal-add.md # /journal-add command
│ ├── journal-export.md # /journal-export command
│ ├── journal-recent.md # /journal-recent command
│ ├── journal-search.md # /journal-search command
│ ├── journal-stats.md # /journal-stats command
│ └── journal-time.md # /journal-time command
├── hooks/
│ ├── hooks.json # Hook configuration
│ └── journal-auto-capture.js # Auto-capture hook
├── skills/
│ ├── journal-capture/
│ │ └── SKILL.md # Proactive capture skill
│ ├── context-recovery/
│ │ └── SKILL.md # Context recovery skill
│ └── find-related-work/
│ └── SKILL.md # Related work finder skill
├── src/
│ └── claude_journal/
│ ├── __init__.py
│ ├── server.py # MCP server
│ ├── database.py # SQLite operations
│ └── time_parser.py # Natural language time parsing
├── tests/
├── .mcp.json # MCP server config
├── pyproject.toml
├── LICENSE
└── README.md为什么不嵌入？
嵌入/语义搜索：
- 优点：按意思查找，而不是精确的单词
- 缺点：4GB以上的依赖关系，需要PyTorch/CUDA
这种方法（SQLite全文）：
- 优点：轻量级（~10MB），即时查询，无机器学习依赖
- 缺点：必须使用类似的关键字来查找条目
权衡：对于期刊，精确的关键字匹配通常就足够了。比起抽象概念，你更能记住“auth”、“bug”、“部署”等粗略的术语。
许可证
麻省理工学院
贡献
欢迎拉取请求！请确保：
- 测试通过
- 代码遵循现有样式
- 更新README以获取新功能