gpt/docs/ARCHITECTURE.md

Architecture: Multi-Layer Memory System

Design Philosophy

aigptは、独立したレイヤーを積み重ねる設計です。各レイヤーは：

• 独立性: 単独で動作可能
• 接続性: 他のレイヤーと連携可能
• 段階的: 1つずつ実装・テスト

Layer Overview

┌─────────────────────────────────────────┐
│  Layer 5: Distribution & Sharing       │  🔵 Future
│  (Game streaming, public/private)      │
├─────────────────────────────────────────┤
│  Layer 4+: Extended Features          │  🔵 Planned
│  (Advanced game/companion systems)      │
├─────────────────────────────────────────┤
│  Layer 4: Relationship Inference       │  ✅ Complete
│  (Bond strength, relationship types)    │  (Optional)
├─────────────────────────────────────────┤
│  Layer 3.5: Integrated Profile         │  ✅ Complete
│  (Unified summary for AI consumption)   │
├─────────────────────────────────────────┤
│  Layer 3: User Evaluation              │  ✅ Complete
│  (Big Five personality analysis)        │
├─────────────────────────────────────────┤
│  Layer 2: AI Memory                    │  ✅ Complete
│  (Claude interpretation, priority_score)│
├─────────────────────────────────────────┤
│  Layer 1: Pure Memory Storage          │  ✅ Complete
│  (SQLite, ULID, entity tracking)       │
└─────────────────────────────────────────┘

Layer 1: Pure Memory Storage

Status: ✅ Complete

Purpose

正確なデータの保存と参照。シンプルで信頼できる基盤。

Technology Stack

• Database: SQLite with ACID guarantees
• IDs: ULID (time-sortable, 26 chars)
• Language: Rust with thiserror/anyhow
• Protocol: MCP (Model Context Protocol) via stdio

Data Model

pub struct Memory {
    pub id: String,                           // ULID
    pub content: String,                      // User content
    pub related_entities: Option<Vec<String>>, // Who/what this memory involves (Layer 4)
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

Note: related_entities added for Layer 4 support. Optional and backward compatible.

Operations

• create() - Insert new memory
• get(id) - Retrieve by ID
• update() - Update existing memory
• delete(id) - Remove memory
• list() - List all (sorted by created_at DESC)
• search(query) - Content-based search
• count() - Total count

File Structure

src/
├── core/
│   ├── error.rs    - Error types (thiserror)
│   ├── memory.rs   - Memory struct
│   ├── store.rs    - SQLite operations
│   └── mod.rs      - Module exports
├── mcp/
│   ├── base.rs     - MCP server
│   └── mod.rs      - Module exports
├── lib.rs          - Library root
└── main.rs         - CLI application

Storage

• Location: ~/.config/syui/ai/gpt/memory.db
• Schema: Single table with indexes on timestamps
• No migrations (fresh start for Layer 1)

---

Layer 2: AI Memory

Status: ✅ Complete

Purpose

Claudeが記憶内容を解釈し、重要度を評価。人間の記憶プロセス（記憶と同時に評価）を模倣。

Extended Data Model

pub struct Memory {
    // Layer 1 fields
    pub id: String,
    pub content: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,

