A Murder Mystery Dinner Party
"Ladies and gentlemen, you all have one thing in common..."
For Jill
Product Manager · Architectural Advisor · Clue Connoisseur
This is how Kagami works—not as documentation, but as experience.
Kagami is an AI system that thinks in seven different ways at once.
Instead of one "brain," it has seven specialized agents living in one house.
Like characters in a story, they argue, collaborate, and solve problems together.
kagami/api/
REST API & WebSocket endpoints. FastAPI routes, middleware, authentication. Where the outside world enters.
routes/ middleware/ socketio/
kagami/core/
The brain. Orchestration, coordination, execution. Where decisions are made and work is routed.
orchestrator/ coordination/ execution/
kagami/core/services/
Where the real work happens. LLM clients, embeddings, storage, MCP connections. The staff quarters.
llm/ embedding_service.py mcp/
kagami/core/world_model/
Prediction engine. RSSM-based world simulation. Doesn't just react—it predicts what's coming.
equivariance/ layers/ memory/
kagami/core/safety/
Control Barrier Functions. h(x) ≥ 0. ALWAYS. The walls that keep danger out.
optimal_cbf.py barriers/
kagami/math/
Mathematical foundations. E8 lattice quantization, Fano plane routing, octonion algebra.
e8_lattice_quantizer.py fano_plane.py octonions/
kagami/core/memory/
Episodic and semantic memory. Vector stores, retrieval, the system's long-term knowledge.
episodic/ semantic/ retrieval/
kagami/core/database/
PostgreSQL connections, migrations, models. Where everything is stored permanently.
connection.py models/
The key players in every request:
How modules connect:
"One plus one plus two plus one..."
What happens when a request enters the mansion?
Follow the body through the house.
api/routes/
Request arrives via REST or WebSocket
orchestrator/process_intent_v2.py
Wadsworth parses intent, plans execution
safety/optimal_cbf.py
Is h(x) ≥ 0? Can we proceed?
services/llm/service.py
LLM generates response, tools execute
api/socketio/broadcaster.py
Stream back to client
"h(x) ≥ 0. ALWAYS."
The safety barrier must never be violated
Proceed normally
Extra validation required
Operation blocked
"The safety invariant is INVIOLABLE."
— Like Mrs. Peacock's sense of propriety
Just like the movie had three endings, there are three ways to understand this architecture.
Click an ending to reveal...
"Let me explain... No, there is too much. Let me sum up."
One plus one plus two plus one...