Tessera
Persistent codebase intelligence for autonomous AI agents. Tessera gives agents bottom-up file access and top-down code understanding — across every project they're authorized to touch, with security from the ground up.
The Problem
Persistent AI agents — orchestrators like AutoJack, task agents like OpenClaw — need to understand codebases the way a senior developer does. Not just "find this string in a file," but "what calls this function, across which projects, and what breaks if I change it?"
Today's agents burn context window and wall-clock time on repeated grep / find / cat cycles. They lose track of project structure between conversations. They can't safely delegate to sub-agents without leaking access to projects those agents shouldn't see. And they can't search documentation, config files, or assets alongside code.
What Tessera Does
Tessera indexes everything — code, documents, config files, media assets, binary files — into a structured, chunked, searchable database. It exposes that through 18 MCP tools that any agent can call. Responses come back in milliseconds, not seconds.
For orchestrator agents: Full system visibility. Register projects, group them into collections, search across all of them. Understand cross-project dependencies. Delegate scoped access to sub-agents via session tokens.
For task agents: Deep code intelligence within their authorized scope. Symbol lookup, reference tracing, impact analysis, document search — everything an IDE provides, but through tool calls.
For security: Deny-by-default scope gating. Sub-agents only see what the orchestrator explicitly grants. Credentials and secrets are blocked from indexing by un-negatable security patterns. No ambient access, no scope creep.
Code Intelligence
- Symbol search — Functions, classes, methods, hooks by name or pattern
- Reference tracing — Call graphs, imports, inheritance chains
- Impact analysis — "What breaks if I change this?" — traced N levels deep
- File context — Complete structural overview of any file in one call
- Cross-project references — Track where project A's exports are used in project B
Event & Hook Analysis
- Cross-language event detection — WordPress hooks (PHP), EventEmitter/DOM (JS/TS), Django signals (Python),
@wordpress/hooks(JS) - Directional edges — Distinguish who registers a listener from who fires an event
- Mismatch detection — Find orphaned listeners (registered, never fired) and unfired events (fired, nobody listening)
- Action vs filter classification — WordPress-specific subtyping preserved without runtime analysis
- Wildcard queries —
events("pum_%")to explore hook namespaces - Pagination — Browse large event sets without blowing context windows
# Who listens to this hook?
events("pum_popup_content", direction="registers_on")
# Find all unfired events (potential dead code)
events(detect_mismatches=True, mismatch_filter="unfired")
# Explore a hook namespace
events("pum_%", direction="fires", limit=20)
Document & Text Search
- Chunked indexing — Files are split into focused, searchable chunks with metadata (by header, key path, or line group) — not stored as monolithic blobs
- Code + docs unified — Query across everything, or filter by source type (
code,asset,document) - Structural formats — PDF, Markdown (break-point scoring with distance decay), YAML/JSON (key-path chunking)
- Markup — HTML/XML with tag stripping
- Plaintext —
.txt,.rst,.csv,.log,.ini,.cfg,.toml, config files, dotfiles
Media & Binary File Indexing
- Asset discovery — Images, videos, audio, fonts, and archives are automatically discovered and indexed
- Metadata extraction — Filename, path, MIME type, file size, and image dimensions (PNG, JPEG, GIF, BMP) — zero external dependencies
- FTS5 searchable — Search for assets by name, category, format, or path components
- Source type filtering — Filter search results to
asset,code, ordocumentvia thesource_typeparameter - SVG dual-indexing — SVGs indexed as both searchable XML documents and image assets
Multi-Project Federation
- Project collections — Group related projects (e.g., a plugin ecosystem) and query across them
- Scope-gated access — Session tokens control what each agent can see. Orchestrators create scoped tokens for sub-agents.
- Search-time federation — Data stays at project level, merged at query time. No duplication.
Security
- Deny-by-default — No access without a valid session token
.tesseraignore— Per-project ignore config with.gitignoresyntax- Two-tier ignore system — Security-critical patterns (
.env*,*.pem,*credentials*) are locked and cannot be overridden by project config trustedfield — Search results from code are marked trusted; document content is marked untrusted so agents can handle prompt injection risk
Infrastructure
- Fully embedded — SQLite + FAISS. No Docker, no daemons, no external servers
- Incremental indexing — Git-aware, only re-indexes changed files
- Schema migration — Versioned database schema with automatic upgrades
- Drift adapter — Switch embedding models without re-indexing (Orthogonal Procrustes)
Supported Languages
Go, Ruby, Swift, PHP, TypeScript, JavaScript, Python — via tree-sitter grammars.
MCP Tools (19)
Search & Navigation
| Tool | Purpose |
|---|---|
search |
Hybrid keyword + semantic search across code, documents, and assets (filterable by source_type) |
doc_search_tool |
Document-only search (filterable by format or source_type) |
symbols |
Look up functions, classes, methods by name/pattern/kind |
references |
Find all references to a symbol (calls, imports, extends) |
file_context |
Complete context for a file (symbols, refs, structure) |
impact |
Trace downstream impact of changing a symbol |
cross_refs |
Cross-project references to a symbol |
events |
Analyze event/hook registrations, emissions, and mismatches across languages |
collection_map |
Overview of projects in a collection with stats |
Administration
| Tool | Purpose |
|---|---|
register_project |
Register a project for indexing |
reindex |
Trigger full or incremental re-index |
status |
Project indexing status and health |
drift_train |
Train embedding drift adapter for model migration |
Access Control
| Tool | Purpose |
|---|---|
create_scope_tool |
Create scoped session tokens for sub-agents |
revoke_scope_tool |
Revoke agent session tokens |
create_collection_tool |
Create a project collection |
add_to_collection_tool |
Add a project to a collection |
list_collections_tool |
List all collections |
delete_collection_tool |
Delete a collection |
Quick Start
Requirements
- Python 3.11+
- uv (recommended) or pip
Install
git clone https://github.com/danieliser/tessera.git
cd tessera
uv sync
Run as MCP Server
Add to your .mcp.json:
{
"mcpServers": {
"tessera": {
"command": "uv",
"args": [
"--directory", "/path/to/tessera",
"run", "python", "-m", "tessera", "serve"
]
}
}
}
Lock to a specific project (single-project mode):
uv run python -m tessera serve --project /path/to/your/project
Embedding Setup (Optional)
Tessera works without embeddings (keyword search only via FTS5). For semantic search, point it at any local OpenAI-compatible embedding endpoint. The embedding dimension is auto-detected — no configuration needed.
Recommended: LM Studio with nomic-embed-text or any embedding model serving on /v1/embeddings.
Search Quality
Validated against Next.js v16.1.6 (3,677 chunks, 1,729 files) and Popup Maker (~580 files):
| Dataset | Doc Top-10 | Cross Top-10 | Code Top-10 | Blend MRR |
|---|---|---|---|---|
| Next.js | 100% | 100% | 70% | 0.748 |
| Popup Maker | — | — | 90% | 0.542 |
Default stack: BGE-base (768d, ~210MB) with filename-aware RRF boosting. No reranker needed — BGE-base vectors are strong enough on their own. PPR graph ranking available for impact/reference analysis but disabled in search (neutral-to-harmful in benchmarks).
Run Tests
uv run pytest tests/ -v
Architecture
MCP Server (stdio)
├── Scope Validator (session-based, deny-by-default)
├── Query Router (project / collection / global)
│ ├── Search (FTS5 keyword + FAISS semantic + RRF merge)
│ ├── Symbols / References / Impact (SQLite graph)
│ └── Document Search (source_type filtering)
├── Per-Project Indexes
│ ├── SQLite (symbols, references, edges, files, chunk_meta)
│ └── FAISS (vector embeddings)
├── Global SQLite (~/.tessera/global.db)
│ ├── projects, collections, sessions
│ └── indexing_jobs
└── Indexer Pipeline
├── Tree-sitter parser (PHP, TS, JS, Python, Swift)
├── AST-aware code chunking
├── Document extraction (PDF, MD, YAML, JSON, HTML, XML, plaintext)
├── Asset metadata extraction (images, video, audio, fonts, archives)
└── Ignore filter (.tesseraignore, two-tier security)
Design Principles
- No external dependencies at runtime — SQLite + FAISS, fully embedded
- Tree-sitter for deterministic parsing — no LLM-extracted graphs, no hallucinated edges
- Chunked everything — every file is split into focused, searchable units with structural metadata
- Security-first scope model — deny-by-default, session-scoped, un-negatable credential protection
- Federation over duplication — data stays at project level, merged at query time
Project Status
v0.10.1 — Event/hook analysis with directional edges, per-language parser plugins, mismatch detection, action/filter subtyping, @wordpress/hooks support.
| Phase | Status | What |
|---|---|---|
| 1 | Done | Single-project indexer + scoped MCP server |
| 2 | Done | Incremental indexing + persistence |
| 3 | Done | Collection federation + cross-project refs |
| 4 | Done | Document indexing + drift adapter + ignore config + text formats |
| 4.5 | Done | Media/binary file metadata catalog |
| 5 | Done | PPR graph ranking + semantic snippet scoring |
| 6 | Planned | Always-on file watcher |
License
MIT
Metadata
Release files for tessera-idx 0.12.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tessera_idx-0.12.1.tar.gz | 867.9 kB | With provenance | Details for tessera_idx-0.12.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tessera_idx-0.12.1-py3-none-any.whl | Python 3 | none | any | Details for tessera_idx-0.12.1-py3-none-any.whl |
Total release size: 1.0 MB
Release files / tessera_idx-0.12.1.tar.gz
| Download URL | tessera_idx-0.12.1.tar.gz |
|---|---|
| Size | 867.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
be5831a01826d29d8d5fe82b127ab19ad53a440df1a5475d0dc876dbf994766e
|
|
BLAKE2b-256 checksum How to use checksums |
f52f39a32899ba865420f7a11c8ebc1a93da3550056cbf21aba490e01ce66943
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.
Transparency logRelease files / tessera_idx-0.12.1-py3-none-any.whl
| Download URL | tessera_idx-0.12.1-py3-none-any.whl |
|---|---|
| Size | 145.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
94a5e6f1dc7f4e29d6cf7339109ca83725702e1a187a7f0dde77146cfdf7a752
|
|
BLAKE2b-256 checksum How to use checksums |
f1609846fdb3fe3fbd100f8a8c06ac8c3c45a3e25ad06ecd769795c421057170
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.
Transparency logSecurity for tessera-idx 0.12.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tessera_idx-0.12.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.