    // Layer 2 additions
    pub ai_interpretation: Option<String>,  // Claude's interpretation
    pub priority_score: Option<f32>,        // 0.0 - 1.0
}

MCP Tools

• create_ai_memory - Create memory with AI interpretation and priority score
  • content: Memory content
  • ai_interpretation: Optional AI interpretation
  • priority_score: Optional priority (0.0-1.0)

Philosophy

"AIは進化しますが、ツールは進化しません" - AIが判断し、ツールは記録のみ。

Implementation

• Backward compatible with Layer 1 (Optional fields)
• Automatic schema migration from Layer 1
• Claude Code does interpretation (no external API)

---

Layer 3: User Evaluation

Status: ✅ Complete

Purpose

Layer 2のメモリパターンからユーザーの性格を分析。Big Five心理学モデルを使用。

Data Model

pub struct UserAnalysis {
    pub id: String,
    pub openness: f32,              // 0.0-1.0: 創造性、好奇心
    pub conscientiousness: f32,      // 0.0-1.0: 計画性、信頼性
    pub extraversion: f32,           // 0.0-1.0: 外向性、社交性
    pub agreeableness: f32,          // 0.0-1.0: 協調性、共感性
    pub neuroticism: f32,            // 0.0-1.0: 神経質さ（低い=安定）
    pub summary: String,             // 分析サマリー
    pub analyzed_at: DateTime<Utc>,
}

Big Five Model

心理学で最も信頼性の高い性格モデル（OCEAN）：

• Openness: 新しい経験への開かれさ
• Conscientiousness: 誠実性、計画性
• Extraversion: 外向性
• Agreeableness: 協調性
• Neuroticism: 神経質さ

Analysis Process

1. Layer 2メモリを蓄積
2. AIがパターンを分析（活動の種類、優先度の傾向など）
3. Big Fiveスコアを推測
4. 分析結果を保存

MCP Tools

• save_user_analysis - Save Big Five personality analysis
  • All 5 traits (0.0-1.0) + summary
• get_user_analysis - Get latest personality profile

Storage

• SQLite table: user_analyses
• Historical tracking: Compare analyses over time
• Helper methods: dominant_trait(), is_high()

---

Layer 3.5: Integrated Profile

Status: ✅ Complete

Purpose

Layer 1-3のデータを統合し、本質のみを抽出した統一プロファイル。「内部は複雑、表面はシンプル」の設計哲学を実現。

Problem Solved

Layer 1-3は独立して動作するが、バラバラのデータをAIが毎回解釈する必要があった。Layer 3.5は統合された1つの答えを提供し、効率性とシンプルさを両立。

Data Model

pub struct UserProfile {
    // 性格の本質（Big Five上位3特性）
    pub dominant_traits: Vec<TraitScore>,

    // 関心の核心（最頻出トピック5個）
    pub core_interests: Vec<String>,

    // 価値観の核心（高priority メモリから抽出、5個）
    pub core_values: Vec<String>,

    // 重要メモリID（証拠、上位10個）
    pub key_memory_ids: Vec<String>,

    // データ品質（0.0-1.0、メモリ数と分析有無で算出）
    pub data_quality: f32,

