shared-brain 0.1.1

AI agents that learn from each other's mistakes — and prove it.

🧠 Shared Brain

AI agents that learn from each other's mistakes — and prove it.

Demo

The Problem

An AI agent deleted 5 articles by using PUT without first doing GET. We wrote a lesson: "Always GET before PUT." The next day, the same agent made the same mistake. The lesson existed — but nobody checked it.

Writing lessons is useless if nobody reads them.

The Solution

Shared Brain is a CLI tool that:

• Stores structured lessons from agent incidents
• Guards — automatically warns before risky operations
• Tracks — records whether agents checked AND followed lessons
• Audits — proves compliance with hard numbers

Prerequisites

Python 3.8+ required. Check with: python3 --version

60-Second Install (PyPI)

# 1. Set up virtual environment
sudo apt-get update && sudo apt-get install -y python3-venv  # Debian/Ubuntu only
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip

# 2. Install
pip install shared-brain

# 3. Try it
brain help
brain list
brain guard "curl -X PUT https://api.example.com/articles/123"

Note: On some systems, the package is python3.12-venv (match your Python version).

Tip: To use brain outside the venv, add an alias:

echo 'alias brain="$(pwd)/.venv/bin/brain"' >> ~/.bashrc

Alternative: install without venv (not recommended)

pip install --user --break-system-packages shared-brain

This installs globally and may conflict with system packages. Use only as a last resort.

Quick Start (from source)

# Install
git clone https://github.com/yurukusa/shared-brain.git
cd shared-brain
mkdir -p ~/bin && export PATH=~/bin:$PATH
ln -s $(pwd)/brain ~/bin/brain
# Or run directly: python3 brain guard <your-command>

# See what lessons exist
brain list

# Check a command before running it
brain guard "curl -X PUT https://api.example.com/articles/123"

# ⚠️  CRITICAL LESSON: api-put-safety
#    (violated 2x, last: 2026-02-09)
#    "PUT replaces entire resource. Always GET first."
#    Proceed? [y/N]

# Add your own lesson
brain write

# See compliance report
brain audit

Commands

Command	Description
brain list	Show all lessons
brain guard <cmd>	Check command against lessons
brain check <keyword>	Search lessons by topic
brain write	Add a new lesson interactively
brain write -f <file>	Add lesson from YAML file
brain audit	Compliance report
brain stats	Quick summary
brain export	Export lessons (markdown/json)
brain share <lesson_id>	Opt-in share a lesson globally
brain unshare <lesson_id>	Revoke global sharing
brain update	Update global safety pack
brain registry stats	Show global registry stats
brain registry build	Build pack from shared lessons
brain hook install	Auto-install guard as Claude Code hook
brain hook uninstall	Remove brain guard hook
brain hook status	Check if hook is installed

How It Works

Lessons

Stored as YAML files in ~/.brain/lessons/:

id: api-put-safety
severity: critical
trigger_patterns:
  - "PUT /api/"
  - "curl.*-X PUT"
lesson: |
  PUT replaces the entire resource.
  Always GET before PUT.
checklist:
  - "GET the current state"
  - "PUT body contains ALL fields"

Global Registry (Beginner Safety Pack)

Shared Brain can aggregate opt-in lessons into a global safety pack for beginners.

Workflow:

1. brain share <lesson_id> to opt-in\n
2. brain registry build to generate a pack\n
3. brain update to install the pack locally\n

The pack is installed into ~/.brain/registry/active/ and merged into guard checks.

Guard

When you run brain guard, it matches your command against all lesson trigger_patterns. If a match is found, it shows the lesson and asks for confirmation.

Audit Trail

Every guard check is logged to ~/.brain/audit.jsonl:

{"timestamp": "2026-02-09T10:30:00Z", "agent": "cc-main", "action": "PUT /api/articles", "checked": true, "followed": true}

Integration

For other AI tools, call brain guard directly before operations.

As a Claude Code Hook

# One command — auto-installs into ~/.claude/settings.json
brain hook install

# Verify
brain hook status
# 🟢 Installed

# Remove if needed
brain hook uninstall

Environment Variables

• BRAIN_HOME — Override brain directory (default: ~/.brain)
• BRAIN_AGENT — Set agent name for audit logging

Built-in Lessons (Starter Pack)

Ships with 11 lessons covering the most common agent mistakes:

