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                │  Future
│  (Romance system, personality growth)   │
├─────────────────────────────────────────┤
│  Layer 4a: Game Systems                │  Future
│  (Ranking, rarity, XP, visualization)   │
├─────────────────────────────────────────┤
│  Layer 3: User Evaluation              │  Future
│  (Personality diagnosis from patterns)  │
├─────────────────────────────────────────┤
│  Layer 2: AI Memory                    │  Future
│  (Claude interpretation, priority_score)│
├─────────────────────────────────────────┤
│  Layer 1: Pure Memory Storage          │  ✅ Current
│  (SQLite, ULID, CRUD operations)       │
└─────────────────────────────────────────┘

Layer 1: Pure Memory Storage (Current)

Status: ✅ Implemented & Tested

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 (Planned)

Status: 🔵 Planned

Purpose

Claudeが記憶内容を解釈し、重要度を評価。

Extended Data Model

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

    // Layer 2 additions
    pub interpreted_content: String,  // Claude's interpretation
    pub priority_score: f32,          // 0.0 - 1.0
    pub psychological_factors: PsychologicalFactors,
}

pub struct PsychologicalFactors {
    pub emotional_weight: f32,    // 0.0 - 1.0
    pub personal_relevance: f32,  // 0.0 - 1.0
    pub novelty: f32,             // 0.0 - 1.0
    pub utility: f32,             // 0.0 - 1.0
}

MCP Tools (Additional)

• create_memory_with_ai - Create with Claude interpretation
• reinterpret_memory - Re-evaluate existing memory
• get_high_priority - Get memories above threshold

Implementation Strategy

• Feature flag: --features ai-memory
• Backward compatible with Layer 1
• Claude Code does interpretation (no external API)

---

Layer 3: User Evaluation (Planned)

Status: 🔵 Planned

Purpose

メモリパターンからユーザーの性格を診断。

Diagnosis Types

pub enum DiagnosisType {
    Innovator,      // 革新者
    Philosopher,    // 哲学者
    Pragmatist,     // 実用主義者
    Explorer,       // 探検家
    Protector,      // 保護者
    Visionary,      // 未来志向
}

Analysis

• Memory content patterns
• Priority score distribution
• Creation frequency
• Topic diversity

MCP Tools (Additional)

• diagnose_user - Run personality diagnosis
• get_user_profile - Get analysis summary

---

Layer 4a: Game Systems (Planned)

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 (Planned)

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 (Next)

• Add AI interpretation fields to schema
• Implement priority scoring logic
• Create create_memory_with_ai tool
• Update MCP server
• Write tests for AI features

Phase 3: Layers 3-4 (Future)

• User diagnosis system
• Game mechanics
• Companion system

Phase 4: Layer 5 (Future)

• Sharing mechanisms
• Public/private modes

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-05 Current Layer: 1