tesserae 0.16.0

Typed LLM wiki graph pipeline for research and development projects

Tesserae

한국어 · 中文 · 日本語 · Русский · Español · Français · Deutsch

A context engine that keeps a self-improving knowledge base of your project and compiles agent-ready context on demand.

Live demo · Docs · Release notes · MCP setup · Obsidian export

What it is

Point Tesserae at a directory of markdown, source code, and (optionally) PDFs/Office docs/images. It reconstructs a typed knowledge graph of the project and keeps it fresh, so agents always have grounded, cited context. Three pillars:

1. Session monitoring — your Claude Code / Codex conversations about the project become first-class graph nodes (decisions, insights, questions, TODOs) as they happen.
2. Autonomous ingestion — a supervised engine watches sources and sessions, coalesces bursts, recompiles, and a self-improvement sidecar reinforces recurring findings while superseding stale ones.
3. On-demand context — the context compiler assembles a tailored, cited context document for any query or seed node (Personalized PageRank under a character budget), ready to paste into any agent.

The graph, the Obsidian vault, and the static site are projections of one knowledge base. Everything runs locally; it is a build step plus a live engine, not a hosted service.

Quickstart

Requires Python 3.10+.

pip install tesserae          # add [semantic] for real embeddings
# or: pipx install tesserae   # easiest PATH-safe install
# or: npx @jokerized/tesserae # Node wrapper around the same CLI

cd /path/to/my-project
tesserae init --yes           # wizard; --yes accepts detected defaults
tesserae compile              # build the knowledge graph
tesserae ask "Where is Mermaid rendering implemented?"

# Compile a tailored, cited context doc for a query:
tesserae context "How does the parser handle arXiv IDs?" --budget 32000 -o context.md

tesserae serve --port 8765    # browse the graph + wiki locally

LLM-backed features default to the codex / claude CLIs over OAuth — no API keys required for the common path. See docs/quickstart.md and docs/installation.md.

tesserae: command not found after install? Linux gotchas?

The most reliable fix on any platform is pipx:

# macOS: brew install pipx · Ubuntu/Debian: sudo apt install pipx
pipx ensurepath          # adds ~/.local/bin to PATH; open a new shell after
pipx install tesserae

Common Ubuntu issues with plain pip install tesserae:

Error	Cause	Fix
error: externally-managed-environment	PEP 668 — system Python is locked	Use pipx (above) or a venv
command not found after pip install --user …	~/.local/bin not on PATH	echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
ModuleNotFoundError on old distros	system python3 is < 3.10	sudo apt install python3.11 python3.11-venv, then install with python3.11 -m pip

Walkthrough GIFs — each Quickstart step against the bundled 135-doc demo corpus

1. Setup — point at a research directory, get a project wiki scaffold

2. Compile + build site — deterministic, no LLM calls

3. Ask — query the compiled wiki from the CLI

Rebuild any GIF with vhs docs/screencasts/<name>.tape.

Everyday commands

Run tesserae --help for the full grouped list, tesserae <cmd> --help for flags.

