AIエージェントは同じミスを繰り返します。セッション間であなたの好みを忘れてしまいます。繰り返しから学習することはありません。

instinctはこれを解決します。エージェントのセッションからパターンを観察し、時間の経過とともに信頼度を追跡し、繰り返し発生するパターンをエージェントが従う提案へと自動的に昇格させます。あなたが同じことを繰り返す必要はありません。

MCP互換エージェントであれば何でも動作します：Claude Code、Cursor、Windsurf、Goose、Codexなど。

仕組み

         observe           track            promote           suggest
        ┌───────┐       ┌───────┐        ┌───────┐        ┌───────┐
  You   │Record │  +1   │ Count │  >=5   │Mature │  >=10  │ Rule  │
  work  │pattern├──────>│ hits  ├───────>│suggest├───────>│ auto- │
        └───────┘       └───────┘        └───────┘        │ apply │
                                                          └───────┘

観察 (Observe) — エージェントの作業中にパターン（ツールシーケンス、好み、繰り返し発生する修正）を記録します
追跡 (Track) — 再観察されるたびに信頼度が上がります
昇格 (Promote) — 信頼度 >= 5 で mature（提案対象）、>= 10 で rule（自動適用）になります
提案 (Suggest) — matureなパターンが、明示的な指示なしにエージェントの行動をガイドします

機能

自動昇格 — 信頼度しきい値に基づき、パターンは成熟度レベル（raw → mature → rule → universal）を自動的に昇格します
自動チェーン検出 — 観察タイムスタンプからシーケンシャルパターン（seq:A->B）を自動的に発見します。手動でのシーケンス定義は不要です (v1.4.0)
有効性スコアリング — 提案されたパターンがその後の観察で確認されたかどうかを追跡し、確認率を計算します (v1.4.0)
信頼度履歴 — 各パターンの信頼度が時間の経過とともにどのように進化したかの完全なタイムライン
プロジェクト横断学習 — 2つ以上のプロジェクトで観察されたルールは、自動的に universal レベルに昇格します
マルチプラットフォームエクスポート — ルールを CLAUDE.md、.cursorrules、.windsurfrules、または Codex 形式にエクスポートします
エージェントスキルエクスポート — ルールを agentskills.io と互換性のある SKILL.md としてエクスポートします
CLAUDE.md インジェクション — CLAUDE.md ファイルへのルールの注入/インポート（冪等）
ニア重複検出 — 類似パターンを見つけ、エイリアスを介してマージします
パターンエイリアス — 表記ゆれによる観察結果を正規のパターンにリダイレクトします
全文検索 — FTS5 を活用したパターン、メタデータ、説明の全文検索
ガベージコレクション — 古いパターンの減衰、重複のマージ、孤立したデータのクリーンアップ、インデックスの再構築
バックアップと復元 — ヘルスチェック付きの SQLite レベルのバックアップと復元

インストール

pip install instinct-mcp

60秒で始める

まだインストールしていない場合は、pip install instinct-mcp を実行してください。
MCPクライアントに instinct を追加します。
Claude Code (ワンライナー):
```
claude mcp add instinct -- instinct serve
```
Cursor / Windsurf / Goose / その他のMCPクライアント — クライアントのMCP設定に追加してください:
```
{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve"]
    }
  }
}
```
パターンを1つ記録し、提案をリクエストします:

instinct observe "seq:test->fix->test"
instinct suggest

suggest が空のリストを返す場合は、繰り返し発生するパターンを観察し続けてください。信頼度が mature レベルに達すると提案が表示されます。

クイック検証

instinct observe "seq:test->fix->test"
instinct suggest

リポジトリの健全性

CIとCodeQLはプッシュおよびプルリクエスト時に実行されます
Dependabotが毎週の更新を追跡します（GitHub Actions + pip）
保護されたデフォルトブランチ（master）には、レビューと会話の解決が必要です

クイックスタート

1. エージェントに追加する

Claude Code — プロジェクトルートの .mcp.json に追加:

{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve"]
    }
  }
}

Codex CLI — ~/.codex/config.toml に追加:

[mcp_servers.instinct]
command = "instinct"
args = ["serve"]

Cursor / Windsurf — MCP設定に追加:

