Novel Agent V2: Multi-Agent LangGraph Pipeline for Consistent Long-Form Novels

1. The Core Challenge: Loss of Control in Long-Form Generation

Directly prompting an LLM to continue a long novel hits three walls:

1. Context Exhaustion

The novel grows too long to fit in the model's context window. Dropping old content causes forgetting; keeping it all exceeds cost and window limits.

2. Fact Drift

Character ages, abilities, relationships, locations, and histories change continuously. Relying on the model to "remember" leads to setting conflicts and new hallucinations overwriting old facts.

3. Narrative Collapse

Models excel at completing the immediate segment but lack innate concern for outcomes dozens of chapters later. Without global control, pacing flattens, conflicts repeat, characters are pushed by plot rather than driving it, and foreshadowing is planted but never paid off.

Simply switching to a larger model does not fundamentally solve these issues. Novel Agent V2 takes a different approach: downgrade the LLM from an omniscient author to a constrained executor. A state machine manages flow, a fact system manages memory, a rule layer enforces boundaries, and distinct agents handle only the tasks they specialize in.

2. A Production Pipeline, Not a Single Prompt

Novel Agent V2 uses LangGraph to orchestrate each chapter's generation. From planning to persistence, a chapter passes through a sequence of dedicated nodes:

Director → Planner → ContextBuilder → Writer → Editor → Checker ──issues found──→ RepairAgent ──→ Checker └─passes──→ NarrativeController → FactExtractor → MemoryMCP → ForeshadowMCP → every 10 chapters trigger Compactor → done

These roles are not merely different system prompts; they carry distinct responsibilities:

Director : High-level story direction.

Planner : Designs the chapter's scenes and conflicts.

ContextBuilder : Assembles the "chapter brief" from structured memory and vector search.

Writer : Produces prose that reads like a novel.

Editor : Polishes style and flow.

Checker : Validates character consistency, timeline, world rules, foreshadowing coverage, and absence of authorial intrusions.

RepairAgent : Generates targeted fixes (not full rewrites) for any issues flagged by Checker.

NarrativeController : Updates plot state and emotional arcs.

FactExtractor : Pulls factual changes from the approved text.

MemoryMCP / ForeshadowMCP : Persist facts and foreshadowing state through the Model Context Protocol service layer.

Compactor : Runs every 10 chapters to summarize and compress history.

Separating duties makes long-form generation observable, verifiable, and repairable. The Writer only needs to "write like a novel," not simultaneously act as director, screenwriter, librarian, reviewer, and database administrator.

3. Layered Memory: The System Remembers So the Model Doesn't Have To

Instead of stuffing the entire book back into the prompt, Novel Agent V2 builds a tiered memory architecture:

In-memory cache for recent high-frequency context.

JSON files for structured facts (characters, world-building, volume plans).

Local vector retrieval for semantic recall of relevant historical passages.

Optional MinIO storage for full chapter text.

For each new chapter, ContextBuilder assembles a tailored "chapter brief" containing only what the current plot requires. The model sees a curated packet, not the whole novel.

A key design principle: the MCP service layer is the single gateway for facts. The Writer cannot spontaneously grant a character a new ability or rewrite history. After prose generation, FactExtractor extracts changes, which are then validated and committed through the unified fact service. The goal is not infinite model memory, but a system that guards factual boundaries even when the model forgets.

4. Foreshadowing as a State Machine

Many AI novels plant foreshadowing but rarely pay it off because "remember to handle foreshadowing" is just a soft prompt that gets drowned out as chapters accumulate.

Novel Agent V2 turns foreshadowing into trackable states:

BURIED (planted) → ACTIVE (triggered) → DUE (in payoff window) → RESOLVED (paid off)

The system knows each foreshadowing item's phase and injects those currently due into the chapter plan. Checker also audits overdue items. Foreshadowing shifts from "hope the model remembers" to "a narrative object with a lifecycle managed by the system."

5. Character-Driven Plot: Want, Fear, Contradiction

Long stories often feel flat not from lack of events, but because characters don't truly participate in them. At initialization, each character receives three core dimensions:

want : What the character seeks in the external world.

fear : What the character deeply dreads.

