ContextLib

ContextLib

すべてのエージェントセッションが終わった後も残る、プロジェクトライブラリです。

_{サンプルライブラリ（架空のプロジェクト）の実際のスクリーンショットです。}

ctxlib セッション：オーナーの決定事項は current に反映され、エージェントの学びは inbox で待機し、シークレットは拒否され、doctor は合格します。

各プロジェクトのナレッジ（決定事項、要件、事実、学び、用語集、情報源、返却された成果物）は、簡単なフロントマターを含むプレーンな Markdown ファイルとして、プロジェクトごとに1つのフォルダーに保存されます。フォルダーは外付け SSD に置くこともできます。Finder だけでプロジェクトを理解できます。エージェントは CLI（ctxlib）と MCP サーバー（context_* ツール）を通じて同じファイルを読み書きします。データベースがある場合も、ファイルから再構築される検索インデックスにすぎず、信頼できる唯一の情報源ではありません。

これは、AgentBrain のコンテキストプラグインのオープンコアです。

Python パッケージは agentbrain_contextlib です。CLI は ctxlib です。Python 3.9 以降に対応し、標準ライブラリのみを使用します。Git は任意です。

その理由

エージェントのセッションは終了します。チャットログは古くなります。モデルしか解析できないストアは、飛行機の中で初めて 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	証拠の状態と置き換えの履歴を含むレコードを1件表示します
search PROJECT QUERY [--type] [--all]	再構築可能なインデックスを検索します
brief PROJECT	常時読み込まれる要約（≤ 8192 bytes）を表示します
supersede PROJECT OLD NEW --reason TEXT --author ID	古いレコードを superseded としてマークし、ファイルを移動して、本文のハッシュを保持します
review PROJECT ID confirm|retire --note TEXT --author ID	レコードを確認するか、廃止します
inbox PROJECT	提案されたレコードを一覧表示します
accept PROJECT ID --author ID	inbox → current に移動します
reject PROJECT ID --reason TEXT --author ID	inbox → rejected に移動します
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]	プロジェクトを ZIP 形式でエクスポートします
import BUNDLE	ZIP をインポートします
doctor [PROJECT] [--ten-minute]	平易な言葉でヘルスチェックを行います
sync	ライブラリが git リポジトリの場合は git pull / git push を実行し、それ以外の場合はメッセージを表示して何もしません
mcp --identity ID	Stdio MCP サーバーです。ID はプロセスの実行中、固定されます

タイプ：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。

ID は起動時に固定されます。ツールは別の ID として書き込めません。エラーは 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 形式のフロントマター（スカラー、引用符付き文字列、スカラーのリスト、フラットなマップのリスト）で始まり、その後に Markdown 本文が続きます。本文のハッシュはフロントマターに保存され、本文は書き換えられません。

---
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 で実行する

イメージは Apple シリコンと Intel 向けに ghcr.io/willykeenan/agentbrain-contextlib で公開されています。ライブラリを /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