How do I install Trellis Ai?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Trellis Ai need an API key?

No required environment variable is listed on this record.

What transport does Trellis Ai use?

Trellis Ai runs locally over stdio.

When was Trellis Ai last checked?

Last checked 2026-10-28. Shared context substrate for AI agents. Retrieval that learns what's useful. Runs local or cloud.

เซิร์ฟเวอร์ MCP Trellis Ai

Trellis

A memory system for AI agents — personal and shared. Agents save memories, experiences, and knowledge from flexible sources. Trellis deduplicates and embeds them on ingest for semantic retrieval, builds a cross-agent graph, attributes outcomes back to the exact context items that produced them, and tunes retrieval under statistical governance. Multi-backend (SQLite, Postgres + pgvector, ArcadeDB, Neo4j, S3). Four interfaces (CLI, MCP, REST, Python SDK). One install.

%%{init: {"flowchart": {"curve": "basis"}}}%%
flowchart LR
    Agent(["🤖 Agent"]) -->|reads| Pack("📦 Context pack")
    Pack -->|grounds| Work("🛠️ Does work")
    Work -->|writes| Trace("📝 Trace + feedback")
    Trace --> Memory[("🧠 Graph +<br/>audit log")]
    Memory -.->|"better pack next time — noise demoted, weights tuned"| Pack

    classDef agent fill:#312e81,stroke:#818cf8,stroke-width:2px,color:#eef2ff;
    classDef read fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#ecfdf5;
    classDef work fill:#1e293b,stroke:#60a5fa,stroke-width:2px,color:#eff6ff;
    classDef write fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#fffbeb;
    classDef store fill:#4a044e,stroke:#f472b6,stroke-width:2px,color:#fdf2f8;
    class Agent agent;
    class Pack read;
    class Work work;
    class Trace write;
    class Memory store;
    linkStyle 4 stroke:#34d399,stroke-width:2px;

Most "agent memory" attributes feedback to a session or a user. Trellis attributes it to the specific items served in the pack. That's the seam that lets noise suppression, advisory fitness, and parameter promotion all work from the same signal — and lets multiple agents share a substrate where institutional knowledge compounds instead of evaporating at the end of each session.

Why Trellis vs rolling your own?

A useful cross-agent knowledge layer means assembling, at minimum:

an immutable trace store with schema validation and an audit log
a graph store with temporal versioning (SCD-2) so "what did we know at time T?" is answerable
a vector + keyword search wired into the same query layer
a retrieval engine that combines them, dedupes by item id, and enforces a token budget
feedback attribution to the specific items served (not just the session or the user)
a statistical-gating mechanism so noisy feedback doesn't destroy your weights
a governed mutation pipeline that won't let agents corrupt the graph
an MCP server, REST API, Python SDK, and CLI around all of it
a tiered extractor that graduates from LLM-driven to deterministic as patterns stabilize
a plugin contract so adopters can swap any backend without forking core

Trellis ships all of that as one install. Started from a vector DB plus glue code, the list above is months of yak-shaving — most of which doesn't surface until something breaks.

What Trellis is NOT

Not a vector DB. Vectors are one of six stores. Pluggable behind the same API (SQLite, pgvector, ArcadeDB, Neo4j HNSW).
Not a session blob. Trellis is agent memory — personal-agent or cross-agent — but feedback attributes to the specific items served, not to a session or user, and multiple agents can share the same substrate.
Not a RAG framework. RAG is one access pattern; Trellis adds attribution, statistical governance, and an audit log around it.
Not a managed service. Self-hosted: local SQLite, or your Postgres / ArcadeDB / Neo4j. One pip install (or one Docker image).
Not a prompt library. Trellis stores what happened (traces) and what was learned (precedents + advisories) — not what to say.

When not to use Trellis

You're building a single-session chatbot. The overhead is unjustified — prompt engineering is enough.
You only need vector similarity. A bare vector DB is simpler.
Your agent has no need to learn from past work. Pure tool-call agents don't benefit.
You're at < 100 agent runs total. The statistical-governance machinery has nothing to chew on yet.

Quickstart — 60 seconds

pip install trellis-ai
trellis admin init          # write ~/.trellis/config.yaml + init SQLite stores
trellis demo load           # populate 66 realistic items: entities, traces, precedents
trellis admin serve         # open http://localhost:8420

You'll land on the dashboard. Try:

