Metadata-Version: 2.4
Name: tessera-context
Version: 0.5.0rc1
Summary: Portable context layer for T-shaped AI-native users. Single-file encrypted SQLite vault served over MCP.
Project-URL: Homepage, https://github.com/Mathews-Tom/Tessera
Project-URL: Repository, https://github.com/Mathews-Tom/Tessera
Project-URL: Issues, https://github.com/Mathews-Tom/Tessera/issues
Author-email: Tom Mathews <tommathews2007@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: agent,identity,local-first,mcp,memory,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.12
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: cryptography>=43.0.0
Requires-Dist: fastembed>=0.4.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: python-ulid>=3.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlcipher3-binary>=0.5.4; sys_platform == 'linux'
Requires-Dist: sqlcipher3>=0.5.4; sys_platform != 'linux'
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: tiktoken>=0.8.0
Requires-Dist: tomli-w>=1.2.0
Description-Content-Type: text/markdown

# Tessera — Portable context for AI tools

[![PyPI](https://img.shields.io/pypi/v/tessera-context?include_prereleases&label=pypi&color=blue)](https://pypi.org/project/tessera-context/)
[![Python](https://img.shields.io/pypi/pyversions/tessera-context)](https://pypi.org/project/tessera-context/)
[![License](https://img.shields.io/github/license/Mathews-Tom/Tessera?color=blue)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/Mathews-Tom/Tessera/ci.yml?branch=main&label=CI)](https://github.com/Mathews-Tom/Tessera/actions/workflows/ci.yml)

> 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):

```bash
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):

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

## Core local flow

```bash
# 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`](docs/quickstart.md#setup-once) for the env-var setup and [`docs/troubleshooting.md`](docs/troubleshooting.md#multi-vault-disambiguation) 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`](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

| If you want to | Read |
|---|---|
| Walk through install + first capture in ~10 minutes | [`docs/quickstart.md`](docs/quickstart.md) |
| Build a hook, skill, or shell script that talks to the daemon | [`docs/api.md`](docs/api.md) |
| Pitch to a colleague or evaluate whether this is interesting | [`docs/pitch.md`](docs/pitch.md) |
| Understand the market position, category claim, and trade-offs | [`docs/system-overview.md`](docs/system-overview.md) |
| Understand the architecture, schema, retrieval pipeline, encryption | [`docs/system-design.md`](docs/system-design.md) |
| Understand the SWCR retrieval algorithm and its ablation bar | [`docs/swcr-spec.md`](docs/swcr-spec.md) |
| Understand the security model and threat analysis | [`docs/threat-model.md`](docs/threat-model.md) |
| Understand how migrations are safe | [`docs/migration-contract.md`](docs/migration-contract.md) |
| Understand how debuggability works without telemetry | [`docs/determinism-and-observability.md`](docs/determinism-and-observability.md) |
| Know what ships in v0.1, v0.3, v0.5, v1.0 | [`docs/release-spec.md`](docs/release-spec.md) |
| Know what will never ship | [`docs/non-goals.md`](docs/non-goals.md) |
| Review the load-bearing decisions | [`docs/adr/`](docs/adr/) |
| Fix an install failure, bad first run, or a broken connector | [`docs/troubleshooting.md`](docs/troubleshooting.md) |

## 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.
