DomainTome

The living knowledge graph for your software project.

Status: pre-1.0, solo-maintained. DomainTome is functional and used in production projects, but the API, the schema and the MCP surface may still break between minor versions. Bug reports are welcome; feature PRs may not be merged while the design stabilizes. The repository will open up to broader collaboration once the API is stable (target: 1.0).

DomainTome captures the business logic of a project — modules, capabilities, flows, events, rules, forms, entities and decisions — as a typed graph backed by SQLite, and exposes it over MCP so AI coding assistants (Claude Code, Claude Desktop) can query and maintain it as part of normal work.

It answers questions like "how many ways of registering a payment exist?", "what breaks if I touch flow-checkout?" or "which rules protect this entity?" in a single tool call, with provenance, without re-exploring the codebase each time.

Why

• Persistent memory across sessions — the graph survives context resets.
• Zero documentation overhead — the assistant writes as concepts get decided, not as a separate chore.
• Auditable — every node carries source, confidence, source_context. Every MCP call is logged.
• Token-efficient — summary-only listings, batch ops, cheap sub-agents for exploration, WAL-mode SQLite.

Token economics (measured)

Bytes-on-the-wire to the model when answering structural questions, with vs. without DomainTome. Reproduce on your machine via examples/booking-api/ (full protocol in examples/booking-api/README.md).

Median 13.9×, range 4–68×. The "without" column is a floor — minimum file set, no Grep/Glob overhead. Real sessions read more. The pattern is clear: ratios grow with project size and how scattered the answer is across the codebase.

Maintenance cost (what Claude pays to keep the graph in sync): a typical "new flow + 3 edges" write costs ~720 B total. Break-even is <1 query per new feature. Reads dominate writes by orders of magnitude.

Caveats: input-payload only (output answer not measured); does not include the one-time /dt:sync (INIT/EXTEND) cost; ratios are descriptive of the questions tested, not a guarantee for arbitrary questions.

Install (Claude Code plugin — recommended)

/plugin marketplace add YACB2/domaintome
/plugin install dt@domaintome
/reload-plugins

The plugin's .mcp.json uses uvx to fetch the domaintome package from PyPI on first run, so the only prerequisite is having uv installed (brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh). No separate pip install step.

Reload, then from the project you want to model run /dt:sync — one command, three auto-detected modes: INIT (no graph yet, interactive seed), EXTEND (graph exists, broad re-scan), DIFF (/dt:sync HEAD~10 to walk only what changed since a git rev). /dt:init is a permanent alias that lands in INIT mode. "Project" can be a single repo or a workspace that contains several repos — DomainTome has no opinion, .dt/graph.db is created relative to whatever directory you launched Claude Code from.

The plugin bundles:

• MCP server exposing dt_overview, dt_add_node, dt_update_node, dt_delete_node, dt_get_node, dt_add_edge, dt_remove_edge, dt_query, dt_traverse, dt_list, dt_audit, dt_history, dt_stats, dt_schema, dt_export_markdown. (dt_add_node and dt_add_edge accept an optional nodes / edges list for atomic batches.)
• Auto-invoked skill (dt-usage) that tells Claude to read before acting and write on decision, with provenance rules and lifecycle conventions.
• Sub-agent dt-explorer (Haiku, read-only) for broad exploration without burning expensive tokens.
• Slash commands: /dt:sync (INIT / EXTEND / DIFF, auto-detected), /dt:init (permanent alias → INIT), /dt:audit [<path>] (active project, or another project's graph at <path>/.dt/graph.db), /dt:show <id>, /dt:recent, /dt:impact <id>, /dt:reconcile, /dt:verify, /dt:stats.

Install (standalone CLI / other MCP hosts)

pipx install domaintome   # or: uv tool install domaintome
dt init

For Claude Desktop / other MCP hosts:

{
  "mcpServers": {
    "dt": {
      "command": "dt",
      "args": ["mcp", "--db", ".dt/graph.db"]
    }
  }
}

CLI reference

dt init                      # create .dt/graph.db
dt list [--type flow]        # summary listing (id, type, title, status)
dt show <id>                 # full detail + edges
dt query "payment"           # exact id → title substring → tag fallback
dt variants <capability-id>  # flows implementing a capability
dt audit                     # orphans, cycles, id hygiene
dt stats [--since ISO]       # token/usage analytics from the audit log
dt export --out .dt/export   # one markdown file per node

Schema

Eight node types (stack-agnostic): module, capability, flow, event, rule, form, entity, decision.

Nine relations: part_of, implements, depends_on, triggers, validates, enforces, supersedes, references, conflicts_with. Type pairs are restricted (see schema.py).

Statuses: active | draft | deprecated | superseded | archived. Soft-delete is the default; dt_delete_node is reserved for typos and warns about edge loss.

The central abstraction is capability — a thing the system knows how to do, independent of how. Multiple flow nodes can implements the same capability, surfacing UX/logic divergences.

Model routing

Operations are split by cost:

• Reads (broad scans, traversals, audits): delegated to Haiku via the dt-explorer sub-agent or model: haiku frontmatter on slash commands.
• Writes & modeling decisions: caller's model (Sonnet/Opus). A sub-agent proposes JSON; the caller reviews and persists.

Override per-project in .dt/config.json:

{
  "language": "es",
  "app_name": "my-app",
  "models": { "exploration": "haiku", "write": "sonnet" }
}

Provenance & history

Every node carries metadata.{source, confidence, source_context} and, when relevant, source_ref (path:line), last_verified_at, deprecated_at, deprecated_reason, replaced_by.

dt_update_node(metadata_patch=…) merges without destroying provenance; metadata still exists for rare full replacements.

dt_history(id) returns every MCP event for a node (newest first) from the append-only audit log. dt_stats aggregates by tool/op and reports input/output bytes.

Status

Pre-MVP, alpha. Schema and MCP tool surface may change before 0.1.0.

Development

uv sync --all-groups
uv run pytest -q
uv run ruff check src tests

Tests live in tests/. The plugin layout is validated by test_plugin_structure.py.

License

MIT.