trellis retrieve search 'user-api'           # keyword + semantic search
trellis retrieve entity user-api             # entity with neighborhood
trellis retrieve traces --domain backend     # recent agent work in a domain
trellis retrieve pack --intent "deploy staging for user-api"   # the pack an agent would be served

Every CLI command supports --format json for machine output.

Wiring an external agent system into Trellis? Start at the one-page decision tree: docs/getting-started/integrate-your-agent.md. For MCP-speaking agents, trellis admin quickstart --with-skills user sets up the stores and the drop-in skills, then prints the claude mcp add command that registers the MCP server with Claude Code.

Setting up for a team, a data platform, or production? Local single-user needs no decisions. Beyond that, a few choices are yours to make and easy to miss — domains & ontology, domain ownership, and API security. They're laid out as a checklist in docs/getting-started/setup-decisions.md.

Architecture at a glance

flowchart TB
    Users(["🤖 Agents + 🧑 Humans — Claude, LangGraph, scripts, CI"])

    subgraph Interfaces["🔌 Interfaces"]
        direction LR
        CLI("CLI<br/>trellis") ~~~ MCP("MCP Server<br/>16 tools") ~~~ REST("REST API<br/>FastAPI") ~~~ SDK("Python SDK<br/>HTTP client") ~~~ UI("Web UI<br/>Memory Explorer")
    end

    subgraph Core["⚙️ Core engine"]
        direction LR
        PB("📦 Pack Builder<br/>keyword + semantic + graph<br/>dedupe · rerank · token budget") ~~~ GP{{"🛡️ Governed Mutations<br/>validate → policy → idempotency<br/>→ execute → emit event"}} ~~~ CL("🏷️ Classification<br/>4 deterministic classifiers<br/>LLM fallback (async)") ~~~ WK("🔄 Workers<br/>enrichment · pattern mining<br/>maintenance · curation")
    end

    subgraph Data["🗄️ Data layer"]
        direction LR
        TR[("Traces<br/>immutable")] ~~~ GR[("Graph<br/>SCD Type 2")] ~~~ DO[("Documents<br/>full-text")] ~~~ VE[("Vectors<br/>semantic")] ~~~ EL[("Event Log<br/>audit")] ~~~ BL[("Blobs<br/>files")]
    end

    subgraph Backends["🧩 Pluggable backends"]
        direction LR
        SQ("SQLite<br/>default / local") ~~~ AR("ArcadeDB<br/>blessed: graph + vector") ~~~ PG("Postgres + pgvector<br/>cloud alternative") ~~~ S3("S3<br/>blob storage")
    end

    Users ==> Interfaces
    Interfaces ==> Core
    Core ==> Data
    Data ==> Backends

    classDef iface fill:#1e293b,stroke:#818cf8,stroke-width:2px,color:#eef2ff;
    classDef agent fill:#312e81,stroke:#a5b4fc,stroke-width:2px,color:#eef2ff;
    classDef core fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#ecfdf5;
    classDef data fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#fffbeb;
    classDef back fill:#4a044e,stroke:#f472b6,stroke-width:2px,color:#fdf2f8;
    class CLI,MCP,REST,SDK,UI iface;
    class Users agent;
    class PB,GP,CL,WK core;
    class TR,GR,DO,VE,EL,BL data;
    class SQ,PG,S3,AR back;
    style Interfaces fill:#0b1120,stroke:#6366f1,stroke-width:1px,stroke-dasharray:6 4,color:#a5b4fc;
    style Core fill:#0b1120,stroke:#10b981,stroke-width:1px,stroke-dasharray:6 4,color:#6ee7b7;
    style Data fill:#0b1120,stroke:#f59e0b,stroke-width:1px,stroke-dasharray:6 4,color:#fcd34d;
    style Backends fill:#0b1120,stroke:#ec4899,stroke-width:1px,stroke-dasharray:6 4,color:#f9a8d4;

What's in the substrate

