ContextLib

ContextLib

一个能跨越每次 Agent 会话持续存在的项目库。

_{示例项目库的真实截图（项目为虚构项目）。}

一次 ctxlib 会话：负责人的决策进入当前记录，Agent 的经验教训留在收件箱，机密内容遭到拒绝，doctor 检查通过。

每个项目的知识——决策、需求、事实、经验教训、术语表、来源和返回的工作成果——都以带有简短前置元数据块的纯 Markdown 文件形式存储，每个项目对应一个文件夹。这些文件夹可以存放在外置 SSD 上。只用 Finder，人也能了解一个项目。Agent 通过 CLI（ctxlib）和 MCP 服务（context_* 工具）读写相同的文件。任何数据库都只是由这些文件重建的搜索索引，绝不是事实来源。

它是 AgentBrain 上下文插件的开源核心。

Python 包为 agentbrain_contextlib。CLI 为 ctxlib。需要 Python 3.9+，且仅使用标准库。Git 可选。

为什么要用

Agent 会话终会结束。聊天记录会变得不可靠。一个只有模型才能解析的存储库，在你第一次于飞机上打开 Finder 时就会成为死胡同。

ContextLib 将持久内容保存为可阅读、比较差异、复制并带到另一台 Mac 的文件。搜索索引可以丢弃。Markdown 才是产品本身。

60 秒快速入门

pip install "git+https://github.com/willykeenan/agentbrain-contextlib"

ctxlib init ~/ContextLib --project lighthouse-app \
  --name "Lighthouse App" \
  --purpose "Harbor dashboard for lamp status, fog signals, and traffic"

ctxlib add lighthouse-app decision "Use keeper logs as lamp status" \
  --body "**Decision:** Lamp status comes from keeper logs, not AIS." \
  --author mara \
  --tag lamp --tag keeper-log

ctxlib brief lighthouse-app
ctxlib doctor lighthouse-app --ten-minute

库路径依次取 --library PATH、环境变量 CONTEXTLIB_ROOT，否则使用 ~/ContextLib。

可在 Finder 中直接打开、无需安装任何内容的完整示例位于 examples/sample-library/。从该目录下的 README 开始，然后查看项目 BRIEF，接着查看 decisions/INDEX.md。

完整演练：docs/QUICKSTART.md。

CLI（ctxlib）

ctxlib [--library PATH] COMMAND

命令	功能
init PATH [--project SLUG --name NAME --purpose TEXT]	创建一个库（并可选择创建第一个项目）
project add SLUG NAME [--purpose]	添加项目文件夹
project list	列出项目
add PROJECT TYPE TITLE (--body TEXT | --body-file F) --author ID [options]	写入一条记录（--evidence、--tag、--review-by、--approved-by）
get PROJECT ID	打印一条记录，包括证据状态和取代链
search PROJECT QUERY [--type] [--all]	搜索可重建的索引
brief PROJECT	打印始终加载的摘要（≤ 8192 字节）
supersede PROJECT OLD NEW --reason TEXT --author ID	将旧记录标记为已取代，移动文件并保留正文哈希
review PROJECT ID confirm|retire --note TEXT --author ID	确认或废弃一条记录
inbox PROJECT	列出提议的记录
accept PROJECT ID --author ID	将记录从收件箱移至当前记录
reject PROJECT ID --reason TEXT --author ID	将记录从收件箱移至已拒绝记录
due PROJECT	列出 review_by 已到期的记录
regen PROJECT|--all	重写 BRIEF、INDEX、GLOSSARY、TIMELINE、README
rebuild	根据文件重建 SQLite 搜索索引
capture PROJECT RESULT.json	将结果文件转换为 return（以及提议的经验教训）
import-md PROJECT FILE --type TYPE --author ID	将 Markdown 文件转换为记录
export PROJECT OUT_DIR [--include-private]	打包导出一个项目
import BUNDLE	导入一个 zip 文件
doctor [PROJECT] [--ten-minute]	使用通俗语言进行健康检查
sync	当库是 git 仓库时执行 git pull / git push；否则提示后不执行任何操作
mcp --identity ID	Stdio MCP 服务；身份对该进程固定不变

类型：decision、requirement、fact、lesson、glossary、source、return、brief-note。

