# edwardathomson/storydaemon architecture

> Architecture diagram of the GitHub repository edwardathomson/storydaemon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/edwardathomson/storydaemon
- Repository: https://github.com/edwardathomson/storydaemon

## Overview

StoryDaemon is a CLI-driven autonomous novel generator. A user creates or resumes a project, then runs story ticks: the agent plans and writes scenes with an LLM, using plot beats when enabled and project memory for continuity. Memory tracks entities, scenes, and searchable context; coherence features guide tension, arcs, threads, and endings. The CLI also exposes inspection, checkpointing, plot controls, and manuscript export. Edges reflect README workflow statements or references visible in the supplied SOURCE INDEX; unsampled modules limit detail on their internal calls.

Main entry points: [`novel_agent/cli/main.py`](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/main.py) (Novel CLI), [`novel_agent/agent/agent.py`](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/agent.py) (Tick Agent), [`novel_agent/agent/multi_stage_planner.py`](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/multi_stage_planner.py) (Scene Planning), [`novel_agent/memory/manager.py`](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/memory/manager.py) (Story Memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_project["Projects and CLI"]
  node_cli["Novel CLI<br/>[main.py]"]
  node_project_setup["Project Setup<br/>[project.py]"]
  node_foundation["Story Foundation<br/>[foundation.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_generation["Story Generation"]
  node_agent["Tick Agent<br/>[agent.py]"]
  node_planner["Scene Planning"]
  node_writer["Scene Writing<br/>[writer.py]"]
  node_writer_context["Writer Context<br/>[writer_context.py]"]
  node_scene_skeleton["Scene Skeletons<br/>[scene_skeleton.py]"]
  node_plot["Plot Beats<br/>[manager.py]"]
end

subgraph group_continuity["Memory and Coherence"]
  node_memory[("Story Memory<br/>[manager.py]")]
  node_entities["Story Entities<br/>[entities.py]"]
  node_vector[("Semantic Search<br/>[vector_store.py]")]
  node_coherence["Arc and Tension<br/>[arc_pressure.py]"]
  node_threads["Narrative Threads<br/>[thread_registry.py]"]
  node_contracts["Beat Contracts<br/>[authoring.py]"]
end

subgraph group_integrations["LLM and Tools"]
  node_llm["LLM Dispatch<br/>[llm_interface.py]"]
  node_tools["Agent Tools<br/>[registry.py]"]
end

subgraph group_output["Inspection and Export"]
  node_inspection["Project Inspection<br/>[inspect.py]"]
  node_checkpoint["Checkpoints<br/>[checkpoint.py]"]
  node_compile["Manuscript Export<br/>[compile.py]"]
  node_export_formats["Export Formats<br/>[chapters.py]"]
end

node_author(("Writer"))

node_author -->|"runs commands"| node_cli
node_cli -->|"creates or finds"| node_project_setup
node_cli -->|"runs ticks"| node_agent
node_project_setup -->|"collects foundation"| node_foundation
node_project_setup -->|"reads settings"| node_config
node_agent -->|"delegates planning"| node_planner
node_agent -->|"delegates writing"| node_writer
node_agent -->|"uses memory"| node_memory
node_agent -->|"generates with LLM"| node_llm
node_agent -->|"uses tool registry"| node_tools
node_writer -->|"builds prompt context"| node_writer_context
node_writer_context -->|"samples skeleton"| node_scene_skeleton
node_writer_context -->|"adds arc guidance"| node_coherence
node_planner -.->|"uses plot beats"| node_plot
node_plot -->|"reads story state"| node_memory
node_plot -->|"sanitizes conditions"| node_contracts
node_memory -->|"loads and saves"| node_entities
node_memory -.->|"semantic retrieval"| node_vector
node_planner -->|"applies arc pressure"| node_coherence
node_planner -.->|"uses thread registry"| node_threads
node_cli -.->|"dispatches inspection"| node_inspection
node_cli -->|"checkpoints project"| node_checkpoint
node_cli -->|"compiles manuscript"| node_compile
node_compile -->|"exports chapters"| node_export_formats

click node_cli "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/main.py"
click node_project_setup "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/project.py"
click node_foundation "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/foundation.py"
click node_config "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/configs/config.py"
click node_agent "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/agent.py"
click node_planner "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/multi_stage_planner.py"
click node_writer "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/writer.py"
click node_writer_context "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/writer_context.py"
click node_scene_skeleton "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/scene_skeleton.py"
click node_plot "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/plot/manager.py"
click node_memory "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/memory/manager.py"
click node_entities "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/memory/entities.py"
click node_vector "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/memory/vector_store.py"
click node_coherence "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/arc_pressure.py"
click node_threads "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/thread_registry.py"
click node_contracts "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/contracts/authoring.py"
click node_llm "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/tools/llm_interface.py"
click node_tools "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/tools/registry.py"
click node_inspection "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/commands/inspect.py"
click node_checkpoint "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/memory/checkpoint.py"
click node_compile "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/commands/compile.py"
click node_export_formats "https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/export/chapters.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_project_setup,node_foundation,node_config toneBlue
class node_agent,node_planner,node_writer,node_writer_context,node_scene_skeleton,node_plot toneAmber
class node_memory,node_entities,node_vector,node_coherence,node_threads,node_contracts toneMint
class node_llm,node_tools toneRose
class node_inspection,node_checkpoint,node_compile,node_export_formats,node_author toneIndigo
```

## Components

### Projects and CLI

- [Novel CLI](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/main.py): `novel_agent/cli/main.py`
- [Project Setup](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/project.py): `novel_agent/cli/project.py`
- [Story Foundation](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/foundation.py): `novel_agent/cli/foundation.py`
- [Configuration](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/configs/config.py): `novel_agent/configs/config.py`

### Story Generation

- [Tick Agent](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/agent.py): `novel_agent/agent/agent.py`
- [Scene Planning](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/multi_stage_planner.py): `novel_agent/agent/multi_stage_planner.py`
- [Scene Writing](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/writer.py): `novel_agent/agent/writer.py`
- [Writer Context](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/writer_context.py): `novel_agent/agent/writer_context.py`
- [Scene Skeletons](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/scene_skeleton.py): `novel_agent/agent/scene_skeleton.py`
- [Plot Beats](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/plot/manager.py): `novel_agent/plot/manager.py`

### Memory and Coherence

- [Story Memory](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/memory/manager.py): `novel_agent/memory/manager.py`
- [Story Entities](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/memory/entities.py): `novel_agent/memory/entities.py`
- [Semantic Search](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/memory/vector_store.py): `novel_agent/memory/vector_store.py`
- [Arc and Tension](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/arc_pressure.py): `novel_agent/agent/arc_pressure.py`
- [Narrative Threads](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/agent/thread_registry.py): `novel_agent/agent/thread_registry.py`
- [Beat Contracts](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/contracts/authoring.py): `novel_agent/contracts/authoring.py`

### LLM and Tools

- [LLM Dispatch](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/tools/llm_interface.py): `novel_agent/tools/llm_interface.py`
- [Agent Tools](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/tools/registry.py): `novel_agent/tools/registry.py`

### Inspection and Export

- [Project Inspection](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/commands/inspect.py): `novel_agent/cli/commands/inspect.py`
- [Checkpoints](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/memory/checkpoint.py): `novel_agent/memory/checkpoint.py`
- [Manuscript Export](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/cli/commands/compile.py): `novel_agent/cli/commands/compile.py`
- [Export Formats](https://github.com/edwardathomson/storydaemon/blob/main/novel_agent/export/chapters.py): `novel_agent/export/chapters.py`

### Other components

- **Writer**

## Connections

- Writer → Novel CLI: runs commands (evidence: `README.md`)
- Novel CLI → Project Setup: creates or finds (evidence: `novel_agent/cli/main.py`)
- Novel CLI → Tick Agent: runs ticks (evidence: `novel_agent/cli/main.py`)
- Project Setup → Story Foundation: collects foundation (evidence: `novel_agent/cli/project.py`)
- Project Setup → Configuration: reads settings (evidence: `novel_agent/cli/project.py`)
- Tick Agent → Scene Planning: delegates planning (evidence: `novel_agent/agent/agent.py`)
- Tick Agent → Scene Writing: delegates writing (evidence: `novel_agent/agent/agent.py`)
- Tick Agent → Story Memory: uses memory (evidence: `novel_agent/agent/agent.py`)
- Tick Agent → LLM Dispatch: generates with LLM (evidence: `novel_agent/cli/main.py`)
- Tick Agent → Agent Tools: uses tool registry (evidence: `novel_agent/agent/agent.py`)
- Scene Writing → Writer Context: builds prompt context (evidence: `novel_agent/agent/writer_context.py`)
- Writer Context → Scene Skeletons: samples skeleton (evidence: `novel_agent/agent/writer_context.py`)
- Writer Context → Arc and Tension: adds arc guidance (evidence: `novel_agent/agent/writer_context.py`)
- Scene Planning → Plot Beats: uses plot beats
- Plot Beats → Story Memory: reads story state (evidence: `novel_agent/plot/manager.py`)
- Plot Beats → Beat Contracts: sanitizes conditions (evidence: `novel_agent/plot/manager.py`)
- Story Memory → Story Entities: loads and saves (evidence: `novel_agent/memory/manager.py`)
- Story Memory → Semantic Search: semantic retrieval
- Scene Planning → Arc and Tension: applies arc pressure
- Scene Planning → Narrative Threads: uses thread registry
- Novel CLI → Project Inspection: dispatches inspection (evidence: `novel_agent/cli/main.py`)
- Novel CLI → Checkpoints: checkpoints project (evidence: `novel_agent/cli/main.py`)
- Novel CLI → Manuscript Export: compiles manuscript (evidence: `novel_agent/cli/main.py`)
- Manuscript Export → Export Formats: exports chapters (evidence: `novel_agent/cli/commands/compile.py`)
