# The Story: Why Trellis Exists > Trellis is not a better database. It's a structured runtime for the agentic era—the system of record for **decisions**, providing agents with the memory they need to act, learn, and explain themselves. --- ## The Problem: The Reasoning/State Gap We are currently witnessing an explosion in **reasoning engines** (LLMs). We have models that can code, plan, and simulate human logic with startling accuracy. But as soon as these reasoning engines are asked to step outside of a single chat window and act as **agents** in the real world, they hit a wall. The wall isn't a lack of intelligence. The wall is a **lack of structured state**. ### The Wall Agents Hit When an AI agent is deployed into a complex environment—handling a code migration, managing a support queue, or orchestrating a multi-step financial workflow—it immediately faces three existential problems: 1. **Amnesia**: The agent's context window is fleeting. It forgets the nuances of decisions it made ten minutes ago, leading to repetitive mistakes or "hallucinated" progress. 2. **Opacity**: When an agent makes a mistake (like deleting a critical file or misinterpreting a policy), humans have no way to audit *why* it did what it did. The reasoning is trapped in a non-deterministic black box. 3. **Fragility**: Agents lack a "safety net." If an agent begins a destructive path, there is no built-in mechanism to "fork" the environment, test a hypothesis, and roll back if it fails. ### What's Missing: Causal Memory Consider an agent tasked with refactoring a legacy authentication module: - It analyzes the code ✓ - It proposes three changes ✓ - It runs the tests ✓ But then it hits the wall. **Why was this specific encryption logic added three years ago?** The agent sees the code, but not the *decision trace*. The reasoning happened in a Jira ticket, a Slack thread, or a Zoom call. To the agent, the most important context for the refactor is invisible tribal knowledge. **What happens if this refactor breaks a downstream dependency?** In a traditional environment, the agent just breaks it. There is no first-class concept of a "simulation branch" where the agent can try the refactor, observe the causal effects on the graph, and discard the work if it's suboptimal. **How does it learn from previous agents?** If a different agent solved a similar problem last week, those "lessons learned" are usually lost. They aren't stored as queryable, structured precedents that the new agent can cite and follow. --- ## The Insight: Decision Traces as the Agentic Kernel What if an agent's reasoning wasn't just transient text, but **first-class data**? In Trellis, every action—every file change, every tool call, every rationale—is recorded as an immutable **Decision Trace** in a causal graph. When an agent refactors that auth module in Trellis, it doesn't just change the lines. It: - **Gathers Context**: It queries the graph for prior decisions linked to this file. - **Records Rationale**: It explains *why* it's moving a symbol or changing a dependency. - **Signs its Work**: Every operation is cryptographically signed by the agent's identity. - **Creates Precedent**: Its successful refactor becomes a structured "triple" in the graph that future agents can search and follow. **With Trellis, the agent's 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 ``` This is now **queryable intelligence**. --- ## The Feedback Loop: The Compounding Agent Here is where the magic happens. Because Trellis stores decisions as a **graph**, the agentic environment becomes a self-improving system. **Day 1:** An agent encounters a complex merge conflict. It asks for human help. The human's resolution and rationale are recorded. **Day 5:** A different agent hits a similar conflict. It searches the graph for "precedent: merge-conflict-resolution." It finds the Day 1 decision, cites it as the justification for its action, and resolves the conflict autonomously. **Day 30:** After 1,000 runs, the repository contains a dense "Experience Graph." The agents aren't just following static rules; they are navigating a living library of context that makes them smarter with every operation. --- ## The Pivot: From VCS to Agentic Framework For decades, we used Version Control to track *files*. In the agentic era, we need something more. We need to track **intent, context, and reasoning**. Trellis is the kernel for this new layer. It provides: - **Immutable Causal History**: No more amnesia. The agent has a perfect memory of every state change and why it happened. - **Semantic Understanding**: Agents operate on AST entities (functions, classes), not just lines of text. - **Safety through Branching**: Agents can "hallucinate" in a fork, test their theories, and only commit to the causal stream when they are certain. - **Auditable Accountability**: Every agent action is traceable, signable, and explainable to human overseers. **We are moving from a world where humans tell computers *what* to do, to a world where agents act on our behalf. Trellis is the system of record that ensures they do it correctly.** --- ## The System of Record for the Next Era The last generation of enterprise software was built on owning the **System of Record for Objects** (Salesforce for customers, Workday for employees). The next generation—the Agentic Era—will be won by whoever owns the **System of Record for Decisions**. Trellis is that layer. --- ## References - [AI's Trillion-Dollar Opportunity: Context Graphs](./CONTEXT-GRAPHS.md) — The market thesis - [Five Pillars](./PILLARS.md) — The architectural foundation - [Agent Framework Guide](./AGENTS.md) — Building your first agent on Trellis - [Five Pillars](./PILLARS.md) — Trellis's core architectural principles