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 4b: AI Companion                │  🔵 Planned
│  (Romance system, personality growth)   │
├─────────────────────────────────────────┤
│  Layer 4a: Game Systems                │  🔵 Planned
│  (Ranking, rarity, XP, visualization)   │
├─────────────────────────────────────────┤
│  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

pub struct Memory {
    pub id: String,              // ULID
    pub content: String,         // User content
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

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 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

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 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/           # Layer 1: Pure storage
├── ai/             # Layer 2: AI features (future)
├── evaluation/     # Layer 3: User diagnosis (future)
├── game/           # Layer 4a: Game systems (future)
├── companion/      # Layer 4b: Companion (future)
└── mcp/            # MCP server (all layers)

---

Version: 0.2.0 Last Updated: 2025-11-06 Current Status: Layers 1-3 Complete, Layer 4 Planned