%%{init: {"flowchart": {"curve": "basis"}}}%%
flowchart TB
    subgraph Graph["🕸️ Entity graph — temporally versioned"]
        direction LR
        A("🧩 service<br/>auth-api") -- depends_on --> B("🧩 service<br/>user-db")
        A -- part_of --> C("👥 team<br/>platform")
    end

    T("📝 trace — 'Added rate limiting to auth-api'<br/>• researched existing patterns<br/>• tool_call edit_file gateway.py<br/>• tool_call run_tests ✅ 42 passed<br/>• outcome: success")
    E("📄 evidence — 'RFC: API guidelines'<br/>uri: s3://…")
    P("⭐ precedent — 'Rate limiting pattern<br/>for API gateways'<br/>confidence: 0.85<br/>applies_to: [auth, payments]")

    A -. touched_entity .-> T
    T -- used_evidence --> E
    T == promoted_to_precedent ==> P

    classDef entity fill:#1e293b,stroke:#818cf8,stroke-width:2px,color:#eef2ff;
    classDef trace fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#ecfdf5;
    classDef evidence fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#fffbeb;
    classDef precedent fill:#4a044e,stroke:#f472b6,stroke-width:2px,color:#fdf2f8;
    class A,B,C entity;
    class T trace;
    class E evidence;
    class P precedent;
    style Graph fill:#0b1120,stroke:#6366f1,stroke-width:1px,stroke-dasharray:6 4,color:#a5b4fc;

Every node carries valid_from / valid_to — query any past state with as_of.

Traces — what agents did: steps, tool calls, reasoning, outcomes. Immutable.
Entities + edges — the graph of services, teams, tools, datasets, and how they relate. Temporally versioned.
Evidence — documents and snippets agents read, with URIs to local files or S3.
Precedents — distilled patterns promoted from successful (and failed) traces.
Events — a full audit log of every mutation, for observability and effectiveness analysis.

How Trellis improves

Most "agent memory" systems attribute feedback to a session or a user. Trellis attributes it to the exact items that were served. Every assembled pack carries a pack_id plus per-item refs; when the agent reports success or failure, a FEEDBACK_RECORDED event joins cleanly back to the specific items, advisories, and strategies that produced the pack.

Three mechanisms build on that attribution:

Noise suppression. Items whose post-hoc success rate drops below a threshold get tagged signal_quality="noise" and are excluded from future packs by default. This happens via the EventLog-authoritative loop (run_effectiveness_feedback) — no manual review required.
Governed parameter promotion. Retrieval scoring weights (recency half-life, domain boosts, position decay) are tunable per (component, domain) cell. Observed outcomes propose parameter changes; promote_proposal only applies them when sample size and effect size clear a statistical gate (defaults: 5 samples, 15% effect). This is the stair-step — each cycle can sharpen retrieval, but only on evidence strong enough to survive the gate.
LLM bootstraps, deterministic inherits. Classification runs four deterministic classifiers inline; the LLM only fires when confidence is below threshold. Extraction routes DETERMINISTIC > HYBRID > LLM, with LLM as an opt-in fallback (allow_llm_fallback=False by default). As rules and tags stabilize, the cost curve drops — the LLM did the bootstrapping, and deterministic paths inherit the signal.

Packs are assembled fresh on every call today — nothing is pregenerated or cached — so every improvement (new noise tags, new parameter snapshots, new precedents) applies immediately to the next retrieval. Session-aware dedup prevents the same items from being re-served to the same agent within a 60-minute window.

How the feedback loop works

%%{init: {"flowchart": {"curve": "basis"}}}%%
flowchart TB
    IF(["🤖 Agents — CLI • MCP • REST • Python SDK"])

    Pack("📦 Context Pack Builder<br/>keyword + semantic + graph<br/>dedupe → rerank → token-budget")
    Work("🛠️ Agent does work<br/>emits trace + feedback")
    Mut{{"🛡️ Governed Write Pipeline<br/>validate → policy → idempotency<br/>→ classify → execute → emit event"}}
    Store[("🗄️ Pluggable Storage<br/>SQLite · Postgres + pgvector<br/>ArcadeDB · Neo4j · S3")]
    W("🔄 Background workers<br/>• noise tagging<br/>• advisory fitness<br/>• precedent promotion<br/>• extraction-tier graduation")

    IF ==> Pack
    Pack == "markdown context" ==> Work
    Work ==> Mut
    Mut ==> Store
    Store --> W
    W -. "tags · advisories · precedents" .-> Pack

    classDef iface fill:#312e81,stroke:#a5b4fc,stroke-width:2px,color:#eef2ff;
    classDef core fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#ecfdf5;
    classDef gate fill:#1e293b,stroke:#60a5fa,stroke-width:2px,color:#eff6ff;
    classDef store fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#fffbeb;
    classDef worker fill:#4a044e,stroke:#f472b6,stroke-width:2px,color:#fdf2f8;
    class IF iface;
    class Pack,Work core;
    class Mut gate;
    class Store store;
    class W worker;
    linkStyle 5 stroke:#f472b6,stroke-width:2px;

