Skip to content
BranchesTags

Repository files navigation

Iris — AI Companion & Assistant Kernel (iris-mind)

AIコンパニオンであり、AIアシスタントとしても機能するKernel

Iris はAIコンパニオンであり、AIアシスタントとしても機能するKernel。自律的行動・タスク実行を担い、最終的には自己進化を目指す。Python 製で Ollama または OpenRouter 上で動作する。脳科学・神経科学の構造を参考にした層分割アーキテクチャを採用する。

Table of Contents

Background

脳科学・神経科学の構造を参考にした層分割アーキテクチャを採用する（詳細は docs/）。

注記: 脳科学マッピングは AI による文献調査を参考にした設計指針であり、厳密な解剖学的正確性を保証するものではありません。

Install

Prerequisites

  • Python 3.13+
  • Ollama（ローカル LLM 利用時）— qwen3.5:9b 等のモデルを事前に pull
  • OpenRouter API Key（OpenRouter 利用時）

Setup

git clone https://github.com/your-org/iris-mind.git
cd iris-mind

uv venv
uv sync

Usage

Configuration

config.yaml でプロバイダーとモデルを設定:

model:
  provider: ollama
  base_url: http://localhost:11434
  models:
    - name: qwen3.5:9b
      roles: default
session:
  host: 127.0.0.1
  port: 9876
  access_token: ""

OpenRouter 利用時は .env ファイルを作成:

OPENROUTER_API_KEY=sk-or-...

Starting Iris

uv run python main.py
uv run python main.py --verbose

Slash Commands

コマンド 説明
/help ヘルプ表示
/status カーネル状態表示
/shutdown グレースフルシャットダウン
/compact コンテキスト圧縮
/memory recent [n] 直近のエピソード記憶を n 件表示
/memory search <q> 意味記憶を検索
/memory clear [type] 記憶を消去（episodic/semantic）
/sessions アクティブセッション一覧
/ping LLM ヘルスチェック
/tools 登録ツール一覧
/llm LLM 設定情報
/state [path] [--history] [--json] システム状態クエリ
/events [n] [--type=TYPE] 最近のイベント一覧
/health ヘルスチェック
/report デバッグレポート出力
/debug help デバッグサブコマンド一覧
/debug on|off LLM 入出力キャプチャ切替
/debug list|last 直近の LLM キャプチャ
/debug show <id> 特定キャプチャ表示
/debug dump 全キャプチャをファイル出力

Architecture

flowchart TD
    subgraph Supervisor["Supervisor (main.py)"]
        Console["管理コンソール (stdin)  Ctrl+C"]
    end
    subgraph Kernel["kernel/ 脳幹"]
        KP["KernelProcess / PluginManager<br/>起動・停止・DI"]
        CMD["CommandHandler<br/>スラッシュコマンド"]
    end
    subgraph IO["io/ 視床"]
        IO_M["IOManager<br/>入出力中継"]
        GRPC["GrpcListener / SessionManager"]
    end
    subgraph Memory["memory/ 感覚野+皮質（3層構造）"]
        MM["MemoryManager<br/>記憶オーケストレーション"]
        SEN["sensory/ 感覚バッファ"]
        STM["short_term/ ワーキングメモリ"]
        LTM["long_term/ 長期記憶<br/>stores + VectorStore"]
    end
    subgraph Agency["agency/ 前頭前野+基底核+運動野"]
        IB["Internal Bus"]
        PL["planning/ 意思決定<br/>ProactiveScoring + ProactiveJudge"]
        EX["execution/ 行動実行<br/>ExecutionOrchestrator(LangGraph)<br/>ToolEngine + Inhibition"]
    end
    subgraph LLM["llm/ 言語処理基盤"]
        LB["LLMBridge / Provider<br/>LLMContextWindowManager"]
    end
    subgraph Event["event/ 神経路"]
        EB["Global EventBus"]
    end
    subgraph External["外部"]
        CLI["CLI / Web / 他言語Client"]
    end

    Console --> Kernel
    CLI <-->|gRPC 127.0.0.1:9876| IO
    EB --- IO
    EB --- Memory
    EB --- Agency
    EB --- Kernel
    EB --- LLM
    IB --- PL
    IB --- EX
