Subconscious

subconscious-mcp

MCP エージェント向けのローカル優先のセマンティックメモリーです。stdio 経由で、想起、記憶、忘却、エコー、ドリフト検出、統計を行います。

サーバーはお使いのマシン上で MCP stdio プロセスとして動作します。エージェントが「このタスクを以前に見たことがあるか」と尋ね、見たことがあれば、作業を再実行することなく数ミリ秒で以前の回答を取得できる、6 つのツールを提供します。コウモリの反響定位に着想を得ています。想起に失敗した場合でも、最も近いメモリーがどれほど近かったかを報告します。echo ツールは回答を取得せずに近くのメモリーを検知し、すべての想起結果を記録するため、drift_report は、キャッシュされた回答が幅広すぎるクエリー群を取り込んでいる状態（初回入力時のセマンティックドリフト）を検出できます。

埋め込みには sentence-transformers/all-MiniLM-L6-v2（384 次元、CPU で動作）を使用します。ストレージには永続的なローカル ChromaDB コレクションを使用します。データがマシンの外に出ることはありません。

---

インストール

# From PyPI:
pip install subconscious-mcp

# Local development:
git clone https://github.com/vishaltorc/subconscious-mcp
cd subconscious-mcp
pip install -e ".[dev]"

インストール後は、どこからでもサーバーを実行できます。

subconscious-mcp --help

ツールを初めて呼び出すときに、埋め込みモデル（約 80MB）がローカルの Hugging Face キャッシュにダウンロードされます。2 回目以降の起動は高速です。

---

MCP クライアントの設定

Claude Desktop

設定ファイルを編集します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

mcpServers エントリーを追加します。

{
  "mcpServers": {
    "subconscious-mcp": {
      "command": "subconscious-mcp",
      "args": []
    }
  }
}

subconscious-mcp が Claude Desktop の PATH にない場合は、which subconscious-mcp で表示される絶対パスを使用します（例："command": "/Users/you/.local/bin/subconscious-mcp"）。

次に Claude Desktop を終了して再起動します。新しいツールが 🔌 インジケーターの下に表示されます。

Claude Code

オプション A。CLI から登録します（推奨）。

claude mcp add subconscious-mcp -- subconscious-mcp

オプション B。~/.claude.json（またはプロジェクトの .mcp.json）を編集して、次の内容を追加します。

{
  "mcpServers": {
    "subconscious-mcp": {
      "command": "subconscious-mcp",
      "args": [],
      "type": "stdio"
    }
  }
}

Claude Code のセッションを再読み込みすると、6 つのツールが利用できるようになります。

コピーしてそのまま使えるファイルは、examples/claude_desktop_config.json と examples/claude_code_config.json にあります。

---

アンビエントメモリ

明示的なツールに加えて、subconscious-mcp は Claude Code のフックを通じて、作業を自動的に記録できます。実行するコマンドは 3 つです。

pip install subconscious-mcp
claude mcp add subconscious-mcp -- subconscious-mcp
subconscious-mcp install-hooks

install-hooks は Claude Code の settings.json（デフォルトは ~/.claude/settings.json）を編集し、SessionStart フックと Stop フックの 2 つを登録します。既存ファイルを先にバックアップし（settings.json.bak.<timestamp>）、アトミックに書き込みます。また、冪等性があり、両方のフックがすでに存在する状態で再実行しても何も変更しません。書き込まずに予定されている変更を表示するには --dry-run を、別の設定ファイルを対象にするには --settings <path> を指定します。

記録される内容：セッション終了時に、Stop フックがトランスクリプトの末尾を読み取り、最後の「ユーザーの依頼からアシスタントの結果まで」のやり取りを抽出し、シークレットを編集したうえで（ベストエフォート。詳細はプライバシーを参照）、セッションごとに 1 件のエピソードを ~/.subconscious-mcp/data/context.db（通常の SQLite 受信トレイ）に書き込みます。フックが埋め込みモデルや ChromaDB を読み込むことはありません。MCP サーバーが次回起動時に、保留中のエピソードを埋め込み、取り込みます。