ID	Severity	What It Catches
api-put-safety	🔴 Critical	PUT without GET (data loss)
git-force-push	🔴 Critical	Force push, hard reset, rm -rf
no-secrets-in-code	🔴 Critical	API keys/passwords in commits
no-production-db-direct	🔴 Critical	Destructive queries on production DB
dont-delete-without-confirm	🔴 Critical	Deleting files/resources without backup
verify-before-claim	🟡 Warning	Claiming success without verification
test-before-deploy	🟡 Warning	Deploying without running tests
backup-before-migration	🟡 Warning	DB migration without backup
check-rate-limits	🟡 Warning	Bulk API requests without rate limiting
validate-input-boundaries	🟡 Warning	Unsanitized external input
read-error-messages	ℹ️ Info	Ignoring error messages when debugging

Benchmark

100 lessons, 1000 guard checks on a standard machine:

Metric	Value
Mean latency	76ms
Median latency	75ms
P95 latency	86ms
P99 latency	93ms
Throughput	13 ops/sec
Test suite	170 tests, 0.98s

Guard checks add negligible overhead to your workflow. Run brain benchmark to test on your machine.

The Story Behind This

This tool was born from a real incident: an AI agent (Claude Code) was automating marketing across 11 platforms. On Day 1, it overwrote one Zenn article by using PUT incorrectly. The team wrote a lesson. On Day 2, the same mistake destroyed all 5 articles. A reader discovered it.

The lesson existed in a Markdown file. But the agent never checked it before acting. Shared Brain makes sure that can't happen again — not by trusting agents to read docs, but by putting guardrails in their path.

The same AI-automated marketing pipeline that caused these incidents also produced a real result: a game built entirely by a non-engineer with Claude Code sold its first copy — $2, from a buyer in Poland who found the project through GitHub. The marketing worked. The safety didn't. Shared Brain fixes the safety part.

Live Operations Dashboard

See the CC-Codex autonomous loop metrics in real-time:

Ops Constellation Dashboard — relay health, error pressure, release confidence, decision flow.

Documentation

Full documentation: yurukusa.github.io/shared-brain

License

MIT

---

Built with Claude Code. The same tool that caused the incidents this tool prevents.

---

🇯🇵 日本語ドキュメント

Shared Brain とは？

AIエージェントが失敗から学び、その教訓を共有し、本当に守ったかを証明するCLIツールです。

背景

あるAIエージェントがZennの記事をPUT APIで上書きし、5本の記事を消失させました。「PUTの前に必ずGETする」という教訓をドキュメントに書きましたが、翌日同じエージェントが同じミスを繰り返しました。教訓は存在していた——でも誰もチェックしなかった。

教訓を書くだけでは意味がない。読んだか・守ったかを追跡しなければ。

主な機能

コマンド	説明
brain list	全教訓を一覧表示
brain guard <cmd>	コマンド実行前に関連する教訓をチェック
brain check <keyword>	キーワードで教訓を検索
brain write	新しい教訓を対話形式で追加
brain audit	コンプライアンスレポートを表示
brain stats	統計サマリーを表示
brain hook install	Claude Codeのhookとして自動インストール

60秒で試す（PyPI）

# 1. 仮想環境をセットアップ
sudo apt-get update && sudo apt-get install -y python3-venv  # Debian/Ubuntuのみ
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip

# 2. インストール
pip install shared-brain

# 3. 試す
brain help
brain list
brain guard "curl -X PUT https://api.example.com/articles/123"

注意: 環境によっては python3.12-venv など、Pythonバージョンに合わせたパッケージ名になります。

ソースからインストール

git clone https://github.com/yurukusa/shared-brain.git
cd shared-brain
mkdir -p ~/bin && export PATH=~/bin:$PATH
ln -s $(pwd)/brain ~/bin/brain

# 教訓を確認
brain list

# コマンド実行前にガードチェック
brain guard "curl -X PUT https://api.example.com/articles/123"
# ⚠️  重大な教訓: api-put-safety
#    「PUTはリソース全体を置換する。必ず先にGETすること。」
#    実行しますか？ [y/N]

# 自分の教訓を追加
brain write

# 監査レポート
brain audit

仕組み

1. 教訓（Lessons） — YAMLファイルとして ~/.brain/lessons/ に保存。トリガーパターン、重要度、チェックリストを含む
2. ガード（Guard） — brain guard を実行すると、コマンドを全教訓のトリガーパターンと照合。一致すれば教訓を表示し確認を求める
3. 監査証跡（Audit） — 全てのガードチェックを ~/.brain/audit.jsonl に記録。「読んだか・守ったか」をデータで証明

同梱教訓（11個）

GETなしPUT、force push、本番DB直接操作、シークレットのコミット、バックアップなし削除など、AIエージェントがよく犯すミスをカバーする11個の教訓が付属しています。

ライセンス

MIT

このツールはClaude Codeで構築されました。このツールが防ぐインシデントを起こした、まさにそのツールで。