dreamscroll-lab / asamana

# Asamana
English | 简体中文
▶️ **Demo video**: watch on Bilibili
**Asamana is an AI-driven emergent narrative engine.**
Give Asamana a theme, and it creates a shared world with a cast of AI characters, each with a distinct persona and cognitive system. The characters act autonomously, and the story emerges from their interactions, with no script or predefined plot.
> **Status**: early development. APIs, configuration formats and save formats may change between releases. Backward compatibility is not yet guaranteed. See CHANGELOG.md for changes.
> **Language**: prompts and generated narratives, including dialogue and memories, are currently in Chinese.
## Philosophy: Treat AI characters as people
Model characters as people with personality, memory, emotions, needs and goals.
## Features
### 1. A human-inspired cognitive system for every character
Every character has personality, values, emotions, goals, needs, relationships and memories, along with the ability to reason, decide and act.
### 2. One world, one theme
Asamana keeps the cast in a bounded setting centered on **a single narrative theme**. This gives the emerging story focus and encourages meaningful interactions, conflict and memorable moments beyond everyday routines.
### 3. Designed as an agent loop, built as an orchestrated pipeline
Conversation-based agent loops accumulate context with each turn, increasing cost and diluting attention to relevant information. Asamana implements its cognitive loop as a pipeline using three techniques:
- **Staged orchestration**: cognition follows five stages, `perception → motivation → decision → action → feedback`, orchestrated deterministically in code. LLM calls within these stages can be tested and tuned independently, with explicitly assembled context.
- **Typed outputs**: stages exchange structured JSON through typed contracts. This makes outputs easier to validate and limits the spread of hallucinated information.
- **Shared context**: each stage receives the relevant persona, emotions, needs, goals, relationships, situation and recent memories to maintain consistency over time.
## Architecture
- **Backend** (Python): a single process serves the REST API and WebSocket updates, and runs the narrative engine as a background task. Strictly layered: `interaction → world / engine / agent → core ← providers`. Business logic depends only on the interfaces in `core/`, and infrastructure such as the LLM, embeddings, vector store and snapshots is pluggable.
- **Frontend** (React + Vite + TypeScript + Phaser): world management, live observation, replay and a 2D map. It communicates with the backend exclusively through the API; the engine is independent of rendering.
- **LLM access**: any OpenAI-compatible endpoint works out of the box, with no code changes, and different scenes can be routed to different models.
- **Deployment**: one image each for the frontend and backend, started with a single Docker Compose command.
 [code] 
## Quick start
We recommend ru