How a trace flows through Trellis

%%{init: {"flowchart": {"curve": "basis"}}}%%
flowchart LR
    A(["🤖 Agent<br/>does work"]) ==> I("1️⃣ Ingest<br/>validate schema")
    I ==> PG{{"2️⃣ Policy Gate<br/>check rules"}}
    PG ==> CL("3️⃣ Classify<br/>tag 4 facets")
    CL ==> EX[("4️⃣ Execute<br/>write to stores")]
    EX ==> EV("5️⃣ Emit event<br/>append to log")

    EV -. feedback .-> W("🔄 Workers<br/>effectiveness · noise<br/>precedent promotion")
    W -. "tags · advisories" .-> PBx("📦 Pack Builder<br/>assembles next pack")
    PBx ==> A2(["🤖 Agent<br/>next task"])

    classDef agent fill:#312e81,stroke:#a5b4fc,stroke-width:2px,color:#eef2ff;
    classDef write fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#fffbeb;
    classDef gate fill:#1e293b,stroke:#60a5fa,stroke-width:2px,color:#eff6ff;
    classDef read fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#ecfdf5;
    classDef worker fill:#4a044e,stroke:#f472b6,stroke-width:2px,color:#fdf2f8;
    class A,A2 agent;
    class I,CL,EX,EV write;
    class PG gate;
    class PBx read;
    class W worker;
    linkStyle 5,6 stroke:#f472b6,stroke-width:2px;

Packs carry pack_id and per-item refs; when the agent reports success or failure, feedback is attributed back to the exact items that were in the pack. Background workers aggregate that feedback into noise tags (so low-signal items drop out of future packs) and advisory confidence adjustments (so learned rules get sharper). Successful traces can be promoted to precedents, which then seed future packs for similar tasks.

Install

Requires Python 3.11+.

pip install trellis-ai                    # core (SQLite everywhere — local default)
pip install "trellis-ai[arcadedb]"        # + ArcadeDB (blessed graph + vector via Bolt + HTTP)
pip install "trellis-ai[cloud]"           # + Postgres, pgvector, S3
pip install "trellis-ai[neo4j]"           # + Neo4j driver (graph + vector via Bolt / AuraDB)
pip install "trellis-ai[llm-openai]"      # + OpenAI for enrichment & extraction
pip install "trellis-ai[llm-anthropic]"   # + Anthropic
pip install "trellis-ai[all]"             # everything

Git-pinned installs (consumers vendoring Trellis from a SHA)

Published-package extras (trellis-ai[arcadedb]) work as above. If instead you pin Trellis directly from Git, the intuitive PEP 508 extras-on-a-URL form is awkward and some build tooling (pip resolver edge cases, older Poetry, certain lockfile generators) rejects it:

# Often rejected / awkward depending on tooling:
trellis-ai[arcadedb] @ git+https://github.com/ronsse/trellis-ai.git@<sha>

The portable workaround is to pin Trellis by direct URL without the extra, and declare the underlying driver dependency yourself. The extras are thin — each just pulls one driver:

Extra	Add this dependency directly
`[arcadedb]`	`neo4j>=5.20` (ArcadeDB speaks the Neo4j Bolt wire protocol)
`[neo4j]`	`neo4j>=5.20`
`[cloud]`	`psycopg[binary]>=3.1`, `psycopg-pool>=3.1`, `pgvector>=0.3`, `boto3>=1.34`

# pyproject.toml — Git-pinned consumer
dependencies = [
  "trellis-ai @ git+https://github.com/ronsse/trellis-ai.git@<sha>",
  "neo4j>=5.20",   # what [arcadedb]/[neo4j] would have pulled
]

See #198 for context.

Interfaces

CLI — trellis for humans and scripts. Every command has --format json.

trellis ingest trace trace.json
trellis retrieve pack --intent "..." --domain backend --max-tokens 2000
trellis curate promote TRACE_ID --title "..." --description "..."
trellis analyze context-effectiveness
trellis classify backfill --dry-run  # re-tag stored documents (preview first)
trellis admin check-extractors       # readiness diagnostic for tiered extraction
trellis admin migrate-graph \
  --from-config sqlite.yaml \
  --to-config aura.yaml      # backend-agnostic graph migration (SQLite↔Postgres↔Neo4j)

