From 6906012c26044648a8cead812b3b009390df260b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 6 Nov 2025 08:00:38 +0000
Subject: [PATCH] Update documentation: reflect Layer 4 completion

- Update README.md with Layer 4 relationship inference features
- Add comprehensive Layer 4 section to ARCHITECTURE.md
- Update implementation strategy to show Phase 4 complete
- Add CLI control flag documentation (--enable-layer4)
- Update version to 0.3.0
- Document personality-aware bond strength calculation
- Add relationship type classification details
---
 README.md            |  71 +++++++++++++++++--
 docs/ARCHITECTURE.md | 162 ++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 207 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index b173a88..4c201b2 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 AI memory system with psychological analysis for Claude via MCP.
 
-**Current: Layers 1-3.5 Complete** - Memory storage, AI interpretation, personality analysis, and integrated profile.
+**Current: Layers 1-4 Complete** - Memory storage, AI interpretation, personality analysis, integrated profile, and relationship inference.
 
 ## Features
 
@@ -28,6 +28,12 @@ AI memory system with psychological analysis for Claude via MCP.
 - ⚡ **Smart Caching**: Auto-updates only when necessary
 - 🔍 **Flexible Access**: Detailed data still accessible when needed
 
+### Layer 4: Relationship Inference (Optional)
+- 🤝 **Relationship Tracking**: Track interactions with entities (people, characters, etc.)
+- 📊 **Bond Strength**: Infer relationship strength from memory patterns
+- 🎮 **Game Ready**: Foundation for companion apps, games, VTubers
+- 🔒 **Opt-in**: Enable only when needed with `--enable-layer4` flag
+
 ### General
 - 🛠️ **MCP Integration**: Works seamlessly with Claude Code
 - 🧪 **Well-tested**: Comprehensive test coverage
@@ -88,6 +94,10 @@ claude mcp add aigpt /path/to/aigpt/target/release/aigpt server
 ### Layer 3.5: Integrated Profile (1 tool)
 - `get_profile` - **Primary tool**: Get integrated user profile with essential summary
 
+### Layer 4: Relationship Inference (2 tools, requires `--enable-layer4`)
+- `get_relationship` - Get inferred relationship with specific entity
+- `list_relationships` - List all relationships sorted by bond strength
+
 ## Usage Examples in Claude Code
 
 ### Layer 1: Simple Memory
@@ -145,6 +155,51 @@ get_profile()
 - For specific details, AI can call `get_memory(id)`, `list_memories()`, etc.
 - Profile auto-updates when needed (10+ memories, new analysis, or 7+ days)
 
+### Layer 4: Relationship Inference (Optional, requires `--enable-layer4`)
+```
+# Create memories with entity tracking
+Memory::new_with_entities({
+  content: "Had lunch with Alice",
+  ai_interpretation: "Pleasant social interaction",
+  priority_score: 0.7,
+  related_entities: ["alice"]
+})
+
+# Get relationship inference
+get_relationship({ entity_id: "alice" })
+
+# Returns:
+{
+  "entity_id": "alice",
+  "interaction_count": 15,
+  "avg_priority": 0.75,
+  "days_since_last": 2,
+  "bond_strength": 0.82,
+  "relationship_type": "close_friend",
+  "confidence": 0.80
+}
+
+# List all relationships
+list_relationships({ limit: 5 })
+```
+
+**Relationship Types:**
+- `close_friend` (0.8+): Very strong bond
+- `friend` (0.6-0.8): Strong connection
+- `valued_acquaintance` (0.4-0.6, high priority): Important but not close
+- `acquaintance` (0.4-0.6): Regular contact
+- `regular_contact` (0.2-0.4): Occasional interaction
+- `distant` (<0.2): Minimal connection
+
+**Starting the Server:**
+```bash
+# Normal mode (Layer 1-3.5 only)
+aigpt server
+
+# With relationship features (Layer 1-4)
+aigpt server --enable-layer4
+```
+
 ## Big Five Personality Traits
 
 - **Openness**: Creativity, curiosity, openness to new experiences
@@ -163,17 +218,19 @@ All data stored in: `~/.config/syui/ai/gpt/memory.db`
 
 Multi-layer system design:
 
-- **Layer 1** ✅ Complete: Pure memory storage
+- **Layer 1** ✅ Complete: Pure memory storage (with entity tracking)
 - **Layer 2** ✅ Complete: AI interpretation with priority scoring
 - **Layer 3** ✅ Complete: Big Five personality analysis
 - **Layer 3.5** ✅ Complete: Integrated profile (unified summary)
-- **Layer 4** 🔵 Planned: Game systems and companion features
+- **Layer 4** ✅ Complete: Relationship inference (optional, `--enable-layer4`)
+- **Layer 4+** 🔵 Future: Extended game/companion features
 - **Layer 5** 🔵 Future: Distribution and sharing
 
