Skip to content

Graph

Graph draws your archive as a network of projects, conversations, and the recorded links between them, such as shared files, commits, continuations, and agent messages. Use it to find related work across harnesses and projects. Graph is available only in the app. The CLI has one maintenance command, hansard graph compact, which packs the Graph index and reclaims free disk space.

App
Graph
CLI
hansard graph compact
The Conversations level of Graph, beside the Projects, Work, and Local levels, showing conversation clusters, links, and a harness color legendThe Conversations level of Graph, beside the Projects, Work, and Local levels, showing conversation clusters, links, and a harness color legend
  1. Select Graph in the dock.
  2. Choose a level in the toolbar: Projects, Conversations, Work, or Local.
  3. Select a node to open its details panel.
  4. In a project’s panel, select Explore to show that project’s conversations. In a conversation’s panel, select Focus to show its neighborhood in Local.
  5. To read a conversation, select Open conversation. For a memory node, select Open memory.
  6. To see why two nodes are linked, select a connection in the panel’s list or on the canvas.
  7. Select Back to return to the previous view.

To search, type in Search graph. Search reaches every indexed conversation, not only the ones on screen, and highlights its matches in place instead of filtering the view: matches stand out, clusters that hold them are ringed and named, and the count beside the field steps through them with Enter, Shift+Enter, Previous, and Next. Conversations shows the 500 most recent conversations by default. Choose a larger Nodes value in Display, up to All, which counts and clusters every conversation, or use From and To to reach older ones. A view of 1,500 or more conversations draws one bubble per cluster, sized by its count and named, which opens into its conversations as you zoom in or select it. With All, smaller clusters also remain reachable through grouped bubbles. Conversations load as their clusters open, so the whole archive need not be drawn at once. With Search by meaning on in Settings → Imports, search also finds conversations about what you typed that do not use its words. Title matches come first, and the panel shows Search match: Similar meaning for a conversation found by meaning alone.

When you explore a project, its name appears beside the Graph title. Select the name to clear the project scope.

Level What it shows
Projects One node per project. Each node is a pie of its conversations by harness or model, depending on Group by. A conversation that used several models is split equally among them. The slices show conversation shares, not token usage.
Conversations Conversations in the current scope and the links between them.
Work Conversations with the files, commits, test failures, decisions, and memories they produced, and outcomes such as a failed test or a reverted commit. Node kinds adds symbols, tasks, test commands, proposed memories, and skills, and Validity can include entries that no longer hold.
Local One conversation and its neighbors, one or two hops away. Local opens the conversation you selected, or a recent conversation in the current scope.

In Local, turn on Show sources to add diamond nodes for the files, URLs, commits, and memories that conversations share.

Select a connection to see what links two nodes and the evidence for it, with links to the supporting conversations. Connection types are:

Connection Meaning
Agent messages The conversations exchanged messages through agent messaging.
Delegation One conversation started the other as a helper or subagent.
Continuations One conversation continues the other.
References One conversation refers to the other, for example by its session ID.
Project mentions A conversation refers to another project, for example by its repository URL.
Shared files, Shared URLs, Shared commits, Shared branches, Shared attachments Both conversations recorded the same file, URL, commit, branch, or attachment. A file counts when a conversation edited it or named it; a URL counts when a conversation named it or its agent fetched the page.
Files read Both agents opened the same file, or one opened a file the other edited. It links conversations more weakly than a shared edit.
Memory origins A memory was recorded from the conversation.
Related topics The conversations use similar language.
Similar subject The conversations are about the same thing: each is among the other’s five closest conversations by meaning. Needs Search by meaning.
Similar screenshots The conversations hold screenshots of the same screen. Needs Screenshot search.

Related topics, Similar subject, and Similar screenshots are inferences. They mark likely related work, not an explicit reference between conversations. Every other connection comes from something recorded in the archive. A Similar subject connection shows the closest passage from each conversation, and a Similar screenshots connection names the closest screenshot in each. With Search by meaning on, Related topics counts only when the conversations are also close in meaning, so shared boilerplate or a pasted error message no longer links unrelated work.

The sidebar holds the graph controls:

