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
```rust
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
```rust
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
```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<Utc>,
}
```

### 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 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<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
```rust
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)
- [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 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