Tesserae v0.5.0 — The engine spine and the On-Demand Context Compiler

<!-- translations:start -->

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

<!-- translations:end -->

Released 2026-06-06 · PyPI · GitHub release · pip install --upgrade tesserae==0.5.0

Tesserae 0.5.0 is the release where the project becomes the context engine its mission describes. It ships the engine spine — a pipeline orchestrator, a supervisor daemon, and a live session monitor — and the Pillar-3 headline feature: the On-Demand Context Compiler, which turns "give me context on X" into a tailored, cited, agent-ready bundle. Underneath, the self-improvement passes are now activated and persisted via the node_memory sidecar (numeric recurrence confidence in output, supersede default-on), real default embeddings replace the hash-bucket stub (Track B), and the incremental-compile infrastructure lands but stays flag-OFF / experimental. Two real compile bugs found along the way are fixed (changed-only idempotence, the injected-store contract), and the test suite reaches 1544 passed / 0 failed. This is the release that delivers Phases 0–6 of the context-engine roadmap.

Table of contents:

1. On-Demand Context Compiler — MD0 (Pillar 3, headline)
2. The engine spine — orchestrator, daemon, live session monitor
3. Self-improvement, activated and persisted (MD0 sidecar)
4. Real default embeddings (Track B)
5. Incremental-compile infrastructure (flag-OFF) + two compile fixes
6. Upgrading from v0.4.0
7. Strategic context

1. On-Demand Context Compiler — compile_context (Pillar 3, headline)

What it is

The feature the whole roadmap pointed at: a query (or a set of seed nodes) in, a tailored, cited, agent-ready context bundle out. compile_context is a pure function — it reads the graph and returns an in-memory ContextBundle, writing nothing to disk. The pipeline is: query/seeds → PPR + hybrid search for seeds → depth-bounded k-hop neighborhood walk → assemble the relevant wiki bodies → optional LLM synthesis (with a graceful deterministic fallback) → budget control with a word-boundary truncation marker. Every node that contributes is recorded as a ContextCitation, so the bundle's citations all resolve back to real graph nodes.

The compiler is exposed three ways:

• MCP tool compile_context — for an agent to call mid-conversation. budget=0 means uncapped.
• CLI tesserae project context — exit-0 / stdout / --output / deterministic, for scripting and pipelines.
• Topic-scoped exports — slice_export_context_for_topic produces a topic-scoped llms.txt slice, and the agent harness brief is now rendered per topic via compile_context (Pattern 4 + Pattern 6) instead of a hard-coded top-12.

Two related retrieval upgrades ship alongside it: node_context gains a use_ppr ranked path (with suppression-aware neighbor fill and edge/limit controls), and the topic slice uses the canonical wiki slug so citations and exports line up.

How to use

# CLI: compile a cited context doc for a topic, print to stdout or a file
tesserae project context "retrieval ranking and RRF fusion"
tesserae project context "retrieval ranking" --output ./context-retrieval.md

From an MCP client:

{
  "tool": "compile_context",
  "arguments": {
    "query": "How does our retrieval stack rank candidates?",
    "depth": 2,
    "budget": 4000
  }
}
// → returns a ContextBundle: assembled body + a list of resolvable citations.
//   budget: 0 means uncapped.

You can also seed directly from node ids (skipping the search step) when you already know the anchors:

{
  "tool": "compile_context",
  "arguments": {
    "seeds": ["decision-2026-05-22-switch-to-rrf-fusion"],
    "depth": 2,
    "budget": 0
  }
}

When to use it

• An agent needs a focused brief on one topic, not the whole-corpus llms.txt dump or a single wiki_page body.
• You want citations that resolve — every claim in the bundle traces back to a graph node — so the agent can follow up.
• You're scripting a handoff and want a deterministic context artifact (--output, no-LLM assembly mode) that regenerates per topic.

Where it lives

Core implementation: MD0 (compile_context, ContextBundle, ContextCitation). MCP registration and dispatch: tesserae/mcp_server.py. CLI wiring: the context subparser and _handle_context in tesserae/cli.py. Topic-scoped harness/export rendering routes through compile_context.

Caveats

