Claude Codeに"潜在意識"を与える！セッションをまたいで学習し続けるAIバックグラウンドエージェント — claude-subconscious

アーキテクチャ・仕組み

claude-subconsciousは、Claude Codeのフック機能（特定のタイミングで外部スクリプトを実行する仕組み）を利用して動作します。4つのフックポイントで介入します：

• SessionStart: 新しいセッション開始時にLettaエージェントに通知
• UserPromptSubmit: プロンプト送信前にメモリ・メッセージを標準出力経由で注入（最大10秒）
• PreToolUse: ツール使用前に最新の更新をadditionalContextで注入
• Stop: セッション終了時にトランスクリプト（会話記録）を非同期でバックグラウンドワーカーに送信（最大120秒）

すべてのコンテンツは標準出力経由で注入され、CLAUDE.mdには一切書き込みません。

メモリブロック構成

デフォルトエージェントは8つのメモリブロックを管理：

動作モード

SDKツールアクセス

LETTA_SDK_TOOLS環境変数でエージェントのツール権限を制御：

• read-only（デフォルト）: Read, Grep, Glob, web_search, fetch_webpage
• full: 全ツール（Bash, Edit, Write, Task等）。Taskツールでサブエージェントの生成も可能
• off: メモリ操作のみ

対応モデル

自動検出・選択機能あり。優先順位：

1. anthropic/claude-sonnet-4-5（推奨）
2. openai/gpt-4.1-mini
3. anthropic/claude-haiku-4-5
4. openai/gpt-5.2
5. google_ai/gemini-3-flash
6. google_ai/gemini-2.5-flash

デフォルトはzai/glm-5（Letta Cloud上で無料）。LETTA_MODEL環境変数で手動指定も可能。

マルチプロジェクト対応

• エージェント設定は~/.letta/claude-subconscious/config.jsonにグローバル保存
• 各プロジェクトの.letta/claude/には会話マッピングのみ保存
• 1つのエージェントが複数プロジェクトの記憶を共有
• プロジェクトごとに別エージェントを使いたい場合はLETTA_AGENT_IDをdirenv等で切り替え

状態管理

• 永続データ: .letta/claude/conversations.json（セッションID↔会話IDマッピング）
• 一時データ: $TMPDIR/letta-claude-sync-$UID/（デバッグ用ログ）

セルフホスト対応

LETTA_BASE_URLを設定すれば自前のLettaサーバーでも利用可能（デフォルトはhttps://api.letta.com）。

ライセンス

MITライセンス（商用利用を含め自由に利用可能）。

注意点

• 実験的なプロジェクトであり、Claude Code（クローズドソース）を外部から拡張するアプローチ
• 初回使用時はエージェントの文脈が少ないため、数セッション使ってから効果が出る
• 完全にオープンソースでメモリファーストなコーディングエージェントが必要な場合はLetta Codeを推奨

Claude Codeプラグインとしてインストール

Claude Code内で以下のコマンドを実行します：

/plugin marketplace add letta-ai/claude-subconscious
/plugin install claude-subconscious@claude-subconscious

APIキーの設定（必須）

app.letta.com でAPIキーを取得し、環境変数に設定します：

export LETTA_API_KEY="your-api-key"

ソースからインストールする場合

git clone https://github.com/letta-ai/claude-subconscious.git
cd claude-subconscious
npm install

Claude Code内で有効化：

/plugin enable .

Linux環境の注意

/tmpが別ファイルシステムの場合、以下の回避策が必要：

mkdir -p ~/.claude/tmp
export TMPDIR="$HOME/.claude/tmp"