contradiction : The tension between want and fear.

When Planner designs a scene, it must specify which character's contradiction is activated. Writer must make key turning points stem from character choices, not coincidences.

The system continuously tracks:

Conflict, progression, and emotional shift per chapter.

Turning points and end-of-chapter cliffhanger intensity.

Recent scene types to avoid repetitive settings.

Character arc stage: conviction, wavering, decision, or transformation.

Major emotional anchors for the whole book and each act.

These rules don't guarantee masterpieces, but they significantly reduce the mechanical repetition and narrative drift common in long-form generation.

6. Generation-Verification-Repair Loop

Generative systems cannot promise zero errors. Novel Agent V2 focuses on catching errors before they enter the canonical record.

After Editor polish, the draft goes to Checker. If character conflicts, timeline errors, world-rule violations, missing foreshadowing, or large authorial notes are found, the flow enters a repair branch. RepairAgent produces localized patches (not full rewrites); the patched version re-enters Checker. This generate → verify → repair → re-verify loop replaces "generate and commit."

The project also supports per-role model routing: fast, cheap models for drafting; stronger reasoning models for Checker and RepairAgent, enabling finer cost-quality trade-offs. Currently compatible with DeepSeek, Qwen, GLM, Kimi via OpenAI-compatible APIs, and local models via Ollama.

7. Web Console for Non-CLI Users

Beyond the CLI, a FastAPI-based web console provides:

Create and view novels.

Launch full-volume or continuous chapter generation.

Inspect characters, foreshadowing, volume plans, and generation status.

Edit, rewrite, or regenerate specific chapters.

Stop tasks, view logs and statistics.

Export generated content.

First-time users can disable vector search, skip Docker and MinIO, and run the core pipeline with just a valid model API key.

8. Quick Start (5 Minutes)

Step 1: Clone and Install Dependencies

git clone https://gitee.com/hmk_855_admin/novelagent.gitcd novelagentpython -m venv .venvsource .venv/bin/activatepip install -r requirements.txt

Windows PowerShell activation:

.venv/Scripts/Activate.ps1

Step 2: Create Configuration

cp .env.example .env

Minimal DeepSeek example:

DEFAULT_PROVIDER=deepseekDEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx# Disable vector search for first run (falls back to keyword search)VECTOR_SEARCH_ENABLED=false# Web console pathWEB_SECRET_PATH=mynovel

Step 3: Verify and Launch

python main.py healthpython main.py web --port 9101

Open http://localhost:9101/mynovel/ in a browser.

CLI alternative: initialize a novel directly:

python main.py init 
  --title "Stars and Oceans" 
  --desc "Protagonist Lin Feng awakens from trash to cultivation..." 
  --volumes 10 
  --world-type xianxia

Use the returned novel_id to generate single chapters, whole volumes, or enter continuous generation mode.

9. Who Is This For?

Developers researching multi-agent systems, LangGraph, and long-horizon orchestration.

Teams building AI writing, interactive narrative, or content generation products.

Creators who want control over characters, world-building, and foreshadowing—not just random continuation.

Users preferring local models and full data/environment control.

AI engineering practitioners studying how generated content can be verified and repaired.

This is not a "one-click bestseller" promise. Final prose quality still depends on model capability, story design, prompt engineering, and parameter tuning; stronger reasoning models in Checker generally yield more reliable consistency checks. But if your question is how to move AI from writing a good paragraph to sustainably completing a full-length novel , this project offers an engineering answer worth studying.

10. Closing Thoughts

I open-sourced Novel Agent V2 not just to add another AI writing tool, but to test a hypothesis:

When model capability has a ceiling, can we organize unstable generative ability into a relatively stable creative system through explicit division of labor, structured memory, state machines, and verification loops?

Today it possesses a complete chain from world initialization, volume planning, chapter generation, to fact persistence, foreshadowing tracking, automatic repair, and text export. Development continues. If you're researching AI novels, long-text generation, or agent workflows, visit the repository, try it, file issues, or contribute.

Gitee: https://gitee.com/hmk_855_admin/novelagent<br/> GitHub: https://github.com/hanmengkai/novelagent

Licensed under MIT. Stars and feedback welcome—they may shape the next version.