    pub last_updated: DateTime<Utc>,
}

pub struct TraitScore {
    pub name: String,    // "openness", "conscientiousness", etc.
    pub score: f32,      // 0.0-1.0
}

Integration Logic

1. Dominant Traits Extraction

• Big Fiveから上位3特性を自動選択
• スコアでソート

2. Core Interests Extraction

• メモリコンテンツから頻度分析
• AI interpretationは2倍の重み
• 上位5個を抽出

3. Core Values Extraction

• priority_score >= 0.7 のメモリから抽出
• 価値関連キーワードをフィルタリング
• 上位5個を抽出

4. Key Memories

• priority_scoreでソート
• 上位10個のIDを保持（証拠として）

5. Data Quality Score

• メモリ数: 50個で1.0（それ以下は比例）
• 性格分析あり: +0.5
• 加重平均で算出

Caching Strategy

Storage: SQLite user_profiles テーブル（1行のみ）

Update Triggers:

1. 10個以上の新しいメモリ追加
2. 新しい性格分析の保存
3. 7日以上経過

Flow:

get_profile()
  ↓
キャッシュ確認
  ↓
更新必要？ → No → キャッシュを返す
  ↓ Yes
Layer 1-3から再生成
  ↓
キャッシュ更新
  ↓
新しいプロファイルを返す

MCP Tools

• get_profile - Primary tool: Get integrated profile

Usage Pattern

通常使用（効率的）:

AI: get_profile()を呼ぶ
→ ユーザーの本質を理解
→ 適切な応答を生成

詳細確認（必要時）:

AI: get_profile()で概要を把握
→ 疑問がある
→ get_memory(id)で詳細確認
→ list_memories()で全体確認

Design Philosophy

"Internal complexity, external simplicity"

• 内部: 複雑な分析、頻度計算、重み付け
• 表面: シンプルな1つのJSON
• AIは基本的にget_profile()のみ参照
• 柔軟性: 詳細データへのアクセスも可能

Efficiency:

• 頻繁な再計算を避ける（キャッシング）
• 必要時のみ更新（スマートトリガー）
• AI が迷わない（1つの明確な答え）

---

Layer 4: Relationship Inference

Status: ✅ Complete (Optional feature)

Purpose

Layer 1-3.5のデータから関係性を推測。ゲーム、コンパニオン、VTuberなどの外部アプリケーション向け。

Activation

CLI引数で明示的に有効化:

aigpt server --enable-layer4

デフォルトでは無効（Layer 1-3.5のみ）。

Data Model

pub struct RelationshipInference {
    pub entity_id: String,
    pub interaction_count: u32,     // この entity とのメモリ数
    pub avg_priority: f32,          // 平均重要度
    pub days_since_last: i64,       // 最終接触からの日数
    pub bond_strength: f32,         // 関係の強さ (0.0-1.0)
    pub relationship_type: String,  // close_friend, friend, etc.
    pub confidence: f32,            // 推測の信頼度 (0.0-1.0)
    pub inferred_at: DateTime<Utc>,
}

Inference Logic

1. データ収集:

• Layer 1から entity に関連するメモリを抽出
• Layer 3.5からユーザー性格プロファイルを取得

2. Bond Strength 計算:

if user.extraversion < 0.5 {
    // 内向的: 少数の深い関係を好む
    // 回数が重要
    bond = interaction_count * 0.6 + avg_priority * 0.4
} else {
    // 外向的: 多数の浅い関係
    // 質が重要
    bond = interaction_count * 0.4 + avg_priority * 0.6
}

3. Relationship Type 分類:

• close_friend (0.8+): 非常に強い絆
• friend (0.6-0.8): 強い繋がり
• valued_acquaintance (0.4-0.6, 高priority): 重要だが親密ではない
• acquaintance (0.4-0.6): 定期的な接触
• regular_contact (0.2-0.4): 時々の接触
• distant (<0.2): 最小限の繋がり

4. Confidence 計算:

• データ量に基づく信頼度
• 1-2回: 0.2-0.3 (低)
• 5回: 0.5 (中)
• 10回以上: 0.8+ (高)

Design Philosophy

推測のみ、保存なし:

• 毎回Layer 1-3.5から計算
• キャッシュなし（シンプルさ優先）
• 後でキャッシング追加可能

独立性:

• Layer 1-3.5に依存
• Layer 1-3.5から独立（オプション機能）
• 有効化しなければ完全に無視される

外部アプリケーション向け:

• aigptはバックエンド（推測エンジン）
• フロントエンド（ゲーム、コンパニオン等）が表示を担当
• MCPで繋がる

MCP Tools

• get_relationship(entity_id) - 特定entity との関係を取得
• list_relationships(limit) - 全関係をbond_strength順でリスト

Usage Example

# サーバー起動（Layer 4有効）
aigpt server --enable-layer4

# 関係性取得
get_relationship({ entity_id: "alice" })

# 結果:
{
  "bond_strength": 0.82,
  "relationship_type": "close_friend",
  "interaction_count": 15,
  "confidence": 0.80
}

---

Layer 4+: Extended Features

Status: 🔵 Planned

Advanced game and companion system features to be designed based on Layer 4 foundation.

---

Layer 4a: Game Systems (Archive)

Status: 🔵 Archived Concept

Purpose

ゲーム的要素で記憶管理を楽しく。

Features

• Rarity Levels: Common → Uncommon → Rare → Epic → Legendary
• XP System: Memory creation earns XP
• Rankings: Based on total priority score
• Visualization: Game-style output formatting

Data Additions

pub struct GameMemory {
    // Previous layers...
    pub rarity: RarityLevel,
    pub xp_value: u32,
    pub discovered_at: DateTime<Utc>,
}

---

Layer 4b: AI Companion

Status: 🔵 Planned

Purpose

育成可能な恋愛コンパニオン。

Features

• Personality types (Tsundere, Kuudere, Genki, etc.)
• Relationship level (0-100)
• Memory-based interactions
• Growth through conversations

Data Model

pub struct Companion {
    pub id: String,
    pub name: String,
    pub personality: CompanionPersonality,
    pub relationship_level: u8,  // 0-100
    pub memories_shared: Vec<String>,
    pub last_interaction: DateTime<Utc>,
}

---

Layer 5: Distribution (Future)

Status: 🔵 Future Consideration

Purpose

ゲーム配信や共有機能。

Ideas

• Share memory rankings
• Export as shareable format
• Public/private memory modes
• Integration with streaming platforms

---

Implementation Strategy

Phase 1: Layer 1 ✅ (Complete)

• Core memory storage
• SQLite integration
• MCP server
• CLI interface
• Tests
• Documentation

Phase 2: Layer 2 ✅ (Complete)

• Add AI interpretation fields to schema
• Implement priority scoring logic
• Create create_ai_memory tool
• Update MCP server
• Automatic schema migration
• Backward compatibility

Phase 3: Layer 3 ✅ (Complete)

• Big Five personality model
• UserAnalysis data structure
• user_analyses table
• save_user_analysis tool
• get_user_analysis tool
• Historical tracking support

Phase 3.5: Layer 3.5 ✅ (Complete)

• UserProfile data structure
• Integration logic (traits, interests, values)
• Frequency analysis for topic extraction
• Value keyword extraction
• Data quality scoring
• Caching mechanism (user_profiles table)
• Smart update triggers
• get_profile MCP tool

Phase 4: Layer 4 ✅ (Complete)

• Add related_entities to Layer 1 Memory struct
• Database migration for backward compatibility
• RelationshipInference data structure
• Bond strength calculation (personality-aware)
• Relationship type classification
• Confidence scoring
• get_relationship MCP tool
• list_relationships MCP tool
• CLI control flag (--enable-layer4)
• Tool visibility control

Phase 5: Layers 4+ and 5 (Future)

• Extended game/companion features (Layer 4+)
• Sharing mechanisms (Layer 5)
• Public/private modes (Layer 5)

Design Principles

1. Simplicity First: Each layer adds complexity incrementally
2. Backward Compatibility: New layers don't break old ones
3. Feature Flags: Optional features via Cargo features
4. Independent Testing: Each layer has its own test suite
5. Clear Boundaries: Layers communicate through defined interfaces

Technology Choices

Why SQLite?

• ACID guarantees
• Better querying than JSON
• Built-in indexes
• Single-file deployment
• No server needed

Why ULID?

• Time-sortable (unlike UUID v4)
• Lexicographically sortable
• 26 characters (compact)
• No collision concerns

Why Rust?

• Memory safety
• Performance
• Excellent error handling
• Strong type system
• Great tooling (cargo, clippy)

Why MCP?

• Standard protocol for AI tools
• Works with Claude Code/Desktop
• Simple stdio-based communication
• No complex networking

Future Considerations

Potential Enhancements

• Full-text search (SQLite FTS5)
• Tag system
• Memory relationships/links
• Export/import functionality
• Multiple databases
• Encryption for sensitive data

Scalability

• Layer 1: Handles 10K+ memories easily
• Consider pagination for Layer 4 (UI display)
• Indexing strategy for search performance

Development Guidelines

Adding a New Layer

1. Design: Document data model and operations
2. Feature Flag: Add to Cargo.toml
3. Schema: Extend database schema (migrations)
4. Implementation: Write code in new module
5. Tests: Comprehensive test coverage
6. MCP Tools: Add new MCP tools if needed
7. Documentation: Update this file

Code Organization

src/
├── core/
│   ├── memory.rs      # Layer 1: Memory struct (with related_entities)
│   ├── store.rs       # Layer 1-4: SQLite operations
│   ├── analysis.rs    # Layer 3: UserAnalysis (Big Five)
│   ├── profile.rs     # Layer 3.5: UserProfile (integrated)
│   ├── relationship.rs # Layer 4: RelationshipInference
│   ├── error.rs       # Error types
│   └── mod.rs         # Module exports
├── mcp/
│   ├── base.rs        # MCP server (all layers, with --enable-layer4)
│   └── mod.rs         # Module exports
├── lib.rs             # Library root
└── main.rs            # CLI application (with layer4 flag)

Future layers:

• Layer 4+: src/game/ - Extended game/companion systems
• Layer 5: src/distribution/ - Sharing mechanisms

---

Version: 0.3.0 Last Updated: 2025-11-06 Current Status: Layers 1-4 Complete (Layer 4 opt-in with --enable-layer4)