Loading
  • Supervisor — Kernel プロセスの起動・監視・管理コンソール（main.py）
  • Kernel 層 — 脳幹。プロセス管理、PluginManager（DI+ライフサイクル）、スラッシュコマンド、TimerTick(5秒) 発行
  • IO 層 — 視床。gRPC入出力、セッション管理、認証
  • Memory 層 — 感覚野+皮質。感覚バッファ、短期/長期記憶（エピソード+意味+ベクトルハイブリッド検索）
  • Agency 層 — 前頭前野+基底核+運動野。PFC評価（ProactiveScoring）+意思決定、基底核抑制（Striatum+Gate）、行動実行（LangGraph状態マシン）
  • LLM 層 — 言語処理基盤。LLM接続（マルチプロバイダ）、ContextWindow圧縮
  • Event 層 — 神経路。全層を疎結合するグローバルEventBus

Client Guide

Iris に gRPC 接続して会話するクライアントを開発する場合:

  1. Client Guide — 応答パターン・自発発話・コマンド・期待される動作
  2. IPC Protocol Spec — ワイヤー形式・認証・プロトコル概要 
flowchart LR
    subgraph Ext["外部クライアント"]
        CLI["CLI / Web / 他言語"]
    end
    subgraph Iris["Iris Mind"]
        GRPC["GrpcListener :9876"]
        IO["IOManager"]
        EV["EventBus"]
    end
    CLI <-->|gRPC| GRPC
    GRPC --> IO
    IO --> EV
    EV --> IO --> GRPC --> CLI
Loading

Features

  • LLM 会話 — Ollama / OpenRouter / Google 等のマルチプロバイダ経由で会話
  • 自律発話 (Proactive) — PFCスコアリング（時間×記憶×文脈）＋基底核抑制制御で適切なタイミングに自発発話
  • 記憶システム — 感覚バッファ→短期記憶→長期記憶の3層。エピソード記憶 (JSONL)、意味記憶 (ChromaDB + BM25 ハイブリッド検索)、GoalStore長期目標管理
  • 会話履歴圧縮 — LLMContextWindowManager が token window 超過時に自動要約
  • 動的ツール拡張 — @tool() デコレータで実行時ツール追加
  • シングル / マルチモデルモード — 設定したモデル数・ロールに応じて自動切替（low/medium/highロール別ルーティング）
  • LangGraph 実行パイプライン — ExecutionOrchestrator によるLLM+ツールループの状態機械制御
  • 抑制制御 (Inhibition) — Striatum+Gate による実行権管理・クールダウン・プロアクティブ抑制
  • Room/Account — ルーム（会話場所）とアカウント（ユーザー識別）の分離。複数Roomで同一ユーザーと会話可能

Design Principles

  • Irisは個として1体のみ存在する — 複数Roomがあっても、Irisは1つの人格・感情を持つ
  • Roomは会話場所を増やすためのシステム — Irisの複製ではなく、会話の文脈を分けるための仕組み
  • 感情（Limbic）はグローバル — Roomごとの個別管理はしない。どのRoomでも同一の感情状態を共有
  • 関係性（Relationship）はユーザー単位 — Room単位ではなく、Account単位で親密度・信頼度を管理

Project Structure

