brainctl — エージェントメモリ CLI

概要

brainctl はエージェントメモリの統一インターフェースです。1 つの SQLite ファイル (brain.db)、サーバー不要。すべてのエージェントで共有します。すべての書き込みは書き込みエージェントに帰属します。

• GitHub: https://github.com/TSchonleber/brainctl
• データベース: ~/agentmemory/db/brain.db (BRAIN_DB 環境変数でオーバーライド可能)
• CLI バイナリ: ~/bin/brainctl または ~/.local/bin/brainctl
• MCP サーバー: brainctl-mcp (201 ツール、同じ DB)

このマシンにすでにインストール済みです。インストール手順が必要な場合は、GitHub README を参照してください。

設計原則：モデル非依存

brainctl は LLM 依存性がゼロです。Anthropic、OpenAI、ベンダー SDK なし。純粋な SQLite + Python 標準ライブラリです。エージェントが考え、brainctl が記憶します。エージェントが LLM を使用した統合を望む場合、エージェントは独自の LLM を呼び出し、brainctl memory add で結果をフィードバックします。consolidate_memories() や compress_memories() などの関数は、オプションの llm_fn パラメータを受け入れます。呼び出し元は独自のものを注入できますが、brainctl は決して呼び出しません。

エージェント帰属

ALWAYS -a AGENT_NAME を渡して書き込みを帰属させます。例：

• -a my-agent — あなたのエージェントの一意の名前
• -a human — 手動/人間による入力
• -a unknown — 不明な場合のフォールバック

コマンド — クイックリファレンス

メモリ (永続的な事実)

# メモリを追加 (カテゴリ: identity, user, environment, convention, project, decision, lesson, preference, integration)
brainctl -a my-agent memory add "All timestamps in logs are UTC" -c convention

# メモリを検索
brainctl -a my-agent memory search "python version"

# 最近のメモリを一覧表示
brainctl -a my-agent memory list --limit 10

イベント (タイムスタンプ付きログ)

# イベントをログに記録 (タイプ: observation, result, decision, error, handoff, task_update, artifact, session_start, session_end, memory_promoted, memory_retired, warning, stale_context)
brainctl -a my-agent event add "Deployed v2.0 to production" -t result -p myproject

# イベントを検索
brainctl -a my-agent event search -q "deploy"

# 最近のイベント
brainctl -a my-agent event tail -n 20

エンティティ (型付きナレッジグラフ)

# エンティティを作成 (タイプ: agent, concept, document, event, location, organization, other, person, project, service, tool)
brainctl -a my-agent entity create "Alice" -t person -o "Engineer; Likes Python; Based in NYC"

# エンティティの詳細と関係を取得
brainctl -a my-agent entity get Alice

# 既存のエンティティに観察を追加
brainctl -a my-agent entity observe "Alice" "Now leads the infrastructure team"

# 有向関係を作成
brainctl -a my-agent entity relate Alice works_at Acme

# エンティティを検索
brainctl -a my-agent entity search "engineer"

決定

brainctl -a my-agent decision add "Switch to local inference" -r "Need local-first fallback"

クロステーブル検索

# メモリ + イベント + エンティティを一度に検索
brainctl -a my-agent search "deployment"

先制的メモリ (トリガー)

# 将来のクエリで発火するトリガーを作成
brainctl trigger create "Alice mentions vacation" -k vacation,alice -a "Remind about project deadline"

# クエリに対するトリガーをチェック
brainctl trigger check "alice is going on vacation"

レポート & Lint

brainctl report                        # 完全なブレインレポート
brainctl report --topic "deploy"       # トピック焦点
brainctl report --entity "Alice"       # エンティティの詳細分析

brainctl lint                          # ヘルスチェック (JSON)
brainctl lint --output text            # 人間が読める形式
brainctl lint --fix                    # 安全な問題を自動修正

統計

brainctl stats                         # DB 概要: テーブル数、サイズ、ヘルス

初期化 (初回セットアップ)

brainctl init                          # 完全なスキーマで brain.db を作成

出力形式

--output でトークン消費を制御します：

brainctl search "deploy" --output json      # デフォルト: きれいな JSON
brainctl search "deploy" --output compact   # ミニファイ JSON (~24% トークン削減)

感情トラッキング

機能的な感情状態 (フラストレーション、緊急性、満足度、混乱、自信、好奇心) — センチメント分析ではありません。メモリ形成と取得に影響します。

brainctl affect classify 'the deploy failed and rollback is stuck'
# → {"state": "frustration", "valence": -0.7, "arousal": 0.8, ...}

brainctl affect log 'finally resolved the outage after 4 hours'
brainctl affect check                  # 現在の状態と軌跡
brainctl affect monitor --watch        # ライブストリーム変更

統合エンジン

純粋な数学的メモリ保守 — LLM 不要。定期的または cron で実行します：

brainctl-consolidate decay             # 未使用メモリの信頼度減衰
brainctl-consolidate compress          # 冗長なメモリをマージ (純粋な文字列重複排除、LLM なし)
brainctl-consolidate promote           # 重要なイベントをメモリに昇格
brainctl-consolidate cycle             # 完全なメンテナンスサイクル

また含まれるもの: ヘブ式共取得強化、時間的降格、EWC 重要度ロック、リコールブースト、経験リプレイ。すべて純粋な SQLite 数学 — 外部呼び出しなし。

MCP サーバー (201 ツール)

アダプターが MCP をサポートしている場合、brainctl-mcp を MCP サーバーとして設定します：

{"mcpServers": {"brainctl": {"command": "brainctl-mcp"}}}

コアツール: memory_add, memory_search, event_add, event_search, entity_create, entity_get, entity_search, entity_observe, entity_relate, decision_add, search, stats, handoff_add, handoff_latest, trigger_check

メモリ、イベント、エンティティ、決定、トリガー、ハンドオフ、統合、感情、信念、時間推論などをカバーする合計 201 ツール。完全なリストと決定ツリーについては MCP_SERVER.md を参照してください。

すべてのツールはオプションの agent_id と profile (タスクスコープ検索プリセット) を受け入れます。CLI と MCP は完全に相互交換可能 — 同じ DB です。

チェックアウト後の位置づけ (タスクベースのエージェント)

タスクをチェックアウト後、自分の位置づけをします：

# 関連するコンテキストを検索
brainctl -a YOUR_AGENT search "keywords about your task"
brainctl -a YOUR_AGENT memory search "relevant topic"
brainctl event tail -n 10

# 作業完了後、ログに記録
brainctl -a YOUR_AGENT event add "what you did and the outcome" -t result -p PROJECT_NAME

# 永続的な何かを学んだ場合
brainctl -a YOUR_AGENT memory add "the fact or lesson" -c lesson

# 決定を下した場合
brainctl -a YOUR_AGENT decision add "what was decided" -r "why"

アーキテクチャ

brain.db (単一の SQLite ファイル、80+ テーブル)
├── memories          FTS5 フルテキスト + オプションのベクトル検索
├── events            タイムスタンプ付きログ (重要度スコアリング付き)
├── entities          型付きノード (person, project, tool, concept...)
├── knowledge_edges   任意のテーブル行間の有向関係
├── decisions         根拠付きで記録
├── memory_triggers   先制的メモリ (将来の条件で発火)
├── affect_log        エージェント単位の機能的感情状態トラッキング
└── 60+ more          統合、信念、ポリシー、エポック...

有効なカテゴリとタイプ

• メモリカテゴリ: identity, user, environment, convention, project, decision, lesson, preference, integration
• イベントタイプ: observation, result, decision, error, handoff, task_update, artifact, session_start, session_end, memory_promoted, memory_retired, warning, stale_context
• タスク状態: pending, in_progress, blocked, completed, cancelled
• タスク優先度: critical, high, medium, low

落とし穴

1. 名前空間の衝突: ~/agentmemory/ がディレクトリとして存在する場合、Python はそれをネームスペースパッケージとして認識する可能性があり、インストール済みの agentmemory ではなくなります。必要に応じて PYTHONPATH を明示的に設定してください。
2. FTS5 特殊文字: brainctl はクエリを自動的にサニタイズしますが、DB を直接呼び出す場合、検索語から . & | * " ' \ ( ) - @ ^ ? ! , ; :` を削除してください。
3. エージェント帰属: 常に -a を使用してください。帰属なしの書き込みは「unknown」にデフォルト設定され、追跡が難しくなります。
4. トークンコスト: 自動パイプラインで --output compact を使用して約 24% トークンを節約してください。
5. ベクトル検索はオプション: brainctl はエンベッディングなしで正常に機能します。セマンティック類似性検索にのみ必要です。
6. 破損したローカルインストール: ~/bin/brainctl がインポートエラーをスローする場合、ラッパーに循環インポートがあるかもしれません。リポジトリから直接実行します: cd ~/agentmemory && python3 -m agentmemory.cli または ~/.local/bin/brainctl を使用してください。
7. brainctl 自体をデバッグする場合: 破損したローカルラッパーを追いかけないでください — GitHub リポジトリ (https://github.com/TSchonleber/brainctl) で正規ソースを確認してください。ローカルインストールは ~/agentmemory/ ディレクトリとの名前空間衝突があります。
8. バッチコマンドなし: brainctl batch サブコマンドは削除されました (ベンダーロックイン)。大量の LLM 操作が必要な場合は、独自のエージェントコードで実行し、brainctl memory add で結果をフィードバックしてください。