• Synthesis quality depends on the LLM backend; with no backend, the compiler falls back to deterministic assembly (still cited, just unsynthesized). The fallback is graceful — a synthesis failure never aborts the bundle.
• The k-hop walk is depth-bounded and PPR runs over the depth-bounded subgraph; very large graphs benefit from a tight depth plus a real budget rather than budget=0.
• Budget truncation cuts on a word boundary and appends a truncation marker, so a clipped bundle is still readable rather than ending mid-token.

2. The engine spine — orchestrator, daemon, live session monitor

What it is

The three foundational pieces the audit called the single biggest gap, now shipped under tesserae/engine/:

• Pipeline orchestrator (pipeline.py) — the ingest → compile → project → publish chain, lifted out of the slash-command markdown skill into a first-class in-process object the daemon, CLI, and MCP all call. This is the shared code path everything continuous hangs off.
• Supervisor daemon (daemon.py) — a supervised long-running process that owns one event loop, coalesces trigger bursts into a single pipeline run, handles graceful SIGTERM / SIGINT shutdown, and survives a pipeline exception without dying.
• Live session monitor (session_tail.py) — tails live harness transcripts and ingests turns as sessions run, replacing the post-hoc sessions discover --import scan (Pillar 1).

Together these turn Tesserae from a one-shot batch CLI into a process that can watch and ingest continuously.

When to use it

• You want the "keeps updating" property — sessions and edits flow into the graph without a manual command.
• You're building on top of Tesserae and want one shared pipeline entry point for daemon, CLI, and MCP rather than re-implementing the refresh chain.

Where it lives

tesserae/engine/pipeline.py, tesserae/engine/daemon.py, tesserae/engine/session_tail.py (merged as the engine spine, roadmap Phases 0–2).

3. Self-improvement, activated and persisted (node_memory sidecar)

What it is

The "self-improving base" pillar moves from bolt-on passes to a persisted node_memory sidecar (tesserae/memory/). The two user-visible changes:

• Supersede default-on with a deterministic verdict. The supersede pass runs by default now (no TESSERAE_SUPERSEDE_PASS=true needed), with a deterministic, decisive session-id verdict in both directions and a threshold guard, plus downstream suppression so a superseded fact stops appearing in context output rather than just gaining an edge.
• Numeric recurrence confidence in output. Recurring-insight reinforcement now produces a numeric confidence from cross-session frequency, injected into the TemporalFactProjector via memory_by_id, replacing the prior coarse string heuristic. Re-stating a fact across sessions measurably raises its confidence in the output.

When to use it

• You run multi-session projects where the same insight recurs — reinforcement turns that recurrence into a confidence signal agents can rank on.
• You want obsolete facts to disappear from compiled context, not just be flagged.

Where it lives

tesserae/memory/ — store.py, reinforce.py (numeric recurrence confidence), supersede.py (default-on, deterministic verdict + suppression), plus decay.py, contradiction.py, and insight_symbol_link.py. The self-improvement test suite (previously zero tests) now covers determinism, idempotence, and the LLM-override path.

Caveats

• Decay and contradiction scaffolding ship in the same sidecar; the user-facing default-on behavior in v0.5.0 is supersede + numeric recurrence confidence.

4. Real default embeddings (Track B)

What it is

The default "semantic" lane is no longer a deterministic hash-bucket pseudo-embedding. v0.5.0 ships a real Model2VecBackend and makes active_embedding_backend fail loud instead of silently downgrading to blake2b. The semantic backend in use is surfaced in embedding_status, and a cosine floor lets the embedding lane admit candidates (not just re-rank), so paraphrase and synonym queries surface nodes BM25 misses.

How to use

{ "tool": "embedding_status" }
// → reports which semantic backend is active (real vs. fallback), so you
//   can tell at a glance whether out-of-the-box retrieval is genuinely semantic.

Where it lives

tesserae/retrieval/hybrid.py (backend selection, fail-loud active_embedding_backend, cosine floor for embedding-only admission) and the Model2VecBackend. Surfaced via the embedding_status MCP tool.

Caveats

