Companion repository for Entangled Alignment: When Safety Is the Substrate — a research program that treats reader augmentation, persistent graph memory, and Reader-Core stability as separable hypotheses. The code here is the paper's annotation pipeline: a multi-agent system that reads a book chronologically and builds a knowledge graph of its concepts, relationships, and emergent themes — Gemini-powered agents coordinated through an MCP (Model Context Protocol) server.
Two completed runs ship with the repo — no API key needed to explore them:
git clone --recursive https://github.com/emergent-wisdom/entangled-alignment
cd entangled-alignment
./setup.sh
./view.sh # opens http://localhost:3000Select a project in the sidebar:
- metamorphosis — Kafka's The Metamorphosis (346 active nodes)
- llada — the LLaDA paper on large language diffusion (285 active nodes)
Click any node to see its content, edges, and the passage that produced it. If port
3000 is taken, PORT=3001 ./view.sh.
setup.sh creates a .env file from .env.example. Open it and add your Gemini API key:
# Get your API key from https://aistudio.google.com/apikey
GOOGLE_API_KEY=your-key-here
GEMINI_MODEL=gemini-3-flash-preview
Keep comments on their own line — run.sh exports the file with xargs, so a
trailing # comment after a value aborts the run.
Then run the agents on any text:
# Run on the bundled Metamorphosis text (use a fresh project name so the
# shipped 'metamorphosis' graph stays untouched)
./run.sh chronological_metacognition/material/metamorphosis.txt --project my-reading-1
# Or on any text file
./run.sh /path/to/book.txt --project my-readingOpen ./view.sh in a second terminal while the agents run — nodes and edges appear in the 3D graph in real time as each passage is processed.
Measured from the shipped traces:
| Metamorphosis | LLaDA | |
|---|---|---|
| LLM calls | 162 | 120 |
| Input tokens | ~1.5 M | ~1.1 M |
| Graph tool calls | 1,997 | 1,339 |
| Active time | ~7 h | ~5 h |
| Wall clock | 47 h | 24 h |
Active time is the time recorded inside the pipeline. The wall-clock figures are
much larger because each swarm.jsonl spans several resumed invocations rather
than one continuous session. The Metamorphosis trace records roughly 18 hours in
explicit 429 RESOURCE_EXHAUSTED cooldowns; other gaps may include manual pauses,
which the released metadata cannot reconstruct precisely.
Both shipped readings completed. For Metamorphosis, the source record reaches
position = total_length (140,527 characters) with status completed, the final
run summary reports 100%, and the append-only trace reaches Content 100% and a
successful final translation. The 88% figure is only the latest Content marker
retained in the released database's graph tables. The complete chronological
Markdown export continues beyond that snapshot. Rate limits and manual restarts
may explain pauses between invocations, but 88% is not where the reading stopped.
- Python 3.10+
- Node.js 22+ (the graph store uses better-sqlite3 13)
- A Gemini API key (only needed for running new texts)
A Reader streams the source text in chronological order, pausing at Thought Moments — emotional peaks, contradictions, conceptual shifts — rather than at fixed intervals. A swarm of specialized Workers (Skeptic, Psychologist, Axiologist, Belief Tracker, Critic, Speculator, Connector, Curator, plus domain specialists) debates each passage by writing typed nodes and edges into a shared Understanding Graph. A Synthesizer collapses their competing readings into a single thought anchored to a fixed first-person identity (the Reader Core), and a Translator renders it as fluid prose. The shipped runs used eleven agents.
Everything is written to a shared knowledge graph via an MCP server (understanding-graph). The web frontend renders the graph as an interactive 3D visualization — nodes appear as the agents work, edges form between related concepts, and clusters emerge as themes develop.
This repo uses understanding-graph as its MCP server — the shared memory that agents read from and write to. The two projects have diverged in how they teach agents to use the graph:
-
entangled-alignment uses prompt composition — modular markdown files in
prompts/that are assembled into system messages for Gemini swarm agents. This is the approach described in the paper and it works. The prompts ship with this repo and are self-contained. -
understanding-graph has moved to a Claude Code skills model — each skill is a standalone teaching unit that Claude Code loads natively. This is the newer approach for interactive use.
The two systems are not interchangeable. This repo carries its own copy of the prompts that the swarm agents depend on, and pins the graph server to understanding-graph@0.1.16 — the earliest version published to npm that the pipeline runs against. setup.sh installs it locally from package-lock.json, so run.sh and view.sh always launch the same build.
The runs that produced the shipped graphs (January 2026) predate that versioning scheme: at the time understanding-graph was consumed as a git submodule and had no released versions. The pinned version is the reproducible equivalent, not a byte-identical rebuild of the original toolchain.
├── setup.sh # One-time setup
├── run.sh # Run agents on any text file
├── view.sh # Launch the web viewer
├── .env.example # API key template
├── package.json # Pinned understanding-graph + embedding backend
├── package-lock.json # Exact Node dependency tree (npm ci)
├── requirements.txt # Pinned Python dependencies
├── paper/ # The paper (LaTeX source, house style, PDF)
├── prompts/ # Agent system prompts (from understanding-graph)
│ ├── core/ # Philosophy, identity, five laws
│ ├── roles/ # Agent identities (reader, skeptic, synthesizer...)
│ ├── modes/ # Phase-specific behavior (reading, thinking)
│ ├── tools/ # Graph tool usage guides
│ └── workflows/ # Orchestration patterns
├── chronological_metacognition/ # Agent code
│ ├── run_reader.py # Main orchestrator
│ └── material/ # Sample texts
├── orchestrator/ # Agent coordination library (submodule)
└── projects/ # Output graphs (one folder per run)
├── metamorphosis/ # Kafka — included
└── llada/ # LLaDA paper — included
@misc{westerberg2026entangled,
title = {Entangled Alignment: When Safety Is the Substrate},
author = {Westerberg, Henrik},
year = {2026},
month = aug,
publisher = {Zenodo},
doi = {10.5281/zenodo.22073296},
url = {https://doi.org/10.5281/zenodo.22073296}
}See CITATION.cff for the machine-readable version (GitHub
renders a "Cite this repository" button from it).
MIT