SessionStart が注入する内容：セッションの開始時に、このプロジェクトの直近のエピソード（最大 3 件）と、難易度の高い作業を始める前に recall を呼び出すよう促す一文が表示されます。Claude Code はそのテキストをコンテキストとして取り込みます。

プロジェクトごとの記録は自動的に行われます。名前空間は Git リポジトリのルートフォルダー名（それがない場合は現在のディレクトリのベース名）から導出されるため、設定しなくても各プロジェクトのエピソードと整理されたメモリは分離された状態に保たれます。上書きするには、設定で namespace を明示的に指定します。

---

プライバシー

データはすべてお使いのマシン内に保存されます。アンビエントフックが記録したエピソードは ~/.subconscious-mcp/data/context.db（通常の SQLite ファイル）に保存され、任意の SQL クライアントで確認できます。

sqlite3 ~/.subconscious-mcp/data/context.db 'SELECT ts, namespace, substr(content,1,80) FROM episodes ORDER BY ts DESC LIMIT 10'

エピソードを書き込む前に、記録されたテキストにはベストエフォートの編集処理が適用されます。現在、以下の形式がマスクされます。

• OpenAI / Anthropic の sk- キー（sk-ant-、sk-proj- を含む）
• PyPI トークン（pypi-）
• GitHub のクラシックトークン（ghp_、gho_、ghu_、ghs_、ghr_）およびファイングレインドトークン（github_pat_）
• Slack トークン（xoxb-、xoxa-、xoxp-、xoxr-、xoxs-）
• AWS アクセスキー ID（AKIA...）
• Bearer 認証トークン
• PEM 秘密鍵ヘッダー（-----BEGIN ... PRIVATE KEY-----）
• 変数名が KEY／TOKEN／SECRET／PASSWORD／PASSWD で終わる KEY=value 形式の環境変数の割り当て（値はマスクされ、名前は保持されます）

編集処理はベストエフォートであり、保証されるものではありません。検出できないことが分かっているもの：AWS シークレットアクセスキー（単独の 40 文字の文字列）、Bearer の接頭辞がない JWT、接続文字列内のパスワード（postgres://user:pass@host）、Stripe シークレットキー（sk_live_／sk_test_ のアンダースコア形式）、npm トークンです。記録機能は便利な機能として利用し、金庫のように扱わないでください。

記録機能を完全に無効にするには、設定で capture_enabled=false を設定するか、環境変数で SUBCONSCIOUS_CAPTURE_ENABLED=false を設定します。その場合、Stop フックは何も記録しません。

subconscious-mcp が保存したデータ（整理されたメモリ、エピソード、エコーログ、サーバーログ）をすべて 1 行のコマンドで消去するには：

rm -rf ~/.subconscious-mcp

---

ツール

recall(task, threshold=0.85, top_k=1)

以前に記憶したタスクを意味的に検索します。

arg	type	default	meaning
task	str	(必須)	検索するタスクの説明
threshold	float	0.85	ヒットとするためのコサイン類似度の最小値
top_k	int	1	検討する候補の数
tags	list[str]	null	省略可能。候補は少なくとも 1 つを共有している必要があります

戻り値：

{
  "hit": true,
  "similarity": 0.91,
  "answer": "...",
  "task_text": "...",
  "entry_id": "uuid",
  "stored_at": 1731000000.0,
  "tags": ["..."]
}

見つからなかった場合、hit は false、answer は null となり、similarity には**top_k 件の中で観測された最高の類似度**が設定されます。呼び出し側は、どの程度近かったかを確認できます。

tags が指定されている場合、見つからなかったときの similarity は、取得した範囲とタグフィルターの両方に該当する候補の中で最高の一致度を示します。タグに一致する項目が取得範囲の外にある場合でも 0.0 になることがあります（取得範囲を広げるには top_k を増やしてください）。

remember(task, answer, tags=[], ttl_seconds=null, skip_if_duplicate=false)

(task, answer) のペアを保存します。{stored, entry_id, embedding_dim} を返します。

ttl_seconds=null は有効期限なしを意味します。整数を渡すと、その秒数が経過した後、今後の検索対象からエントリが除外されます。