REST API — trellis admin serve or trellis-api. OpenAPI at /docs, UI at /.

Method	Endpoint	Purpose
POST	`/api/v1/traces`	Ingest a trace
POST	`/api/v1/documents`	Store a document (embeds on ingest when enabled)
POST	`/api/v1/packs`	Assemble a context pack
POST	`/api/v1/packs/sectioned`	Assemble a sectioned pack (per-section budgets)
GET	`/api/v1/entities/{id}`	Entity + neighborhood
GET	`/api/v1/documents`	Browse/search stored documents
GET	`/api/v1/events`	Tail the audit event log
GET	`/api/v1/packs`	Inspect assembled-pack telemetry
GET	`/api/v1/graph/history`	SCD-2 version history for a node
POST	`/api/v1/feedback`	Record pack outcome
GET	`/api/v1/effectiveness`	Pack effectiveness report

MCP server — trellis-mcp. Local agents use the default stdio transport; remote clients use the opt-in HTTP transport (TRELLIS_MCP_TRANSPORT=http, bearer-token auth), documented in adr-mcp-http-transport.md. Sixteen macro tools. Thirteen return markdown, not raw JSON, so context lands clean in the agent's window; the three structured tools (record_observation, query_observations, execute_mutation) return JSON.

Tool	Purpose
`get_context`	Combined keyword + semantic + graph search → markdown pack
`get_objective_context`	Objective-tier sectioned pack (domain + operational)
`get_task_context`	Task-tier sectioned pack scoped to entities
`get_sectioned_context`	Custom sectioned pack with per-section budgets
`save_experience`	Ingest a trace
`save_knowledge`	Create entity + optional relationship
`save_memory`	Store a document: content-hash + MinHash dedup, classify-on-write, embed-on-ingest; tiered extraction when `TRELLIS_ENABLE_MEMORY_EXTRACTION=1`
`record_observation`	Record an empirical observation about an entity
`query_observations`	Query recorded observations
`get_lessons`	Precedents as markdown
`get_graph`	Entity + neighborhood as markdown
`get_items`	Full bodies for known item ids (max 50), token-budgeted — the fetch step after an index pack
`get_file_context`	Stored context for file paths: documents whose `source_path` names the file, plus doc-linked entities
`record_feedback`	Grade a pack (`rating` 0.0–1.0) or a trace, with per-item attribution; writes the JSONL audit row and the authoritative event
`search`	Combined doc (keyword + semantic) + graph search as markdown
`execute_mutation`	Governed mutation escape hatch (validate → policy → execute → audit)

Retrieval tools accept max_tokens (default 2000; get_items defaults to 4000, and the three sectioned tools to retrieval.budgets in config.yaml, or 4000 if it is unset). With TRELLIS_ENABLE_EMBED_ON_INGEST=1 and an embedder configured, documents saved via save_memory, save_knowledge, POST /documents, POST /evidence, trellis ingest corpus / conversations or trellis ingest dbt-manifest become semantically retrievable immediately; backfill existing documents with trellis admin reindex-vectors.

System prompt — a model you call with an API key, a framework agent or a dispatched subagent reads no skill. trellis admin show-prompt prints the retrieve, record, grade loop as a system prompt (--variant claude-md and --variant agent-rule print the shorter forms); docs/getting-started/system-prompt.md says where to paste each.

Python SDK — HTTP-only (import trellis_sdk): point base_url at a running trellis admin serve, or use trellis.testing.in_memory_client in tests. Against a server running TRELLIS_AUTH_MODE=required, pass api_key= so the client sends it as Authorization: Bearer on every request.

from trellis_sdk import TrellisClient

client = TrellisClient(base_url="http://localhost:8420")

pack = client.assemble_pack("deploy checklist for staging", max_tokens=2000)
trace_id = client.ingest_trace(trace_dict)
client.record_feedback(pack["pack_id"], rating=0.8, helpful_item_ids=[...])

Skill helpers return pre-summarized markdown strings for direct LLM injection:

from trellis_sdk.skills import get_context_for_task

context = get_context_for_task(client, "implement retry logic", domain="backend")

The returned markdown carries the pack_id whenever the pack has items; pass it to client.record_feedback together with the item ids the model cites.