Section Controls
Filters Harness, Model, Sessions, Connections, From, To, and Show unconnected, plus Node kinds and Validity on the Work level. Reset beside the heading clears them.
Neighborhood Depth (1 hop or 2 hops) and Show sources, for the Local level.
Display Size (Uniform, Tokens, User messages, Connections, or Conversations) and Nodes (500, 1,000, 2,500, 5,000, 10,000, or All, which counts every conversation and draws the largest clusters with their members loaded as you open them). A larger graph takes longer to arrange: the status bar reads Arranging N nodes… until it settles, and you can zoom and pan meanwhile. A large graph refreshes less often, up to once a minute, and waits for its layout to settle before it refreshes. Reset restores Uniform and 500.
Layout Arrange (Connected clusters, Groups, or Forces only), Center force, Repulsion, Link force, and Link distance. Reset restores the default arrangement and forces, releases pinned nodes in the view, and places the graph again.
Groups Group by (Project / portfolio, Connected clusters, Harness, or Model) and the legend of the groups it makes. Select a group to hide or show it, select Only to show that group alone, or select its swatch to change its color. Find a group searches the list, and Reset restores the default grouping, colors, and every hidden group.

Harness, Model, and Connections accept several choices. Choices within one filter widen the result, and different filters narrow it together. Sessions chooses which kinds of sessions appear: Conversations (the default, which shows conversations people started), All agent work, Delegated, Subagents, or SDK jobs. Use Connections to show only some connection types.

Harness and model choices, and harness and model groups, follow the same order as every other filter in the app: by company, most capable model or newest harness first. To list them by how many sessions used them or by which you used most recently, use Settings → Appearance → Model order and Harness order.

Connected clusters gathers conversations that share evidence into separate islands. Links between islands stay drawn but barely pull, inferred links pull less than recorded evidence, and conversations without connections ring the islands when they are shown. Each island starts with a name from its distinctive keywords. Cluster names in Settings → Imports → Search lets a local model write a short name as the group forms or changes. Keyword names remain until the model supplies one.

Where Apple’s on-device model is available, naming starts without a download. Elsewhere, turning Cluster names on downloads the naming model. Settings shows the model, download size, and progress. Leaving the setting unchanged does not download a fallback model. Naming uses conversation titles and keywords on this computer. It sends nothing to a model provider.

Names appear above the islands on screen, in the panel’s Cluster fact, and in the Groups legend when Group by is Connected clusters. Groups gathers each group from Group by into its own island instead, and Forces only places nodes by the forces alone. Under Groups, web chats outside any of their service’s projects, and other gray catch-all groups, are not one island: they gather by their own connections around the projects, and the ones without a connection ring the view. Under Connected clusters, such chats without a connection gather in small clusters by month around the edge, named like ChatGPT, Mar 2025. Nodes never overlap, so a larger Size moves neighbors aside, and the view fits the graph again after a display or layout change. While Graph is open, newly indexed conversations settle into place without moving the nodes already on screen.

Display → Group temporary folders starts on. In Projects, it combines scratch folders into Temporary folders. Select that node and Show its folders to expand it. In Conversations, those folders share one color group. Turning the setting off shows the folders separately.

Labels appear wherever they have room without covering another node or label; zoom in to see more. Hovering or selecting a node names every node it connects to. To keep a node in place, drag it or select Pin; select Unpin to release it.

When the canvas has focus, the arrow keys pan, + and - zoom, F fits the graph to the window, and Escape clears the selection. The buttons at the right of the status bar zoom with + and − and fit the graph with Fit. Reset beside them returns filters, groups, display, layout, and pinned nodes to their defaults and keeps the current level. Pause layout stops the layout from moving, and Resume layout starts it again.

Select List to browse the current nodes as a keyboard-friendly list. The list also works when the device cannot draw the graph.

The graph is empty and says it is building. Hansard builds the graph from your archive on this machine, in the background, the first time you open Graph and after upgrades. Nodes appear as indexing progresses. During the first pass the status bar counts the conversations read so far, such as “Indexing 1,200 of 8,000 conversations”; later passes show “Indexing in the background”. Indexing keeps going while imports run. Once Graph has been opened, Hansard keeps it current in the background while it is closed, so new conversations are in it the next time you open it. Nothing leaves your machine.

The status bar says updates are paused. On battery power, while the computer cools down, or while background work is paused in Settings, Graph shows the connections it already holds and stops updating them. Updates resume on their own. If Automatic graph builds is off in Settings → Imports → Search, turn it on there.

The graph did not load. Select Retry in the status bar.

The canvas went blank after the computer woke. Graph rebuilds its drawing on its own. After three failures within a minute, it shows the List instead.

The Graph index uses too much disk. Run hansard graph compact. It keeps every relationship and needs free space of twice the index size plus 2 GiB. --dry-run inspects the index without changing it.

A project or conversation is missing. Check Filters, especially Sessions, From, and To, or select Reset beside Filters. Conversations shows the 500 most recent conversations unless Display → Nodes is larger, so raise Nodes, narrow From and To, or search, which highlights a match wherever it is.

Local cannot find a conversation. No conversation in the current scope matches the filters, or none has been indexed yet. Adjust the filters, then select Local again.