Update the graph and organize synonyms and topics

Lesson 6 of 614 min

What you'll learn

you can find every maintenance surface in the knowledge graph's left rail and say what each one is for
you can run the one-click "Tune up AI search" pipeline and read its progress thread
you can build the topic map and use themes, bridges, and summary notes
you can merge or split synonyms and curate suggested relationships, including how "Skip" differs from off
you can review agent-learned notes and manage excluded files

As you add sources, an entity may appear under several names or have no assigned type. After adding or editing documents, check extraction status, synonyms, and the topic map.

The graph view’s left rail contains the tools for this work. This lesson explains each management panel and the steps for updating the graph.

Synonym and type changes update the graph. Some actions also create or delete document files, such as creating a summary note or deleting a learned note, so check what each action affects.

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.

Rail section	What you do there
"Graph"	The 3D canvas itself. Your home view.
"Lifecycle"	See every stage's health and run the one-click "Tune up AI search".
"Topic map"	Build and browse the big themes across all your notes.
"Domain vocabulary"	Teach extraction your field: domain, reading persona, canonical predicates.
"Synonyms"	Review which near-duplicate labels are merged into one entity or kept apart.
"Relationships"	Approve, retype, or reject suggested links: broader / narrower / related / same.
"Revisions"	Confirm or reject later notes that revise an earlier note's decision.
"Extraction"	Coverage, per-note "Re-extract", and the big "Re-extract everything" button.
"Entity types"	The kind inventory, plus "Fill in missing types".
"Code intelligence"	Code-index health and the "Concept ↔ code" bridge.
"Learned"	Notes the agent learned and saved on its own; delete what you don't want.
"Excluded"	Files in `.consilienceignore` that extraction and the code index skip.

Click a stage to see what it does.

1Learnfollows automatic extraction settings

When automatic extraction is enabled, saving a note can extract its concepts and relationships into the graph. Extracted facts link to their source sentences.

The loop behind the rail: the app learns facts from your notes, links the same and related things, and clusters the workspace into themes. Then you tidy up what it proposed. New notes start the loop over again.

Lifecycle: status and graph maintenance

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".)

Run the one-click tune-up

Read the recommendation
Open "Lifecycle" and read the "Suggested next step" card. It tells you whether a tune-up is worth running right now.
Decide how deep to go
Leave "Re-read every note (slower, but more thorough)" unchecked for a normal pass. Check it when you want older notes re-extracted with your latest vocabulary.
Press "Tune up AI search"
The button switches to "Tuning up…" and a "Progress" thread appears just below it.
Watch the pipeline
Five steps run in order: Domain vocabulary → Re-extraction → Synonym check → Relationship check → Topic map. Each one shows as pending, running, done, skipped, or error, with detail lines and a summary once it's finished.

Let the badges schedule you

You don't need a maintenance calendar. Badges like "re-tune advised" and "rebuild advised" appear once the workspace grows past what the last tune-up saw, and "{n} to review" counts pile up on Relationships and Revisions whenever the machine wants your judgment.

When everything reads "up to date" and "tuned", there's genuinely nothing to do. Close the rail and go write.

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.

Review synonyms and relationship proposals

"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.

Deciding what counts as the same thing

Deciding whether two records name the same real-world thing has a name: entity resolution, also called record linkage. It's a classic problem. Any database that mixes "Acme Corp" and "Acme Corporation" has to solve it, and Consilience does the same for the labels in your notes.

Consilience's twist is provenance discipline. Machine merges live in a separate resolution graph that gets rebuilt from scratch, while your own merge and split verdicts are stored for keeps. So re-running the matcher can never overwrite a call you made.

"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” in a structural relationship proposal merges the entities. Structural identity proposals always wait for confirmation, even when automatic addition is enabled. AI semantic judgments are a separate path; the synonym and suspect-merge review tools let you correct those decisions.

One merge reaches everywhere

Choosing "same" here, like a merge in the "Synonyms" panel, combines the two entities' facts everywhere at once. Search, profiles, and statements all start treating them as one thing. A single confirmation rewires the whole graph.

So when two nodes really are the same, merging them is the highest-leverage move in the rail. Every future answer the agent gives you inherits the one unified picture.

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.

Give your graph a check-up

Open the knowledge graph with the titlebar "Knowledge graph" button, or press ⌘⇧G.
In the left rail, open "Lifecycle" and read the badge on each stage card. Is anything "not tuned" or "not built"?
Press "Tune up AI search" and watch the "Progress" thread walk Domain vocabulary → Re-extraction → Synonym check → Relationship check → Topic map.
When it finishes, open "Topic map" and find the theme closest to what you've been writing about lately.
Press "Summary note" on that theme.

A new note opens, gathering that theme's notes and concepts as wikilinks: a table of contents your workspace never had. Back in "Lifecycle", the button now reads "Run again", and the stage badges show fresh counts and times.

Update the graph and review individual results

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.

← Previous lesson