trellis/ai
Semantic embeddings, vector search, and RAG context generation for intelligent code discovery.
Overview
The trellis/ai subpath provides semantic intelligence on top of the Trellis graph: embedding issues, milestones, files, code entities, and decisions into a vector store for intelligent search and retrieval-augmented generation (RAG).
import { EmbeddingManager } from "trellis/ai";
EmbeddingManager
The EmbeddingManager connects the Trellis engine to an embedding store and keeps it in sync as the graph changes:
const manager = new EmbeddingManager(engine, { dbPath: ".trellis/embeddings.db" });
// Index all entities (run once or after bulk changes)
await manager.reindex();
Configuration
interface EmbeddingConfig {
dbPath: string;
model?: string; // Embedding model identifier
dimensions?: number; // Vector dimensions (default: 1536)
batchSize?: number; // Entities per embedding batch (default: 50)
autoEmbed?: boolean; // Auto-embed on every op (default: true)
}
Semantic Search
Search across all embedded entities using natural language:
const results = await manager.search("authentication flow", { limit: 10 });
// SearchResult[] — { entityId, entityType, score, snippet }
CLI
trellis ask "authentication code" # Semantic search
trellis ask "auth flow" --rag # Output as RAG context for LLMs
RAG Context Generation
Generate structured context blocks for LLM prompts:
const context = await manager.getRAGContext("authentication implementation");
// string — formatted context with entity references and snippets
The RAG context includes:
- Relevant file snippets with line numbers
- Linked issues and decisions
- Recent milestone messages that touch the queried topic
- Cross-references from the wiki-link graph
What Gets Embedded
By default, EmbeddingManager embeds:
| Entity Type | Source Text |
|---|---|
File | Full file content |
ASTEntity | Function/class signature + doc-comment |
Issue | Title + description + acceptance criteria |
Milestone | Message + affected file paths |
Decision | Tool name + rationale + output summary |
WikiRef | Target entity label + surrounding context |
Auto-Embedding
When autoEmbed: true (the default), the manager subscribes to op events and re-embeds changed entities in the background:
const manager = new EmbeddingManager(engine, {
dbPath: ".trellis/embeddings.db",
autoEmbed: true, // default
});
Newly modified files, created issues, and recorded decisions are indexed within seconds of creation.
Querying the Vector Store Directly
For custom retrieval pipelines:
const store = manager.vectorStore;
const nearest = await store.query(queryVector, { k: 5, minScore: 0.75 });
// { id: string; score: number; metadata: Record<string, unknown> }[]