Core Concepts

Six words carry most of the weight in Trellis: entity, op, causal stream, projection, capability, and identity. This page defines each one. Every other page in these docs assumes them.

The Graph

Everything in Trellis is an Entity-Attribute-Value graph. Not "stored in" one everything is the graph:

• Entities: Files, directories, branches, milestones, issues, code symbols, notes, people
• Attributes: Properties like name, status, contentHash, kind
• Values: The data itself
• Links: Relationships between entities (file→directory, milestone→ops, issue→branch)

CMS and knowledge-graph entities (types like person, note, calendar_event) persist as EAV facts via dedicated store op kinds (vcs:storeAssert, vcs:storeRetract, vcs:storeLink, vcs:storeUnlink). Payload fields live on VcsPayload.facts[] and VcsPayload.links[]. See trellis/vcs EAV store operations.

The graph is queryable using TQL (structured queries) or natural language via embeddings.

Ops and the Causal Stream

The graph never mutates in place. Every change produces an immutable VcsOp:

interface VcsOp {
  hash: string; // trellis:op:<sha256> content-addressed
  kind: VcsOpKind; // e.g. 'vcs:fileModify'
  timestamp: string; // ISO 8601
  agentId: string; // Author identity (DID)
  previousHash?: string; // Causal chain link
  vcs: VcsPayload; // Op-specific data
  signature?: string; // Ed25519 signature
}

Ops are append-only and content-addressed. They are never rewritten, rebased, or deleted. Each op links to its predecessor via previousHash, forming the causal stream the graph's memory. Current state is a derivation; the stream is the truth. This is why time travel is a primitive in Trellis, not a feature.

Op Tiers

Tier 0 ops are generated automatically by the file watcher. Tier 1 ops come from CLI/API commands. Tier 2 ops are produced by the semantic analysis engine.

Projections

A projection is a view over the graph: a query plus a renderer. A kanban board is a projection of type=Issue entities grouped by status. A timeline is a projection of the same entities ordered by date. A graph diagram, a table, an editor pane all projections.

This is the inversion that makes Trellis different from an app: the data doesn't live inside the view; the view is disposable and the data is permanent. Change the projection and the view changes. The data stays. Trellis Studio is itself a projection the first one not a privileged container.

Branches

Branches work similarly to Git they're named pointers into the causal stream. The key difference is CRDT support for conflict-free concurrent work:

trellis branch feature/new-parser    # Create + switch
trellis branch                       # List branches
trellis branch -d old-experiment     # Delete

Milestones vs Commits

A Git commit is a snapshot of the entire tree at a point in time. A Trellis milestone is a narrative marker that spans a range of ops:

• Milestones carry a human-readable message
• They reference the ops they cover (from → to)
• They list affected files
• They can be created retroactively

The Idea Garden

When you context-switch, abandon a branch, or revert changes, those ops don't disappear. The Idea Garden automatically detects these patterns and lets you search, inspect, and revive abandoned work.

Identity and Capability

Every actor in the graph human or AI agent is bound to an Ed25519 keypair you generate locally. Ops are cryptographically signed, so authorship is a property of the data, not a claim in someone's database. Capabilities control what an identity can do: governance policies decide who can create branches, merge, or modify protected paths all stored in the graph itself, not an external server. Agents get no special backdoor: same identity system, same rules, every decision traced.