Planes & substrates

Trellis separates agent-facing stores from Trellis-internal stores. Each plane has a blessed default backend ("substrate"); other backends are opt-in. Backends are pluggable — SQLite is the local default for everything, ArcadeDB is the blessed graph + vector substrate for self-hosted AWS deployments (Apache 2.0, Bolt + openCypher 25, native HNSW), and Postgres + pgvector remains a supported alternative for cloud workloads.

flowchart LR
    subgraph Knowledge["🧠 Knowledge Plane — agent-facing"]
        direction TB
        G[("Graph<br/>entities + edges")] ~~~ D[("Documents<br/>full-text")] ~~~ V[("Vectors<br/>semantic similarity")] ~~~ B[("Blobs<br/>files & artifacts")]
    end

    subgraph Operational["⚙️ Operational Plane — Trellis-internal"]
        direction TB
        TR[("Trace store<br/>immutable work records")] ~~~ EL[("Event log<br/>mutation audit trail")]
    end

    subgraph Substrates["🧩 Substrates"]
        direction TB
        SQ("SQLite<br/>local default — every store") ~~~ PG("Postgres + pgvector<br/>cloud — every store but blobs") ~~~ AR("ArcadeDB — blessed<br/>graph + vector (Apache 2.0)") ~~~ N4("Neo4j + AuraDB<br/>graph + vector alternative") ~~~ S3("S3<br/>blobs in cloud")
    end

    Knowledge == "each store binds to a substrate<br/>via config.yaml" ==> Substrates
    Operational == "same registry,<br/>own plane" ==> Substrates

    classDef knowledge fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#ecfdf5;
    classDef ops fill:#4a044e,stroke:#f472b6,stroke-width:2px,color:#fdf2f8;
    classDef sub fill:#1e293b,stroke:#818cf8,stroke-width:2px,color:#eef2ff;
    classDef blessed fill:#1e293b,stroke:#34d399,stroke-width:2px,color:#ecfdf5;
    classDef alt fill:#1e293b,stroke:#94a3b8,stroke-width:2px,color:#cbd5e1,stroke-dasharray:5 5;
    class G,D,V,B knowledge;
    class TR,EL ops;
    class SQ,PG,S3 sub;
    class AR blessed;
    class N4 alt;
    style Knowledge fill:#0b1120,stroke:#10b981,stroke-width:1px,stroke-dasharray:6 4,color:#6ee7b7;
    style Operational fill:#0b1120,stroke:#ec4899,stroke-width:1px,stroke-dasharray:6 4,color:#f9a8d4;
    style Substrates fill:#0b1120,stroke:#6366f1,stroke-width:1px,stroke-dasharray:6 4,color:#a5b4fc;

Each store binds to a substrate through ~/.trellis/config.yaml; the table below has the exact store-by-store mapping. In the diagram, green-bordered substrates are blessed defaults and dashed ones are alternates. Choosing pgvector collocates keyword, semantic, and graph retrieval in a single Postgres transaction — one DSN, one consistency story. Neo4j (and AuraDB) is supported as a graph-native alternative for graph + vector when you want Cypher-native traversal or are already on a managed Neo4j instance.

Storage — local or cloud

Backends are wired from ~/.trellis/config.yaml (or $TRELLIS_CONFIG_DIR/config.yaml). SQLite is the local default; ArcadeDB is the blessed graph + vector substrate (Apache 2.0, Bolt + openCypher 25, native HNSW via jVector) — see docs/design/adr-arcadedb-blessed-substrate.md and docs/deployment/recommended-config.yaml for the recommended shape. Postgres + pgvector remains a supported alternative for shops standardized on Postgres. Neo4j / AuraDB is the migration target for existing Neo4j deployments — see docs/deployment/neo4j-local.md and docs/deployment/neo4j-auradb.md.

Store	Local default	Cloud blessed	Alternatives
Trace / Document / Event Log	`sqlite`	`postgres`	—
Graph	`sqlite`	`arcadedb`	`neo4j` (Bolt / AuraDB), `postgres`
Vector	`sqlite`	`arcadedb` (native HNSW)	`pgvector`, `neo4j` (HNSW on `:Node`)
Blob	`local`	`s3`	—