{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve", "--transport", "sse"]
    }
  }
}

2. 学習を見守る

作業を進めると、エージェントがパターンに気づき始めます:

Session 1:  observe("seq:test->fix->test")          → confidence 1 (raw)
Session 3:  observe("seq:test->fix->test")          → confidence 3 (raw)
Session 5:  observe("seq:test->fix->test")          → confidence 5 (mature ✓)
            suggest() → "When tests fail, apply fix and re-run tests"

十分な繰り返しが行われると、instinctはそのパターンを提案し始めます。エージェントがあなたの作業スタイルに適応します。

パターンの形式

# Tool sequences your agent repeats
instinct observe "seq:lint->fix->lint"
instinct observe "seq:build->test->deploy"

# Your preferences it should remember
instinct observe "pref:style=black" --cat preference
instinct observe "pref:commits=conventional" --cat preference

# Fixes it keeps rediscovering
instinct observe "fix:missing-import" --cat fix_pattern
instinct observe "fix:utf8-encoding-windows" --cat fix_pattern

# Tools that work better together
instinct observe "combo:pytest+coverage" --cat combo

命名規則

プレフィックス	用途	例
`seq:`	アクションシーケンス	`seq:lint->fix->lint`
`pref:`	ユーザーの好み	`pref:style=black`
`fix:`	繰り返し発生する修正	`fix:missing-import`
`combo:`	ツール組み合わせ	`combo:pytest+coverage`

成熟度レベル

レベル	信頼度	動作
raw	< 5	観察・保存済み、まだアクション不可
mature	>= 5	`suggest()` で返される — エージェントがガイドとして使用
rule	>= 10	`export_rules()` でエクスポートされる — 自動適用に十分な強度
universal	rule + 2プロジェクト	プロジェクト横断ルール、どこでも提案される

MCPツール

ツール	内容
`observe`	パターンを記録する（繰り返しで信頼度が自動増加）
`suggest`	現在の行動をガイドする成熟したパターンを取得する
`list_instincts`	フィルター付きで観察された全パターンを閲覧する
`get_instinct`	特定のパターンを検索する
`consolidate`	信頼度しきい値を超えたパターンを昇格させ、チェーンを検出する
`search_instincts`	パターンとメタデータの全文検索
`stats`	instinctストアの統計概要
`export_rules`	ルールレベルのパターンを構造化データとしてエクスポートする
`alias_pattern`	重複パターンをマージするためのエイリアスを作成する
`import_patterns`	辞書リストからパターンを一括インポートする
`session_summary`	自動統合機能付きのセッション終了スナップショット
`trending`	最近の期間で最も成長しているパターンを表示する
`export_claude_md`	CLAUDE.md 用にフォーマットされたルールをエクスポートする
`export_skill`	ルールをエージェントスキル（SKILL.md / agentskills.io）としてエクスポートする
`inject_claude_md`	CLAUDE.md ファイルにルールを注入する（冪等）
`find_duplicates`	マージ用の重複に近いパターンを見つける
`import_claude_md`	CLAUDE.md ファイルからパターンをインポートする
`history`	時間経過に伴うパターンの信頼度履歴
`export_platform`	Cursor、Windsurf、Codex などのルールをエクスポートする
`gc`	ガベージコレクション：減衰 + 重複排除 + 孤立データ削除 + FTS再構築
`detect_chains`	タイムスタンプからシーケンシャルパターンチェーンを自動検出する
`effectiveness`	提案の有効性スコア（確認率）を表示する

MCPプロンプト

プロンプト	内容
`instinct_rules`	エージェントの指示としてすべてのinstinctルールを取得する
`instinct_suggestions`	現在のプロジェクトの成熟したパターン提案を取得する

CLIリファレンス

# Core
instinct observe <pattern>       # Record/reinforce a pattern
instinct get <pattern>           # Look up a specific pattern
instinct list                    # List all instincts
instinct suggest                 # Get mature suggestions
instinct consolidate             # Auto-promote + detect chains
instinct stats                   # Summary statistics
instinct delete <pattern>        # Remove a pattern

# Analysis
instinct trending                # Fastest-growing patterns
instinct history <pattern>       # Confidence history over time
instinct effectiveness           # Suggestion confirmation rates
instinct detect-chains           # Auto-detect sequential chains

