内容
# ContextWolf
[](LICENSE)
[](https://python.org)
[](https://modelcontextprotocol.io)
[](https://github.com/pgvector/pgvector)
用于 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 的高性能本地知识系统，通过 MCP 集成。存储决策、代码片段、基础设施详细信息和待办事项 - 这样您的 AI 助手永远不会忘记您已经做出的决定。
## 功能
- **跨项目搜索** - 跨所有项目的全文搜索 + 语义向量搜索
- **MCP 集成** - 44 种工具直接在 Claude Code 会话中可用
- **笔记** - 长篇参考文档，带有标签和全文搜索
- **代码片段** - 代码片段库，带有标签和类型检测
- **基础设施跟踪** - 结构化 SSH 主机和服务管理
- **待办事项生命周期** - 任务跟踪，带有优先级、类别和状态
- **现在（冲刺待办事项）** - 精选的跨项目短期清单，带有工作量限制（今天 / 本周 / 稍后），可以链接到现有的待办事项 / 笔记 / 代码片段，并显示其实时状态
- **Git 集成** - 提交后钩子自动跟踪提交（每个仓库可选）
- **重复检测** - 警告相似度超过 85%
## 为什么
Claude Code 很出色 - 但它有健忘症。每次会话结束时，所有上下文都会消失。下一次会话时，它会建议 Cassandra，而您两周前已经决定使用 PostgreSQL。
ContextWolf 解决了这个问题。它作为本地 MCP 服务器与 Claude Code 一起运行，将决策、代码模式和基础设施详细信息存储在您自己的 PostgreSQL 数据库中。当 Claude 启动新会话时，知识仍然存在。
### 实践中的工作原理
**第 1 天** - 您正在使用 Claude 调试身份验证问题：
```
您： “Claude，保存这个：我们决定使用会话 cookie 而不是 JWT 进行身份验证。”
Claude 调用 context_save → 决策存储在 ContextWolf 中。
```
**第 14 天** - 新会话，不同的功能：
```
您： “Claude，在构建登录路由之前检查我们有哪些身份验证决策。”
Claude 调用 context_search → 找到您的决策 → 实现会话 cookie 而不是 JWT。
```
无需重复自己。您的 AI 助手终于有了长期记忆。
> **它有多自动？** Claude 通过 MCP 看到 ContextWolf 工具，可以随时使用。但它不会可靠地自己使用 - 即使在 `CLAUDE.md` 中有指令。实际上，您有时需要说“将此保存到 ContextWolf”或“先检查 ContextWolf”。将其视为 Claude 可以使用的工具，而不是它总是使用的工具。使用得越多，工作流程就越自然。
### 为什么不使用 Markdown 文件？
您可以在 `.md` 文件或 `CLAUDE.md` 中存储上下文。对于小型项目，这可行。但它无法扩展：
- **搜索** - Markdown 文件会全部加载到上下文窗口中。ContextWolf 使用全文搜索 + 向量相似性来返回相关结果。
- **跨项目** - Markdown 位于一个仓库中。ContextWolf 通过一次查询搜索所有项目。
- **扩展性** - 7,000+ 条目，搜索时间约 1 毫秒。带有 1,000 行的 Markdown 文件每次 Claude 读取时都会消耗令牌。
- **语义搜索** - 搜索“身份验证”并找到有关“JWT”、“登录”、“OAuth”的条目。Markdown 无法做到这一点。
- **结构** - 类型、项目、标签、优先级、时间戳、重复检测。不仅仅是自由文本。
## 先决条件
- **Python 3.12+**
- **Docker** （推荐用于 PostgreSQL）或现有的 PostgreSQL 13+，带有 [pgvector](https://github.com/pgvector/pgvector)
## 架构
ContextWolf 运行为两个部分：
- **PostgreSQL + pgvector** （存储）- 一个容器，任何地方都可运行（本地 Docker、树莓派、NAS）
- **`cm-mcp`** （MCP 服务器）- 始终在您的编码机器上本地运行，通过 stdio 由 Claude Code 启动
可选的 GUI ([context-wolf-ui](https://github.com/DarkWolfCave/context-wolf-ui)) 是第三个组件，重用相同的数据库 - 它从不运行自己的 PostgreSQL 实例。
## 快速入门
```bash
git clone https://github.com/DarkWolfCave/context-wolf.git
cd context-wolf
cp .env.example .env
# 编辑 .env 并设置 POSTGRES_PASSWORD
bash setup.sh
```
就是这样。设置脚本将：
1. 安装 [uv](https://docs.astral.sh/uv/) （快速 Python 包管理器，如果需要）
2. 安装所有依赖项
3. 通过 `docker compose up -d` 启动 PostgreSQL（从 `.env` 读取凭证）
4. 编写 `~/.context/config.yaml`（CLI 配置，使用与 `.env` 相同的凭证）
5. 下载 ONNX 嵌入模型（~90 MB，用于语义搜索）
6. 配置 Claude Code MCP 集成
7. 运行诊断以验证一切正常
<details>
<summary>手动设置（高级）</summary>
```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 安装依赖项（选择需要的）
uv sync # 核心 CLI + MCP 服务器用于 Claude Code
uv sync --extra embeddings # + 语义搜索（ONNX，~90 MB）
uv sync --extra all # 所有内容
# 启动 PostgreSQL
cp .env.example .env
# 编辑 .env，设置 POSTGRES_PASSWORD
docker compose up -d
# 配置 CLI（读取 .env 获取凭证）
cm init # 编写 ~/.context/config.yaml
# 配置 Claude Code
cm setup-mcp # 编写 ~/.claude.json
# 检查一切
cm doctor
```
</details>
### 配置文件
两个文件具有相同的凭证：
- **`.env`** - Docker Compose 启动 PostgreSQL 时使用
- **`~/.context/config.yaml`** - CLI 和 MCP 服务器用于连接
`cm init` 读取 `.env` 并编写 `config.yaml`，因此两者保持同步。更改密码？编辑两个文件，重启容器，然后再次运行 `cm init`。
### 数据位置
默认情况下，PostgreSQL 数据存储在 `./data/postgres/` 中，与 `docker-compose.yml` 相邻（该目录被 gitignore）。这使得数据易于查找、备份或删除。
要在其他位置存储数据（例如，在您的主目录中或单独的 SSD 上），请编辑 `docker-compose.yml` 中的 `volumes:` 行。示例在该文件的顶部注释中。
## 设置脚本选项
```bash
bash setup.sh # 完整的交互式设置
bash setup.sh --install-only # 仅安装依赖项
bash setup.sh --doctor # 运行诊断
bash setup.sh --init # 配置数据库
bash setup.sh --setup-mcp # 配置 Claude Code MCP
```
### 更新到新版本
ContextWolf 没有自动更新器 - 新版本不会到达您的机器，直到您获取它们。从仓库目录：
```bash
git pull
bash setup.sh --install-only # 重新构建 cm / cm-mcp / cm-embed 工具
```
`setup.sh --install-only` 运行 `uv tool install --reinstall`，强制 uv 从当前源重新构建轮并替换以前的安装。（普通 `--force` 不够 - uv 可能重用仍然带有旧版本的缓存轮。）之后：
- **CLI（`cm`）：** 新命令立即可用 - 使用 `cm --version` 检查。
- **MCP 服务器：** 重启 Claude Code（或运行 `/mcp` 并重新连接 `context-manager` 服务器），以便它加载新代码。
- **数据库架构：** 任何新的 SQL 迁移都将在下一个 `cm` 调用或 MCP 服务器启动时自动应用 - 无需手动步骤。
如果您只需要更新 MCP 工具（不包括 CLI），则在 `git pull` 后重启 Claude Code 就足够了，因为 MCP 服务器直接通过 `uv run` 从仓库启动。CLI 是在您重新安装它之前保持冻结的部分。
### 单独服务器上的数据库
如果您想在另一台机器上使用 PostgreSQL（例如，树莓派或 NAS），而在本地机器上使用 MCP 服务器：
```bash
# 1. 在服务器上：克隆仓库，配置 .env，启动 PostgreSQL
ssh user@your-server
git clone https://github.com/DarkWolfCave/context-wolf.git
cd context-wolf
cp .env.example .env
# 编辑 .env，设置 POSTGRES_PASSWORD
docker compose up -d
# 2. 在本地机器上：安装 CLI，选择“外部服务器”
git clone https://github.com/DarkWolfCave/context-wolf.git
cd context-wolf
bash setup.sh --install-only
cm init
# → 选项 [2]，输入服务器的 IP，端口 5432，匹配的用户/密码
cm setup-mcp
```
> **安全注意：** Compose 文件在服务器的所有网络接口上将 PostgreSQL 暴露在端口 5432 上。对于不受信任的网络，请使用防火墙限制访问，绑定到特定 IP（编辑 `ports:` 行：“`192.168.1.37:5432:5432`”），或通过 Tailscale/WireGuard 进行隧道传输。PostgreSQL 受密码保护，但原始端口暴露仍然是攻击面。
## 用法
### CLI
```bash
# 保存上下文
cm save "实现了带有刷新令牌的 JWT 身份验证"
# 搜索
cm search "身份验证" # 当前项目
cm search "身份验证" --all # 所有项目
cm smart-search "XSS 防御" # 全局搜索（指令 + 代码片段 + 操作）
# 会话和统计
cm session # 今日活动
cm stats # 数据库统计
cm doctor # 系统健康检查
# 待办事项
cm todo add "修复身份验证错误" --priority high
cm todo start 123
cm todo done 123
# 现在（跨项目冲刺待办事项）
cm now add "修复身份验证错误" --bucket today --project myapp
cm now add "润色设置页面" --link-type todo --link-id 123 # 引用待办事项
cm now list
cm now move 5 week
cm now done 5
# AI 指令
cm ai-instruction "始终使用 snake_case" --category style --priority should
# 基础设施
cm infra add-host "web01" --ip 10.0.0.1 --user deploy --location extern
cm infra list-hosts
# 固定项（固定需要可选的 GUI；CLI 仅只读）
cm pinned # 所有固定项为 Markdown
cm pinned --project myapp # 全局 + 项目范围的固定项
cm pinned --json # JSON 输出
```
> **注意：** 固定项是在可选的 [context-wolf-ui](https://github.com/DarkWolfCave/context-wolf-ui) GUI 中完成的。CLI 只能列出您在那里固定的项。没有安装 GUI 时，`cm pinned` 返回一个空列表（无错误）。
### MCP 服务器（Claude Code）
由 `bash setup.sh` 或 `cm setup-mcp` 自动配置。公开 44 种工具：`context_save`、`context_search`、`todo_add`、`infra_list_hosts`、`infra_add_host`、`note_save`、`now_add`、`now_list` 等。
参见 [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) 以获取完整列表。
<details>
<summary>手动 MCP 配置</summary>
添加到 `~/.claude.json`：
```json
{
"mcpServers": {
"context-manager": {
"command": "uv",
"args": ["--directory", "/path/to/context-wolf", "run", "cm-mcp"]
}
}
}
```
</details>
### 嵌入式工作器（语义搜索）
```bash
cm-embed batch # 处理所有未嵌入的条目
cm-embed stats # 显示嵌入式统计信息
```
要自动更新，请设置 cron 作业或 launchd 计时器（参见 `embedding_worker/cron_embed.sh`）。
## 隐私和令牌经济
**您的数据属于您。** ContextWolf 完全在您的基础设施上运行:
- **本地数据库** - 您机器上的 PostgreSQL、NAS 或树莓派。您存储的数据保留在您的基础设施上。（注意：您与 Claude 的对话仍通过 Anthropic 的 API 进行 - ContextWolf 不会更改这一点。）
- **本地嵌入** - 语义搜索使用轻量级 ONNX 模型（all-MiniLM-L6-v2，~90 MB）在您的 CPU 上运行。向量生成时无需 API 调用。
- **按需检索** - ContextWolf 不会将您的整个数据库注入 Claude 的上下文中。MCP 工具仅返回当前查询的相关结果（按全文搜索 + 向量相似性排名）。
**令牌开销：** 44 个 MCP 工具定义默认情况下是延迟的 - 仅在会话启动时加载工具名称。完整的模式仅在 Claude 实际使用工具时按需获取。实际数据仅在调用工具时检索。
## 架构
```
src/
├── core/ # 数据库、配置、后端（PostgreSQL）
├── domain/ # 业务逻辑（操作、搜索、会话）
├── features/ # 模块（代码片段、待办事项、笔记、基础设施、AI 指令）
└── cli/ # 参数解析器 + 命令处理程序 + 设置向导
mcp_server/ # MCP 集成（stdio，44 种工具）
embedding_worker/ # 基于 ONNX 的向量嵌入（all-MiniLM-L6-v2）
```
具有 4 层的 Clean Architecture：CLI → 功能 → 领域 → 核心。
依赖关系仅向内流动。
## 入口点
| 命令 | 描述 | 需要 |
|---------|-------------|----------|
| `cm` | CLI 工具 | 核心 |
| `cm-mcp` | MCP 服务器（stdio）| 核心 |
| `cm-embed` | 嵌入式工作器 | `[embeddings]` 额外 |
## 文档
- [docs/USER_GUIDE.md](docs/USER_GUIDE.md) - 入门指南
- [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) - MCP 工具参考（44 种工具）
- [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) - 完整的 CLI 命令参考
- [CHANGELOG.md](CHANGELOG.md) - 版本历史
## 背景
ContextWolf 最初是一个简单的 CLI 工具，帮助我跨 Claude Code 会话保持上下文。没有 MCP，没有向量搜索 - 只需保存和检索决策，以免重复自己。
它从那里开始，一次一个功能，基于我需要的下一个功能：笔记、待办事项、基础设施跟踪、代码片段、语义搜索。我在生产环境中使用早期版本相当长一段时间，直到几个人建议我应该公开它。这导致了 V5 - 清洁和重构以发布到开源。
也就是说，这是一个个人项目，经过多个版本有机增长。可能仍然存在粗糙的边缘或早期迭代遗留的代码。如果您发现某些内容损坏或可改进，请 [打开问题](https://github.com/DarkWolfCave/context-wolf/issues) 或提交 PR。欢迎贡献。
## 许可证
MIT - 有关详细信息，请参见 [LICENSE](LICENSE)。
