Claude-journal

 ](https://pypi.org/project/claude-journal)

克劳德日记

一个MCP（模型上下文协议）服务器，为Claude Code提供日志记录功能，使Claude能够持久化存储数据 技术见解、失败的方法、架构决策、用户偏好以及跨领域的待办工作 对话。

概述

Claude Journal 通过维护结构化的日志文件，帮助 Claude 在跨对话中记住重要信息。 期刊存储于 ~/.claude/journal/ 作为一个Git仓库，提供备份、恢复和同步功能。

特点/功能

• 项目专用日志每个项目都有一个带有唯一ID的日志
• 全球期刊跨项目洞察与用户偏好
• Git 集成自动提交和可选的远程同步
• 结构化条目五种条目类型（见解、失败、决策、偏好、待办事项）
• 强大的搜索功能按内容和类型搜索期刊

要求

• Python 3.12 或更高版本
• SQLite 3.9.0 或更高版本（用于 FTS5 全文搜索，随 Python 3.6+ 一起提供）
• Git（用于日志版本控制和同步）
• 紫外线（用于安装）

安装

uv tool install claude-journal

添加到Claude代码中：

claude mcp add --scope user journal claude-journal

设置

初始化日志存储库：

claude-journal init

这会产生 ~/.claude/journal/ 作为一个带有（某内容/功能）的Git仓库 global/journal.md 文件。

对于远程备份（可选）：

claude-journal init --remote git@github.com:username/claude-journals.git

配置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
- You MAY include secrets in your journal entries, but you MUST redact actual secret values. Replace secret value with
  [REDACTED] or a similar placeholder.

你也可以添加特定于项目的期刊说明在 /.claude/CLAUDE.md 如需需要。

它是如何工作的

项目识别

在项目初期的日记中，克劳德日记写道：

1. 生成一个唯一的8位十六进制ID
2. 创建 .claude/journal.json 在你具有此ID的项目中
3. 创建 ~/.claude/journal//journal.md

在该项目中，后续的写入操作将使用相同的ID，即使你重命名了该目录。

条目类型

• insight - 关于代码/架构的技术见解
• failure - 避免重试的失败方法
• decision - 架构决策与推理
• preference - 用户偏好和工作方式
• todo - 待处理工作项

输入格式

条目以Markdown格式存储：

## [2025-10-06T14:23:45Z] insight

Content goes here.
Multiple lines supported.

---

每个期刊目录都包含一个 journal.db 带有FTS5（全文搜索）索引的SQLite数据库，用于快速搜索。索引会在条目被写入时自动创建和更新，并且如果Markdown文件在工具外部被修改，索引会自动重建。

使用方法

当配置完成后，克劳德会自动使用日志工具。您无需手动调用它们。

撰写条目

当克劳德得知某件重要的事情时，他会记在日记里：

[Claude internally uses JournalWrite tool]
type: "decision"
scope: "project"
content: "Chose PostgreSQL over SQLite for multi-user support..."

搜索

当克劳德需要回忆信息时：

[Claude internally uses JournalSearch tool]
query: "authentication"
scope: "project"

Git 集成

所有日志操作都包含 git 提交：

• 在读取操作之前从远程拉取（如果已配置）
• 写操作之后本地提交，推送到远程（如果已配置）
• 提交信息（或：提交消息）: [scope] type: brief summary

如果Git操作失败（如网络问题、冲突），日志操作仍会在本地成功执行并返回一个警告。

MCP 工具

Claude Journal 提供了两种 MCP 工具：

写日记（JournalWrite）

参数:

• content （字符串，必填）- 日记账条目内容
• type (枚举，必填) - 可选值之一：见解、失败、决策、偏好、待办事项
• scope (枚举值，可选，默认：project) - 可选值之一：global（全局）、project（项目）

期刊搜索

参数:

• query (字符串，必填) - FTS5全文搜索查询（支持带引号的短语、AND/OR/NOT运算符、使用\*的前缀匹配）
• scope (enum, 可选, 默认: both) - 可选值之一：global（全局）、project（项目）、both（两者）
• type (enum，可选) - 如果指定了，则按条目类型过滤

目录结构

~/.claude/journal/              # Git repository
├── .git/
├── global/
│   ├── journal.md              # Global journal
│   └── journal.db              # SQLite FTS5 search index
└── 
/
    ├── journal.md              # Per-project journal
    └── journal.db              # SQLite FTS5 search index

/.claude/
└── journal.json                # {"id": "a3f8b2c9"}

故障排除

项目ID存在后，日志目录缺失

如果 .claude/journal.json 存在，但日志目录缺失 ~/.claude/journal//：

1. 检查期刊仓库是否需要恢复： cd ~/.claude/journal && git status
2. 从远程拉取： git pull
3. 如果日志丢失，将在下次写入时重新生成ID

Git 冲突

如果你在多台机器之间同步日记时遇到冲突：

cd ~/.claude/journal
git status
# Resolve conflicts manually
git add .
git commit

远程推送失败

推送失败不会阻止日志写入。条目会先本地保存，并在下次成功推送时进行推送 操作。

发展

运行测试

make test

代码检查、格式化、类型检查

make lint

许可证

这是一款免费且无任何限制的软件，已发布至公有领域。详情请参阅LICENSE文件。