The Story

Why Trellis exists; the reasoning/state gap, decision traces as data, and the system of record for decisions.

Trellis is not a better database. It is a structured runtime for the agentic era: the system of record for decisions, giving agents the memory they need to act, learn, and explain themselves.

For the local-first graph thesis (projections, sovereignty, design principles), read Vision. This page is the agent-centric narrative: what breaks when reasoning engines leave the chat window, and how decision traces close the loop.

The problem: the reasoning/state gap

Reasoning engines (LLMs) can code, plan, and simulate logic with startling accuracy. When those engines step outside a single chat window and act as agents in the real world, they hit a wall.

The wall is not a lack of intelligence. It is a lack of structured state.

The wall agents hit

In a complex environment (a code migration, a support queue, a multi-step workflow), agents face three problems:

  1. Amnesia: The context window is fleeting. Nuance from ten minutes ago is gone, which drives repeated mistakes or "hallucinated" progress.
  2. Opacity: When an agent deletes a critical file or misreads a policy, humans cannot audit why. Reasoning stays in a non-deterministic black box.
  3. Fragility: There is no built-in way to fork the environment, test a hypothesis, and discard the work if it fails.

What's missing: causal memory

An agent refactoring legacy authentication might analyze the code, propose changes, and run tests. Then it stalls.

Why was this encryption logic added three years ago? The agent sees code, not the decision trace. The reasoning lived in a ticket, a thread, or a call. The refactor's most important context is tribal knowledge.

What if the refactor breaks a downstream dependency? In a traditional setup, it just breaks. There is no first-class simulation branch to try the change, observe effects on the graph, and discard if wrong.

How does it learn from prior agents? Last week's "lessons learned" rarely become queryable precedents the next agent can cite.

The insight: decision traces as the agentic kernel

What if reasoning were first-class data, not transient text?

In Trellis, every action (file change, tool call, rationale) is an immutable decision trace in a causal graph.

When an agent refactors that auth module, it:

  • Gathers context from prior decisions linked to the file
  • Records rationale for each structural change
  • Signs its work with its identity key
  • Creates precedent future agents can search and follow

With Trellis, a run looks like data:

Agent Run: auth-refactor-3000
├─ Inputs Gathered:
│     ├─ Knowledge: [[Decision:DEC-42]] (Why we use AES-256)
│     ├─ Semantic: [[src/auth.ts#encrypt]] (AST structural view)
│     └─ Related: [[Issue:TRL-105]] (The original requirements)
├─ Simulation Branch: feature/agent-exploration-1
├─ Tool Call: symbolMove(encrypt, src/crypto.ts)
├─ Rationale: "Following crypto-locality policy v2."
├─ Decision: Approved by Test Suite
└─ Outcome: Merged to main

That structure is queryable intelligence. See Decision traces for how this works in the CLI and MCP harness today.

The feedback loop: the compounding agent

Because decisions live in a graph, the environment can compound:

Day 1: An agent hits a merge conflict, asks for help. The human resolution and rationale are recorded.

Day 5: Another agent hits a similar conflict, searches for precedent, cites the Day 1 decision, and resolves autonomously.

Day 30: After many runs, the repo holds a dense experience graph. Agents navigate a living library of context, not only static rules.

From VCS to agentic framework

For decades, version control tracked files. In the agentic era, we need to track intent, context, and reasoning.

Trellis is the kernel for that layer:

  • Immutable causal history: memory of every state change and why
  • Semantic understanding: AST entities, not only line diffs
  • Safety through branching: explore in a fork, merge when certain
  • Auditable accountability: traceable, signable actions for human overseers

We are moving from humans telling computers what to do, to agents acting on our behalf. Trellis is the system of record that keeps that legible.

The system of record for the next era

The last generation of enterprise software owned the system of record for objects (customers, employees, assets).

The agentic era will be shaped by whoever owns the system of record for decisions.

Trellis is built for that layer.

Go deeper

Kernel repo mirror: THE-STORY.md (keep in sync on substantive edits).