DEV Community: AlexMikhalev

Graph Embeddings You Can Watch Being Built

AlexMikhalev — Tue, 20 Oct 2026 15:20:59 +0000

Originally published at terraphim.ai — where this article is fully interactive.

Graph Embeddings You Can Watch Being Built

A graph embedding does not have to be a vector. In Terraphim it is a node plus its directed edges and a set of integer counters: the synonyms that map to the concept, and the concepts that appear next to it in real text. That claim is easy to make and hard to feel, so we built a page that proves it — the actual Rust terraphim_rolegraph crate, compiled to WebAssembly, running the algorithm in your browser. Nothing on screen is staged or reimplemented; the counters you watch increment are the same code paths the crate's own tests exercise.

What the page does

Live Aho-Corasick matching. Type any sentence into the matcher and a real automaton — compiled from a 19-term thesaurus — scans it in a single pass and reports concept ids. raft quorum consensus fires #1 raft, #6 quorum, #2 consensus. The matching is case-folding and leftmost-longest, exactly as the Rust crate configures it.

Step-by-step indexing. Index the eight-document corpus one click at a time. Each document is matched, adjacent concept matches become directed edges, and node and edge counters increment. The end state — 10 concepts, 23 directed edges — includes a raft → raft self-loop that falls out of Document::to_string() matching titles as well as bodies. No special-casing; that is what the Rust code does, so that is what the page shows.

A query ledger you can audit. Query consensus and the winner, doc-membership, earns 19 points decomposed as node 7 + edge 1 + doc 2 through one edge plus node 7 + edge 1 + doc 1 through another. Every point of the sum is a named node, a named edge and an inspectable document count. That is the explainability argument for symbolic retrieval made concrete: there is no answer to "why 0.87" for a dense vector, and a complete answer here.

Honest failure. byzantine fault tolerance matches no thesaurus term and the graph returns an empty set — displayed as such — while the illustrative vector panel next to it still produces fuzzy similarity scores. The contrast is the lesson: dense retrieval always answers, symbolic retrieval tells you when it does not know.

Real rebuild cost. Add a synonym — say leader selection — and the page calls the crate's thesaurus.insert plus rebuild_automata, measuring the result live (single-digit milliseconds on an M-series laptop). Set against the "update the embedding" column for node2vec, GCN or a hosted vector index, this is the cost-of-change argument.

The honest comparison

The page includes a side-by-side table across training requirements, update cost, explainability, determinism and memory footprint for learned graph embeddings (node2vec, GCN, TransE, Cleora), dense text embeddings behind an API and vector database, and Terraphim's graph. It does not pretend the symbolic graph wins everywhere: it is blind to out-of-vocabulary terms, its ranks reflect frequency rather than importance, and its reach is one hop of adjacency.

Those gaps have engineered answers that already exist in the codebase rather than proposals: query_graph_with_trigger_fallback backs the graph with a TF-IDF trigger index as an opt-in fallback, and search_sessions_hybrid fuses BM25 full-text scoring with knowledge-graph concept boosts for session search.

Try it

Everything above is one click away at terraphim.ai/docs/graph-embeddings-interactive/. The WASM build, its provenance manifest and a conformance suite that cross-checks the browser output against an independent oracle are all in the site's repository.

What would you index first on a graph you can watch being built?

Graph Embeddings for Checklists

AlexMikhalev — Tue, 20 Oct 2026 12:19:36 +0000

Originally published at terraphim.ai.

Graph Embeddings for Checklists

A checklist is an enumerated set of terms that must be checked. That is the whole problem, and it is the reason vector embeddings are the wrong tool for it: a nearest-neighbour index returns fuzzy neighbours, it cannot enumerate a fixed set and report which members fired. A knowledge graph can. Write the checklist once as synonyms under a normalised term, compile it into an Aho-Corasick automaton, and every check becomes a deterministic match with a named edge you can audit.

This post shows that machinery applied to the two places a checklist earns its keep around an LLM call: terraphim-grep with a role thesaurus before the call, and terraphim-agent hooks plus learning after it. Every command below was run while writing this article; the outputs are real.

The Checklist Is an Automaton, Not a Promise

The usual pattern for "checklists" in agent workflows is a paragraph in a system prompt that the model promises to honour. That is a probabilistic check enforced by the thing being checked. Terraphim inverts it: the checklist lives outside the model, in the same structure that powers graph embeddings elsewhere on this site.