Command	What it does
tesserae init	Setup wizard → .tesserae/config.json. --yes non-interactive, --bare minimal.
tesserae compile	Rebuild the knowledge graph and all artifacts. compile <paths> ad-hoc ingests extra files.
tesserae ingest <file|url>	Merge a single document or web page into the knowledge base without a full recompile (parity-gated incremental fast path).
tesserae context "<query>"	On-demand context compiler: cited context doc via PPR expansion under --budget; --synthesize adds an LLM summary.
tesserae ask "<question>"	Ask the compiled knowledge base. With no --scope a smart router picks the target across your projects (federated fallback); --scope federated returns ONE merged, cross-referenced answer, --scope all-registered one answer per project.
tesserae engine	Supervised refresh daemon for the current project: watch, debounce, recompile.
tesserae engine --all	Fleet mode: one process keeps every registered project fresh — registry hot-reload, --compile-slots throttling.
tesserae refresh	One-shot pipeline: import new sessions → compile → sync vault.
tesserae sessions discover --import	Find and import local Claude Code / Codex session history for this project.
tesserae export site	Build the static site (--deploy, --watch).
tesserae export okf	Export the graph as a Google OKF v0.1 bundle (Markdown + YAML frontmatter); --import DIR reads one back (round-trips Tesserae's own bundles losslessly).
tesserae serve	Serve every registered project under one server — a projects landing at /, each project at /<alias>/, and a Projects switcher in the header. --project X serves just one (with the live /api/ask widget).
tesserae setup	Machine-wide setup — interactive by default: pick the LLM provider/effort and which optional deps to install. Flags (--install all, --llm-provider …) skip the prompts. (config setup is a back-compat alias.)
tesserae config deps	List / install optional dependencies (memex, cognee, raganything, understand-anything).
tesserae projects …	Multi-project registry: register, list, unregister, mcp-config (no privileged "active" project).
tesserae federation status / explain	Inspect a cross-project federation: per-project node counts, identity merges, semantic links, and why a node bridges projects.
tesserae integrations refresh …	Re-run companion tools (Understand-Anything, RAG-Anything).

Keep it fresh automatically

The engine is what makes the knowledge base self-improving rather than a one-shot build:

# One project: watch sources + live sessions, recompile on change.
tesserae engine

# Every registered project, one process (v0.8.0):
tesserae engine --all --compile-slots 1

Fleet mode reconciles against ~/.tesserae/registry.json every 10 s — registering or removing a project takes effect without a restart — and serializes compiles across projects so concurrent LLM extraction never tramples shared account rate limits. The first run sweeps your session history once (it says so in the log); restarts resume from a persisted floor.

What you get after compile

.tesserae/
  graph.json              # typed nodes/edges (the knowledge base)
  sqlite.db               # queryable graph store
  markdown_projection/    # human-readable wiki pages
  obsidian_vault/         # ready to drop into Obsidian
  site/                   # static site (graph view + wiki + search)
  harness_sessions/       # imported Claude/Codex session memory
  agent_harness/          # per-agent context config (Claude/Codex/Gemini/...)
  cognee_bundle/          # JSONL ready for Cognee ingest
  config.json · manifest.json · report.md · …

MCP server

tesserae projects mcp-config prints a server entry for Claude Code, Codex, or any MCP client. Headline tools:

• compile_context — tailored, cited context doc for a query or seed nodes (deterministic unless synthesize=true), backed by graph_ppr. preview=N returns a bounded preview + a handle instead of the full body.
• get_handle — page a large payload (e.g. a previewed compile_context body) in slices on demand, so the agent isn't forced to hold it all in context.
• Graph + wiki: search_nodes, node_context, graph_summary, wiki_page, raw_source, timeline, search_facts, lint_report, ask.
• Session memory: list_sessions, find_session_findings, find_code_symbol_mentions, fresh_insights (decay-ranked, deduplicated, now carrying extraction confidence + revisit_signals when available).
• ingest — merge raw web/text content (e.g. a browser clip) into the graph.
• Registry: list_projects, register_project, unregister_project.

Multi-project

A registry at ~/.tesserae/registry.json resolves project names everywhere — CLI, MCP, and the fleet engine. All registered projects are equal — there's no "active" project; per-project commands resolve the project you're standing in (cwd), and queries route across projects automatically:

tesserae projects register /path/to/my-project --name myproj
tesserae ask "compare retrieval in research and notes"   # routes -> federated
tesserae ask "how does myproj compile?"                  # routes -> that project
tesserae ask "..." --scope federated                     # ONE merged, cross-referenced answer
tesserae ask "..." --scope all-registered                # one answer per project
tesserae serve                                           # serve EVERY project at /<alias>/

Markdown in one project can deep-link a node in another via wiki://<alias>/<kind>/<slug>; at compile time these become bridge nodes in the graph view. See docs for details.

Integrations (all opt-in)

• Claude Code plugin — slash commands, session hooks, skill, and MCP auto-registration in one /plugin install. docs/integrations/claude-code-plugin.md
• Session graph — Claude Code / Codex conversations → Insight / Decision / Question / TODO nodes, linked to the docs they touched. No API key required. docs/integrations/sessions.md
• Understand-Anything — code knowledge graph ingestion. docs/integrations/understand-anything.md
• RAG-Anything — multimodal ingestion (PDF/Office/images via MinerU/Docling) and a LightRAG question backend. docs/integrations/rag-anything.md
• Cognee — graph+vector memory backend; compile always writes a Cognee-ready bundle, runtime cognify is best-effort.
• Obsidian — bidirectional vault sync with user-edit overlay. docs/integrations/obsidian.md
• Web Clipper (Chrome extension) — one-click clip a page or selection into the corpus via POST /api/clip / the MCP ingest tool. docs/integrations/chrome-extension.md

How it compares

Feature matrix vs Quartz, Logseq, Cognee, Foam

Feature	Tesserae	Quartz	Logseq	Cognee	Foam
Static HTML output	yes	yes	partial (export)	no	partial (publish)
Built-in graph view	yes	yes	yes	yes (separate UI)	yes (VSCode)
Typed node schema	yes (41 types)	no	partial (tags)	yes	no
Concept extraction from sources	yes (LLM)	no	no	yes	no
Multimodal ingestion (PDF/image)	yes (via RAG-Anything)	no	partial (embeds)	yes	no
Code-graph ingestion	yes	no	no	partial	no
MCP server	yes	no	no	yes	no
On-demand cited context compiler	yes (PPR + budget)	no	no	no	no
Live session monitoring → graph	yes	no	no	no	no
Multi-project registry	yes	no	yes (graphs)	partial	no
Multi-project daemon (fleet)	yes	no	no	no	no
Works without API key (OAuth)	yes	n/a	n/a	no	n/a
Deterministic byte-identical compile	yes	yes	n/a	no	n/a
Live edit	no	partial	yes	n/a	yes
Real-time collaboration	no	no	yes (DB beta)	no	no

Tesserae picks compile-from-source over live editing. If you want to edit notes in a UI, use Logseq or Obsidian. If you want a build tool and a live engine for your knowledge graph, this is the project.

Use it if you want a durable, inspectable knowledge graph over a project's text-heavy sources, a local MCP server grounded in your own files, or clean bundles for Cognee/Obsidian without writing glue.

Skip it if you only need vector search over a small directory, want a hosted wiki with an editing UI, or expect a turnkey "ask anything" agent — Tesserae builds the substrate; you wire it into your agent of choice.

Authentication and LLM providers

The common path uses no API keys:

• Codex CLI (default) and Claude Code CLI over OAuth, with multi-account rotation.
• Embeddings: native hybrid retrieval uses an offline, torch-free semantic lane via pip install "tesserae[semantic]" (model2vec). Cognee/RAG-Anything backends default to a deterministic provider; switch to Ollama or any OpenAI-compatible endpoint for better recall.

ANTHROPIC_API_KEY / OPENAI_API_KEY are picked up if present, never required.

Status and limitations

Current release: see release notes. Known limitations:

• First-run compiles over large corpora (thousands of files) take minutes; compile time scales roughly linearly. Incremental compile (--changed-only) ships but is experimental and OFF by default.
• Without the semantic extra, hybrid retrieval degrades to a non-semantic stub (with a loud warning).
• RAG-Anything vision (image description) is not yet wired end-to-end.
• Cognee runtime cognify is best-effort: missing providers are logged and skipped, never fatal.
• The MCP tool set is stable; the graph schema may still gain node types.

Project layout

tesserae/        # the package (CLI, compiler, engine, MCP server, adapters)
docs/            # English docs + docs/i18n/ for the seven other languages
ontology/        # node/edge schemas the compiler validates against
prompts/         # extraction and synthesis prompts
tests/           # pytest suite
evals/           # graph quality eval harnesses
examples/        # demo corpus used by the screencasts

Localized docs

한국어 · 中文 · 日本語 · Русский · Español · Français · Deutsch

Long-form docs are mirrored under docs/i18n/.

License

MIT. See LICENSE.