For copy-paste config, see docs/deployment/recommended-config.yaml — four shapes: ArcadeDB (blessed), Neo4j local, Neo4j cloud (AuraDB + Postgres) and Postgres-only. The REST API (trellis-api or trellis admin serve) builds every store when it starts, so a missing DSN or bucket stops startup instead of failing the first request. TRELLIS_VALIDATE_CONNECTIVITY=1 also checks each cached Bolt driver (Neo4j, ArcadeDB graph) with one round-trip.

knowledge:
  graph:
    backend: postgres   # DSN from TRELLIS_KNOWLEDGE_PG_DSN
  vector:
    backend: pgvector   # DSN from TRELLIS_KNOWLEDGE_PG_DSN
  blob:
    backend: s3
    bucket: trellis-artifacts
    region: us-east-1

Graph stores support SCD Type 2 temporal versioning — every node carries valid_from / valid_to, and get_node_history() returns the full audit trail. Pass as_of to any query to time-travel.

Classification & tiered extraction

Items are tagged on four orthogonal facets: domain, content_type, scope, signal_quality. Deterministic classifiers run inline (microseconds); LLM-backed classifiers only fire when deterministic confidence is below threshold.

Tagging at write time is opt-in: set TRELLIS_ENABLE_CLASSIFY_ON_INGEST=1 (also accepts true/yes/on) and five write seams tag as they store — bulk ingest (trellis ingest corpus, ingest conversations, the session-capture sweep), MCP save_memory and the evidence document save_knowledge creates, and REST POST /documents / POST /evidence. Fill-if-absent and fail-soft: existing tags are never clobbered, and a classification error stores the document untagged rather than failing the write. Everything else — rows stored before the flag was set, tags that have drifted, and the write paths outside those five seams — is covered by trellis classify backfill. Full contract: operations.md — Document → content tags.

Raw sources (agent messages, dbt manifests, OpenLineage events, …) flow through a tiered extraction pipeline: deterministic rule-based extractors run first, then hybrid JSON extractors, then LLM extraction as an opt-in fallback. As patterns stabilize, extraction graduates from expensive-but-universal LLM calls to cheap-and-deterministic rules — so the cost curve drops the more the domain crystallizes.

Integrations

New here? The integrate-your-agent decision tree picks the right path (MCP / Python SDK / REST) and gives each a verification step.

The Claude Code / Cursor / Claude Desktop rows are first-class — trellis-mcp ships with the package. The bottom three are reference templates under examples/integrations/ — copy the file into your own project rather than depending on it as a library.


Claude Code	`trellis admin quickstart`, then the `claude mcp add` command it prints
Cursor	Add Trellis MCP via `~/.cursor/mcp.json`
Claude Desktop	Add Trellis MCP via `claude_desktop_config.json`
OpenClaw template	MCP skill + `openclaw.json` snippet for OpenClaw agents
LangGraph template	Reference `tools.py` wrapping the SDK as LangChain tools
Obsidian template	Reference `vault.py` + `indexer.py` for indexing notes as evidence

Examples & skill templates

examples/ — runnable scripts: SDK in-memory + remote, retrieve→act→record loop, custom extractor, custom classifier, LangGraph agent, batch ingest.
skills/ — drop-in Claude Code skills: retrieve-before-task, record-after-task, link-evidence, trellis-loop. Install with trellis admin install-skills user (or trellis admin quickstart --with-skills user).
docs/getting-started/ — IDE-specific MCP setup walkthroughs.

Development

git clone https://github.com/ronsse/trellis-ai.git
cd trellis-ai
uv pip install -e ".[dev]"

pytest tests/unit/                # unit tests
pytest -m postgres                # postgres integration tests
pytest -m neo4j                   # neo4j integration tests (set TRELLIS_TEST_NEO4J_URI)
ruff check src/ tests/            # lint
mypy src/                         # type check

Docs

Getting started — 5-10 min on-ramp + IDE-specific MCP setup
Agent guide — trace format, schemas, operations reference, playbooks
Design docs — architecture, ADRs, classification, dual-loop evolution
CLAUDE.md — quick orientation for AI coding assistants working in this repo

Before writing an ingestion runner for a new source, read docs/agent-guide/modeling-guide.md — it covers the four-question test for deciding what becomes a node vs a property vs a document, and the anti-patterns to avoid.

License

MIT — see LICENSE.

Trellis Ai

เพิ่มเซิร์ฟเวอร์นี้

Host a copy with our keys and logs.

Server facts

Tools

Questions