• If the real backend can't load, retrieval now says so loudly rather than pretending the hash stub is semantic — this is the intended behavior change.

5. Incremental-compile infrastructure (flag-OFF) + two compile fixes

What it is

The designed incremental layer through the GraphStore port lands as infrastructure: a provenance sidecar, a GraphStore delete surface, reconcile-on-full, edge-aware readiness, producer-provenance plumbing, and a persistent url_resolver async runtime (no more asyncio.run-per-call). Byte-parity against full-compile is proven for the covered paths (rename, alias-identity, both-endpoints-move parity gates).

The incremental_compile flag stays OFF / experimental. Codex review surfaced multi-owner / producer-lifecycle / cap-fallback gaps, so the flag is opt-in and byte-parity-proven only for the covered paths until those gaps close.

Two real compile bugs uncovered in this work are fixed in the default path:

• Changed-only idempotence — compile now honors changed-only idempotence so a no-op re-compile doesn't churn the graph.
• Injected-store contract — the injected-store contract in project compile is honored, fixing a class of failures on direct-ingest paths.

Where it lives

The incremental infrastructure spans the GraphStore port and the provenance sidecar; the two fixes land in the project compile path (fix(project): honor changed-only idempotence + injected-store contract in compile).

Caveats

• Do not turn on incremental_compile for production graphs yet — it is experimental by design until the multi-owner / lifecycle / cap-fallback gaps close. Full compile remains the trusted path.

Upgrading from v0.4.0

pip install --upgrade tesserae==0.5.0

v0.5.0 is additive for existing workflows — tesserae project compile still works exactly as before, now with two correctness fixes (changed-only idempotence, injected-store contract). The new surfaces are opt-in to call:

New on-demand context compiler:

tesserae project context "<topic>"            # cited context bundle to stdout
tesserae project context "<topic>" --output out.md

{ "tool": "compile_context", "arguments": { "query": "<topic>", "depth": 2, "budget": 4000 } }

Behavior now on by default (previously opt-in or absent):

• Supersede pass on by default (with output suppression of superseded facts).
• Numeric recurrence confidence surfaced in projected output.
• Real default embeddings with a fail-loud backend (no silent hash-stub downgrade).

Still experimental — leave off for production graphs:

• incremental_compile (infrastructure shipped, flag OFF).

Everything else — graph_ppr, hybrid search_nodes, sync-code, research, the live hooks, embedding_status, fresh_insights, schema-drift, slash commands, the wiki / Obsidian projection — carries forward from v0.4.0.

Strategic context

The context-engine audit (2026-06-02) named the gap in one line: Tesserae was a mechanically healthy, well-tested batch CLI compiler, manual-trigger and post-hoc on all three pillars, and the single biggest missing piece was a long-running supervisor that owns one event loop. v0.5.0 closes that line. The engine spine is the supervisor; the live session monitor makes Pillar 1 live instead of post-hoc; the node_memory sidecar makes Pillar 2 self-improving in place; and the On-Demand Context Compiler is Pillar 3 — the headline that turns the typed graph, vault, and site from static projections into a query-scoped, cited, agent-ready output on demand.

No tool in the 2026 PKM-AI landscape we survey does this composition. Cursor Memories, Claude CLAUDE.md, Cline memory-bank, and Aider CONVENTIONS.md are static text bags with no engine loop, no typed self-improvement, and no on-demand cited context compiler. Microsoft GraphRAG has typed entities and community summaries but is a corpus-RAG system, not a continuously-running project-memory engine. v0.5.0 ships the loop that keeps the base fresh and the compiler that hands agents exactly the context they ask for — the mission stated plainly in AGENTS.md, now running in code.

What's left: Phase 7 — unifying serve + watch + deploy under the supervisor for continuous publish, plus turning the incremental-compile flag on once its remaining gaps close. The spine and the headline are in; the convergence release is next.

See also:

• v0.4.0 release notes — extraction-feedback loop, research mode, evolution on by default
• Context-engine roadmap — per-phase status (Phases 0–6 shipped here)
• Context-engine audit — the gap analysis this release closes
• Architecture overview — module map and pipeline
• MCP integration — full MCP tool list (the new compile_context tool lands here)