Tessera — Portable context for AI tools

A local-first context layer for agents and AI tools. Tessera stores durable user and project context in an encrypted SQLite vault, exposes it through a scoped MCP surface, and retrieves cross-facet bundles with hybrid search, rerank, SWCR, and token budgeting.

Open source. Local-first. Apache 2.0.

Install

From PyPI (recommended):

pip install --pre tessera-context
# or pin explicitly:
pip install tessera-context==0.5.0rc1

pip's default resolver skips pre-releases, so --pre or an explicit version pin is required. The PyPI distribution name is tessera-context; the CLI binary and Python import path remain tessera. The short tessera name on PyPI is held by a 2017-dormant Graphite dashboard project; PEP 541 reclaim is pursued in parallel.

From source (for development):

git clone https://github.com/Mathews-Tom/Tessera.git
cd Tessera && uv sync --dev
uv run tessera --help

Core local flow

# one-time setup: pin a passphrase in your shell so commands run flag-free.
# the vault path defaults to ~/.tessera/vault.db; override with $TESSERA_VAULT.
export TESSERA_PASSPHRASE='your-passphrase-here'   # add to ~/.zshrc or your global .env

tessera init                          # creates ~/.tessera/vault.db
tessera models set --name nomic-ai/nomic-embed-text-v1.5 --dim 768 --activate
tessera daemon start                  # starts tesserad, picks up the env var
tessera connect claude-desktop        # mints token, writes config
# or wire every detected client in one shot:
tessera connect all

The tessera models set --activate step picks the embedder Tessera will use; the daemon refuses to start without an active model. Embedding runs in-process via fastembed (ONNX Runtime) — no Ollama, no torch, no separate model server. The first daemon start downloads the model weights to ~/.cache/fastembed (~520 MB for the default nomic-embed-text-v1.5; one-time cost). Reranking runs in the same stack via Xenova/ms-marco-MiniLM-L-12-v2.

--vault and --passphrase flags are still accepted for one-off use, multi-vault setups, or scripted invocations. Resolution order is flag → $TESSERA_VAULT / $TESSERA_PASSPHRASE → default. See docs/quickstart.md for the env-var setup and docs/troubleshooting.md for multi-vault disambiguation.

ChatGPT Developer Mode is deferred to v0.1.x because the current ChatGPT flow requires HTTPS/OAuth/canonical HTTP MCP compatibility that Tessera v0.1 does not yet ship. The v0.1 demo flow uses Claude Desktop and Claude Code as the MCP-capable clients.

What is Tessera

A local daemon owns a single-file SQLite vault that holds five v0.1 context facets:

• identity — stable user facts
• preference — behavioral rules and tool preferences
• workflow — repeated procedures
• project — active work context
• style — writing voice samples

Two transports reach the vault, sharing one daemon dispatcher and one token-based auth model:

• MCP at /mcp for tool-aware AI clients that auto-discover Tessera (Claude Desktop, Claude Code, Cursor, Codex). Six MCP tools: capture, recall, show, list_facets, stats, forget, plus the v0.3 learn_skill / get_skill / list_skills / resolve_person / list_people surface.
• REST at /api/v1/* for hooks, skills, and shell scripts. Curl-friendly endpoints that skip MCP's JSON-RPC envelope so high-frequency hook calls do not pay the per-call envelope tax. See docs/api.md for the full reference and copy-pasteable recipes; tessera curl --print recall "..." emits canonical curl invocations safe to paste into hook scripts.

A bare recall (either transport) searches every facet type the token can read and returns a budgeted cross-facet bundle.

The lead user is the AI-native developer who wants durable context across Claude Code, Claude Desktop, Cursor, Codex, local model workflows, and custom harnesses without handing memory to a hosted service.

Where to read, by role

Posture

This is a solo-developer craft project by Tom Mathews, paced by evening and weekend velocity while a dissertation on agentic memory systems lands in parallel. The v0.1 commitment is explicit; v0.3 and beyond are contingent on real-user signal. There is no telemetry, no hosted service in v0.1, and no model reselling ever. See docs/non-goals.md for the full list of things Tessera will not become.

The reason this exists is that the amnesia tax is real for a growing audience — T-shaped users operating across three or more AI tools a week — the engineering shape is interesting, and the adjacent products in the space treat memory as flat blobs in someone else's cloud. Tessera treats it as structured context on disk.

License

Apache 2.0. No CLA.