A checklist item set looks like this in the knowledge graph. This is bun install.md from the rewrite graph on this machine (committed verbatim at .terraphim/rewrite/bun install.md in this site's repository):

# bun add

Install dependencies using Bun package manager.

synonyms:: npm install, yarn install, pnpm install, npm i, yarn add, pnpm add

The filename gives the normalised term the hook reports back (the suggestion in the findings output below is bun install, matching bun install.md), while the heading names the approved form inside the file. The synonyms:: line is the checklist itself: every surface form that must be recognised and dealt with. Compile the directory of such files into thesaurus.json and you get the "Terraphim Engineer" role used below, currently 219 entries. Rebuilding the automaton after an edit takes about 20 ms, a figure we verified in Why Graph Embeddings Matter, so the checklist is cheap to change and free to consult.

Before the LLM Call: Retrieval as Checklist Execution

The first job of a checklist is deciding what goes into the prompt. "Gather relevant context" is vague; "which of the enumerated terms in this role's graph appear in the repository, and what do they pull in" is a check.

Here is the query I ran over this site's own source while preparing this article, using the Terraphim Engineer thesaurus:

terraphim-grep "quality gate" --haystack all --paths . \
  --thesaurus ~/.config/terraphim/thesaurus.json -n 8 -C 1 --json

The result, abridged:

"stats": {
  "search_latency_ms": 53,
  "chunks_returned": 8,
  "kg_hits": 8
},
"concepts": [
  {"name": "accept"}, {"name": "accepted"}, {"name": "escalate"},
  {"name": "fail"}, {"name": "improve"}, {"name": "judge-verdicts"},
  {"name": "needs improvement"}, {"name": "pass"}
]

Two things worth pausing on. First, the concepts list is the checklist executing: the graph expanded "quality gate" into its item set (accept, fail, escalate, pass, judge-verdicts and friends) and matched those terms across the tree. Second, the chunks it returned came from .github/workflows/*.yml and campaigns/skills-2026/*, files that contain none of the words "quality" or "gate". They matched on fail, curl --fail, accepted: items on the checklist, not words in the query. Fifty-three milliseconds, no embedding model, and every hit can name the edge that produced it.

The honest empty case

A checklist that cannot say "not covered" is useless, so here is the control run against the same thesaurus:

terraphim-grep "checklist" --haystack all --paths . \
  --thesaurus ~/.config/terraphim/thesaurus.json -n 8 -C 2 --json

"kg_hits": 0,
"sufficiency": "SearchOnly",
"sufficiency_explanation": "Found 4 chunks but KG confidence 0.00 < 0.50,
  diversity 1 < 2; returning search results only (pass --answer or
  --force-rlm to synthesise)."

Zero KG hits, four plain lexical chunks, and an explicit admission that graph confidence was too low to claim concept coverage. The tool does not pretend the checklist applied. If you want "checklist" to be a graph concept, you write it into a kg/*.md file with a synonyms:: line and rebuild; the gap is a text edit, not a retraining run. The project-local variant of this workflow (a .terraphim/ directory in your repo with its own role thesaurus) is documented in the terraphim-grep offline setup and the concepts can be enriched with code anchors mined by ast-grep.

Reproduce it

The artefacts behind these outputs are committed. This site's repository carries a .terraphim/ directory: kg/ holds the concept files used above (validation gate, judge-verdicts, hook, grounding gate and friends), rewrite/ holds the hook checklist, and thesaurus.json is the compiled 39-entry public subset of the working role. Run the same command against it:

terraphim-grep "quality gate" --haystack all --paths . \
  --thesaurus .terraphim/thesaurus.json -n 8 -C 1 --json

Same eight concepts, same honest kg_hits: 0 on the "checklist" control. For larger published checklist graphs, docs/src/kg/checklists/ in the terraphim-ai repository carries the code review and security concepts.

After the LLM Call: The Hook Is a Findings Checklist

The second job of a checklist is gating what comes back. In current releases, terraphim-agent hook does not silently rewrite the agent's proposed action; it returns a machine-readable findings list. That distinction matters: the hook's job is to check, and a check that mutates silently is a check you cannot audit.

Run from the directory holding the rewrite config, against a tool call an agent might propose:

echo '{"tool_name":"Bash","tool_input":{"command":"npm install react"}}' \
  | terraphim-agent hook --hook-type pre-tool-use --json

{"tool_input":{"command":"npm install react"},"tool_name":"Bash",
 "validations":{"findings":[{"matched_term":"npm install",
 "suggested_replacement":"bun install"}],"has_findings":true}}

Read that output as a completed checklist line: item "npm install" found, prescribed action "bun install", flag raised. The hook types cover the lifecycle (pre-tool-use, post-tool-use, pre-commit, prepare-commit-msg), and --with-guard is on by default for pre-tool-use so destructive commands get intercepted in the same pass. We covered the git-hook end of this in Teaching AI Coding Agents with Knowledge Graph Hooks and the end-to-end verified flow in Native Hook Support.

When the checklist itself fails

Checklists also cover the checking tool. Two honest notes from this session:

terraphim-agent learn query "checklist" returned a list of past failed commands (exit-1 runs captured by the PostToolUse hook); the learning store is doing its job remembering what went wrong before.
terraphim-agent replace in this build reports replacements: 1, "changed": true while returning the input unchanged. The findings-based hook path above is the contract to rely on; if replace is your integration point, verify the output rather than the flag. This is itself a captured learning; see Teaching AI Agents to Learn from Their Mistakes for how such a failure becomes a stored correction and eventually a new synonym.

The Loop, Closed

Put the phases together and the checklist lifecycle is:

Declare: write kg/*.md files; heading = normalised item, synonyms:: = surface forms to catch.
Compile: generate thesaurus.json; ~20 ms per role.
Retrieve (pre-LLM): terraphim-grep with the role thesaurus expands queries into concept terms and pulls grounded chunks — or honestly reports kg_hits: 0.
Draft: the LLM call runs with checklist-shaped context instead of a vibes-based prompt.
Gate (post-LLM): terraphim-agent hook emits findings; guards intercept destructive commands; failed commands are captured by the learning hook.
Correct: learn correct / learn correction add turn observed failures into reviewed rules; memory capture stores authored lessons; the synonyms grow and the automaton recompiles.

Step 6 is what makes this different from a static lint list. Corrections feed back into the graph, so the checklist the next session runs against is the checklist this session finished — a property the learn/memory subcommands exist to provide, described in the learning capture spotlight.

Why This Is Not a Vector Problem

A vector index answers "what is near this?" A checklist asks "which of these exact items occurred, and what was the prescribed response?" Those are different questions with different audit requirements. Graph embeddings give you the second in tens of milliseconds on a laptop, with an explainable edge for every match and no network call. The full performance case, including the 1.4-million-pattern sub-millisecond figure, is in Why Graph Embeddings Matter and Sub-Millisecond Context with Knowledge Graphs; the mechanism is on the Graph Embeddings reference page.

If you want the wiring for your own agent setup, the command rewriting how-to walks through where the synonym files live, how the role graph is built, and how host hooks call the matcher. Write the checklist once; let the automaton enforce it on both sides of the call.

Context Engineering: the book is out

AlexMikhalev — Mon, 19 Oct 2026 10:58:34 +0000

Most AI systems don't fail because the model is wrong.

They fail because the context is.

But here's the uncomfortable part: context engineering isn't a new activity. We've been doing it for decades under different names:

Configuration management gave us baselines and change control. Systems engineering gave us decision gates and requirements traceability.
Domain-driven design gave us the ubiquitous language and bounded contexts. The systems-thinking tradition gave us a method for building explanations rather than narratives.
Then LLMs arrived, and a lot of that discipline was set aside. Context became "the prompt" — something to tweak, not something to version, validate and govern.

That's the argument in my book, Context Engineering: Designing AI That Understands, Remembers, Acts, and Learns.

It isn't a new invention. It's an old discipline applied to a new kind of system — one where the "software" is partly prompts, partly knowledge, partly retrieval, partly policy, and partly the model's emergent behaviour.

Inside, 25 chapters cover:

why AI software fails differently — context drift, not crashes
knowledge graphs as context infrastructure, and when deterministic search beats vector embeddings
token budgets, compression and skill architecture
judge harnesses, typed decision models and evidence lineage — how to make an AI's decisions inspectable
validation gates, multi-agent context and enterprise governance
building a context engineering practice

It's written for senior developers, engineering managers and architects who need AI to be dependable in production, not just impressive in a demo.

The book is out now on Kindle: amazon.com and amazon.co.uk.

Which older discipline do you think AI teams have forgotten most?

3 Ways to Save Money on Tokens for Your AI Agents

AlexMikhalev — Mon, 19 Oct 2026 09:25:58 +0000

Three levers we run in production: let a cheap model summarise the evidence, put expensive reasoning only where it earns its keep, and route every request through a proxy that knows the price of each lane.

Your agent bill is mostly input tokens. Not the clever parts: the re-reading.

Every turn, a coding agent replays its entire transcript to the provider. Add a repository to explore and a handful of tool outputs, and a single session can carry a hundred thousand tokens of context that the model reads over and over at full price. The frontier model you are paying for spends most of its expensive attention budget on text it has already seen, or text a much cheaper model could have filtered first.

We run a fleet of overnight coding agents on a single machine, so we feel this directly. Over the past few months we have landed on three levers that cut token spend without cutting output quality. Each one is running in production today, and each one comes with a caveat we will not hide: we have measured the mechanisms, not the end-to-end savings. The arithmetic below uses published prices and our own logs; treat it as illustrative, not invoiced.

1. Search first, let a cheap model summarise

The most expensive way to give a frontier model context is to hand it raw search results. The cheapest way is to let a small model read them first.

The pattern looks like this. A local search tool retrieves candidate chunks from your codebase or knowledge base. Before those chunks reach your GPT-6 or Fable-class session, a lower-cost model synthesises them into a compact answer, with deterministic references back to the source. The expensive model receives the synthesis and the few references it may need to reopen, not ten near-duplicate excerpts.

We do this with terraphim-grep (part of the open-source terraphim-clients repository), which resolves query terms through a curated knowledge-graph thesaurus before ranking local matches:

export OPENROUTER_MODEL='deepseek/deepseek-v4-flash-0731'

terraphim-grep provider \
  --thesaurus docs/src/thesaurus.json \
  --haystack code --paths crates -n 10 \
  --answer --force-rlm --json

--answer requests an answer when the sufficiency check calls for one; --force-rlm forces the synthesis path. Only the selected excerpts leave the machine, through OpenRouter to a DeepSeek-flash-class model. There is also --search-only, which hard-disables synthesis and skips building the LLM client entirely, so a stray API key in the environment cannot cost a single network call.

In our verified run, the raw chunk contents measured 505 characters, the evidence with source locations 1,108 characters, and the synthesised answer text 440 characters: the frontier model received about 40% of the context it would otherwise have been fed, with references it could reopen on demand.

Two honest caveats. First, we measured characters, not tokens: the CLI does not expose token usage, so treat the ratio as directional. Second, the win is conditional on the handoff shape. The full answer object with all ten references measured 1,918 characters; forward that wholesale and the saving evaporates. Pass the synthesis plus the references needed for verification, nothing more.

2. Put expensive reasoning at the edges of the V, not in the middle

The second lever is not a tool but a lifecycle decision: match the model's price to the phase of work.

We structure agent work as a V-model. The left side asks "what should we build" (research, design, specification); the right side asks "did we build it correctly" (review, validation, judge panels). The long middle (implementation, test-writing, mechanical verification loops) is where most of the tokens burn, and it is precisely the part that needs the least reasoning depth.

So we split the model placement:

Edges get the expensive models. Research synthesis, architecture decisions, and final review stay on high-reasoning lanes, because a bad plan or a rubber-stamped review costs more than the tokens save.
The middle runs on fast delivery models. Implementation and test loops run on grok, MiniMax, or Kimi highspeed lanes over flat-rate subscriptions. Our overnight agents execute on opencode-go subscription models; our judge panels run on Kimi K2.5, which reaches 90% verdict agreement with human reviewers at around nine seconds per review.

The arithmetic is worth doing once. At published API prices, an illustrative workload of 100 million input and 20 million output tokens costs $800 if everything runs on a frontier model. Route 80% of it to a mid-tier model and the same token volume costs $480: 40% less, with the model count unchanged. That is a counterfactual at published prices, not a measured bill, but the shape of the saving is real: you are not paying for fewer tokens, you are paying less per token for the phases that do not need frontier reasoning.

The catch is discipline. Left to itself, an agent uses whatever model it started on for everything. The phases have to be explicit, which is why this lever only works inside a structured lifecycle rather than a free-running session.

3. Put a proxy in front of the providers

The third lever makes the cheap route the default: an LLM proxy between the agent and every provider, routing each request by what it contains or how fast each lane currently is.

Ours is terraphim-llm-proxy, shared with our GitHub Sponsors supporters. It sits on localhost, exposes OpenAI and Anthropic compatible endpoints, and decides where each request goes:

Keyword routing. The proxy matches prompt content against a markdown taxonomy using Aho-Corasick string matching (microsecond overhead, the same crate our knowledge graph uses). A prompt that says "think step by step about this architecture" routes to the think chain regardless of the model ID the client requested. In our logs, three consecutive requests landed on three different providers under three different scenarios, transparently to the client.
Speed and price routing. Eligible candidates can be ranked by time to first token, or by cost class: free lanes first, then subscription, then metered. Per scenario you choose whether latency or price wins. Agent idle time waiting on a rate limit is a real cost, just billed in hours rather than tokens.
Fallback chains make the cheap lanes safe. Cheap providers have real reliability gaps: silent API format changes, undocumented capacity errors, higher latency from Europe. Pipe-delimited fallback chains mean a dead provider just moves the request to the next target. We verify this with deliberate failure injection (pointing the primary provider's domain at localhost in /etc/hosts) rather than trusting the config.

One caveat that took us by surprise: prompt caches are per model, not per session. Measured across real coding sessions, 82% of mid-session model switches collapsed the cache read below 10% of its previous value: a warm 107,000-token prefix became 110,000 tokens of uncached input, roughly ten times the cached price for the same text. The saving pattern is therefore to route the session or the scenario, not each turn at random. Pick a lane for the job and stay on it.

What we do not claim

Token savings are not measured end-to-end. The synthesis example is measured in characters, not tokens; the model-mix example is arithmetic at published prices, not an invoice; the 82% cache-collapse figure comes from one operator's session logs, not a fleet benchmark. The honest metric is quality-adjusted cost per accepted task, and we are still building the instrumentation to report it.

What we can claim is mechanism: retrieval that filters before the expensive model reads, a lifecycle that spends reasoning budget where judgement lives, and a proxy that prices the lanes before it forwards the request. None of these require trusting a benchmark. All three are running today.

The underlying pieces have full write-ups: terraphim-grep and role-aware search and the V-model for AI agents. The grep tooling is in terraphim-clients. The routing proxy from section 3 is terraphim-llm-proxy, shared with GitHub Sponsors supporters. If you want this running inside your team rather than as homework, we do it as part of our consulting work at zestic.ai.

Testing a learning hook from failed command to real execution

AlexMikhalev — Tue, 13 Oct 2026 08:55:34 +0000

Update: what the model requested, and what actually ran

The hook rewrites the command; OpenCode executes it. I extended the included adapter so one execution record now links the original request, matching compiled rule ID and graph hash, final executed command, tool result and saved output file. The result file carries the same execution ID and its SHA-256 is checked.

The new 66-second demo uses actual saved outputs and synthetic British narration. All 22 regression tests pass, and the downloadable ZIP was extracted and run again with released terraphim-agent 1.21.19 and OpenCode 2.0.20. The adapter source is version 2.0.0; this covers the public example’s sequential whole-command mapping.

Watch the new demo · Download the source, tests and saved evidence · Inspect the execution receipt

The original walkthrough below retains its original recorded outputs.

The adapter normalizes OpenCode V2 after-tool events for learn hook and applies the pre-tool result through mutable event.input. A failure-record correction is explicitly promoted to a tool-preference record, then compiled to the role thesaurus. Returned JSON and actual shell execution are verified separately.

A coding agent uses the wrong flag. You explain the correction, and the command works. The useful question is what happens when another session makes the same mistake.

This walkthrough follows one harmless error from failure to saved correction to actual execution. It uses the Harbour project brief from the memory walkthrough, a released Terraphim agent, and an OpenCode adapter included in the download.

Watch the narrated demonstration: https://terraphim.ai/how-tos/command-rewriting-howto/

Download the Harbour hooks example · Read the transcript

Start with the command that fails

Harbour's validator checks that its brief contains a decision, a risk and an owner. The correct command ends with --check. In the baseline run, OpenCode actually attempts:

python3 validate-brief.py --chek

The argument is misspelled. Python's argument parser reports that --check is required and exits with status 2. No validation.json is created. The downloadable trace contains the host's actual tool result, including that output and exit status.

That distinction matters: the coding host itself can finish normally after reporting a failed tool. Its overall process exit code is not evidence that the validator succeeded. Here we inspect the shell tool's result and the expected output file.

Capture the failure that really happened

The included project-local adapter receives OpenCode's after-tool event. It translates the real command, combined output and exit status into Terraphim's learning-hook schema, then calls the released agent.

The saved Markdown learning contains the command, exit code 2 and the parser's actual error. A new CLI process can list it again. This gives the correction a concrete source: an observed failure, with a saved record that can be inspected.

The adapter is part of this example. In the tested release, passing a native OpenCode event directly with --format opencode does not by itself establish that a learning was captured. The script checks the resulting file and later readback.

Review and promote the correction

We add the intended command to the failure record with learn correct. That records a proposed correction. It does not automatically make it a replacement rule: compiling the failure record alone produces zero correction entries in this release.

The next step is explicit human review and promotion to a tool preference. The reproduction script runs this command inside its isolated store:

terraphim-agent learn correction add \
  --correction-type tool-preference \
  --original 'python3 validate-brief.py --chek' \
  --corrected 'python3 validate-brief.py --check' \
  --context 'Manually reviewed correction from the captured failure'
terraphim-agent learn compile --output compiled-corrections.json
terraphim-agent learn export-kg --output kg

Compilation now reports one correction. The selected Harbour Validator role loads that compiled JSON. The exported Markdown makes the relationship readable:

# python3 validate-brief.py --check
synonyms:: python3 validate-brief.py --chek

This uses the same explicit synonyms:: idea as the editor-to-search flow. The correction says which command this project prefers. In this walkthrough the hook reads the compiled JSON; exporting a Markdown file alone is not the activation step.

Inspect the hook before involving execution

First we call the pre-tool hook on a saved input. Without --rewrite, the returned command keeps --chek and includes a warning about a replaceable match. With --rewrite, the returned JSON contains:

{
  "tool_input": {"command": "python3 validate-brief.py --check"},
  "tool_name": "Bash"
}

That is a hook result. It has not executed Python. The example retains both results so you can compare the disabled and enabled behavior. An unrelated command and a role without this correction remain unchanged.

Verify what the coding host actually runs

Now start a fresh OpenCode process and ask it to try the same misspelled command. Its before-tool event reaches the adapter. The adapter calls Terraphim with rewriting enabled, then applies the returned command through OpenCode V2's mutable tool input.

The after-tool event records python3 validate-brief.py --check. Its exit status is 0. The validator prints a valid Harbour result and writes this file:

{
  "project": "Harbour",
  "status": "valid",
  "fields": ["Decision", "Risk", "Owner"]
}

The host transcript can still display the model's original attempted input. That is why the download includes adapter events, the actual tool result and validation.json, as well as the transcript. Together they show the attempted command, the applied correction and the resulting execution.

Reproduce it in a new folder

The example was verified with terraphim-agent v1.21.19 and OpenCode 2.0.20. Follow the ZIP's README to check the release archive, choose your already authenticated coding model and run:

python3 reproduce.py \
  --agent /absolute/path/to/terraphim-agent \
  --model kimi-code-plan-global/k3 \
  --output /absolute/path/to/a-new-harbour-run

Use your configured model identifier if it differs. The script uses a new folder for the fixture, settings, learning store and project-local adapter. It does not install global hooks or select a paid fallback. The recorded run used the existing Kimi coding-plan route.

Read evidence/verification.json, the host events and validation.json. The script fails if the host does not perform the expected command or the saved outputs do not match. You can inspect the source before running it; only the two local validator commands are permitted by the fixture's host configuration.

Keep the scope of the example visible

This demonstrates one reviewed correction with one tested host adapter. It does not prove every coding host applies the same JSON, or that failure capture should automatically approve arbitrary substitutions. The earlier memory example and this learning store also remain separate; neither silently copies into the other.

Use public sample data for this release's learning capture. Tests with deliberately fake secret-shaped values found redaction gaps in saved command and working-directory fields, and in some hook passthrough values. The example makes no blanket secret-redaction claim. The coding host uses its configured online model; Terraphim's demonstrated correction lookup uses the local compiled graph.

Download the example and saved outputs to follow the whole chain: a failure that happened, a correction someone reviewed, and a later command whose result can be checked.

Updated 13 October 2026. The video uses synthetic British female narration and readable excerpts from actual released-binary and host outputs. The Harbour project is fictional public sample data.

Testing authored memory across fresh CLI processes

AlexMikhalev — Tue, 13 Oct 2026 08:25:25 +0000

The example separates persistence from retrieval: an evolution-store record survives process exit, while a role thesaurus and co-occurrence graph select relevant memory items. Nine assertions check exact capture/readback/export, useful retrieval and negative controls. Roles are retrieval filters, not access controls.

You explain the project's validation command. The session ends. Next time, the agent needs the same explanation. Keeping the instruction somewhere is useful only if the next run can find the right instruction again.

This walkthrough saves one lesson from a fictional project, opens it in a new process, and retrieves it through a small knowledge graph. You can inspect the exact saved text and repeat the same checks with the downloadable example.

Watch the narrated demonstration: https://terraphim.ai/posts/cold-start-tax-agentic-memory/

Download the Harbour example · Read the transcript

Start with an instruction worth keeping

Harbour is a small public project brief. It records a decision, a risk and an owner. Before publication, its validator checks that all three fields are present. The instruction we want the next session to remember is deliberately specific:

Validate the Harbour project brief with python3 validate-brief.py --check.
Keep the source decisions in brief.md intact.

That gives a future agent an action and a boundary. “Remember to be careful” would be much harder to use. The example also includes the brief and validator, so the instruction has something concrete to refer to.

The first step is to save this actual text. Download and extract the example, then install terraphim-agent v1.21.20. From the example folder, prepare a new, isolated run before entering the manual commands below:

python3 reproduce.py --agent /path/to/terraphim-agent \
  --output ./harbour-run --prepare-only
cd harbour-run/fixture
export TERRAPHIM_DEFAULT_DATA_PATH="$(cd .. && pwd)/data"
export TERRAPHIM_SETTINGS_PATH="$(cd .. && pwd)/settings"

Use your actual binary path in the first command and put that same verified binary on your PATH for the remaining commands. Preparation creates the role configuration, settings and lesson.md; it has not captured anything yet. To run all checks automatically instead, omit --prepare-only and choose a fresh output folder.

terraphim-agent --format json memory capture \
  --file lesson.md \
  --provenance-tag harbour-public-brief-v1

Capture returns a memory identifier. We use that identifier to inspect the saved item, rather than treating a successful exit code as the whole result. The saved content is the lesson itself, and the provenance tag identifies which public example supplied it.

--content accepts a short instruction directly. --file is convenient for a multiline note. Both preserve the supplied text. Missing, blank, unreadable or conflicting inputs fail without creating a substitute placeholder.

End the process, then open the memory

Each command in the demonstration starts a new process. After capture exits, memory show opens the saved identifier. memory list finds the item, and memory export includes the same instruction in JSON.

terraphim-agent --format json memory show MEMORY_ID
terraphim-agent --format json memory list
terraphim-agent memory export --format json --output memories.json

Replace MEMORY_ID with the identifier returned by capture. The reproduction script does this automatically and checks that the reopened and exported text exactly matches lesson.md.

The store has an explicit location. The example sets TERRAPHIM_DEFAULT_DATA_PATH to a new folder for that run; the evolution file lives beneath terraphim/evolution/cli-agent.json. A second empty folder supplies the independent-store check. This keeps the demonstration separate from your existing memory files.

Without an explicit data root, the agent retains its usual platform configuration-directory location. Changing the root selects another store; it does not silently migrate or merge your previous one.

Teach the role the words used by the project

Knowing an identifier is useful for inspection. Day to day, you are more likely to ask a question such as “validate brief”. The Brief Reviewer role supplies the terminology for that question.

Its small graph has a Brief validation concept:

# Brief validation
synonyms:: validate brief, brief validation, --check

A second concept describes the Project brief, including brief.md. Both definitions are ordinary Markdown in the download. The saved instruction mentions these concepts, connecting an action with the document it applies to.

The synonyms:: property makes the relationship visible: “validate brief” and --check are labels for the same concept in this project. You can review or change that relationship. Saving a memory does not invent new terminology or update every other role automatically.

This is the same explicit-knowledge principle used in the editor-to-search example: record the relationship, then use the configured graph to find relevant work. Here the searched material is an authored memory item.

Retrieve the instruction, then check the empty cases

With the example's role configuration loaded, this query retrieves the stored lesson:

terraphim-agent --config ../config.json memory retrieve 'validate brief' \
  --role 'Brief Reviewer' --format json

The result includes the original text, its memory identifier, the provenance tag and a matched concept. It is a retrieved instruction, not a generated paraphrase. The viewer can compare it directly with the file that was captured.

The accompanying controls matter just as much. “Volcanic eruption” returns no memory. The Finance Reviewer role, which has budget and grant concepts, does not match the validation query. The same useful query against a separate empty store also returns nothing.

Those observations distinguish useful retrieval from a command that always prints the latest note. Roles shape which concepts are recognised. They are not an access-control system: use separate stores and ordinary filesystem permissions where separation is required.

What happens inside the CLI

The agent stores the lesson using Terraphim's existing evolution types. During retrieval, the role's thesaurus matches terms, and the role graph ranks memory items by their concept relationships. There is no lexical fallback when a question matches none of the configured concepts.

This graph uses co-occurrence edges, so the example intentionally connects validation with the project brief. A single isolated concept is not enough to assume the same retrieval behavior. Keep the graph and the note inspectable, and test the questions people will actually ask.

memory apply can preview proposed context for a prompt. That preview does not execute a command or prove a coding host consumed it. The separate hooks walkthrough will follow the instruction into actual execution. Captured memories and reviewed learning corrections also use different stores; neither is an automatic copy of the other.

Try the next run yourself

The ZIP contains the public brief, validator, lesson, Markdown concepts, reproduction script and saved outputs. Follow its README to verify the released binary, create an isolated run and compare the positive and negative results. The script checks the saved content, rather than relying on expected screenshots.

Download and reproduce the memory example. You can also inspect the saved outputs and verification manifest.

The useful result here is modest and concrete: an instruction survives the process that captured it, and the intended project terminology can find it again. Measuring whether that saves tokens or improves later decisions needs a separate experiment.

Updated 13 October 2026 with a reproducible walkthrough. The broader memory-lifecycle vocabulary was inspired by memco.ai's field guide. The video uses synthetic British female narration and readable views of actual CLI outputs. The Harbour fixture is public sample data.

From editor alternatives to synonym-aware search with Terraphim

AlexMikhalev — Mon, 12 Oct 2026 10:45:02 +0000

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.

Plug Terraphim Search into Claude Code and opencode (CLI First, MCP When You Need It)

AlexMikhalev — Sat, 18 Apr 2026 08:53:07 +0000

Your AI coding agent already has a knowledge graph. It is just not yours yet. The model knows GitHub, Stack Overflow, and the public training corpus -- it has no idea that in your project npm should be bun, that RFP is shorthand for acquisition need, or that the email about the Stripe receipt for the Obsidian licence lives in your Fastmail mailbox. This post shows the smallest path to fixing that for both Claude Code and opencode, using Terraphim and the three roles we have published over the last week (Terraphim Engineer, Personal Assistant, System Operator).

Two paths. CLI first.

What "integrate" means here

The host -- Claude Code or opencode -- needs a way to ask your role-aware Terraphim setup a question and get back ranked, source-attributed results. The model decides when to ask. The role decides which haystacks to search. Terraphim's terraphim-graph ranker decides which results come back first.

Concrete example. You are working in opencode and you type:

/tsearch "System Operator" RFP

The slash command runs against the System Operator role. The role's knowledge graph normalises RFP to its INCOSE-canonical form acquisition need. The Aho-Corasick matcher walks the role's haystack (1,347 Logseq pages from the terraphim/system-operator repository). The top hit comes back ranked 13 -- Acquisition need.md -- with the synonyms:: line that mapped your query to it visible in the snippet. The model now has the right page in its context window and can answer your follow-up without a hallucinated INCOSE handbook reference.

This works in both hosts because both speak the same two integration languages: shell-out slash commands and MCP servers. We are going to use both.

Path A -- CLI via slash command

Why this is the recommended starting point

terraphim-agent already exists, takes --role and --limit, and writes ranked results to stdout. There is nothing to build. Both Claude Code and opencode let slash commands shell out via Bash. So a two-line command file is the entire integration.

One file, two hosts

Drop this at ~/.claude/commands/tsearch.md (and an identical copy at ~/.config/opencode/command/tsearch.md -- both hosts read the same frontmatter shape):

---
description: "Terraphim search across configured roles. Usage: /tsearch [role] <query>"
allowed-tools: Bash(terraphim-agent search:*), Bash(terraphim-agent-pa search:*)
---
Run `terraphim-agent search --role "<role>" --limit 5 "<query>"` (or
`terraphim-agent-pa search ...` if the role is "Personal Assistant" and
the query needs the JMAP haystack). Return the top results as a numbered
list with title, source path/URL, and a 120-char snippet.

That is it. The allowed-tools line auto-approves the two CLI invocations so the model does not have to ask permission per call. Restart the host (or reload commands) and /tsearch is live.

Why fast enough

terraphim-agent reads its persisted role state at start (low milliseconds), runs the query against the role's haystacks, and returns. For a typical knowledge-graph query against the Terraphim Engineer role on a laptop, the round trip from slash command to formatted output is well under a second. The agent already has the typed CLI -- --role, --limit, --format json -- so there is nothing the MCP layer adds for the search-only flow.

Three example queries

/tsearch "Terraphim Engineer" rolegraph
/tsearch "System Operator" RFP
/tsearch "Personal Assistant" invoice    # uses terraphim-agent-pa wrapper for JMAP

The Personal Assistant case is the most interesting because it crosses surfaces -- Obsidian notes interleave with jmap:///email/<id> URLs from your Fastmail mailbox, ranked by the same terraphim-graph scoring. The wrapper script injects JMAP_ACCESS_TOKEN from 1Password at call time so the secret never lands on disk; the bare terraphim-agent continues to work for the other five roles without paying the unlock cost.

Path B -- MCP server (when you want typed tools)

The CLI path is enough for search. If you want the model to call search as a first-class tool with structured JSON parameters -- alongside autocomplete_terms, autocomplete_with_snippets, four flavours of fuzzy autocomplete, build_autocomplete_index, and update_config_tool -- that is what terraphim_mcp_server exposes. It reads the same ~/.config/terraphim/embedded_config.json, so the role list is identical.

Build and install

cd ~/projects/terraphim/terraphim-ai
cargo build --release -p terraphim_mcp_server --features jmap
cp target/release/terraphim_mcp_server ~/.cargo/bin/terraphim_mcp_server

For the Personal Assistant role, mirror the existing terraphim-agent-pa wrapper at ~/bin/terraphim_mcp_server-pa so the JMAP token flows through op run instead of being baked into config.

Register

opencode -- add to ~/.config/opencode/opencode.json under mcp:

"terraphim":    { "type": "local", "command": ["/Users/alex/.cargo/bin/terraphim_mcp_server"] },
"terraphim-pa": { "type": "local", "command": ["/Users/alex/bin/terraphim_mcp_server-pa"] }

Claude Code -- one shell command per server:

claude mcp add terraphim    /Users/alex/.cargo/bin/terraphim_mcp_server
claude mcp add terraphim-pa /Users/alex/bin/terraphim_mcp_server-pa
claude mcp list      # both should show as Connected

The model now sees mcp__terraphim__search and mcp__terraphim_pa__search (plus the autocomplete tools) in its tool list.

SessionStart primer (both paths)

Slash commands and MCP tools are useless if the model does not know the roles exist. Extend the SessionStart hook in ~/.claude/settings.json to print a one-screen role index when each session starts:

printf '\n--- Terraphim search via /tsearch [role] <query> ---\n'
printf '  Terraphim Engineer  (Rust/agent KG)\n'
printf '  Personal Assistant  (Obsidian + Fastmail JMAP, use terraphim-agent-pa for email)\n'
printf '  System Operator     (INCOSE/MBSE Logseq KG)\n'
printf '  Context Engineering Author, Rust Engineer, Default\n'

Equivalent hook in opencode. Cost: one screen of context per session. Benefit: the model picks the right role on the first try instead of guessing.

When to pick which path

	CLI (Path A)	MCP (Path B)
New binaries	None	`terraphim_mcp_server` plus wrapper
Cold start	~50-200 ms per call	~10-50 ms per call (long-lived process)
Tools exposed	`search` only	`search` + 4 autocomplete + `build_autocomplete_index` + `update_config_tool`
Works in any host	Yes -- anything that runs a slash command	Only hosts that speak MCP
Token handling	`terraphim-agent-pa` wrapper	`terraphim_mcp_server-pa` wrapper

For the search-across-roles flow, CLI is enough. Add MCP when the model needs autocomplete-as-you-type, when you want it to manage role configuration without leaving the conversation, or when you are using a host where the typed-tool surface matters more than the cold-start cost.

You do not have to choose. Wire both. The slash command above defaults to CLI and falls back to MCP if the binary is missing -- the two paths coexist cleanly because they read the same role config.

Why this is the right shape

Most "AI assistant + knowledge base" integrations end up tightly coupled to a specific host. Vendor X's plugin marketplace, Vendor Y's tool format. Terraphim takes the opposite stance: the role configuration lives in your filesystem, the haystacks live in your filesystem (or your mailbox), the ranker runs in a process you own, and the integration with the AI host is the thinnest possible shim -- a slash command or an MCP server, both of which are commodity surfaces.

Yesterday the Personal Assistant role was a private setup on one laptop. Today it is callable from inside two different AI coding hosts via a one-file slash command. Tomorrow you can add Cursor or Aider with the same two-line wrapper because the integration surface is terraphim-agent search, not vendor-specific-tool-protocol-v3.

The expensive part of context engineering is not the ranker. It is the vocabulary in the knowledge graph and the haystacks the role can reach. The integration layer should not be allowed to compete for that budget. CLI-first keeps it small.

Try it

# Build (or install the published crate when JMAP feature lands on crates.io)
cd ~/projects/terraphim/terraphim-ai
cargo install --path crates/terraphim_agent --features jmap

# Configure roles -- copy the snippets from the how-tos linked below
$EDITOR ~/.config/terraphim/embedded_config.json

# Install the slash command
mkdir -p ~/.claude/commands ~/.config/opencode/command
cp ~/projects/terraphim/terraphim-ai/docs/src/howto/mcp-integration-claude-opencode.md \
   /tmp/tsearch.md  # adapt to your slash command file shape

# Reload roles
terraphim-agent config reload

# Try
terraphim-agent search --role "Terraphim Engineer" --limit 3 "rolegraph"

Step-by-step in the docs: Plug Terraphim Search into Claude Code and opencode.

For the underlying engine, start with Why Graph Embeddings Matter. For the two roles this integration most cleanly exposes, see Personal Assistant and System Operator.

System Operator Demo: A Logseq Knowledge Graph Drives Enterprise MBSE Search

AlexMikhalev — Fri, 17 Apr 2026 18:31:00 +0000

Terraphim's System Operator role is the demo we point people at when they want to see a real Logseq knowledge graph drive search. 1,347 Logseq pages, 52 of them carrying explicit synonyms:: lines, covering Model-Based Systems Engineering vocabulary -- requirements, architecture, verification, validation, life cycle concepts. This post walks the demo end-to-end and shows the piece people miss: the KG is doing real work, not just re-ranking text matches.

What the demo is

The terraphim/system-operator repository on GitHub is a Logseq vault -- flat folder of markdown files under pages/, one page per concept, with Logseq's bullet-tree syntax for structure and Terraphim-format synonyms:: lines for the knowledge-graph layer. Two things make it a useful demo rather than a toy:

Real MBSE vocabulary. The synonyms are not invented; they track the INCOSE Systems Engineering Handbook v.4, the V-Model, and SEMP conventions. When you type RFP, the automaton normalises it to acquisition need because that is what the handbook calls it.
Real scale. 1,347 markdown files is enough to expose cold-start behaviour (~5-10 seconds to index on a laptop) without being so large it obscures the ranking signal.

Run it

There is an automated setup script in the repo. As of today it clones to a durable path under ~/.config/terraphim/system_operator instead of /tmp, so the vault survives a reboot:

./scripts/setup_system_operator.sh

Then either drive the role via the server --

cargo run --bin terraphim_server -- \
  --config terraphim_server/default/system_operator_config.json
curl "http://127.0.0.1:8000/documents/search?q=RFP&role=System%20Operator&limit=5"

-- or via the terraphim-agent CLI after adding the role entry to ~/.config/terraphim/embedded_config.json:

terraphim-agent config reload
terraphim-agent search --role "System Operator" --limit 5 "RFP"

The full config snippet and the embedded_config.json entry are in the README_SYSTEM_OPERATOR.md.

The piece people miss

Search-over-notes tools usually describe ranking in terms of "it uses a knowledge graph". That sentence hides a lot. Is the graph actually consulted at query time? Is it just a post-hoc re-ranker on top of BM25? Does it expand synonyms? On what vocabulary?

Terraphim exposes the answer directly. validate --connectivity prints which words in your query the automaton matched and what canonical terms they normalised to:

$ terraphim-agent validate --role "System Operator" --connectivity \
    "RFP business analysis life cycle model business requirements documentation tree"

Connectivity Check for role 'System Operator':
  Connected: false
  Matched terms: ["acquisition need", "business or mission analysis",
                  "business requirements", "documentation tree",
                  "life cycle concepts"]

Five query fragments, five canonical matches. RFP collapsed to acquisition need (its synonym, from Acquisition need.md in the vault). business analysis collapsed to business or mission analysis (INCOSE terminology). life cycle model collapsed to life cycle concepts. None of this is text matching -- the word RFP does not appear in the canonical page body; it lives in the synonyms:: line.

Once a query is normalised, the ranker walks the graph. A document that mentions acquisition need directly outranks one that mentions it through three synonym hops, and both outrank a document that mentions none of the canonical terms at all. Ranks come back with concrete integer scores -- [13] on a top result, not an opaque 0.87 cosine.

How it compares to the Personal Assistant role

We wrote up the Personal Assistant role yesterday: a private per-user role that indexes a Fastmail mailbox plus an Obsidian vault. Same engine, same ranker, different haystacks. The knowledge graph there is a small kg/ folder inside the user's vault with 14 synonym files covering personal vocabulary (bun with npm/yarn/pnpm synonyms, odilo, invoice, meeting).

The two roles expose the same pattern at two scales:

	System Operator	Personal Assistant
KG size	52 synonym files, 1,300-concept vocabulary	14 synonym files, ~30-concept personal vocabulary
Haystacks	1 (Logseq repo)	2 (Obsidian vault + Fastmail JMAP)
Source	Public GitHub repo	Private user files and mailbox
Audience	Demos, onboarding, public showcase	One user
Lifetime	Frozen per release	Edited daily, rebuilt in 20 ms per edit

Both use terraphim-graph ranking. Both build an Aho-Corasick automaton once at role-load time. Both run in a 4 GB process on a laptop with no cloud round-trip. The only interesting difference is the vocabulary, which is exactly the separation of concerns a knowledge-graph-first design is supposed to deliver.

Why this matters for teams evaluating MBSE tooling

If you are evaluating Terraphim for a systems engineering group, the System Operator role is the honest starting point. It runs on a laptop against a public vault; you can check that every synonym mapping traces back to a concrete page; you can diff the pages/ folder against the INCOSE handbook and argue about terminology. When your team's own vocabulary diverges (every organisation's does), you clone the repo, edit synonyms:: lines, and the graph rebuilds in 20 milliseconds without a retraining step.

The expensive part of enterprise search is not the ranker. It is the vocabulary. A deterministic graph makes the vocabulary an asset you curate, not a black box you tune.

Try it

git clone https://github.com/terraphim/terraphim-ai
cd terraphim-ai
./scripts/setup_system_operator.sh
cargo run --bin terraphim_server -- \
  --config terraphim_server/default/system_operator_config.json

Or cut to the CLI if you already have terraphim-agent installed -- the embedded_config.json snippet is in the README.

For the underlying engine, start with Why Graph Embeddings Matter. For the personal-productivity analogue, see the Personal Assistant role post.

Personal Assistant Role: One Search Across Email and Notes

AlexMikhalev — Fri, 17 Apr 2026 13:31:38 +0000

Most "personal AI" tools split your context across silos: one search box for email, another for notes, a third for your chat history. Terraphim treats every source as a haystack on the same role, so a single query crosses all of them. This post shows how to wire up the two most common personal sources -- email via JMAP and notes in an Obsidian vault -- under a new Personal Assistant role.

Why a unified role matters

The mental tax of personal search is not the typing. It is the deciding. "Did I read that in an email or write it in a note?" Each silo you skip is a context switch with no useful payload. Once Terraphim is the front door for both surfaces, the question collapses to "where is the thing about X" and the role's terraphim-graph ranking serves whichever source actually has the strongest signal.

The Personal Assistant role uses two haystacks under one role:

Obsidian vault indexed by the Ripgrep service. Plain markdown, sub-millisecond local search, no daemon.
Fastmail mailbox indexed by the Jmap service (RFC 8620/8621). One HTTPS round trip per query, server-side full-text against your real mailbox, results returned with jmap:///email/<id> URLs you can paste back into a mail client.

Ranking is the same terraphim-graph scoring as every other Terraphim role: an Aho-Corasick automaton built from the Obsidian vault contributes synonyms specific to your project vocabulary, then both haystacks share the same rank ladder. Notes and email interleave by relevance, not by source.

What you get

A single command: terraphim-agent-pa search "<query>" returns mixed hits ordered by rank.
Determinism. Every match traces back to a concrete edge in your knowledge graph -- no opaque embedding score.
Privacy. The Obsidian vault never leaves disk; the JMAP query goes directly to your mail provider with your token. No Terraphim cloud component sits in the path.
Composition. The role is just a JSON entry in ~/.config/terraphim/embedded_config.json. Add another haystack tomorrow (calendar, contacts, browser history) and the same query sweeps it too.

A 4 GB process on your laptop holds the whole working set; queries return in single-digit milliseconds for the local side and a few hundred for the remote JMAP round trip.

Wiring sketch

The role config is roughly thirty lines of JSON: two haystacks, one knowledge-graph pointer, no LLM. The Fastmail token is not in the config -- it is injected at runtime via op run from 1Password into the JMAP_ACCESS_TOKEN environment variable, so the secret never lands on disk:

exec op run --account my.1password.com \
  --env-file=<(echo 'JMAP_ACCESS_TOKEN=op://VAULT/ITEM/credential') \
  -- /Users/alex/.cargo/bin/terraphim-agent "$@"

Wrap that in ~/bin/terraphim-agent-pa, chmod +x, and the JMAP haystack lights up only for queries that ask for it. The other roles keep using the bare terraphim-agent and never pay for the 1Password unlock.

Why graph embeddings make this practical

The reason a unified role works at all -- not just for two haystacks but for any reasonable number -- is that Terraphim's graph-embeddings layer is sub-millisecond and deterministic. There is no per-query embedding API call to amortise across sources, no vector database to keep in sync, no opaque ranker that has to be retrained when you add a new haystack. The matching is byte-level Aho-Corasick traversal of an automaton built once at role-load time. We wrote up the engine in detail at Why Graph Embeddings Matter; this Personal Assistant role is one application of that engine.

Try it

The end-to-end how-to is in the docs: install the prerequisites, add the JSON snippet, write the wrapper, run three verification queries.

Read the how-to: Personal Assistant Role on docs.terraphim.ai

One caveat worth surfacing up front: the published terraphim-agent on crates.io does not yet ship with the JMAP haystack (the haystack_jmap dependency is not published either). For email search you need to build from local source with cargo build --release -p terraphim_agent --features jmap. The how-to walks through the two Cargo.toml edits required.

What is next

Personal Assistant is the smallest useful instance of "Terraphim as the front door for everything I read." Calendar (CalDAV), contacts (CardDAV), browser bookmarks, RSS, and AI session logs are all natural follow-ups -- each is a single haystack entry on the same role. The pattern composes; the cost stays linear in haystacks, not quadratic in cross-source queries.

If you want the underlying engine, start with Why Graph Embeddings Matter. If you want to wire knowledge-graph hooks into your AI coding agent on the same machine, Teaching AI Coding Agents with Knowledge Graph Hooks covers that side of the same engine.

Teaching AI Coding Agents with Knowledge Graph Hooks

AlexMikhalev — Fri, 17 Apr 2026 10:50:07 +0000

How we use Aho-Corasick automata and knowledge graphs to automatically enforce coding standards across AI coding agents like Claude Code, Cursor, and Aider.

New: see Why Graph Embeddings Matter for the underlying engine that makes these hooks possible — sub-millisecond, deterministic, fully explainable.

Anthropic Bought Bun. Claude Still Outputs `npm install`.

On December 3, 2025, Anthropic announced its first-ever acquisition: Bun, the blazing-fast JavaScript runtime. This came alongside Claude Code reaching $1 billion in run-rate revenue just six months after public launch.

As Mike Krieger, Anthropic's Chief Product Officer, put it:

"Bun represents exactly the kind of technical excellence we want to bring into Anthropic... bringing the Bun team into Anthropic means we can build the infrastructure to compound that momentum."

Claude Code ships as a Bun executable to millions of developers. Anthropic now owns the runtime their flagship coding tool depends on.

And yet...

Ask Claude to set up a Node.js project, and what do you get?

npm install express
yarn add lodash
pnpm install --save-dev jest

Yet Anthropic's own models still default to npm, yarn, and pnpm in their outputs. The training data predates the acquisition, and old habits die hard.

So how do you teach your AI coding tools to consistently use Bun, regardless of what the underlying LLM insists on?

The Problem: LLMs Don't Know Your Preferences

AI coding agents are powerful, but they're trained on the internet's collective habits—which means npm everywhere. Your team might have standardized on Bun for its speed (25% monthly growth, 7.2 million downloads in October 2025), but every AI agent keeps suggesting the old ways.

Manually fixing these inconsistencies is tedious. What if your knowledge graph could automatically intercept and transform AI outputs?

The Solution: Knowledge Graph Hooks

Terraphim provides a hook system that intercepts AI agent actions and applies knowledge graph-based transformations. The system uses:

Aho-Corasick automata for efficient multi-pattern matching
LeftmostLongest strategy ensuring specific patterns match before general ones
Markdown-based knowledge graph files that are human-readable and version-controlled

How It Works

Input Text → Aho-Corasick Automata → Pattern Match → Knowledge Graph Lookup → Transformed Output

The knowledge graph is built from simple markdown files:

# bun install

Fast package installation with Bun.

synonyms:: pnpm install, npm install, yarn install

When the automata encounter any synonym, they replace it with the canonical term (the heading).

Real-World Example: npm → bun

Let's prove it works. Here's a live test:

$ echo "npm install" | terraphim-agent replace
bun install

$ echo "yarn install lodash" | terraphim-agent replace
bun install lodash

$ echo "pnpm install --save-dev jest" | terraphim-agent replace
bun install --save-dev jest

The LeftmostLongest matching ensures npm install matches the more specific pattern before standalone npm could match.

Hook Integration Points

Terraphim hooks integrate at multiple points in the development workflow:

1. Claude Code PreToolUse Hooks

Intercept Bash commands before execution:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "terraphim-agent replace"
      }]
    }]
  }
}

When Claude Code tries to run npm install express, the hook transforms it to bun install express before execution.

2. Git prepare-commit-msg Hooks

Enforce attribution standards in commits:

#!/bin/bash
COMMIT_MSG_FILE=$1
ORIGINAL=$(cat "$COMMIT_MSG_FILE")
TRANSFORMED=$(echo "$ORIGINAL" | terraphim-agent replace)
echo "$TRANSFORMED" > "$COMMIT_MSG_FILE"

With a knowledge graph entry:

# Terraphim AI

Attribution for AI-assisted development.

synonyms:: Claude Code, Claude, Anthropic Claude

Every commit message mentioning "Claude Code" becomes "Terraphim AI".

3. MCP Tools

The replace_matches MCP tool exposes the same functionality to any MCP-compatible client:

{
  "tool": "replace_matches",
  "arguments": {
    "text": "Run npm install to setup"
  }
}

Architecture

The hook system is built on three crates:

Crate	Purpose
`terraphim_automata`	Aho-Corasick pattern matching, thesaurus building
`terraphim_hooks`	ReplacementService, HookResult, binary discovery
`terraphim_agent`	CLI with `replace` subcommand

Performance

Pattern matching: O(n) where n is input length (not pattern count)
Startup: ~50ms to load knowledge graph and build automata
Memory: Automata are compact finite state machines

Extending the Knowledge Graph

Adding new patterns is simple. Create a markdown file in the mdBook source tree under docs/src/kg/ (published at https://docs.terraphim.ai/src/kg/).

# pytest

Python testing framework.

synonyms:: python -m unittest, unittest, nose

The system automatically rebuilds the automata on startup.

Pattern Priority

The LeftmostLongest strategy means:

npm install matches before npm
python -m pytest matches before python
Longer, more specific patterns always win

Installation

Quick Setup

# Install all hooks
./scripts/install-terraphim-hooks.sh --easy-mode

# Test the replacement
echo "npm install" | ./target/release/terraphim-agent replace

Manual Setup

Build the agent:

cargo build -p terraphim_agent --features repl-full --release

Configure Claude Code hooks in .claude/settings.local.json
Install Git hooks:

cp scripts/hooks/prepare-commit-msg .git/hooks/
chmod +x .git/hooks/prepare-commit-msg

Use Cases

Use Case	Pattern	Replacement
Package manager standardization	npm, yarn, pnpm	bun
AI attribution	Claude Code, Claude	Terraphim AI
Framework migration	React.Component	React functional components
API versioning	/api/v1	/api/v2
Deprecated function replacement	moment()	dayjs()

Claude Code Skills Plugin

For AI agents that support skills, we provide a dedicated plugin:

claude plugin install terraphim-engineering-skills@terraphim-ai

The terraphim-hooks skill teaches agents how to:

Use the replace command correctly
Extend the knowledge graph
Debug hook issues

Conclusion

Knowledge graph hooks provide a powerful, declarative way to enforce coding standards across AI agents. By defining patterns in simple markdown files, you can:

Standardize package managers across your team
Ensure consistent attribution in commits
Migrate deprecated patterns automatically
Keep your knowledge graph version-controlled and human-readable

The Aho-Corasick automata ensure efficient matching regardless of pattern count, making this approach scale to large knowledge graphs.

Next Steps

To wire knowledge-graph hooks into your own project, the Command Rewriting How-to walks through the configuration end to end. To understand why the matching is sub-millisecond and deterministic — and what that lets you promise to your users — read Why Graph Embeddings Matter.

Resources

Why Graph Embeddings Matter

AlexMikhalev — Fri, 17 Apr 2026 10:49:56 +0000

Vector databases are probabilistic and slow. Graph embeddings are deterministic and sub-millisecond. If you are building context for an AI coding agent — or any system where you need to know why a result came back — the difference is not academic. It changes what your application is allowed to promise.

The Pitch in One Paragraph

Terraphim represents concepts as nodes in a knowledge graph and ranks them by how many synonyms and edges connect them. There is no embedding model, no GPU, no per-query distance computation in a 1024-dimensional space. There is an Aho-Corasick automaton built once, queried in O(n+m+z) time over the input length plus the number of matches. The mechanism is described in detail on the Graph Embeddings reference page; this post is about why it matters.

The Numbers

Three numbers carry the argument. Each is reproducible on a laptop.

1.4 million patterns matched in under one millisecond, with under 4 GB of RAM. That is the working set behind a multi-role knowledge graph — operator, engineer, analyst — held resident in the same process that serves the query.
5–10 nanoseconds per knowledge-graph inference step. Not microseconds. Nanoseconds. Once the automaton is built, traversal is a tight loop over byte slices and graph edges, and modern CPUs are extremely good at that.
20 milliseconds to rebuild the embeddings for a role from scratch. Rename a synonym, add a new term, drop an obsolete one — the whole role's graph is reconstituted before your editor has rendered the next frame.

For comparison, a typical vector-DB nearest-neighbour query lands in the 5–50 ms range after you have paid the embedding API call (50–500 ms) and the network round-trip. We are not in the same regime.

Three Consequences

The numbers are interesting on their own. The reason they matter is what they let you build.

1. Full Explainability

Every match in Terraphim traces back to a specific edge in the knowledge graph and a specific synonym in a specific role. There is no "the model said so." When a search returns a document, you can show the user exactly which terms matched, which role's graph supplied the synonym, and which edges connected them. That is not a debugging nicety — it is a regulatory requirement in any domain where you have to defend a decision after the fact. Healthcare, legal, finance, government. Vector search by construction cannot do this.

2. No Training, No Retraining, No Fine-Tuning

Adding a new concept is a text edit. You write the synonym down, you point Terraphim at the file, the graph rebuilds in 20 ms. There is no training run, no GPU bill, no "we need to schedule a retrain on the new corpus." This collapses the loop between noticing a gap and fixing the gap from days or weeks to seconds. For an AI coding agent that needs to learn a project's vocabulary as you onboard, this is the difference between a working tool and a stalled rollout.

3. Language-Agnostic Without Language Detection

Because matching is done on normalised terms — synonyms you supply explicitly — the same node in the graph can carry English, French, Russian, and Mandarin labels at no extra cost. There is no language-detection step, no per-language embedding model, no separate index. The query "consensus" and the query "консенсус" both reach the same node if you have told the graph they are synonyms. Stop-word lists become irrelevant: if a word is not in the graph, it does not match, full stop.

What This Lets You Do

The pieces above are infrastructure. The story arc continues:

Build hooks that transform AI coding agent output deterministically. When Claude Code suggests npm install, intercept it via a graph-embeddings match and replace it with bun install. We wrote this up at Teaching AI Coding Agents with Knowledge Graph Hooks — that post is the demo of what this engine enables.
Capture and reuse mistakes. When an agent gets corrected, store the correction as a new synonym and the next session never repeats it. See Teaching AI Agents to Learn from Their Mistakes and Learning via Negativa.
Run the whole thing in a 4 GB process on your laptop with no network calls. The compactness is not an accident — it is the engineering brief from the Origin Story, which explains where the design came from and why it has stayed this small.

How to Apply

If you want to wire this into your own project, the Command Rewriting How-to walks through the moving parts: where to put your synonyms, how the role graph is built, how hooks call the matcher.

The mechanism — automata, ranking formula, ASCII walk-through — is on the Graph Embeddings reference page. Read that next if you want the data structures.

Why Bother Saying This Out Loud

The current default in the AI tooling ecosystem is to reach for a vector database the moment anyone mentions "semantic search." It is the path of least resistance because the tools are well-marketed and the API surface is familiar. But for a large class of problems — explainability-first systems, on-device agents, anywhere you need a hard latency budget or a hard explainability guarantee — graph embeddings are the better-engineered answer. Not the only answer; the better one for that class.

The promotion campaign over the next few weeks goes deeper: a sub-millisecond context article walks through the FST/Aho-Corasick implementation, and the Context Engineering with Knowledge Graphs book (launching in May) puts it in the wider context of moving from RAG to context graphs.

Until then: read the reference, try the how-to, and let us know in Discourse what you build with it.

DEV Community: AlexMikhalev

Graph Embeddings You Can Watch Being Built

Graph Embeddings You Can Watch Being Built

What the page does

The honest comparison

Try it

Graph Embeddings for Checklists

Graph Embeddings for Checklists

The Checklist Is an Automaton, Not a Promise

Before the LLM Call: Retrieval as Checklist Execution

The honest empty case

Reproduce it

After the LLM Call: The Hook Is a Findings Checklist

When the checklist itself fails

The Loop, Closed

Why This Is Not a Vector Problem

Context Engineering: the book is out

3 Ways to Save Money on Tokens for Your AI Agents

1. Search first, let a cheap model summarise

2. Put expensive reasoning at the edges of the V, not in the middle

3. Put a proxy in front of the providers

What we do not claim

Testing a learning hook from failed command to real execution

Update: what the model requested, and what actually ran

Start with the command that fails

Capture the failure that really happened

Review and promote the correction

Inspect the hook before involving execution

Verify what the coding host actually runs

Reproduce it in a new folder

Keep the scope of the example visible

Testing authored memory across fresh CLI processes

Start with an instruction worth keeping

End the process, then open the memory

Teach the role the words used by the project

Retrieve the instruction, then check the empty cases

What happens inside the CLI

Try the next run yourself

From editor alternatives to synonym-aware search with Terraphim

Start with the sentence

Make the relationship inspectable

Search with the meaning you just recorded

Decide whether you need a generated answer

Open the same example in Obsidian

Open the same example in Logseq

Try the released VS Code extension and the Kilo example

Try the evidence, not just the video

Plug Terraphim Search into Claude Code and opencode (CLI First, MCP When You Need It)

What "integrate" means here

Path A -- CLI via slash command

Why this is the recommended starting point

One file, two hosts

Why fast enough

Three example queries

Path B -- MCP server (when you want typed tools)

Build and install

Register

SessionStart primer (both paths)

When to pick which path

Why this is the right shape

Try it

System Operator Demo: A Logseq Knowledge Graph Drives Enterprise MBSE Search

What the demo is

Run it

The piece people miss

How it compares to the Personal Assistant role

Why this matters for teams evaluating MBSE tooling

Try it

Personal Assistant Role: One Search Across Email and Notes

Why a unified role matters

What you get

Wiring sketch

Why graph embeddings make this practical

Try it

What is next

Teaching AI Coding Agents with Knowledge Graph Hooks

Anthropic Bought Bun. Claude Still Outputs npm install.

The Problem: LLMs Don't Know Your Preferences

The Solution: Knowledge Graph Hooks

How It Works

Anthropic Bought Bun. Claude Still Outputs `npm install`.