保存前に、最も近い厳選済みエントリを確認します。そのコサイン類似度が近似重複の範囲 [0.75, 0.92] に入る場合、結果には warning="near_duplicate" に加えて nearest_task、nearest_similarity、nearest_entry_id も含まれます（drift_report を補完する、書き込み時の初回登録におけるドリフト検出ガードです）。エントリは保存されます。代わりに書き込みをスキップするには、skip_if_duplicate=true を渡します。この場合、結果は同じ警告フィールドを含む {stored: false, ...} になります。アンビエントキャプチャのエピソードでは、この警告は発生しません。

範囲 [0.75, 0.92] は default_threshold（0.85）とは意図的に独立しており、リコールのしきい値をまたいでいます。そのため、リコールで返される場合も返されない場合もある近傍エントリに対して警告が発生します。0.92 を超える類似度は更新対象領域（基本的に同じタスク）として扱われ、意図的に警告されません。警告に対処するには、nearest_entry_id を指定して recall する（または検索する）ことで既存のエントリを確認し、統合、更新、または続行するかを判断します。

echo(task, top_k=5)

ソナーピング：最も近い有効期限内のエントリを、回答なしで返します。

引数	型	デフォルト	意味
task	str	（必須）	ピングに使用するタスクの説明
top_k	int	5	報告する最も近いエントリの数
tags	list[str]	null	任意。候補は少なくとも1つを共有する必要があります

戻り値：

{
  "count": 47,
  "echoes": [
    {"entry_id": "uuid", "similarity": 0.91, "task_text": "...", "stored_at": 1731000000.0, "tags": ["..."], "kind": "memory"}
  ]
}

リコールを実行する前に、タスクが既知の領域に該当するかを確認するために使います。回答は返されないため、エコーによって古くなった、または誤ったキャッシュ済み回答が伝播することはありません。エコー呼び出しはヒット率に含まれず、エコーログにも記録されません。

各エコーには kind が付与されます。厳選済みの remember エントリには "memory"、取り込まれたアンビエントキャプチャには "episode" が設定されます。エピソードは echo には表示されますが、recall の回答には含まれません。

drift_report(min_hits=3, min_spread=0.08)

エコーログを分析し、初回登録時のセマンティックドリフトの候補を特定します。異なるクエリ表現に対するリコールヒットが、広い類似度の範囲にわたるエントリが対象です。範囲が広い場合、1つのキャッシュ済み回答が、微妙に異なる解釈を含む可能性のある幅広いクエリ群を吸収していることを意味します（検出対象となる不具合の例は validation/results.md を参照してください）。

引数	型	デフォルト	意味
min_hits	int	3	エントリを対象とみなすために必要な、記録済みヒット数の最小値
min_spread	float	0.08	検出対象とするヒット類似度範囲の最小値（最大値 - 最小値）

戻り値：

{
  "analyzed_recalls": 412,
  "entries_with_hits": 38,
  "candidates": [
    {
      "entry_id": "uuid",
      "task_text": "Pull out all digits...",
      "still_stored": true,
      "hits": 5,
      "distinct_queries": 4,
      "similarity_min": 0.82,
      "similarity_max": 0.94,
      "similarity_spread": 0.12
    }
  ]
}

検出されたエントリはレビュー候補です。forget で削除する、より具体的なエントリに分割する、またはそのグループのリコールしきい値を引き上げてください。

forget(entry_id)

この ID のエントリを削除します。エントリが存在した場合は {"forgotten": true}、それ以外の場合は false を返します。

stats()

{"total_entries", "last_hit_at", "hit_rate_last_100"} を返します。hit_rate_last_100 は、直近100回のリコール呼び出しを対象とするスライディングウィンドウです。メモリが実際に役立っているかを確認するのに便利です。

---

設定

設定は次の優先順位で解決されます。

1. 環境変数（最優先）
2. ~/.subconscious-mcp/config.json
3. 組み込みのデフォルト値