# Export
instinct export-rules            # Export rules as JSON
instinct export-claude-md        # Export rules as CLAUDE.md markdown
instinct export-skill            # Export rules as Agent Skill (SKILL.md)
instinct export-platform <fmt>   # Export for cursor/windsurf/codex
instinct export-all              # Export all instincts as JSON

# Import & Sync
instinct inject <path>           # Inject rules into CLAUDE.md (idempotent)
instinct import-claude-md <path> # Import patterns from CLAUDE.md
instinct import <file.json>      # Bulk import from JSON

# Maintenance
instinct gc                      # Garbage collection (decay + dedup + cleanup)
instinct decay                   # Reduce stale patterns
instinct dedup                   # Find/merge near-duplicate patterns
instinct alias <pat> <target>    # Create a pattern alias
instinct aliases                 # List all aliases

# Infrastructure
instinct serve                   # Start MCP server
instinct fingerprint             # Print project fingerprint for cwd
instinct backup                  # Create database backup
instinct restore <file>          # Restore from backup
instinct doctor                  # Run health checks

すべてのコマンドは構造化出力のために --json をサポートしています。

Observe オプション

instinct observe "seq:a->b" \
  --cat sequence              # Category: sequence|preference|fix_pattern|combo
  --source claude-code        # Which agent/tool recorded this
  --project auto              # Project fingerprint (auto-detected from cwd)
  --explain "why this matters"

サーバーオプション

instinct serve                              # stdio (default, for Claude Code)
instinct serve --transport sse              # SSE for remote/HTTP clients
instinct serve --transport streamable-http  # Streamable HTTP
instinct serve --port 3777                  # Custom port (default: 3777)

Pythonライブラリ

from instinct.store import InstinctStore

store = InstinctStore()  # uses ~/.instinct/instinct.db

# Record patterns
store.observe("seq:test->fix->test", source="my-tool")
store.observe("seq:test->fix->test")  # confidence = 2

# Query
suggestions = store.suggest()                     # mature+ patterns
results     = store.search("test")                # full-text search
rules       = store.export_rules()                # rule-level only

# Lifecycle
store.consolidate()                               # promote + detect chains
store.decay(days_inactive=90)                     # fade stale patterns

# Auto-chain detection
chains = store.detect_chains(window_minutes=5, min_occurrences=3)

# Effectiveness scoring
eff = store.effectiveness(days=30)

# Stats
print(store.stats())
# {'total': 42, 'raw': 30, 'mature': 10, 'rules': 2, 'avg_confidence': 4.2, ...}

カスタムデータベースパス

store = InstinctStore(db_path="/path/to/custom.db")

プロジェクト横断学習

instinctは作業ディレクトリをハッシュ化してプロジェクトのフィンガープリントを作成します。つまり：

プロジェクト固有のパターンは、そのプロジェクト内にいるときのみ提案されます
グローバルパターン（空のプロジェクトフィールド）はどこでも提案されます
ユニバーサルルール — 2つ以上のプロジェクトで rule レベルに達したパターンは自動的に universal に昇格し、すべてのプロジェクトで提案されます

# See your current project's fingerprint
instinct fingerprint
# → a1b2c3d4e5f6

ストレージ

データベース: SQLite (WALモード) ~/.instinct/instinct.db
依存関係: mcp>=1.0.0 のみ
Python: >= 3.11
設定: しきい値オーバーライド用のオプション ~/.instinct/config.toml

比較

	instinct	手動 CLAUDE.md	.cursorrules
自動学習	はい	いいえ	いいえ
セッション間メモリ	はい	はい	はい
信頼度スコアリング	はい	いいえ	いいえ
自動チェーン検出	はい	いいえ	いいえ
有効性追跡	はい	いいえ	いいえ
古いパターンの減衰	はい	いいえ	いいえ
プロジェクト横断学習	はい	いいえ	いいえ
エージェント横断動作	はい (MCP)	Claudeのみ	Cursorのみ
マルチプラットフォームエクスポート	はい	N/A	N/A
手動編集が必要	いいえ	はい	はい

ライセンス

MIT

instinct

目次

仕組み

機能