From editor alternatives to synonym-aware search with Terraphim

Jason Fried shared a video of Write_On, and it clicked. I had a Terraphim Editor built in Rust and WebAssembly that I’d abandoned two years ago. His idea of “alternative control” gave me a meaningful way to return to it: keep the alternatives we choose while writing connected to a knowledge graph, then use that same graph to find our work. Now I can finish the editor with a clear purpose.

I’m building Terraphim around a small frustration in knowledge work: we change our words, then lose track of the ideas behind them.

A project brief calls something a risk. A colleague asks about their concerns. A literal search can miss the useful decision sitting beside the word neither person remembered to type.

We made an 80-second demonstration of a different flow. It starts with choosing a word in an editor and ends with finding a decision from the command line. The connection is an explicit, exportable knowledge graph.

Try the editor and download the actual files.

Start with the sentence

The example is a public community garden brief. Timber might arrive late, rain might delay planting, and volunteers might cancel. Each risk has a decision beside it: keep a backup supplier, reserve a covered area, or keep a reserve list.

In Terraphim Editor, I add “Concern” as an alternative to “Risk”. I can swap between the two without losing the other wording. For the final clean document, I keep “Risk”. The word “Concern” is absent.

That last detail matters. Otherwise a successful search for “concern” could simply be a literal match dressed up as a knowledge-graph demonstration.

Make the relationship inspectable

The editor’s Knowledge graph export shows the authored relationship:

synonyms:: Risk, Concern

Those alternatives refer to the same idea in this document. I download the graph as a Terraphim thesaurus and export the clean text. This is an explicit sharing step; creating an alternative does not silently change every role or every other application’s graph.

The downloads are part of the demonstration. You can inspect the graph, reopen the Markdown with alternatives, and compare it with the clean brief.

Search with the meaning you just recorded

I pass that exported graph to terraphim-grep:

terraphim-grep concern --thesaurus knowledge-graph.json --paths corpus -C 2 --search-only --json

It finds all three “Risk” passages and the decisions next to them, even though “Concern” does not appear in the clean text.

The released-binary verification also includes a baseline. With the editor’s default role, which does not contain this authored synonym, the query returns zero passages. Supplying the exported graph produces three. That makes the effect of sharing the synonym visible.

Decide whether you need a generated answer

Search alone gives the source passages and their locations. Replace --search-only with --answer to request synthesis from your configured model provider.

The paired results retrieve the same three passages. The generated answer adds a summary with references; it does not replace the evidence. It also should not turn a decision into a completed action. “Keep a backup supplier” is a recorded decision, not proof that someone has already contacted one.

Editing and local retrieval run locally. Optional synthesis sends the retrieved passages to the configured provider. A fresh answer may use different wording.

Open the same example in Obsidian

The Obsidian walkthrough now includes a downloadable sample vault and an actual screenshot from the installed app.

The raw synonyms:: Risk, Concern property lives in Notes/Risk.md. The separate project brief contains “Risk” and no literal “Concern”. The search-results note contains only saved CLI passages; it does not define the synonyms.

Using released terraphim-grep 1.21.19 against Notes/Projects, the baseline returns zero passages and the supplied synonym graph returns three exact passages at lines 7, 10 and 13. The concept note and saved results are outside that search corpus. The ZIP includes both graphs, source notes, actual outputs and a checksum manifest.

Terraphim’s synonyms:: convention uses Logseq-compatible Markdown property syntax. Obsidian native aliases use YAML aliases. This example passes the exported graph explicitly; saving the note does not automatically rebuild it. Obsidian displays saved CLI output, and this additional capture demonstrates retrieval only. The main narrated video separately compares synthesis off and on.

Open the same example in Logseq

The Logseq walkthrough includes a downloadable graph and a screenshot from Logseq 2.0.2. Import the included Markdown graph through Import existing notes → File to DB graph, then open Risk and the Concern search sidebar.

The Risk concept owns alias:: Concern and synonyms:: Risk, Concern; the project brief holds the decisions. Native Logseq aliases give a page another name. Terraphim uses the explicitly supplied editor-exported graph for the CLI search.

Run released terraphim-grep 1.21.19 from the extracted graph folder:

terraphim-grep concern --thesaurus baseline-role.json --paths pages/Projects -C 2 --json --search-only
terraphim-grep concern --thesaurus knowledge-graph.json --paths pages/Projects -C 2 --json --search-only

The baseline returns zero passages; the shared graph retrieves three decisions about a backup supplier, a covered area and a volunteer reserve list. The searched project notes never contain “concern”; concept definitions and saved results are outside the corpus. Logseq displays imported notes and saved CLI results. Its database import is a copy; the commands read the original Markdown folder.

The graph-view screenshot shows the project brief connected to Risk, Start here and the saved-results page. Its arrows are native Logseq page links; the Risk note holds the synonym definition shared through the supplied Terraphim graph.

Try the released VS Code extension and the Kilo example

Install Terraphim for VS Code, then create an alternative, save your document and explicitly export its knowledge graph. Keep the graph separate from the clean text you search.

The tutorial also includes a 44-second captioned replay of a saved Kilo integration run. Its example ZIP contains the actual graph, annotated Markdown, clean brief and results from both search modes. The replay is silent and retains the versions used in that run; the candidate Kilo marketplace skills are still under review.

Extract that ZIP and run these commands from its folder with released terraphim-grep 1.21.20:

terraphim-grep Concern --thesaurus knowledge-graph.json --paths corpus -n 3 --search-only --json
terraphim-grep Concern --thesaurus knowledge-graph.json --paths corpus -n 3 --answer --json

The first returns the source passages. The second uses your configured model provider to synthesize an answer from them. A fresh answer may differ from the saved example. I rechecked the downloaded graph and clean corpus with the released binary: an empty-graph baseline returned zero passages, and the exported synonym graph returned all three Risk passages. The corpus contains no literal Concern.

Try the evidence, not just the video

The tutorial includes the graph, clean brief, annotated Markdown, actual results with and without synthesis, captions, transcript, and a ZIP with reproduction instructions. Follow the included README to try the same search on your machine.

“Grammarly for knowledge work” is the ambition: help with the wording now, and preserve enough meaning to make the work easier to find later.

Which pairs of words cause missed searches in your project notes?

Demo and reproducible downloads: https://terraphim.ai/how-tos/synonym-search/

Disclosure: I work on Terraphim. The example is public sample input; the graph exports and search results are actual outputs. The video uses synthetic British female narration. This article was prepared with AI assistance and checked against the actual outputs.