The three layers: workspace, graph, agent

Lesson 3 of 310 min

What you'll learn

You can name the three layers and say which one owns your files, your connections, and your answers.
Distinguish source documents, extracted facts, vocabulary, and decisions, and explain what must be preserved for each.
You can trace one fact from a sentence in a note to a node on the graph and back to its source.
You can describe what Consilience quietly does in the background while you write.

It's month six. You have hundreds of notes, and a teammate asks: "Wait, what did we decide about pricing, and where did we write it down?" In a plain folder of markdown files, that answer is twenty minutes of searching and skimming. The note is in there somewhere. What's missing is the connection.

Consilience's answer is three layers, each with one job. Your markdown files stay exactly as you wrote them. On top of them, a knowledge graph grows into an index of who connects to what. And an AI agent reads that graph to follow the connections you'd otherwise chase down by hand.

You connected a folder during first launch, so extraction is already building that graph in the background. While it works, here's the picture the rest of the course hangs on.

The three layers at a glance

Layer	What it holds	Its one rule
1 · Markdown workspace	Your notes, as plain, portable files on your own machine	Source files that you edit; the agent can also write or change them according to its permissions.
2 · Knowledge graph	Entities, relationships, and your verbatim statements, extracted note by note	A rebuildable index: every fact remembers which note asserted it
3 · Agent	The AI that follows graph connections to answer and act	Reasons on top; anything it learns is saved as new, clearly labeled notes

Workspace: Your folder of markdown files. It's the permanent, portable layer that everything else is built from.
Entity: A thing your notes mention, like a person, organization, place, project, or idea. It becomes a node in the graph.
Named graph: A per-note compartment in the graph store. Each note's extracted facts live in their own compartment, keyed by the note's path.
Provenance: Where a fact came from. In Consilience the named graph is the provenance record: it names the note that asserted the fact.
Agent: The built-in AI that reads the graph, follows connections to answer questions, and writes its own knowledge as labeled notes.

Layer 1, the workspace: source files

The bottom layer is the plainest and the most important: a folder of markdown files on your own machine. Everything above is built from these files, and nothing above ever writes back into them. Save a note, rename it, move it. It's still a plain text file any editor can open. If you left Consilience tomorrow, this layer would leave with you, intact.

Extraction and document editing

Extraction reads document content and records facts in a separate graph. Document editing and agent file-writing are separate actions that can change file contents.

Even the agent's own knowledge respects that line. Notes it learns are written as new files under learned/ and tagged as agent-authored, so you can always tell its words from yours.

Layer 2, the graph: entities, relationships, and sources

Every time you save a markdown note, Consilience quietly reads it. The people, projects, places, and ideas it mentions become entities. The typed facts that connect them become relationships. And with "Capture your decisions and questions" on, your own decisions, questions, claims, and quotes are kept word for word as statements. All of it lands in an on-device graph store, never in your files.

The design choice that matters most: each note's facts live in that note's own named graph, keyed by the note's path.

One note = one named graph

# Each note gets its own compartment, named after the note:
note "strategy/pricing.md" {
    (Acme) -acquired-> (Initech)
}
# Re-extract the note -> only this compartment is replaced.
# Delete or rename it -> this compartment is dropped or re-keyed.

A named graph for each note preserves the source of its extracted facts. Hover a connection to see the supporting note and sentence. Source facts can be extracted again, but preserving the same ontology also requires the graph, vocabulary, and decisions.

Disposable, because the whole layer can be regenerated. Settings has a "Rebuild knowledge graph" action that re-extracts every note with the latest logic. And your corrections (type overrides, synonym verdicts, removed connections) live outside the per-note graphs, so a rebuild never erases what you've taught it.

Quads: the fourth slot is for trust

In RDF (the web standard Consilience's store speaks), a fact is a triple: subject, predicate, object. Practical systems add a fourth slot for which graph the triple belongs to, which makes it a quad.

That fourth slot is how the wider semantic-web world records provenance. The store keeps the source along with the fact: "this source says Acme acquired Initech," with the note that said it attached. Consilience points the slot at your notes, one named graph per note, so every fact carries its origin. An intelligence analyst works by the same rule: never separate a claim from its source.

Drag the nodes. Click a community chip to focus it.

A miniature knowledge graph. Drag the nodes around. Each sphere is an entity pulled from a note, and each line is a typed relationship. The full-size version is one shortcut away: ⌘⇧G.

Layer 3, the agent: reasoning on top

The top layer is the built-in AI. The graph exists for its sake as much as yours. As the app's own empty state puts it, Consilience builds the graph "so the AI can follow those connections to a complete answer." Instead of keyword-matching one note at a time, the agent walks from an entity to its relationships to the notes behind them. Every hop stays backed by the exact source sentence in layer 1.

It reads through the graph. Entities, relationships, and your verbatim statements (the "In your words" section on entity pages) all become context it can follow, and each one traces back to a source note.
It builds the graph too. Extraction is the AI reading your notes in the first place. You pick which model runs it in Settings under "Extraction model".
It learns in the open. Notes the agent saves land under learned/, indexed like yours but always labeled as agent-authored, never blended into your own writing.

Background graph maintenance

Think of it the way memory works. Layer 1 is your lived experience. Layer 2 is what your brain does while you sleep: it consolidates the day into associations without touching the memories themselves.

With "Automatic knowledge-graph extraction" on, every save kicks off a quiet background pass over just the note you changed, and untouched notes are left alone. The deeper cleanup waits for one click on "Tune up AI search". And if you've been away six hours or more and something really changed, the graph greets you with a "While you were away" digest.

The life of one fact

You write it (layer 1)
You type "Acme acquired Initech in March" into a note and save. The file is the permanent record. Nothing will ever edit it.
Extraction catches the change (layer 1 → 2)
The moment you save, background extraction notices that just this note changed, re-reads only it, and rewrites its named graph. Acme and Initech become entities, and "acquired" becomes a typed relationship between them.
You can audit it (layer 2)
In the document sidebar, the "Key facts" button opens the "What this note says" dialog: entity cards, relation rows, and this note's local connection graph.
The agent follows it (layer 3)
On the knowledge graph, Acme's card lists the connection. Hover it, and Consilience quotes back the exact sentence from your note. That's layer 3's answer, grounded in layer 1's words.

Keep this model in your pocket

Everything later in this course hangs off this picture. When a lesson says "extraction," picture layer 1 building layer 2. When it mentions entity pages, collections, or the topic map, you're looking at layer 2.

When you chat, run research, or review the agent's proposals, you're at layer 3. And every claim it makes should point back to the exact sentence in layer 1.

Walk all three layers in two minutes

Open any markdown note, then click the "Key facts" button (the waypoints icon) in the document sidebar. The "What this note says" dialog shows what layer 2 extracted from this one note.
Close it and press ⌘⇧G (or the titlebar waypoints button, "Knowledge graph"). It's the same data, now fused across every note's named graph.
Left-drag to rotate, scroll to zoom, and hover a node to see its "n connections · m notes" summary.
Click an entity node, then hover one of the chips under "Connections" on its card.

The exact sentence from your note appears, the one that states the fact. That one hover is the whole architecture in a single gesture: layer 2's index pointing straight back to layer 1's words. (Brand-new workspace? You'll see "Your knowledge graph is empty," so save a note or two first.)

Where these three layers live

Next you'll map the app window surface by surface, and you'll be able to point at where each of these three layers shows up on screen.

← Previous lesson