Chaos Substrate
A portable, persistent code-knowledge memory for AI agents that survives process restarts.
Chaos Substrate indexes a repository into a source-grounded knowledge graph plus real embedding
vectors stored in Postgres + pgvector, so agents stop re-reading the whole repo on every task
and instead get fast, source-grounded answers from durable memory. It is a single Rust binary
(chaos) that exposes that memory through a CLI and a stdio MCP server.
The implementation is Rust-only. It analyzes Rust, TypeScript, JavaScript, Python, and Solidity with
real AST parsers, treats Markdown/MDX and text PDFs as supplemental document context, and reads a
small set of JSON config manifests. Non-Rust languages are analysis targets only — they are parsed
Rust-side, never run as a separate Node or Python service. It can also export a standalone
graph.html page or an Obsidian vault for visual validation of the persisted graph.
Why it exists
- Persistent memory. The graph, chunks, and embeddings live in your Postgres/pgvector and
survive process restarts — queries after a restart use disk-backed memory, not a re-scan.
- Source-grounded answers. Graph nodes and edges stay canonical for source grounding and context
routing; chunks are symbol-aware retrieval projections, not the source of truth.
- Fail-closed. Runtime code has no mock embedder and no random vectors. If no real embedder is
configured, analysis fails rather than producing fake vectors.
Two ways to use
| Mode | What | For | How to start |
|---|
| Agent via MCP | A stdio MCP server with 23 tools (chaos_analyze, chaos_add, chaos_stats, chaos_stack, chaos_pages, chaos_gaps, chaos_query, chaos_feature_context, chaos_impact, chaos_usage, chaos_sui_migration_impact, chaos_write_feature_website, chaos_obsidian, chaos_refresh, chaos_write_storyboard, chaos_change_plan, chaos_components, chaos_features, chaos_compose, chaos_project, chaos_help, chaos_clean, chaos_graph). | Coding agents (Claude Code, Codex, Windsurf, OpenCode) that should query durable code memory instead of re-reading files. | chaos setup to register the server, then ask the agent to analyze and query. See docs/EDITOR_SETUP.md. |
| Raw CLI | The chaos binary: analyze, add, stats, query, feature-context, impact, change-plan, storyboard, graph, obsidian, refresh, clean. | Humans and scripts doing setup, debugging, one-off indexing, or agentless operation. | chaos analyze <repo> then chaos query <repo> "<question>". See Quick Start. |
| Generated static feature-website | A self-contained HTML feature page (light editorial theme) with interactive graph/story/code navigation plus a machine-readable manifest. | Sharing or reviewing how a feature works, and seeding future agent context from the embedded manifest. | chaos feature-context <repo> "<task>" --output-html page.html, or the chaos_write_feature_website MCP tool. |
| Client/user storyboard | A self-contained HTML page (light editorial theme) that explains a feature from the UI/UX user-story perspective with no code: personas, "As a … I want … so that …" stories, clickable frames, confidence rings, an embedded manifest, and optional real-UI previews per frame (a captured screenshot/clip or a live iframe of the running app). | Handing a stakeholder or end user an interactive presentation of a feature without showing code. | The chaos_write_storyboard MCP tool, or chaos storyboard <repo> --manifest story.json. |
Quick Start
This is the canonical bootstrap. Bundled Postgres uses pgvector/pgvector:pg16 on host port 54329.
cp chaos-substrate.example.toml chaos-substrate.toml # example config defaults to local Ollama
docker compose up -d # pgvector on localhost:54329
# Ollama default: ensure Ollama is running and the model is pulled:
# ollama pull embeddinggemma (see docs/OLLAMA_SETUP.md)
chaos migrate # create schema (sqlx migrations)
chaos doctor # check Postgres + real embedding probe
chaos analyze /path/to/repo # index the repository
chaos query /path/to/repo "where is the request handler validated?"
# After editing a few files, index just the diff + regenerate docs in one shot:
chaos add /path/to/repo -m "added the export pipeline" # detects changed files from git
The default DATABASE_URL for the bundled container is
`[REDACTED:DB Connection String]
New to the project and using Claude Code? The
Setup from scratch section below walks the full path
from installing Docker and Rust to registering the agent, in order.