MCP（context_* 工具）

ctxlib mcp --identity ID 是一个 stdio JSON-RPC 服务。协议版本：2024-11-05、2025-03-26、2025-06-18。

工具：context_brief、context_search、context_get、context_record、context_supersede、context_review_due、context_review、context_capture、context_export、context_import、context_status。

身份在启动时固定。工具无法以其他身份写入。错误会以 isError 结果返回。

Claude Code

{
  "mcpServers": {
    "contextlib": {
      "command": "ctxlib",
      "args": ["mcp", "--identity", "claude:project"],
      "env": { "CONTEXTLIB_ROOT": "/Volumes/SSD/ContextLib" }
    }
  }
}

Codex

{
  "mcpServers": {
    "contextlib": {
      "command": "ctxlib",
      "args": ["mcp", "--identity", "codex:project"],
      "env": { "CONTEXTLIB_ROOT": "/Volumes/SSD/ContextLib" }
    }
  }
}

Cursor

在 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（用户级）中：

{
  "mcpServers": {
    "contextlib": {
      "command": "ctxlib",
      "args": ["mcp", "--identity", "cursor:project"],
      "env": { "CONTEXTLIB_ROOT": "/Volumes/SSD/ContextLib" }
    }
  }
}

详情：docs/MCP.md。

记录格式

记录采用 UTF-8 Markdown 格式。开头是类似 YAML 的 front-matter 块（标量、带引号的字符串、标量列表、扁平映射列表），后接 Markdown 正文。正文哈希存储在 front-matter 中；正文不会被重写。

---
id: dec-20260926-7f3a
type: decision
title: Use plain files as the source of truth
status: current
project: lighthouse-app
scope: {lane: workstream, team: owner}
created: 2026-09-26T14:03:00Z
author: mara
approved_by: mara — "files first, database is only an index"
evidence:
  - {ref: "project:BRIEF.md"}
  - {ref: "url:https://example.com/x"}
supersedes: []
superseded_by: null
review_by: 2027-03-25
tags: [storage, library]
sensitivity: normal
body_sha256: "…"
---
**Decision:** …
**Why:** …
**Consequences:** …
**How to verify:** …

证据引用格式为 project:<relative path>、ssd:<relative path>、room:<name>#<seq>、url:<https url> 或 note:<text>。写入时会拒绝绝对主目录路径和机密信息。

ID 格式：<prefix>-<YYYYMMDD>-<4 hex>，前缀为 dec、req、fact、les、glo、src、ret、note。

文件格式：<YYYY-MM-DD>_<title-slug>_<id-suffix>.md。被取代的记录会移至 superseded/，正文哈希仍保持有效。

库目录结构

<library root>/
├── README.md              how to read this in 10 minutes
├── INDEX.md               one line per project
├── library.json           {"format": "contextlib/1", "library_id", "created"}
└── projects/<slug>/
    ├── README.md BRIEF.md GLOSSARY.md TIMELINE.md project.json
    ├── decisions/ requirements/ facts/ lessons/ glossary/ sources/ returns/
    │   ├── INDEX.md
    │   ├── <YYYY-MM-DD>_<title-slug>_<id-suffix>.md
    │   └── superseded/
    ├── inbox/             proposed records
    ├── exports/
    └── .contextlib/       ledger + rebuildable index.sqlite

关于将库保存在 SSD 上、在未连接状态下使用，以及在 Mac 之间移动：docs/SSD.md。

开发

PYTHONPATH=src python3 -m unittest discover -s tests
python3 tools/check.py packaging

Python 3.9+，仅使用标准库。请参阅 CONTRIBUTING.md 和 CHANGELOG.md。

Apache-2.0，版权所有 KE Studios。报告问题请参阅 SECURITY.md。

ContextLib 是 AgentBrain（agentrooms.io）的开源库层。

使用 Docker 运行

镜像发布于 ghcr.io/willykeenan/agentbrain-contextlib，支持 Apple silicon 和 Intel。将你的库挂载到 /library：

claude mcp add contextlib -- docker run -i --rm --user "$(id -u):$(id -g)" -v ~/ContextLib:/library ghcr.io/willykeenan/agentbrain-contextlib mcp --identity you