Multi view with game demo

demos/AOTAI_Hike/PR_DESCRIPTION.md

@@ -0,0 +1,73 @@
+# Integrate AoTai Hike Demo with MemOS Multi-View Memory System
+
+## Summary
+
+This PR integrates the AoTai Hike game demo with MemOS's multi-view memory capabilities, demonstrating how multiple game roles can maintain independent memory spaces and extract memories from their own first-person perspectives.
+
+## Key Features
+
+### 1. Multi-View Memory Integration
+- **World Memory**: Stores global game events accessible to all roles (`cube_{user_id}_world`)
+- **Role Memory**: Each role has an independent memory space (`cube_{role_id}_{role_id}`)
+- **Automatic Mode Detection**: MemOS automatically enables `multi_view` mode when messages contain `role_id` or `role_name` fields
+
+### 2. Memory Flow
+```
+GameService.act
+  ├─ add_event (world memory write with role_id/role_name)
+  ├─ search (world memory retrieval)
+  └─ CompanionBrain.generate
+        ├─ search_memory (role memory retrieval)
+        ├─ chat_complete (LLM generation)
+        └─ add_memory (role memory write-back with multi-view extraction)
+```
+
+### 3. Core Implementation
+
+**MemoryAdapter** (`adapters/memory.py`):
+- Wraps MemOS API calls (`/product/add`, `/product/search`, `/product/chat/complete`)
+- Supports multi-view memory writing and retrieval
+- Handles world memory and role memory isolation
+
+**CompanionBrain** (`adapters/companion.py`):
+- Generates NPC dialogue based on role memory
+- Uses MemOS `chat_complete` API with role-specific context
+- Writes dialogue back to role memory with multi-view extraction
+
+**GameService** (`services/game_service.py`):
+- Coordinates game logic with memory system
+- Formats and writes game events to memory
+- Retrieves world memory for NPC dialogue context
+
+## Technical Details
+
+### Multi-View Memory Detection
+When messages contain `role_id` or `role_name`, MemOS automatically:
+1. Switches to `multi_view` mode
+2. Extracts memories from the role's first-person perspective
+3. Filters irrelevant information
+4. Maintains role memory isolation
+
+### Memory Namespace
+- Role memory: `cube_{role_id}_{role_id}`
+- World memory: `cube_{user_id}_world`
+
+## Files Changed
+
+- `demos/AOTAI_Hike/backend/aotai_hike/adapters/memory.py` - MemOS memory adapter
+- `demos/AOTAI_Hike/backend/aotai_hike/adapters/companion.py` - NPC dialogue generation
+- `demos/AOTAI_Hike/backend/aotai_hike/services/game_service.py` - Game service with memory integration
+- `demos/AOTAI_Hike/backend/aotai_hike/router.py` - API routes
+- `demos/AOTAI_Hike/README.md` - Updated documentation
+- `demos/AOTAI_Hike/INTRODUCTION_ZH.md` - Chinese documentation
+- `demos/AOTAI_Hike/INTRODUCTION_EN.md` - English documentation
+
+## Related Issue
+
+Closes #[ISSUE_NUMBER]
+
+## Documentation
+
+- [Memory Integration Guide](./backend/MEMORY_INTEGRATION.md)
+- [Complete Introduction (中文)](./INTRODUCTION_ZH.md)
+- [Complete Introduction (English)](./INTRODUCTION_EN.md)

demos/AOTAI_Hike/README.md

