Knowledge Graph
Noumenon compiles a repository into a multi-level Datomic graph. Queries traverse between levels naturally.
Three Levels
Noumenon compiles a repository into a multi-level Datomic graph. A single query can join commit history, file structure, and component architecture.
Code Segments
Functions, classes, and types with complexity ratings, code smells, safety concerns, purity analysis, and call graphs. Extracted by an LLM during the analyze stage.
Files and Imports
Git history, authorship, change frequency, cross-file import edges, and per-file semantic summaries. Files connect upward to components and downward to segments.
Components and Architecture
Logical subsystems identified from directory structure, import graphs, and file summaries. Component dependencies, architectural layers, and category labels.
Schema Overview
The graph schema is intentionally small. A handful of entity types, each with a few canonical attributes.
| Entity | Key facts |
|---|---|
Repository | Repo, branch, working tree, head SHA |
Commit | SHA, author, timestamp, message, parent commits |
File | Path, size, language, line count, latest commit, summary |
Segment | Function/class/type with complexity, code smells, purity, calls |
Component | Logical subsystem with files, dependencies, and layer assignment |
Import | Edge between two files (resolved cross-file) |
Author | Email, display name, contribution history |
The full picture, with every attribute and the entity diagram, lives at Schema. For the live schema as the daemon sees it, run noum show-schema or call noumenon_get_schema over MCP.
Querying the Graph
All structure is queryable via Datalog. Noumenon ships with a catalog of 90+ named queries covering hotspots, dependency analysis, contributor graphs, and more. Pose natural-language questions with noum ask, or invoke queries directly from the CLI, HTTP API, or MCP.
Compared to RAG
Retrieval-Augmented Generation (RAG) systems use vector similarity to find relevant documents before the LLM sees them. Noumenon's knowledge graph is a different shape: it stores facts and relationships as queryable structure, not chunks and embeddings. The two are complementary, not opposed.
| Job | RAG is good at | Knowledge graph is good at |
|---|---|---|
| Discovery | Fuzzy lexical/semantic match. "Files about authentication" | Bad without a hint; the agent has to guess where to look. |
| Relationships | Implicit, by chunk proximity. Often wrong on "what depends on X." | Explicit. "Which components depend on auth-system" is a one-line query. |
| Composition | Hard. Combining "about auth" with "changed in last 30 days" requires reranking. | Datalog joins. Combine arbitrary facts with no extra machinery. |
| Reproducibility | Embeddings drift between models and quantizations. | Same query, same database state, same answer. |
Noumenon does both. The TF-IDF retrieval tier in the analyze pipeline gives the Ask agent a RAG-style warm start ("where to look"); the Datalog graph handles relationships and composition ("how everything connects").
Branch-Aware Graph
Experimental — interfaces may change between releases. Each database carries the branch it represents — :branch/name, :branch/kind, :branch/vcs — and the repo entity points to its current branch via :repo/branch. A hosted instance tracks trunk; each developer materializes a sparse delta database at ~/.noumenon/deltas/ for the local feature branch. Federated queries merge trunk and delta in one HTTP roundtrip so answers reflect the working branch. Files are also content-addressed via :file/blob-sha — analyses promote across blobs with matching prompt + model without re-invoking the LLM. See Source control for details.
Time Travel
Datomic stores every transaction immutably and tags it with a basis-t. Old facts are not overwritten; they're superseded by newer facts at later transaction points. Any query can run "as of" any past basis.
This shows up two places: the HTTP API exposes POST /api/query-as-of with an ISO-8601 or epoch-ms parameter, and benchmark and introspect runs record the basis-t of the database they ran against. Reproducing a benchmark from six months ago means restoring the agent's prompt and re-querying the database as-of that same basis. The graph keeps its own history; we don't have to.