Stateful runtime environment for cognitive work. Durable world state + deterministic execution + event audit trail.
Substrate is not a chat interface. It's a living world for AI agents.
When an agent needs to:
- Analyze documents without losing context
- Decompose complex tasks deterministically
- Remember prior work across sessions
- Rollback + explore alternatives
- Create an auditable record of reasoning
…it uses Substrate as its durable working memory.
Core idea: State persists. Decisions are recorded. Execution is deterministic. Agents (Claude, GPT, etc.) read the world, reason, and invoke actions—but the world itself carries the work.
LLM agent creates tasks in Substrate. Systems decompose work. Agent reads results, decides next step. Crash? Load snapshot + replay events. No lost context.
Hit a bug mid-workflow. Rollback to step 5. Fork a branch. Test hypothesis. Keep main timeline intact. Explore without consequences.
Multiple Claude instances share one world. SessionContext is the working memory. No chat residue; all state is queryable.
Every mutation is an event. Event log is JSONL—append-only, immutable. What was analyzed? What was decided? Why? All in the log.
Task decomposition doesn't rely on LLM calls. ECS systems (Planner, Router, Executor) run deterministically. No hallucination in workflow structure.
Index artifacts once. Reuse summaries and facts across turns. No re-processing. Tasks reference concrete entities, not hand-wavy context.
Entities: tasks, artifacts, messages, memories, agents, tools, constraints, goals. Not just chat. AI reasons over structured state.
Fork → try approach B → rollback if it fails. Original world untouched. Safe exploration.
deno run --allow-read --allow-write src/cli.js init# Artifact (document, code, link, etc.)
deno run --allow-read --allow-write src/cli.js create-artifact "My Doc" "https://..." "0.95"
# Task (work to do)
deno run --allow-read --allow-write src/cli.js create-task "analyze-document" "Analyze it" "2"
# Message (input to agent)
deno run --allow-read --allow-write src/cli.js create-message "user" "What's in the doc?"# Run 5 ticks (planning, routing, execution, attention)
deno run --allow-read --allow-write src/cli.js tick 5# View session context (tasks, artifacts, messages, focus)
deno run --allow-read --allow-write src/cli.js query session:2# Save checkpoint
deno run --allow-read --allow-write src/cli.js snapshot "before-branch"
# Fork world
deno run --allow-read --allow-write src/cli.js fork
# Rewind
deno run --allow-read --allow-write src/cli.js rollback 3
# View history
deno run --allow-read --allow-write src/cli.js list-snapshots
deno run --allow-read --allow-write src/cli.js eventsEntity-Component-System model. Entities (tasks, agents, artifacts, etc.). Components (state, metadata). Systems (planning, execution, attention).
- PlanningSystem — decomposes answer-user tasks into analyze + draft subtasks
- ToolRoutingSystem — matches tasks to online tools
- ExecutionSystem — runs tasks, produces output, creates side effects
- AttentionSystem — scores tasks, updates session focus
- IndexDocumentsSystem — indexes artifacts, extracts summaries + facts
Every N ticks, snapshot full world state (configurable). Between snapshots, event log captures every mutation (JSONL format). Crash? Load snapshot + replay events.
SessionContext: computed on-demand from entity hierarchy. No stale data. Artifacts, tasks, messages, memories, focus—all live views.
Direct subprocess calls. No HTTP overhead. Minimal serialization.
deno run --allow-read --allow-write src/cli.js query session:1
deno run --allow-read --allow-write src/cli.js create-task ...Model Context Protocol server. Claude Code calls Substrate via tool_use. The project-scoped config lives in .mcp.json at the repo root:
{
"mcpServers": {
"substrate": {
"command": "deno",
"args": [
"run",
"--allow-read",
"--allow-write",
"src/substrate-server.ts"
],
"cwd": "/home/pjensen/Repos/Substrate"
}
}
}Codex uses TOML config. The repo-local config lives in .codex/config.toml:
[mcp_servers.substrate]
command = "deno"
args = [
"run",
"--allow-read",
"--allow-write",
"src/substrate-server.ts",
]
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 60Import as Deno module. Call world.tick() directly in agent code.
import { World } from "./src/main.js";
const world = new World();
world.tick(1);- ProjectEntity — root container
- SessionEntity — conversation context
- TaskEntity — unit of work
- Artifact — knowledge resource (doc, code, link)
- AgentEntity — decision maker (declarative; not yet used in execution)
- ToolEntity — executor (analyze-document, draft-answer, etc.)
- MessageEntity — user/assistant exchange
- MemoryEntity — durable facts
State attached to entities:
- TaskState — kind, status, input, output, priority
- ArtifactState — title, uri, trust, needsIndex
- SessionState — turn, status, focus
- AgentState — role, busy, budget
- ToolState — name, online, supports[], latency
- Summary, Facts — indexed knowledge
- Attention — task scoring
- MemoryNote — semantic facts
- Index — mark artifacts needsIndex→false, add Summary + Facts
- Plan — decompose new tasks into subtasks
- Route — assign tasks to online tools
- Execute — run assigned tasks, produce output
- Attend — score tasks, update session focus
- Persist — snapshot world, drain event log
- ✅ Durable snapshots + event log
- ✅ Rollback to any step
- ✅ Fork/branch exploration
- ✅ Event sourcing (JSONL audit trail)
- ✅ Sparse checkpointing (events close gaps between snapshots)
- ✅ Deterministic task decomposition
- ✅ CLI tool surface
- 🔜 MCP integration
- 🔜 Agent capability routing
- 🔜 Budget enforcement
- 🔜 Multi-branch merging
- Transactional History & Branching — snapshot, rollback, fork
- Event Sourcing — mutation capture, replay, delta compression
- Agents — agent semantics, future routing
deno task test24 tests covering event log, snapshots, transaction ops, and end-to-end workflows.
deno task start # Run 3-tick demo with event logging
deno task test # Run all tests
deno run --allow-read --allow-write src/cli.js --help # CLI helpMIT (for now; subject to change).