キー	デフォルト値	環境変数
storage_dir	~/.subconscious-mcp/data	SUBCONSCIOUS_STORAGE_DIR
embedding_model	all-MiniLM-L6-v2	SUBCONSCIOUS_EMBEDDING_MODEL
default_threshold	0.85	SUBCONSCIOUS_DEFAULT_THRESHOLD
default_ttl_seconds	null
log_level	INFO	SUBCONSCIOUS_LOG_LEVEL
echo_log_enabled	true	SUBCONSCIOUS_ECHO_LOG_ENABLED
echo_log_max_bytes	5000000	SUBCONSCIOUS_ECHO_LOG_MAX_BYTES
namespace	default	SUBCONSCIOUS_NAMESPACE
capture_enabled	true	SUBCONSCIOUS_CAPTURE_ENABLED

サーバーを起動せずに、解決済みの設定を確認します。

subconscious-mcp --print-config

---

ディスクに書き込まれるファイル

~/.subconscious-mcp/
├── config.json            (optional, user-edited)
├── data/                  ChromaDB collection (sqlite + parquet)
│   ├── echo_log.jsonl     one line per recall: query, nearest entry, similarity, hit
│   └── context.db         SQLite inbox for ambient-capture episodes (shared across namespaces)
└── logs/server.log        rotating, 2MB x 3 backups

上のツリーはデフォルトの名前空間です。デフォルト以外の namespace を指定すると、エコーログのファイル名は echo_log_{namespace}.jsonl になります。一方、context.db は名前空間間で共有されます（各エピソードは独自の namespace 列を持ちます）。

エコーログは自動的に圧縮されます。echo_log_max_bytes（デフォルトは5MB）を超えると、古い半分が削除されます。完全に無効にするには SUBCONSCIOUS_ECHO_LOG_ENABLED=0 を設定します（これにより drift_report も無効になります）。

メモリ（エコーログを含む）を消去するには、rm -rf ~/.subconscious-mcp/data を実行します。

---

デモセッション

エージェントが recall を呼び出す（検索に失敗し、その後 remember を呼び出す）例と、後のターンで言い換えを使って再び recall を呼び出し、該当する結果を得る例については、examples/demo_session.md を参照してください。

---

アーキテクチャ

レイヤー構成（サーバー／ツール／メモリ／設定）、ChromaDB とコサイン類似度を採用した理由、TTL 戦略については、docs/architecture.md を参照してください。

---

トラブルシューティング

インストール後に subconscious-mcp: command not found と表示される シェルの PATH にインストール先が含まれていません。まず python -m subconscious_mcp.server --help を実行してパッケージが動作することを確認し、その後、MCP クライアントの設定で絶対パスを指定してください。

Claude Desktop に「Server disconnected」と表示される スタックトレースを確認するには、~/.subconscious-mcp/logs/server.log を確認してください。よくある原因は次のとおりです。

1. モデルのダウンロードに失敗した（初回起動時にオフラインだった）。ネットワークに接続して再実行してください。
2. storage_dir が読み取り専用のボリュームにあります。

最初の recall が遅い 初回の呼び出しでは、センテンストランスフォーマーモデルを遅延読み込みするため（一般的な CPU で約5秒）、時間がかかります。以降の呼び出しでは読み込み済みのモデルを再利用するため、数ミリ秒で応答します。

drift_report が候補を返さない 記録された recall が少なすぎる（各候補には、少なくとも2種類の異なる表現による min_hits 回のヒットが必要）か、エコーログが無効になっています（SUBCONSCIOUS_ECHO_LOG_ENABLED=0）。~/.subconscious-mcp/data/echo_log.jsonl が存在し、サイズが増えていることを確認してください。

明らかな言い換えでも Recall が見つからない しきい値を下げる（recall(task=..., threshold=0.7)）か、top_k を増やして候補を表示してください。all-MiniLM-L6-v2 は小型で高速なモデルです。より高品質なマッチングを行うには、SUBCONSCIOUS_EMBEDDING_MODEL=all-mpnet-base-v2 を設定してください。

sentence-transformers のダウンロードエラーでテストが失敗する オフラインであるか、プロキシ経由で接続しています。モデルを事前にダウンロード済みの場合は HF_HUB_OFFLINE=1 を設定してください。または、ネットワークに接続した状態で python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')" を一度実行してください。

---

ライセンス

MIT © 2026 Vishal Jayaprakash