-**Design Philosophy**: "Internal complexity, external simplicity"
-- Layers 1-3 handle detailed data collection and analysis
-- Layer 3.5 provides a simple, unified view for AI consumption
-- Detailed data remains accessible when needed
+**Design Philosophy**:
+- **"Internal complexity, external simplicity"**: Simple API, complex internals
+- **"AI judges, tool records"**: AI makes decisions, tool stores data
+- **Layered architecture**: Each layer independent but interconnected
+- **Optional features**: Core layers always active, advanced layers opt-in
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details.
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index b4b2ba9..4dd18c2 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -15,11 +15,11 @@ aigptは、独立したレイヤーを積み重ねる設計です。各レイヤ
 │  Layer 5: Distribution & Sharing       │  🔵 Future
 │  (Game streaming, public/private)      │
 ├─────────────────────────────────────────┤
-│  Layer 4b: AI Companion                │  🔵 Planned
-│  (Romance system, personality growth)   │
+│  Layer 4+: Extended Features          │  🔵 Planned
+│  (Advanced game/companion systems)      │
 ├─────────────────────────────────────────┤
-│  Layer 4a: Game Systems                │  🔵 Planned
-│  (Ranking, rarity, XP, visualization)   │
+│  Layer 4: Relationship Inference       │  ✅ Complete
+│  (Bond strength, relationship types)    │  (Optional)
 ├─────────────────────────────────────────┤
 │  Layer 3.5: Integrated Profile         │  ✅ Complete
 │  (Unified summary for AI consumption)   │
@@ -31,7 +31,7 @@ aigptは、独立したレイヤーを積み重ねる設計です。各レイヤ
 │  (Claude interpretation, priority_score)│
 ├─────────────────────────────────────────┤
 │  Layer 1: Pure Memory Storage          │  ✅ Complete
-│  (SQLite, ULID, CRUD operations)       │
+│  (SQLite, ULID, entity tracking)       │
 └─────────────────────────────────────────┘
 ```
 
@@ -51,13 +51,16 @@ aigptは、独立したレイヤーを積み重ねる設計です。各レイヤ
 ### Data Model
 ```rust
 pub struct Memory {
-    pub id: String,              // ULID
-    pub content: String,         // User content
+    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
@@ -295,10 +298,120 @@ AI: get_profile()で概要を把握
 
 ---
 
-## Layer 4a: Game Systems
+## Layer 4: Relationship Inference
+
+**Status**: ✅ **Complete** (Optional feature)
+
+### Purpose
+Layer 1-3.5のデータから関係性を推測。ゲーム、コンパニオン、VTuberなどの外部アプリケーション向け。
+
+### Activation
+CLI引数で明示的に有効化:
+```bash
+aigpt server --enable-layer4
+```
+
+デフォルトでは無効（Layer 1-3.5のみ）。
+
+### Data Model
+```rust
+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 計算**:
+```rust
+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
 ゲーム的要素で記憶管理を楽しく。
 
@@ -398,9 +511,20 @@ pub struct Companion {
 - [x] Smart update triggers
 - [x] `get_profile` MCP tool
 
-### Phase 4: Layers 4-5 (Next)
-- [ ] Game mechanics (Layer 4a)
-- [ ] Companion system (Layer 4b)
+### Phase 4: Layer 4 ✅ (Complete)
+- [x] Add `related_entities` to Layer 1 Memory struct
+- [x] Database migration for backward compatibility
+- [x] RelationshipInference data structure
+- [x] Bond strength calculation (personality-aware)
+- [x] Relationship type classification
+- [x] Confidence scoring
+- [x] `get_relationship` MCP tool
+- [x] `list_relationships` MCP tool
+- [x] CLI control flag (`--enable-layer4`)
+- [x] 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)
 
@@ -472,26 +596,26 @@ pub struct Companion {
 ```
 src/
 ├── core/
-│   ├── memory.rs      # Layer 1: Memory struct
-│   ├── store.rs       # Layer 1-3.5: SQLite operations
+│   ├── 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)
+│   ├── base.rs        # MCP server (all layers, with --enable-layer4)
 │   └── mod.rs         # Module exports
 ├── lib.rs             # Library root
-└── main.rs            # CLI application
+└── main.rs            # CLI application (with layer4 flag)
 ```
 
 **Future layers**:
-- Layer 4a: `src/game/` - Game systems
-- Layer 4b: `src/companion/` - Companion features
+- Layer 4+: `src/game/` - Extended game/companion systems
 - Layer 5: `src/distribution/` - Sharing mechanisms
 
 ---
 
-**Version**: 0.2.0
+**Version**: 0.3.0
 **Last Updated**: 2025-11-06
-**Current Status**: Layers 1-3.5 Complete, Layer 4 Planned
+**Current Status**: Layers 1-4 Complete (Layer 4 opt-in with --enable-layer4)