@@ -0,0 +1,96 @@
+# 鳌太线徒步模拟器（AoTai Hike）Demo
+
+> A pixel-art interactive narrative game demo based on the MemOS multi-view memory system
+
+<div align="center">
+  <img src="./banner.png" alt="AoTai Hike × MemOS - Multi-View Memory"
+width="100%">
+</div>
+
+## 📖 Overview
+
+**鳌太线徒步模拟器（AoTai Hike）** is a Web game demo showcasing MemOS's multi-view memory capabilities. Players can create multiple roles, lead a team across the dangerous AoTai route, and experience memory-based intelligent NPC dialogues and dynamic storytelling.
+
+### Key Highlights
+
+- 🎮 **Multi-role roleplay**: Create and switch between multiple roles, each with an independent memory space
+- 🧠 **Multi-view memory**: Fully integrated MemOS multi-view memory system
+- 💬 **Intelligent NPC dialogue**: Generate personality-consistent dialogue based on role memory
+- 🗺️ **Fixed route exploration**: Follow the real AoTai route and experience the full journey
+- 🎨 **Pixel-art UI**: Use Phaser 3 to render pixel-art maps and role animations
+
+**📚 For detailed documentation, see: [INTRODUCTION_ZH.md](./INTRODUCTION_ZH.md) | [INTRODUCTION_EN.md](./INTRODUCTION_EN.md)**
+
+## 🚀 Quick Start
+
+### Requirements
+
+- Python 3.8+
+- MemOS service (local or remote)
+
+### Installation Steps
+
+1. **Install backend dependencies**
+```bash
+cd backend
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+2. **Configure MemOS service address (optional)**
+```bash
+export MEMOS_API_BASE_URL=http://localhost:8002
+```
+
+3. **Start the service**
+```bash
+uvicorn app:app --host 0.0.0.0 --port 8010 --reload
+```
+
+4. **Access the game**
+Open your browser and visit: `http://localhost:8010/demo/ao-tai/`
+
+## 📡 Core API
+
+- `GET /api/demo/ao-tai/map` - Get map information
+- `POST /api/demo/ao-tai/session/new` - Create a new session
+- `POST /api/demo/ao-tai/roles/upsert` - Create/Update a role
+- `POST /api/demo/ao-tai/roles/quickstart` - Quick-create default roles
+- `PUT /api/demo/ao-tai/session/active_role` - Switch active role
+- `POST /api/demo/ao-tai/act` - Perform an action (core endpoint)
+
+For detailed API documentation, see [INTRODUCTION_EN.md](./INTRODUCTION_EN.md#-api-documentation)
+
+## 🏗️ Project Structure
+
+```
+demos/AOTAI_Hike/
+├── backend/              # FastAPI backend
+│   ├── aotai_hike/      # Game core code
+│   │   ├── router.py    # API routes
+│   │   ├── services/    # Game services
+│   │   ├── adapters/    # Adapters (memory/dialogue/background)
+│   │   └── world/       # Map data
+│   └── app.py           # Application entry
+├── frontend/            # Frontend (Phaser 3 + DOM UI)
+│   ├── src/            # Source code
+│   └── assets/          # Asset files
+└── README.md           # This file
+```
+
+## 🔧 Extensible Interfaces
+
+The game is designed to be "lightweight but extensible"; all intelligence-related features are isolated via adapters:
+
+- `adapters/memory.py` - **MemoryAdapter**: Interface with MemOS memory system
+- `adapters/companion.py` - **CompanionBrain**: NPC dialogue generation (based on MemOS chat_complete)
+- `adapters/background.py` - **BackgroundProvider**: Background asset provider
+
+## 📚 Related Documents
+
+- [INTRODUCTION_ZH.md](./INTRODUCTION_ZH.md) - **Complete project introduction (中文)**
+- [INTRODUCTION_EN.md](./INTRODUCTION_EN.md) - **Complete project introduction (English)**
+- [backend/MEMORY_INTEGRATION.md](./backend/MEMORY_INTEGRATION.md) - Memory system interaction guide
+---
+
+**Enjoy your AoTai hike!** 🏔️

demos/AOTAI_Hike/backend/MEMORY_INTEGRATION.md

@@ -0,0 +1,109 @@
+# 游戏系统与记忆系统交互说明（AoTai Hike）
+
+本文说明 AoTai Hike 中游戏系统与记忆系统的交互方式，并给出关键代码位置。
+
+## 总体流程概览
+
+一次 `act` 的主链路如下：
+
+1. 游戏处理阶段门控与动作执行（更新世界状态）。
+2. 写入世界事件记忆（world cube）。
+3. 检索世界记忆，作为 NPC 对话上下文。
+4. 若触发 NPC 对话：
+   - 每个 NPC 检索自身记忆（role cube）
+   - 调用 chat 生成回复
+   - 将对话写回角色记忆
+5. 写入 `chat_history` 供后续对话使用。
+
+## 关键交互点与代码位置
+
+### 1) 游戏事件写入（world 记忆）
+
+- 位置：`GameService.act`
+- 作用：把本轮事件结构化写入记忆系统（world cube）
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/services/game_service.py`
+  - `GameService.act()` 内：
+    - `mem_event = self._format_memory_event(...)`
+    - `self._memory.add_event(...)`
+
+### 2) 世界记忆检索（world 记忆）
+
+- 位置：`GameService.act`
+- 作用：为 NPC 对话提供全局上下文
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/services/game_service.py`
+  - `mem_res = self._memory.search(...)`
+
+### 3) NPC 对话（角色记忆检索 + chat + 回写）
+
+- 位置：`MemoryCompanionBrain._generate_role_reply`
+- 作用：每个 NPC 走完整记忆链路生成发言
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/adapters/companion.py`
+  - `self._memory.search_memory(...)` 角色记忆检索
+  - `self._memory.chat_complete(...)` 调用算法 chat
+  - `self._memory.add_memory(...)` 写回角色记忆
+
+### 4) 记忆命名空间（cube_id）
+
+- 位置：`MemoryNamespace`
+- 规则：
+  - 角色记忆：`cube_{user_id}_{role_id}`
+  - 世界记忆：`cube_{user_id}_world`
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/adapters/memory.py`
+
+### 5) 记忆适配与客户端
+
+- 位置：`MemOSMemoryClient` / `MemOSMemoryAdapter`
+- 作用：封装 MemOS `/product/add`、`/product/search`、`/product/chat/complete`
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/adapters/memory.py`
+
+### 6) 对话历史记录
+
+- 位置：`GameService._append_chat_history`
+- 作用：将系统/发言消息转为 `chat_history`，供后续对话使用
+
+代码位置：
+- `demos/AOTAI_Hike/backend/aotai_hike/services/game_service.py`
+
+## 算法回放脚本（调试用）
+
+脚本 `algorithm_tuning.py` 以 1:1 的方式调用 `GameService.act`，并打印记忆/对话日志：
+
+- `demos/AOTAI_Hike/backend/aotai_hike/scripts/algorithm_tuning.py`
+
+常用参数：
+- `--user-id`：指定用户
+- `--base-url`：MemOS 服务地址
+- `--log-world-search`：打印 world 搜索
+- `--log-full-prompt`：打印完整 prompt
+
+## 简要链路图
+
+```
+GameService.act
+  ├─ add_event (world add)
+  ├─ search (world search)
+  └─ MemoryCompanionBrain.generate
+        ├─ search_memory (role search)
+        ├─ chat_complete (LLM)
+        └─ add_memory (role add)
+```
+
+## 多视角记忆集成
+
+本游戏完整集成了 MemOS 的多视角记忆系统，实现了每个角色拥有独立记忆空间、从角色视角提取记忆的功能。
+
+**核心特性**：
+- ✅ 自动多视角模式检测（通过 `role_id` 和 `role_name` 字段）
+- ✅ 角色记忆隔离（每个角色独立的记忆空间）
+- ✅ 第一人称视角记忆提取
+- ✅ 基于记忆的智能 NPC 对话生成

demos/AOTAI_Hike/backend/aotai_hike/__init__.py

@@ -0,0 +1 @@
+"""AoTai line pixel-hiking demo (single-player, multi-role)."""