# Architecture: Multi-Layer Memory System ## Design Philosophy aigptは、独立したレイヤーを積み重ねる設計です。各レイヤーは： - **独立性**: 単独で動作可能 - **接続性**: 他のレイヤーと連携可能 - **段階的**: 1つずつ実装・テスト ## Layer Overview ``` ┌─────────────────────────────────────────┐ │ Layer 5: Distribution & Sharing │ 🔵 Future │ (Game streaming, public/private) │ ├─────────────────────────────────────────┤ │ Layer 4b: AI Companion │ 🔵 Planned │ (Romance system, personality growth) │ ├─────────────────────────────────────────┤ │ Layer 4a: Game Systems │ 🔵 Planned │ (Ranking, rarity, XP, visualization) │ ├─────────────────────────────────────────┤ │ 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, CRUD operations) │ └─────────────────────────────────────────┘ ``` ## 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 ```rust pub struct Memory { pub id: String, // ULID pub content: String, // User content pub created_at: DateTime, pub updated_at: DateTime, } ``` ### 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 ```rust pub struct Memory { // Layer 1 fields pub id: String, pub content: String, pub created_at: DateTime, pub updated_at: DateTime, // Layer 2 additions pub ai_interpretation: Option, // Claude's interpretation pub priority_score: Option, // 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 ```rust 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, } ``` ### Big Five Model 心理学で最も信頼性の高い性格モデル（OCEAN）： - **O**penness: 新しい経験への開かれさ - **C**onscientiousness: 誠実性、計画性 - **E**xtraversion: 外向性 - **A**greeableness: 協調性 - **N**euroticism: 神経質さ ### 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 ```rust pub struct UserProfile { // 性格の本質（Big Five上位3特性） pub dominant_traits: Vec, // 関心の核心（最頻出トピック5個） pub core_interests: Vec, // 価値観の核心（高priority メモリから抽出、5個） pub core_values: Vec, // 重要メモリID（証拠、上位10個） pub key_memory_ids: Vec, // データ品質（0.0-1.0、メモリ数と分析有無で算出） pub data_quality: f32, pub last_updated: DateTime, } 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 4a: Game Systems **Status**: 🔵 **Planned** ### 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 ```rust pub struct GameMemory { // Previous layers... pub rarity: RarityLevel, pub xp_value: u32, pub discovered_at: DateTime, } ``` --- ## 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 ```rust pub struct Companion { pub id: String, pub name: String, pub personality: CompanionPersonality, pub relationship_level: u8, // 0-100 pub memories_shared: Vec, pub last_interaction: DateTime, } ``` --- ## 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) - [x] Core memory storage - [x] SQLite integration - [x] MCP server - [x] CLI interface - [x] Tests - [x] Documentation ### Phase 2: Layer 2 ✅ (Complete) - [x] Add AI interpretation fields to schema - [x] Implement priority scoring logic - [x] Create `create_ai_memory` tool - [x] Update MCP server - [x] Automatic schema migration - [x] Backward compatibility ### Phase 3: Layer 3 ✅ (Complete) - [x] Big Five personality model - [x] UserAnalysis data structure - [x] user_analyses table - [x] `save_user_analysis` tool - [x] `get_user_analysis` tool - [x] Historical tracking support ### Phase 3.5: Layer 3.5 ✅ (Complete) - [x] UserProfile data structure - [x] Integration logic (traits, interests, values) - [x] Frequency analysis for topic extraction - [x] Value keyword extraction - [x] Data quality scoring - [x] Caching mechanism (user_profiles table) - [x] Smart update triggers - [x] `get_profile` MCP tool ### Phase 4: Layers 4-5 (Next) - [ ] Game mechanics (Layer 4a) - [ ] Companion system (Layer 4b) - [ ] 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 │ ├── store.rs # Layer 1-3.5: SQLite operations │ ├── analysis.rs # Layer 3: UserAnalysis (Big Five) │ ├── profile.rs # Layer 3.5: UserProfile (integrated) │ ├── error.rs # Error types │ └── mod.rs # Module exports ├── mcp/ │ ├── base.rs # MCP server (all layers) │ └── mod.rs # Module exports ├── lib.rs # Library root └── main.rs # CLI application ``` **Future layers**: - Layer 4a: `src/game/` - Game systems - Layer 4b: `src/companion/` - Companion features - Layer 5: `src/distribution/` - Sharing mechanisms --- **Version**: 0.2.0 **Last Updated**: 2025-11-06 **Current Status**: Layers 1-3.5 Complete, Layer 4 Planned