Understand Anything companion workflow

<!-- translations:start -->

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

<!-- translations:end --> Understand Anything and Tesserae are complementary projects.

• Understand Anything is great at producing a codebase knowledge graph and interactive dashboard.
• Tesserae is focused on long-lived agent memory: docs, markdown/wiki compilation, static publishing, session history, and agent-facing exports.

Tesserae should not vendor or absorb Understand Anything. Treat it as an independent companion that can produce useful graph artifacts.

Why use both?

Understand Anything can write:

.understand-anything/knowledge-graph.json

That graph captures code structure such as files, functions, classes, modules, concepts, dependencies, layers, and tours.

Tesserae can then preserve that artifact alongside the rest of the project memory:

• source docs and markdown pages;
• repository files;
• research notes;
• local Claude Code / Codex session history;
• generated static wiki pages;
• 2D / 3D graph website views;
• llms.txt, llms-full.txt, search-index.json, graph.json, and per-page agent siblings.

Current low-friction workflow

The recommended path is the setup wizard:

tesserae project setup

Choose Understand Anything in the companion-tools step. Tesserae installs/updates the companion skills when requested and writes a managed refresh command into .tesserae/config.json. Future tesserae project compile calls run that wrapper automatically when the UA graph is missing or stale.

For non-interactive automation, use:

tesserae project setup \
  --yes \
  --with-understand-anything \
  --install-understand-anything \
  --understand-anything-platform codex
tesserae project compile

The stored command is Tesserae-owned, not something the user has to invent:

tesserae project refresh-understand-anything --platform codex

During compile, Tesserae:

1. checks whether .understand-anything/knowledge-graph.json exists and matches the current git commit when metadata is available;
2. runs the configured agent platform (codex, opencode, or claude) only when the graph is missing/stale or refresh is forced;
3. verifies the graph was written;
4. materializes .tesserae/external/understand-anything.md;
5. continues the normal memory compile.

You can force all configured external refresh commands before a compile:

tesserae project compile --refresh-external-tools

Need Cognee too? Add the runtime memory flags in the same setup command:

tesserae project setup \
  --yes \
  --with-understand-anything \
  --install-understand-anything \
  --understand-anything-platform codex \
  --run-cognee \
  --install-cognee

Manual equivalent

The managed setup path is preferred. If you intentionally want to use UA outside Tesserae, run Understand Anything first inside your agent environment:

/understand

Then run tesserae project setup --with-understand-anything so Tesserae records the markdown projection source. Direct JSON files are kept as raw companion artifacts, not hand-entered source paths.

tesserae project setup --with-understand-anything
tesserae project compile
tesserae project build-site

If you also want local agent-session memory:

tesserae project sessions discover --import
tesserae project build-site

Native graph synchronization

Tesserae now keeps the markdown projection for readability and also imports the UA graph natively during compile when the configured tool uses sync_mode: native_graph.

The native adapter reads .understand-anything/knowledge-graph.json, maps UA nodes/edges into Tesserae's controlled ontology, and writes a sync manifest:

.tesserae/external/understand-anything-sync.json

Current mapping:

Concept synchronization is canonicalized instead of blindly duplicated. If UA emits Mermaid Rendering and Tesserae already has Mermaid rendering, compile keeps one concept node and adds UA provenance under metadata.external_refs.

Tesserae remains the memory compiler; UA remains an independent companion graph generator.

Collaboration principle

Do not frame Tesserae as replacing Understand Anything.

A better framing:

• Understand Anything helps a developer understand a codebase now.
• Tesserae helps agents remember, search, cite, update, and publish project knowledge over time.