The living graph: lifecycle and tune-up

Three months in, your workspace holds a few hundred notes. "k8s" and "Kubernetes" sit as two separate nodes. Half your entities have no type. And the themes you cared about in week one have quietly moved on. Nothing is broken. The graph has just fallen a little behind your thinking, the way any index lags a collection that keeps growing.

Consilience treats that lag as normal and gives the graph its own maintenance space: the left rail of the Knowledge graph view. This lesson walks the whole rail, top to bottom.

One rule holds throughout: everything here rewrites the graph, never your markdown.

The left rail: twelve sections

Open the graph with the titlebar "Knowledge graph" button, or press ⌘⇧G. Down the left side sits a Settings-style rail. The first item, "Graph", is the 3D canvas itself. Below it come eleven tuning sections, laid out roughly in the order your notes flow through the app. Picking a section hides the canvas but keeps it loaded in the background, so flipping back is instant.

Lifecycle: the health dashboard and the one-button tune-up

The "Lifecycle" panel answers one question: how healthy is my graph right now? At the top it shows extraction coverage ("{done} of {total} added to AI search").

Below that sit six stage cards, each with a one-line role and a live status badge. Badges read "not tuned", "re-tune advised", "tuned · {time}", "up to date", "{n} to review", or "not built". A "Suggested next step" card reads those badges for you and points to the most useful thing to do next.

• "Your topics & terms": does the extractor know your field's vocabulary? (Set in "Domain vocabulary".)
• "Adding files": is every note actually in AI search? (Set in "Extraction".)
• "Same-thing matching": are duplicate names merged into one entity? (Set in "Synonyms".)
• "Connections": are suggested links reviewed and applied? (Set in "Relationships".)
• "Topic map": is the theme map built, and still fresh?
• "Experience": what has the agent learned on its own? (Reviewed in "Learned".)

Topic map: themes, bridges, and islands

The "Topic map" panel finds the big themes running across your whole workspace. Each theme is a cluster of related entities, with an AI-written name and summary. You build it on demand: press "Build topic map" (later "Rebuild") and "Finding the themes in your notes…" runs. When it's done, the header reports "{themes} themes · {concepts} concepts".

• Each theme card shows a color dot (the theme's color on the graph), its name, "{count} concepts", a summary, and its member notes.
• A theme that connects to nothing else gets an "On its own" badge. That's an island, and it's worth bridging with a connecting note.
• "Summary note" builds a map-of-content note that gathers the theme's notes and concepts as wikilinks.
• "Ideas that tie themes together" lists the bridge concepts, each labeled "Links {count} themes together".

Building the map also changes the Graph view itself. Nodes take on theme colors, the stats readout stops saying "Themes: 0", and "Map mode" shows up in the view settings. Turn it on and the whole graph collapses to one node per theme, so you see the overall shape at a glance.

Synonyms and relationships: curating what the machine matched

"Synonyms" is the "Same-thing matching" stage up close. The app spots when two near-duplicate labels, like "k8s" and "Kubernetes", name the same thing and merges them into one node. Each row shows the pair, its state ("merged" or "kept apart"), and a toggle to flip it.

Your changes rebuild the resolution graph and take effect right away, no re-extraction needed. The "Also known as" chips you'll later meet on an entity's page are the same system from the other side: split a chip there and the pair flips to "kept apart" here.

"Relationships" holds suggested structural links between entities. For each pair you pick a type (broader, narrower, related, or same) and flip the switch: on applies the relationship, off rejects it. A "Skip" link, shown only on rows you haven't applied yet, puts the decision off without recording a verdict.

Choosing "same" merges the two entities as synonyms. So even with "Add suggested connections automatically" turned on in Settings, merges always wait for your explicit OK.

Learned notes and excluded files

"Learned" lists the notes the agent wrote for itself: answers you gave it, verified task results, facts it looked up. They're saved under a learned/ folder and indexed into the graph as they land. Each carries an origin marker, so machine notes stay easy to tell apart from yours.

There's no approval step, so this panel is your review after the fact. Read them, and press "Delete" on anything wrong or unwanted: the note moves to the OS trash and its graph entries go with it.

"Excluded" manages .consilienceignore, the list of files that extraction and the code index skip entirely. It gives you three views:

• "List": every excluded path, with "Restore" to bring a file back into extraction. A "missing" badge marks paths that no longer exist.
• "Browse": the workspace tree with exclude checkboxes, for point-and-click exclusion.
• "Edit file": the raw .consilienceignore editor with "Save" and "Revert", using gitignore-style patterns.

topic map

A workspace-wide map of themes: clusters of related entities detected across all notes, each with an AI-written name and summary.

bridge

A concept that links several themes together: the connective tissue of your workspace.

island

A theme with no links to other themes, shown with an "On its own" badge.

resolution graph

The separate, machine-built graph of synonym merges. It's rebuilt from scratch, so your merge and split verdicts always survive.

learned note

A note the agent wrote and indexed on its own, marked by origin so machine notes stay easy to tell apart from yours.

.consilienceignore

A gitignore-style file listing paths that extraction and the code index skip.

Wrap-up: keeping the graph fresh

A knowledge graph needs upkeep as it grows, and the left rail is where you give it: "Lifecycle" tells you what has fallen behind, one button runs the full pass, and the individual panels let you fix the machine right where it guessed wrong. Ten minutes here now and then keeps every answer the agent gives you sharper. Next, the entity table turns the dots you just tuned into rows: every entity in your graph, ready to inspect one by one.