iris-mind/
├── .agents/                     # コーディングエージェント用導線・Skills
├── .iris/                       # 設定・データ
│   ├── config/
│   │   └── system_prompt.md
│   └── data/                    # 記憶データ (runtime generated)
├── docs/                        # 設計ドキュメント
│   ├── how-it-works/            # 動作原理の詳細解説（6ファイル）
│   ├── architecture.md          # 全体アーキテクチャ
│   ├── agency-layer.md          # Agency 層設計
│   ├── memory-layer.md          # Memory 層設計
│   ├── io-layer.md              # IO 層設計
│   ├── kernel-layer.md          # Kernel 層設計
│   ├── config.md                # Config 設定一覧
│   └── external/                # 外部開発者向けドキュメント
│       ├── protocol-spec.md          # IPC プロトコル仕様 (概要・通信方式・エラー)
│       ├── protocol-types.md         # IPC データ型定義
│       ├── protocol-flows.md         # IPC 接続シーケンス・実装例
│       └── client-guide.md      # クライアント開発ガイド
├── iris/                        # アプリケーションコア
│   ├── agency/                  # 前頭前野+基底核+運動野
│   │   ├── planning/            # PFC: 意思決定・ProactiveScoring・Judge
│   │   ├── execution/           # 基底核+運動野: LangGraph状態マシン・ToolEngine
│   │   └── inhibition/          # 基底核: Striatum+Gate による実行権制御
│   ├── event/                   # 神経路: グローバル EventBus
│   ├── io/                      # 視床: TCP入出力・セッション・認証
│   ├── kernel/                  # 脳幹: プロセス管理・DI・コマンド
│   ├── llm/                     # LLM接続・ContextWindow管理
│   ├── memory/                  # 感覚野+皮質記憶（3層構造）
│   │   ├── sensory/             # 感覚バッファ（断片+raw入力 2系統）
│   │   ├── short_term/          # ワーキングメモリ
│   │   └── long_term/           # 長期記憶（EpisodicStore + SemanticStore + VectorStore + GoalStore）
│   └── tools/                   # @tool, ToolRegistry, ビルトイン
├── tests/                       # テストスイート
├── config.yaml                  # Iris 設定ファイル
└── main.py                      # Supervisor エントリーポイント

Development

Lint / Typecheck / Test

uv run ruff check .                   # lint
uv run ruff format --check .          # format check
uv run ruff check --fix .             # lint + auto-fix
uv run mypy .                         # type check
uv run pytest tests/                  # 全テスト実行

Capability Additions

  1. iris/tools/builtins/<name>/server.py に配置
  2. @tool() デコレータでツール定義（型ヒント→JSON Schema 自動生成）
  3. register(registry) 関数で registry.register_decorated(fn) をエクスポート
  4. .iris/config/iris_profile.md の該当セクションを更新

詳細は .agents/skills/capability-pattern/SKILL.md を参照。

Documentation

設計ドキュメントは docs/README.md から参照できます。

ドキュメント 内容
architecture.md 全体アーキテクチャ — 脳科学ベース層分割
agency-layer.md Agency 層 — 意思決定と行動実行
io-layer.md IO 層 — gRPC入出力・セッション管理
kernel-layer.md Kernel 層 — プロセス管理・PluginManager
memory-layer.md Memory 層 — 感覚野+皮質記憶（3層）
config.md Config 設定一覧
external/protocol-spec.md IPC プロトコル仕様 (gRPC)
external/client-guide.md クライアント開発ガイド
how-it-works/ 動作原理の詳細 — 計算式・条件分岐・Mermaid図を網羅（6ファイル）

API

外部 Client は gRPC（127.0.0.1:9876）で Iris に接続する。プロトコル仕様は IPC Protocol Spec を参照。

各層の内部インターフェースについては設計ドキュメントを参照。

Tech Stack

  • 言語: Python 3.13+
  • LLM: Ollama / OpenRouter / Google AI（マルチプロバイダ）
  • ベクトル検索: ChromaDB + ONNX MiniLM-L6-v2 + BM25 ハイブリッド
  • IPC: gRPC（HTTP/2, 双方向ストリーミング）
  • UI: Rich（TUI）, prompt_toolkit
  • LangGraph: ExecutionOrchestrator 実行パイプライン
  • テスト: pytest, ruff, mypy, pyright（uv run 経由）
  • パッケージ管理: uv

Contributing

PR 歓迎。 Issues で提案してからお送りください。

License

MIT © ibuibu

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages