![\"Obsidian](\"/demos/obsidian-synonym-search/screenshots/03-synonyms-in-knowledge-note.jpg\")
Stay up-to-date with the latest Terraphim AI releases.
\nReleased: 15 October 2026
\nGitHub Releases | Release Notes
\nIf you already have a Terraphim client installed, update it with a single command — no GitHub credentials, no rate limiting:
\nterraphim-agent update\nterraphim-grep update\nThe self-update backend is served from our R2 bucket (downloads.terraphim.ai) with Ed25519 signature verification. GitHub Releases is an automatic fallback if R2 is unreachable.
curl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash\nBinaries are distributed via Cloudflare R2 with zero-egress CDN. Browse the manifests:
\n\nThe stable-v2.json manifests carry the version, release date and a SHA-256\ndigest plus size for every published archive. The older stable.json pointers\nare still served for pre-1.21.15 clients.
Download the latest archive for your platform directly:
\ncurl -fsSLO "https://downloads.terraphim.ai/terraphim-agent/terraphim-agent-1.21.22-x86_64-unknown-linux-gnu.tar.gz"\ntar -xzf terraphim-agent-1.21.22-*.tar.gz\nsudo mv terraphim-agent /usr/local/bin/\nv1.21.22 ships across three client tools:
\nterraphim-agent — full CLI + REPL + TUIterraphim-grep — intelligent hybrid search with RLM fallbackterraphim-cli — lightweight command-line toolkitPlatforms:
\n| Platform | Agent | Grep | CLI |
|---|---|---|---|
| Linux x86_64 (GNU) | ✓ | ✓ | ✓ |
| Linux x86_64 (MUSL) | ✓ | ✓ | ✓ |
| Linux ARM64 (MUSL) | ✓ | ✓ | ✓ |
| macOS Apple Silicon | ✓ | ✓ | ✓ |
| macOS Intel | ✓ | ✓ | ✓ |
| macOS Universal | ✓ | ✓ | — |
| Windows x64 | — | — | — |
Native Windows archives are unavailable on the current stable channel. Use WSL\nor build from source.
\nAll Linux and macOS archives are Ed25519-signed and verified on install by the self-updater. macOS universal binaries are additionally notarised by Apple.
\nPublic install path corrected
\nVersion reporting and exit codes
\nRelease integrity
\nstable-v2.json manifests publish a SHA-256 digest and byte size for every archive.tar.gz# Already have terraphim-agent? Update in-place.\nterraphim-agent update\nterraphim-grep update\ncurl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash\ncargo install terraphim_agent --features repl-full\nbrew tap terraphim/terraphim && brew install terraphim-agent\nView complete release history on GitHub Releases (terraphim-clients).
\nStable releases are recommended for production use. They are thoroughly tested and signed. The self-updater fetches signed archives from downloads.terraphim.ai by default.
Latest Stable: v1.21.22
\nDevelopment releases contain the latest features and improvements. Use these for testing.
\nCheck the main branch for development builds.
\n# Self-update (recommended, no GitHub token needed)\nterraphim-agent update\n\n# Or via the universal installer\ncurl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash\nTerraphim maintains backward compatibility for configuration files across minor versions. Major version bumps may require configuration updates.
\nterraphim-agent --version\nterraphim-agent check-update\nWant to test new features before they're released?
\nJoin our Discord server and look for #beta-testing channel. Beta testers get early access to new features and help shape the product.
\nIf you encounter issues with a release:
\nReleased: 14 June 2026
\nThe final release distributed exclusively through GitHub Releases before the R2 migration. v1.20.5 binaries remain available on GitHub and will continue to be served as the GitHub fallback. From v1.21.9 onward, all releases are published to both GitHub and R2.
\n", "https://terraphim.ai/properties/date" : "2026-07-08", "https://terraphim.ai/properties/tags" : {}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/how-tos/synonym-search/", "https://atomicdata.dev/properties/name" : "Different words. The same idea.", "https://terraphim.ai/properties/url" : "https://terraphim.ai/how-tos/synonym-search/", "https://atomicdata.dev/properties/description" : "Your project brief says risk. Later, you search for concern. Terraphim connects the two so a change of wording does not hide the decisions you need.
\nThe inspiration came from Jason Fried’s original Write_On video and its idea of “alternative control”. It prompted Alex Mikhalev to return to Terraphim Editor, a Rust/WebAssembly project he had abandoned two years earlier, with a clear purpose: connect wording alternatives to a reusable knowledge graph and carry that meaning into search.
\n\nTry Terraphim Editor · Install for VS Code · Read the narration
\nIn our community garden brief, timber might arrive late. The team has decided to keep a backup supplier. Add Concern as an alternative to Risk, then swap between them. The other wording stays attached to the document.
\nOpen Knowledge graph from the Markdown export menu. The editor shows Risk ↔ Concern and its actual definition:
\nsynonyms:: Risk, Concern\nDownload the graph and the clean text. This explicitly shares the document's authored synonym groups as a Terraphim thesaurus; it does not silently change your active role. The saved example contains Risk, with no literal occurrence of Concern.
\nUse the graph downloaded from that editing session:
\nterraphim-grep concern --thesaurus knowledge-graph.json --paths corpus -C 2 --search-only --json\nThe actual result contains three risk passages and their related decisions, with file and line locations. No generated answer is requested.
\nReplace --search-only with --answer for synthesis:
terraphim-grep concern --thesaurus knowledge-graph.json --paths corpus -C 2 --json --answer\nThe video shows the generated summary and its references to the same three passages. Decisions remain decisions: the source does not establish whether they have been carried out. Check the evidence alongside any generated answer.
\nEditing and local search use your local data. Optional synthesis sends the retrieved passages to your configured model provider.
\nThis supplier brief says Risk. Search for Concern using its exported graph, and both retrieval and synthesis find the same three passages. The generated answer points back to the brief's decisions and actions.
\n\nA 44-second replay of saved tool results in Kilo, with captions and no audio. It shows the saved Risk/Concern alternative, source lines and cited summary. The Kilo skills are under marketplace review; this is a configured integration.
\nDownload the brief, graph and actual results · Kilo setup guide · Recorded versions and checksums
\nKeep the words that describe a concept in the note that owns it. In this example, Risk.md contains the actual synonyms:: Risk, Concern property and embeds the community garden brief. The separate brief still says risk, never concern. The search-results note contains saved passages, with no synonym definition.
Download the Obsidian demo vault ZIP. Extract it, open the included obsidian-demo/vault folder as an Obsidian vault, and open Notes/Risk.md. Open Search results/Concern search.md alongside it to inspect the saved output. No community plugins are required.
To reproduce the retrieval, install terraphim-grep v1.21.19, open a terminal in the extracted vault directory, and run:
terraphim-grep concern --thesaurus "Knowledge graph/baseline-role.json" --paths "Notes/Projects" -C 2 --json --search-only\nterraphim-grep concern --thesaurus "Knowledge graph/knowledge-graph.json" --paths "Notes/Projects" -C 2 --json --search-only\nThe released binary returned zero passages with the baseline graph and three exact risk-and-decision passages with the exported graph, at lines 7, 10 and 13. The commands search only the project brief directory, excluding the concept definition and saved results. Inspect the baseline output, synonym output, execution receipt and file checksums.
\nTerraphim’s synonyms:: convention uses Logseq-compatible Markdown property syntax. Obsidian’s native aliases use YAML aliases. This example supplies the same graph exported by the editor explicitly: saving a note does not automatically rebuild the graph or synchronise the vault. Search runs in the CLI; Obsidian displays the notes and saved results. The capture reruns local retrieval only; the video above shows the separate synthesis comparison.
Prefer linked blocks? Open the same garden project in Logseq. The Risk concept page owns the wording relationship and embeds the project brief. Its properties are:
\nalias:: Concern\nsynonyms:: Risk, Concern\nalias:: gives the page another name inside Logseq. Terraphim’s synonyms:: property records the words connected by the exported search graph.
![\"Logseq](\"/demos/logseq-synonym-search/screenshots/logseq-synonyms-and-results.jpg\")
![\"The](\"/demos/logseq-synonym-search/screenshots/logseq-graph-view.jpg\")
graph folder. If you use a Logseq version with file graphs, open that folder directly.From a terminal in the extracted graph folder, run:
terraphim-grep concern --thesaurus baseline-role.json --paths pages/Projects -C 2 --json --search-only\nterraphim-grep concern --thesaurus knowledge-graph.json --paths pages/Projects -C 2 --json --search-only\nThe first search returns zero passages. The shared synonym graph brings back three decisions: keep a backup supplier, reserve a covered area and keep a volunteer reserve list. The commands search only the project notes, leaving concept definitions and saved results outside the search.
\nCompare the baseline and synonym search output, or follow the download instructions. The CLI reads the included Markdown files; Logseq 2.0 imports a copy into its database. Use the extracted folder for these commands. File checksums are included.
\n--answer when you want a summary alongside the source passages.Searching for concern returns no passages before the graph is shared. With the graph, it finds all three risk passages and their related decisions. Compare the saved results before sharing, with the synonym graph, and with a generated summary.
\nThen try the same steps with a pair of words from your own project notes.
\nThe video uses a sample project brief and synthetic British English narration. The graph and search results are saved outputs from the demonstrated workflow. Recording details and versions, commands and file checksums are available with the downloads.
\nExplore more editor walkthroughs.
\n", "https://terraphim.ai/properties/date" : "2026-10-11", "https://terraphim.ai/properties/tags" : {"tags":["editor","knowledge-graph","search"],"categories":["How-tos"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/how-tos/command-rewriting-howto/", "https://atomicdata.dev/properties/name" : "A failed command, a saved correction, and the next run", "https://terraphim.ai/properties/url" : "https://terraphim.ai/how-tos/command-rewriting-howto/", "https://atomicdata.dev/properties/description" : "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.
\nThis walkthrough follows one harmless error from failure to saved correction to actual execution. Each execution now has one record linking the model’s request, the matching rewrite rule, the command the tool ran and its saved result. It uses the Harbour project brief from the memory walkthrough, a released Terraphim agent, and an OpenCode adapter included in the download.
\n\nDownload the Harbour hooks example · Read the transcript
\nHarbour'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\nThe 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.
\nThe 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.
\nThe 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.
\nThe 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.
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. Here, “review” means checking the intended correction; it is not a built-in approval gate. The reproduction script runs this command inside its isolated store:
\nterraphim-agent learn correction add \\\n --correction-type tool-preference \\\n --original 'python3 validate-brief.py --chek' \\\n --corrected 'python3 validate-brief.py --check' \\\n --context 'Manually reviewed correction from the captured failure'\nterraphim-agent learn compile --output compiled-corrections.json\nterraphim-agent learn export-kg --output kg\nCompilation now reports one correction. The selected Harbour Validator role loads that compiled JSON. The exported Markdown makes the relationship readable:
\n# python3 validate-brief.py --check\nsynonyms:: python3 validate-brief.py --chek\nThis 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.
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:
{\n "tool_input": {"command": "python3 validate-brief.py --check"},\n "tool_name": "Bash"\n}\nThat 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.
\n![\"The](\"/demos/hooks-execution-evidence/poster.png\")
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.
\nThe after-tool event records python3 validate-brief.py --check. Its exit status is 0. The validator prints a valid Harbour result and writes evidence/executions/<execution_id>/validation.json:
{\n "execution_id": "19578f09-a59a-4e80-be31-7d319b0c9368",\n "project": "Harbour",\n "status": "valid",\n "fields": ["Decision", "Risk", "Owner"]\n}\nThe host transcript can still display the model's original requested input. The hook changes the command; OpenCode executes it. Inspect the actual after-tool event to establish what ran.
\nThe included adapter records an execution ID alongside the host’s session and tool-call IDs. Its receipt.json links:
The validator embeds the same execution ID in its printed result and saved file. The verifier checks those values against the native host events and rehashes the graph and output. A stale file, mismatched command, unmatched host call, missing artifact or altered bytes fails verification. A blocked call is retained without being labelled executed.
\nInspect the execution receipt, saved result and run verification.
\n![\"The](\"/demos/hooks-execution-evidence/rule-and-command.png\")
This recorder covers the example’s sequential, whole-command mapping. It rejects overlapping fixture calls and unsupported rule attribution; it is not a general multi-rule provenance system.
\n![\"The](\"/demos/hooks-execution-evidence/saved-result.png\")
The example was verified with terraphim-agent v1.21.19 and OpenCode 2.0.20. The download includes the new adapter source, version 2.0.0; it is separate from the earlier binary release. Follow the ZIP's README to check the release archive, choose your already authenticated coding model and run from the extracted folder:
\npython3 reproduction/reproduce.py \\\n --agent /absolute/path/to/terraphim-agent \\\n --model kimi-code-plan-global/k3 \\\n --output /absolute/path/to/a-new-harbour-run\nUse 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.
\nRun node reproduction/verify.mjs /absolute/path/to/a-new-harbour-run to check the saved evidence. Read evidence/verification.json, the host events and each execution’s receipt.json and validation.json. The ZIP also includes 22 regression tests, runnable with node --test tests/*.test.mjs. 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.
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.
\nUse 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.
\nDownload 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.
\nEarlier 75-second walkthrough · Original example.
\nUpdated 13 October 2026. The new video is 66 seconds. 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.
\n", "https://terraphim.ai/properties/date" : "2026-04-15", "https://terraphim.ai/properties/tags" : {"categories":["Tutorials"],"tags":["Terraphim","hooks","OpenCode","knowledge-graph","developer-tools"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/how-tos/knowledge-work-editor/", "https://atomicdata.dev/properties/name" : "Write and search with the same knowledge graph", "https://terraphim.ai/properties/url" : "https://terraphim.ai/how-tos/knowledge-work-editor/", "https://atomicdata.dev/properties/description" : "Watch the new 80-second story: create a synonym, share it, then search
\nThese earlier host recordings remain available as versioned evidence. The new story above follows the current alternative-to-search flow.
\n\nKeep alternatives attached to words, sentences and paragraphs. Ghost a passage without losing it, stash notes in Overflow, and use the Lab to inspect possible cuts. The editor runs as WebAssembly in your browser with a bundled local knowledge graph.
\nFollow a public project brief from editing to search using the same knowledge graph. The 77-second captioned overview shows the browser editor, explicitly hands off to the clean file exported from Safari, then compares real terraphim-grep executions with and without --answer.
--answer — 21sThe browser recordings produced identical saved annotated files. A separately checked Safari clean-export file supplies the grep corpus; the Safari walkthrough does not show that export gesture. Newly authored Assessment registers as a document-scoped synonym; it does not update the shared KG used by the CLI. Zed demonstrates existing extension capabilities; the Zed fork is separate. The brief's Trim preview produced zero cuts, so this recording does not demonstrate text reduction. The generated synthesis overstates a review policy as observed practice; compare that statement with the returned evidence rather than treating it as verified fact.
\nAll six videos now have explanatory on-screen captions. Idle intervals are cut, actions are accelerated by 1.5–3× where disclosed, and the long terminal end hold is removed. Captions sit outside the application image. Safari setup is cut and the Zed avatar remains masked. Chronological source ranges and speed changes are recorded in the manifest; original captures are retained. These are finite walkthroughs, not complete acceptance of all 41 requirements. Build identities, media hashes and edit disclosures identify the recorded candidate. The current editor preview includes the Unicode normalization repair: canonically equivalent accents, Terraphim Unicode lowercase and Greek sigma equivalence protect exact original spellings during Trim. The videos retain their earlier recorded build identity; they do not demonstrate this later repair.
\nThis is a preview. The complete source-video requirements are still being qualified; Safari dragging and some visual/native cases remain unresolved. Keyboard pull from Overflow is available. The browser demo does not imply full custom visual parity in the stock Zed extension.
\nPaste this supplied example into the editor. It is sample input, not generated output:
\n# Public research workspace\n\nDecision: launch a local-first research workspace for the delivery team.\n\nThe decision owner will review the brief before the pilot begins.\n\nRisk: inconsistent terminology makes prior decisions hard to locate.\n\nUse the project brief to align the team and keep the decision record clear.\nTurn on Write_On using the word counter. Explore alternatives for “decision”, add your own wording, and compare it in context. Ghost/revive a passage, stash a note in Overflow and inspect the Lab. Save the result and reopen the actual file to check the choices and annotations.
\nSave keeps the Markdown, alternatives, ghosts and Overflow together. Clean Markdown export includes active text and omits ghosts, Overflow and the annotation block. Chrome can offer a file handle; Firefox and Safari use a download. Check the actual browser dialog and downloaded file.
\nDownload the same bundled KG and inspect the editor build identity. Newly authored alternatives register as document-scoped synonyms; they do not silently change this shared KG.
\nMove the chosen saved or clean-exported file into a dedicated local corpus folder. Keep evidence logs and other copies outside that folder. With terraphim-grep installed, set paths for that public corpus and downloaded KG:
terraphim-grep "decision" --thesaurus ./default.json --paths ./public-corpus --json\nterraphim-grep "decision" --thesaurus ./default.json --paths ./public-corpus --json --answer\nThe first command returns search evidence without enabling synthesis. The second asks for an answer when sufficient evidence and a configured provider are available. Keep the query, corpus and KG unchanged to compare them. Add the same --role-config path to both commands if configuring a provider through a role. Check the generated answer against the returned source lines; a missing answer or provider error is not a successful synthesis.
Writing and local search do not require sending your document to an LLM. Synthesis may send retrieved content to the configured provider. Use public sample content for the demo and inspect the provider configuration before enabling --answer.
Most pages about embeddings show you a picture of some dots and ask you to trust the maths.\nThis one is different: the Terraphim side of every demo below runs the real algorithm —\nthe actual terraphim_rolegraph Rust crate, compiled to WebAssembly and executing in your\nbrowser — on a real thesaurus and corpus. Nothing is staged or ported: the counters you watch\nincrement are the same code paths the Rust tests exercise.
The same eight documents, two retrieval systems. On the left, the classic picture: every\ndocument is a point in a high-dimensional space; a query lands as another point; similarity\nis distance. On the right, the Terraphim graph: every concept is a node; documents feed\nco-occurrence counters; a query lights up a path.
\nRun a query — including byzantine fault tolerance, which is deliberately absent from the\nthesaurus — and watch what each side does with it.
Every dot is a document. The ring is a cosine-similarity radius.\n You get a score — 0.98, 0.87, 0.76 — and nothing else. There is no answer to\n why this document matched.
\nNodes are concepts; numbers inside are node.rank —\n co-occurrence counts. Lit nodes and edges are the ones the query actually traversed.
Before anything is a graph, there is a dictionary. The role's thesaurus maps synonyms to\nnormalised concepts — leader election and election are the same node, id 3. At startup the\nthesaurus compiles into an Aho-Corasick automaton: a finite-state machine that scans text in a\nsingle pass, regardless of how many patterns it holds.
Watch it read. The matcher runs leftmost-longest, case-insensitive: at each position it\ntakes the longest pattern that fits, then jumps past it. Type anything — the highlights and the\nconcept sequence update live.
\nTry a consensus algorithm vs\n a consensus: consensus algorithm wins as one match,\n not two. That is LeftmostLongest. Overlapping terms collapse into a single concept id —\n and that ordered sequence of ids is all the indexer sees.
Here is the whole trick, and it is smaller than you expect. When a document is indexed:
\ntitle + body — Document::to_string() — which is why \"Raft notes\"\nadds a raft → raft self-loop: the title itself matches.)(a, b) becomes a directed edge magic_pair(a, b) — an integer\nkey computed by a Cantor-style pairing function, so (raft → consensus) and\n(consensus → raft) are different edges.node.rank += 1 for both endpoints; edge.doc_hash[doc] += 1 counts how often that pair\nappeared in that document.That is the embedding. What a concept \"is\" here: a node plus its edges in conceptual\nspace — the synonyms that map to it and the concepts that appear next to it — not a point\nin a vector space. Press \"Index next\" a few times and watch the graph accrete; then index\nyour own sentence (only thesaurus terms count).
\nEdge thickness ∝ total document count on that pair. Loops are real:\n partition tolerance → partition tolerance and leader → leader appear\n when the same concept is matched twice in a row. Re-indexing removes a document's\n contributions before re-counting — replace semantics. Honest caveat: removal decrements\n node rank once per edge, while insertion counts once per pair occurrence,\n so a document that repeats the same directed pair leaves a small rank residual on re-index.\n That is the Rust implementation's real behaviour, running live — not smoothed over.
Querying is the mirror image. The automaton matches the query terms to node ids; for each\nmatched node, the engine walks its edges; for every document on each edge it adds:
\nscore += node.rank + edge.rank + doc_hash[doc]\n
Documents are sorted by the sum. And because every point of the sum comes from a named node,\na named edge and a count you can inspect, the ranking is auditable — click a query and read\nthe ledger. This is the part a cosine score cannot give you.
\nThe deepest difference is not the data structure — it is where computation lives.
\nTraditional graph embeddings — DeepWalk, node2vec, GraphSAGE, TransE, Cleora — front-load\neverything: random walks or message passing produce dense vectors once, then queries are cheap\nANN lookups. Adding a term means re-walking and re-training. Terraphim inverts this: all the\nwork is tiny counters at index time; a query is a lookup and a sum.
\nAdd a synonym right now. The Terraphim column measures the real rebuild time in your browser.
\nTimings on the Terraphim column are measured live in this page; the other\n columns are indicative ranges consistent with published measurements, shown for comparison.
\n| Aspect | Learned graph embeddings (node2vec, GCN, TransE, Cleora) | Dense text embeddings (API + vector DB) | Terraphim graph embeddings |
|---|---|---|---|
| What a concept \"is\" | A point in ℝᵈ learned from walks/adjacency | A point in ℝᵈ learned from text | A node + its edges + integer counters |
| Training | Walks + SGD / iterative propagation | Pre-trained model; per-doc embed call | None — counters at index time |
| Query mechanism | Vector → ANN cosine | Vector → ANN cosine | AC match → traverse → integer sum |
| Multi-hop semantics | Yes — walks/message passing | Indirect | Neighbourhood only (1 hop) |
| Unseen vocabulary | Degrades silently | Generalises (that's the point) | Returns nothing — honestly |
| Update cost | Re-embed affected subgraph | Re-embed document | Edit thesaurus, ~ms rebuild |
| Explainability | Vector distance only | Vector distance only | Every contribution named and countable |
| Memory / hardware | Float32 × nodes × dims | ANN index + API | ints; 15–20 MB typical; runs on a Pi |
| Determinism | Seed-dependent | Model/version dependent | Same input → same output, always |
byzantine fault tolerance query above returns an empty set while the vector panel cheerfully\nreturns neighbours. Domain coverage is an authoring problem, not a learning problem.node.rank counts co-occurrences, not importance. Popular concepts\ndominate. Hybrid search already exists to soften this:\nquery_graph_with_trigger_fallback falls back to a TriggerIndex (TF-IDF over trigger\ndescriptions) inside the rolegraph itself — exposed in the editor bridge as the\nfallback query mode — and search_sessions_hybrid in terraphim_sessions fuses BM25\nscores with knowledge-graph boosts.Every label above maps to a real symbol:
\nRoleGraph::new_sync → builds the automaton (MatchKind::LeftmostLongest, case-insensitive)insert_document → find_matching_node_ids → tuple_windows → add_or_update_documentmagic_pair / magic_unpair → directed edge idsquery_graph → the node.rank + edge.rank + doc_hash sum and sort you watchedremove_document_contributions → the replace semantics that made re-indexing idempotentOne honest detail the prose docs gloss over: edge.rank is currently always 1 — the real\nper-document count lives in edge.doc_hash, which is why the ledger above shows the\ndocument count rather than an edge rank. This page shows the code, not the approximation.
The reference text lives at Graph Embeddings; the short version of\nwhy it matters is in Why Graph Embeddings Matter.
\n", "https://terraphim.ai/properties/date" : "2026-10-20", "https://terraphim.ai/properties/tags" : {"categories":["Documentation"],"tags":["graph-embeddings","knowledge-graph","aho-corasick","interactive","explainer"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/docs/crates/", "https://atomicdata.dev/properties/name" : "Crate Reference", "https://terraphim.ai/properties/url" : "https://terraphim.ai/docs/crates/", "https://atomicdata.dev/properties/description" : "Terraphim AI is a modular Rust workspace comprising 54 crates. Each crate has a single responsibility and can be used independently or composed into larger systems. All crates are available in the terraphim-ai monorepo.
\nThe foundational crates that power Terraphim's deterministic knowledge graph search.
\n| Crate | Description |
|---|---|
| terraphim_automata | Aho-Corasick automata for searching and processing knowledge graphs. The core matching engine. |
| terraphim_rolegraph | Role-based knowledge graph module. Maps search roles to domain-specific graph views. |
| terraphim_types | Core types crate shared across the entire workspace. |
| terraphim_config | Configuration loading and management for all Terraphim components. |
| terraphim_settings | Settings handling library for runtime preferences and defaults. |
| terraphim_service | Service layer handling user requests and responses for the Terraphim core. |
| terraphim_middleware | Middleware for searching haystacks (pluggable data source backends). |
| terraphim-markdown-parser | Markdown parser for extracting structured content from knowledge base files. |
| terraphim_persistence | Persistence layer with Persistable trait and DeviceStorage backends (memory, SQLite, redb). |
| terraphim_build_args | Build argument management for compile-time feature configuration. |
| terraphim_test_utils | Shared test utilities and fixtures for all Terraphim crates. |
User-facing executables and command-line tools.
\n| Crate | Description |
|---|---|
| terraphim_agent | Terraphim AI Agent CLI with interactive REPL, session search, learning capture, and ASCII graph visualisation. |
| terraphim-cli | CLI tool for semantic knowledge graph search with JSON output for automation and scripting. |
| terraphim_server | HTTP server handling the core logic of Terraphim AI. Provides REST API and knowledge graph backend. |
| terraphim_update | Shared auto-update functionality for all Terraphim AI binaries. |
| terraphim_validation | Release validation system ensuring binary and asset integrity before publishing. |
OTP-inspired agent management system for running autonomous AI coding agents.
\n| Crate | Description |
|---|---|
| terraphim_orchestrator | AI Dark Factory orchestrator wiring spawner, router, and supervisor into a reconciliation loop. |
| terraphim_spawner | Agent spawner with health checking, output capture, and lifecycle management. |
| terraphim_router | Unified routing engine for LLM and agent providers (keyword routing, tier selection). |
| terraphim_agent_supervisor | OTP-inspired supervision trees for fault-tolerant AI agent management. |
| terraphim_agent_application | OTP-style application behaviour for the Terraphim agent system. |
| terraphim_agent_messaging | Erlang-style asynchronous message passing system for AI agents. |
| terraphim_agent_registry | Knowledge graph-based agent registry for intelligent agent discovery and capability matching. |
| terraphim_agent_evolution | Agent evolution and self-improvement tracking. |
| terraphim_workspace | Workspace management for agent execution including lifecycle, hooks, and isolation. |
| terraphim_multi_agent | Multi-agent system built on roles with rust-genai integration. |
Advanced crates for KG-powered reasoning, task planning, and goal management.
\n| Crate | Description |
|---|---|
| terraphim_kg_orchestration | Knowledge graph-based agent orchestration engine for coordinating multi-agent workflows. |
| terraphim_kg_agents | Specialised knowledge graph-based agent implementations. |
| terraphim_kg_linter | Linter for markdown-based Terraphim KG schemas (commands, types, permissions). |
| terraphim_goal_alignment | Knowledge graph-based goal alignment system for multi-level goal management and conflict resolution. |
| terraphim_task_decomposition | Knowledge graph-based task decomposition for intelligent task analysis and execution planning. |
| terraphim_rlm | Recursive Language Model (RLM) orchestration for structured reasoning chains. |
| terraphim_hooks | Unified hooks infrastructure for knowledge graph-based text replacement and validation. |
| terraphim_file_search | Knowledge-graph scored file search integration. |
| terraphim_codebase_eval | Codebase evaluation system with manifest types and metrics aggregation. |
| terraphim_negative_contribution | Negative contribution analysis for identifying anti-patterns and risks. |
Pluggable data source connectors for searching external systems.
\n| Crate | Description |
|---|---|
| haystack_core | Core traits and types for all Terraphim haystack integrations. |
| haystack_atlassian | Atlassian (Confluence, Jira) integration for searching enterprise knowledge bases. |
| haystack_discourse | Discourse forum integration for fetching posts and messages. |
| haystack_grepapp | Grep.app integration for searching code across GitHub repositories. |
| haystack_jmap | JMAP email protocol integration for searching email (Fastmail, etc.). |
Tools for analysing AI coding assistant sessions and tracking usage.
\n| Crate | Description |
|---|---|
| terraphim_sessions | Session management for AI coding assistant history. Search across Claude Code, Cursor, and Aider sessions. |
| terraphim-session-analyzer | Analyse AI coding assistant session logs to identify agent usage patterns. |
| terraphim_ccusage | Claude Code usage tracking and cost analysis. |
| terraphim_usage | General usage telemetry and analytics. |
Deployment, CI/CD, and infrastructure management.
\n| Crate | Description |
|---|---|
| terraphim_symphony | Symphony orchestration service. Reads issues from trackers and dispatches coding agent sessions. |
| terraphim_tracker | Issue tracker abstraction for Gitea and Linear with PageRank-based prioritisation. |
| terraphim_github_runner | GitHub Actions runner with Firecracker sandbox integration. |
| terraphim_github_runner_server | HTTP server for the GitHub Actions runner service. |
| terraphim-firecracker | Sub-2-second VM boot optimisation system for sandboxed agent execution. |
| terraphim_mcp_server | Model Context Protocol (MCP) server exposing Terraphim tools to AI assistants. |
| terraphim_onepassword_cli | 1Password CLI integration for secret management. |
| terraphim_atomic_client | Atomic Data Server client for managing stores and agents. |
Multi-channel AI assistant interfaces.
\n| Crate | Description |
|---|---|
| terraphim_tinyclaw | Multi-channel AI assistant for Telegram, Discord, and CLI. |
Cross-language bindings for using Terraphim from Python, Node.js, and WebAssembly.
\n| Crate | Description |
|---|---|
| terraphim_automata_py | Python (PyO3) bindings for terraphim_automata. Fast autocomplete and text processing for knowledge graphs. |
| terraphim_rolegraph_py | Python bindings for terraphim_rolegraph. Knowledge graph operations for AI agents. |
| terraphim-automata-node-rs | Node.js (NAPI) bindings for Terraphim's Aho-Corasick matcher. |
| terraphim-automata-wasm | WebAssembly bindings for terraphim_automata. Runs in the browser. |
| Crate | Description |
|---|---|
| terrraphim-automata-wasm (extension) | WASM core for the Terraphim browser extensions (Sidebar and Autocomplete). |
# Install the agent (interactive REPL + session search)\ncargo install terraphim_agent --features repl-full\n\n# Install the CLI (JSON output for automation)\ncargo install terraphim_cli\nOr use the universal installer:
\ncurl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash\nThe crate dependency graph follows a layered architecture:
\nterraphim_types, terraphim_config, terraphim_settingsterraphim_automata, terraphim_rolegraph, terraphim_persistenceterraphim_service, terraphim_middleware, haystack integrationsterraphim_spawner, terraphim_router, terraphim_agent_supervisorterraphim_orchestrator, terraphim_kg_orchestration, terraphim_symphonyterraphim_agent, terraphim-cli, terraphim_server, terraphim_tinyclawEach crate has its own README.md with specific build instructions and examples. See the Contribution Guide for the overall workflow.
Source: github.com/terraphim/terraphim-ai
\n", "https://terraphim.ai/properties/date" : "2026-04-12", "https://terraphim.ai/properties/tags" : {}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/docs/graph-embeddings/", "https://atomicdata.dev/properties/name" : "Graph Embeddings", "https://terraphim.ai/properties/url" : "https://terraphim.ai/docs/graph-embeddings/", "https://atomicdata.dev/properties/description" : "\n\nTry it live: Graph Embeddings, Explained Interactively runs the actual
\nterraphim_rolegraphRust crate compiled to WebAssembly in your browser — matching, indexing and scoring with no server round-trips.
Terraphim uses a fundamentally different approach to semantic search compared to traditional vector embeddings. Instead of dense numerical vectors, Terraphim leverages graph structure embeddings where ranking is determined by the number of synonyms and related concepts connected to a query term in the knowledge graph.
\nUnlike vector embeddings that represent concepts as points in a high-dimensional semantic space, Terraphim represents concepts as nodes in a knowledge graph. Each node is a normalized term, and edges represent co-occurrence relationships between terms found in documents.
\nThe key insight is that rank is defined by the number of synonyms connected to a concept. When you search for a term, Terraphim expands your query to include all synonyms and related concepts from the knowledge graph, then traverses the graph to find documents that mention these connected concepts.
\n "raft" ----(edge)---- "consensus"\n | |\n (edge) (edge)\n | |\n "leader" ----(edge)---- "election"\nWhen you search for \"consensus algorithms\", the graph traverses from the matched node to connected nodes, finding documents that mention related concepts like \"raft\", \"leader election\", and so on.
\nThe Terraphim Graph (scorer) uses unique graph embeddings with the following ranking algorithm:
\ntotal_rank = node.rank + edge.rank + document_rank\nWhere:
\nWhen you search, Terraphim:
\nThe graph embedding system is implemented in crates/terraphim_rolegraph/src/lib.rs:
For domain-specific embeddings (e.g., medical), the SymbolicEmbeddingIndex in crates/terraphim_rolegraph/src/medical.rs builds embeddings from IS-A hierarchies, allowing for hierarchical concept relationships.
The system is configured via config/atomic_graph_embeddings_config.json:
{\n "roles": {\n "Atomic Graph Embeddings": {\n "relevance_function": "terraphim-graph"\n }\n }\n}\nThe terraphim-graph relevance function enables graph-based ranking.
Graph embeddings excel when content relationships matter more than simple keyword matching:
\nWith a learning knowledge graph:
\n| Feature | Vector Embeddings | Graph Embeddings |
|---|---|---|
| Representation | Dense vectors | Graph structure |
| Explainability | Black box | Full traceability |
| Queries expand | Implicit via distance | Explicit via synonyms |
| Relationship capture | Learns patterns | Encodes relationships |
| Domain adaptation | Requires retraining | Add to thesaurus |
Unlike vector embeddings where you don't know WHY a document matched, Terraphim's graph embeddings show:
\nThis makes results fully auditable and debuggable.
\n# Search with the Engineer role\nterraphim-agent search "graph embeddings" --role engineer\nThis returns results for:
\nuse terraphim_rolegraph::RoleGraph;\nuse terraphim_types::{Thesaurus, RoleName};\n\n// Create rolegraph with domain knowledge\nlet thesaurus = build_domain_thesaurus();\nlet role_name = RoleName::new("Engineer");\nlet mut graph = RoleGraph::new(role_name, thesaurus).await?;\n\n// Index documents\nfor doc in documents {\n graph.insert_document(&doc.id, doc);\n}\n\n// Query - automatically expands to synonyms\nlet results = graph.query_graph("distributed systems", None, Some(10))?;\nEnable graph embeddings in your config:
\n{\n "roles": {\n "Your Role": {\n "relevance_function": "terraphim-graph",\n "kg": {\n "knowledge_graph_local": {\n "path": "./docs/your-domain"\n }\n }\n }\n }\n}\nChoose the installation method that best suits your needs and platform.
\nThe universal installer detects your platform, resolves the current release\nfrom the release channel, verifies the download's SHA-256, and unpacks it into\n~/.local/bin.
curl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash\nOptions:
\n# Also install the CLI and grep tools\ncurl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash --with-cli --with-grep\n\n# Install somewhere else\ncurl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash --install-dir /usr/local/bin\n\n# Require a specific version (fails if the channel serves a different one)\ncurl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash --version 1.21.22\nThe installer publishes these exit codes: 0 success, 1 usage error,\n2 manifest unreachable, 3 requested version unavailable, 4 download\nfailed, 5 checksum mismatch, 6 installation failed.
brew tap terraphim/terraphim && brew install terraphim-agent\nThe tap also carries terraphim-grep. There is no terraphim-ai formula.
# Install agent with interactive REPL and full features\ncargo install terraphim_agent --features repl-full\nArchives are served from downloads.terraphim.ai. Substitute the release you\nwant for 1.21.22, or read the current version from the\nmanifest.
VERSION=1.21.22\n\n# x86_64 (GNU)\ncurl -fsSLO "https://downloads.terraphim.ai/terraphim-agent/terraphim-agent-${VERSION}-x86_64-unknown-linux-gnu.tar.gz"\ntar -xzf "terraphim-agent-${VERSION}-x86_64-unknown-linux-gnu.tar.gz"\nsudo mv terraphim-agent /usr/local/bin/\n\n# x86_64 (MUSL / static)\ncurl -fsSLO "https://downloads.terraphim.ai/terraphim-agent/terraphim-agent-${VERSION}-x86_64-unknown-linux-musl.tar.gz"\n\n# ARM64 (MUSL)\ncurl -fsSLO "https://downloads.terraphim.ai/terraphim-agent/terraphim-agent-${VERSION}-aarch64-unknown-linux-musl.tar.gz"\nVerify the download against the digest in the manifest before installing:
\ncurl -fsSL https://downloads.terraphim.ai/terraphim-agent/stable-v2.json \\\n | python3 -c 'import json,sys; m=json.load(sys.stdin); print(m["version"]); print(m["assets"]["x86_64-unknown-linux-gnu"]["sha256"])'\nsha256sum "terraphim-agent-${VERSION}-x86_64-unknown-linux-gnu.tar.gz"\ngit clone https://github.com/terraphim/terraphim-clients.git\ncd terraphim-clients\n\ncargo build --release -p terraphim_agent --bin terraphim-agent\n\nsudo cp target/release/terraphim-agent /usr/local/bin/\nVERSION=1.21.22\n\n# Apple Silicon (ARM64)\ncurl -fsSLO "https://downloads.terraphim.ai/terraphim-agent/terraphim-agent-${VERSION}-aarch64-apple-darwin.tar.gz"\ntar -xzf "terraphim-agent-${VERSION}-aarch64-apple-darwin.tar.gz"\nsudo mv terraphim-agent /usr/local/bin/\n\n# Intel (x86_64)\ncurl -fsSLO "https://downloads.terraphim.ai/terraphim-agent/terraphim-agent-${VERSION}-x86_64-apple-darwin.tar.gz"\n\n# Universal (runs on both)\ncurl -fsSLO "https://downloads.terraphim.ai/terraphim-agent/terraphim-agent-${VERSION}-universal-apple-darwin.tar.gz"\nmacOS builds are signed and notarised by Apple; the self-updater verifies an\nEd25519 signature over every archive before installing it.
\nRequires Xcode command line tools.
\ngit clone https://github.com/terraphim/terraphim-clients.git\ncd terraphim-clients\ncargo build --release -p terraphim_agent --bin terraphim-agent\nsudo cp target/release/terraphim-agent /usr/local/bin/\nNative Windows archives are unavailable on the current stable channel. Use the Linux instructions inside WSL, or build from source below.
\nRequires Rust for Windows.
\ngit clone https://github.com/terraphim/terraphim-clients.git\ncd terraphim-clients\ncargo build --release -p terraphim_agent --bin terraphim-agent\n# Binary will be in target\\release\\\nThe commands above install the client tools (terraphim-agent,\nterraphim-grep, terraphim-cli). The server and the language bindings have\ntheir own release paths:
The server is built and released from\nterraphim-ai. Build it from\nsource, or use the container images published to the GitHub Container\nRegistry.
\nThe @terraphim/autocomplete package provides NAPI bindings for autocomplete and knowledge graph functions.
npm install @terraphim/autocomplete\nThe terraphim-automata package provides PyO3 bindings for text matching and autocomplete.
pip install terraphim-automata\nTwo browser extensions are available for developer-mode installation:
\nInstall from source:
\ngit clone https://github.com/terraphim/terraphim-ai.git\ncd terraphim-ai/browser_extensions\nThen load unpacked in Chrome at chrome://extensions (enable Developer Mode). Coming to the Chrome Web Store soon.
See browser_extensions/INSTALL.md for detailed instructions.
\nAfter installation, verify that Terraphim is working:
\n# Check version\nterraphim-agent --version\n# terraphim-agent 1.21.22\n\n# Confirm the updater can see the channel\nterraphim-agent check-update\n\n# Start the REPL\nterraphim-agent repl\nIf you get a permission denied error, make the binary executable:
\nchmod +x /usr/local/bin/terraphim-agent\nEnsure that the installation directory is in your PATH. The universal\ninstaller adds ~/.local/bin to your shell profile:
# For bash\necho 'export PATH=$PATH:$HOME/.local/bin' >> ~/.bashrc\nsource ~/.bashrc\n\n# For zsh\necho 'export PATH=$PATH:$HOME/.local/bin' >> ~/.zshrc\nsource ~/.zshrc\nThe installer exits with code 5 if the downloaded archive does not match the\ndigest in the release manifest. Re-run the install; if it fails again, please\nopen an issue rather than using --skip-verify.
Ensure that you have a recent Rust version:
\nrustc --version # Should be 1.85.0 or later\nrustup update stable\nGet up and running with Terraphim AI in just 5 minutes. The agent works offline by default -- no server required.
\nChoose your preferred installation method:
\ncurl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash\nbrew tap terraphim/terraphim && brew install terraphim-agent\ncargo install terraphim_agent --features repl-full\nterraphim-agent repl\nYou will see:
\n============================================================\nTerraphim TUI REPL\n============================================================\nType /help for help, /quit to exit\nMode: Offline Mode | Current Role: AI Engineer\n\nAI Engineer>\nThe REPL runs offline by default. No server or network connection required.
\nSearch your knowledge graph:
\nAI Engineer> /search knowledge graph\nResults are displayed in a ranked table with title and file path.
\nHere are the most useful commands to get started:
\n| Command | Description |
|---|---|
/search \"query\" | Search knowledge graph with role context |
/autocomplete \"query\" | Autocomplete terms from the thesaurus |
/extract \"text\" | Extract matching paragraphs |
/find \"text\" | Find exact matches in indexed documents |
/replace \"text\" | Replace matches using thesaurus mappings |
/thesaurus | Show loaded thesaurus entries |
/graph | Visualise knowledge graph (ASCII) |
/role list | List available roles |
/role select <name> | Switch to a different role |
/config show | Display current configuration |
/help | Show all available commands |
/quit | Exit the REPL |
For scripting and automation, use subcommands directly:
\n# Search from the command line\nterraphim-agent search "knowledge graph" --limit 5\n\n# List roles\nterraphim-agent roles list\n\n# Show configuration\nterraphim-agent config show\n\n# Visualise knowledge graph (ASCII)\nterraphim-agent graph --top-k 10\nImport and search your AI coding assistant history (Claude Code, Cursor, Aider):
\n# Check available sources\nterraphim-agent sessions sources\n\n# Import sessions\nterraphim-agent sessions import\n\n# Search across sessions\nterraphim-agent sessions search "rust async error"\nTerraphim captures failed commands and their corrections for future reference:
\n# List captured learnings\nterraphim-agent learn list\n\n# Query by pattern\nterraphim-agent learn query "npm"\n\n# Compile corrections into a thesaurus\nterraphim-agent learn compile\nSee the blog post Teaching AI Agents to Learn from Their Mistakes for a worked example.
\nOn first run, the interactive wizard helps you configure:
\nYou can re-run the wizard at any time with terraphim-agent onboard.
If you run into issues:
\nMost of the functionality is driven from the config file.
\nsection for global parameters - like global shortcuts
\n[[roles]]\nFor example I can be engineer, architect, father or gamer. In each of those roles I will have a different concens which are driving different relevance/scoring and UX requirements.
\nRoles are the separate abstract layers and define behaviour of the search for particular role. It's roughly following roles definition from ISO 42010 and other systems engineering materials and at different point in time one can wear diferent heat (different role).
\nEach role have a
\nThe powers roughly follows:
\n[[Skill]]\nParameters:
\nHaystack is a source, can be PubMed, Github, Coda.io, Notion.so etc.\nHaystack arguments
\n", "https://terraphim.ai/properties/date" : "2022-02-21", "https://terraphim.ai/properties/tags" : {"tags":["terraphim","config","plugins"],"categories":["Documentation"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/docs/contribution/", "https://atomicdata.dev/properties/name" : "Contribution Guidelines", "https://terraphim.ai/properties/url" : "https://terraphim.ai/docs/contribution/", "https://atomicdata.dev/properties/description" : "General guidelines for contributing to the project.
\nEven for conceptual topics such as ethics or enterprise architecture, there should be path to be implemented in real would: student's head or software working in production considered to be real world.
\n", "https://terraphim.ai/properties/date" : "2021-12-15", "https://terraphim.ai/properties/tags" : {"categories":["Documentation"],"tags":["contribute","zola"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/docs/donate/", "https://atomicdata.dev/properties/name" : "Support project by contributing", "https://terraphim.ai/properties/url" : "https://terraphim.ai/docs/donate/", "https://atomicdata.dev/properties/description" : "This is the beginning of an exciting great new journey: support open-source projects by donating or contributing.
\nTerraphim AI is partially supported by Innovate UK via the Eureka funding program up to 60% of costs, under grant 600594, \"ATOMIC\", jointly with our collaborators Ontola - the team behind Atomic Data Server and Protocol.\nBut for the rest of the costs, we need your help.
\nAfter several months of agonising over which license to release Terraphim AI under, I created a new repository with the two most liberal licenses open source MIT and APACHE2.\nWe may build a commercial service on top of Terraphim Core(Cortex), but the core and our promise that it is open-sourced to allow you all to build on top of Terraphim AI, with a privacy-first, building AI tooling right way around: you don't need to move your data. You codify and move your knowledge where it needs to be and helps you to get things done the most.
\nTo support the project's development, we introduce a \"donation-driven roadmap\": if you want a feature, vote for it not only with your thumb but with your money.\nIn exchange:
\nSponsor the features on our GitHub page or propose a new idea in GitHub discussions
\n", "https://terraphim.ai/properties/date" : "2020-08-31", "https://terraphim.ai/properties/tags" : {"tags":["donate","support"],"categories":["donations","open-source"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/kg-concepts-code-checklists/", "https://atomicdata.dev/properties/name" : "KG Concepts Before Code, Checklists After", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/kg-concepts-code-checklists/", "https://atomicdata.dev/properties/description" : "The Graph Embeddings for Checklists article\nshows how a knowledge graph acts as an enumerable checklist around an LLM call:\nterraphim-grep before it, terraphim-agent hook and learning after it. This\nhow-to applies the same loop to terraphim-agent code — the bounded coding loop —\non the simplest possible concept: npm install must become bun add.
Every command below was run while writing this article; the outputs are real.
\nDeclare the concept once (kg/*.md or .terraphim/rewrite/*.md with\nsynonyms::), let the hook find npm install in a proposed tool call and\nprescribe bun add, run code inside the policy gate, then validate the\nproduced work with validate --checklist. The checklist guards the write and\njudges the result — the model is never trusted to police itself.
One file, written once, compiled into the role's automaton. From this site's own\n.terraphim/rewrite/bun install.md:
# bun add\n\nInstall dependencies using Bun package manager.\n\nsynonyms:: npm install, yarn install, pnpm install, npm i, yarn add, pnpm add\ncode: The Hook Checks the ActionAn agent proposing npm install hits the checklist first — pre-tool-use with\n--rewrite (opt-in so a stray substring can't silently mutate a destructive\ncommand):
echo '{"tool_name":"Bash","tool_input":{"command":"npm install react"}}' \\\n | terraphim-agent hook --hook-type pre-tool-use --rewrite \\\n --role "Terraphim Engineer" --json\n{\n "tool_input": {\n "command": "bun install react"\n },\n "tool_name": "Bash"\n}\nThe concept fired: npm install in, bun install out — a checklist line\nexecuted before the tool call runs, with a named edge (bun install.md) to\naudit.
code: The Loop Is Gatedcode run puts the model inside a bounded loop — every tool call is\npolicy-decided, audited to JSONL, and the run is exit-coded for callers:
TERRAPHIM_CODE_MODEL=auto \\\n terraphim-agent code run "Create a Cargo.toml and src/main.rs that prints Hello from terraphim"\n- **Cargo.toml** — package `terraphim` v0.1.0, edition 2021, no dependencies\n- **src/main.rs** — `fn main()` printing `Hello from terraphim`\n\nVerified with `cargo run`, which compiled cleanly and output:\n\n Hello from terraphim\nThe hook and the gate compose: the KG checklist shapes what commands the agent\nmay propose, the deny-first policy decides whether a call runs at all, and the\naudit JSONL records both decisions. Sessions persist as transcripts plus\nTurnStep checkpoints, so code resume replays context and reads persisted\nsteps back.
code: The Checklist Judges the ResultThe same graph that prescribed bun judges the output — code_review is a KG\nchecklist, not a prompt suggestion:
echo "no tests, unwrap() everywhere" \\\n | terraphim-agent validate --checklist code_review\nChecklist 'code_review' Validation for role 'AI Dark Factory Author':\n Passed: false\n Score: 0/5\n Missing items:\n ✗ tests\n ✗ documentation\n ✗ error_handling\n ✗ security\n ✗ performance\nZero-inflated honesty applies here too: if the produced work mentions none of\nthe checklist items, the report says so with the missing set enumerated — the\nsame \"honest empty case\" property terraphim-grep shows on retrieval.
declare kg/*.md ──► hook pre-tool-use (npm install → bun add)\n │\n code run — gated, audited, resumable\n │\n validate --checklist code_review — the verdict\n │\n learn/correct — feed misses back into synonyms\nhook --rewrite is opt-in (--rewrite flag, default off): findings are\nalways emitted; the substitution is explicit. Without --rewrite the same\nrun returns the input unchanged with the finding attached.terraphim-agent replace in this build reports changed: true while\nreturning the input unchanged — the findings-based hook path above is the\ncontract to rely on (this caveat is carried from the checklists post, which\ndocumented it first).auto on terraphim-llm-proxy resolves through the measured dynamic pool\nwith a static MiniMax-M3 fall-through, so a gated-out pool degrades to a\nhealthy lane rather than failing — fixed during this session (the pool's\neligibility gates had evicted every candidate while the static fallback was\nabsent; auto answered with a generic 400). A dead member in the pool\n(kimi-for-coding-highspeed, subscription 403) still costs probe traffic.TERRAPHIM_CODE_AUTOMATA_PATH rather than registering\na role.Two fframes renders of real captures back this article — every terminal\nline is a real command output captured while writing it.
The joined storyline (spec → graph → gate → surface → code → checklist): a\nreal spec.md, terraphim-grep firing validation gate on the context, the\ngate denying two shell calls by rule name, the tools/commands/policy surface,\na verified cargo run output, and the 0/5 checklist verdict on\nspec-violating code.
The disciplined-engineering cut (issue → research → design → impl → verify → validate): real issue #431\nthrough the disciplined-* phases — the rg finding, the design decision,\nreal commits, fmt/blaze verification, and the checklist verdict.
Cloudflare published an excellent post this week: Cutting our inference bill by 68% by being obsessive about optimization. Their AI code reviewer went from $2.43 to $0.77 per review, and the median review time fell from 4m 09s to 1m 32s. It is a masterclass in squeezing the token economics of a single provider: shared prompt-cache prefixes, fewer LLM calls per session, and relentless model/effort A/B tests.
\nIt is also a study in what optimisation inside the call cannot reach. Every one of their levers operates after the request has already been committed to a provider, a model, and an effort level. Their architecture answered the question of which lane each request deserves by experiment rather than by a decision mechanism. That layer is what terraphim-llm-proxy exists for, and the interesting part is that its answer costs zero tokens.
\nCloudflare's optimisations and Terraphim's routing operate on disjoint parts of the spend. Neither substitutes for the other, but only one of them requires a Cloudflare-scale engineering team and production traffic to discover.
\n| Lever | Layer | What it costs to make the decision |
|---|---|---|
| Shared cache prefixes (14–26% → 91–99.5% first-request hits) | Inside the call | Engineering time; nothing per request once landed |
| Fewer LLM calls per session (16.6 → ~fewer; index into prompt) | Inside the call | Engineering time |
| Model + effort A/B splits (Sonnet 5 vs 5.5, medium vs high) | Across calls | Real production traffic and real dollars for days per split |
| Keyword/synonym routing to provider lanes | Before the call | Zero tokens, sub-millisecond, deterministic |
| Latency-probed \"fastest\" policy | Before the call | Probe requests; zero tokens on the routed request |
| Runtime fallback on outage/rate-limit/credit exhaustion | Before the call | Zero; the fallback is a failover rather than a retry of the same lane |
Cloudflare's answer to \"which model should handle this\" was a 50/50 production split run for two and a half days, read off dashboards, then rolled out. That is the honest way to do it when your router is a human. A deterministic router answers the same question per-request, for free, in microseconds, and it can change its mind the moment a lane degrades.
\nThese are real requests through the Terraphim Proxy desktop app (v0.1.45) running on 127.0.0.1:17890 with five configured provider lanes: z.ai GLM-5.3, MiniMax-M3, OpenAI Codex gpt-5.6-sol, xAI Grok-4.3, and a free OpenRouter lane (nvidia/nemotron-3.5-lightning:free). The route policy was fastest, which is latency-probed rather than keyword-pinned.
$ curl -X POST http://127.0.0.1:17890/v1/messages \\\n -H "Authorization: Bearer <caller-key>" \\\n -d '{"model":"auto","max_tokens":32,\n "messages":[{"role":"user","content":"Reply with exactly: ok"}]}'\n| Request | Route decision | Provider that served it | Wall time | Decision cost |
|---|---|---|---|---|
| \"deep security code review…\" | auto → fastest lane | MiniMax-M3 | 1.28s | 0 tokens |
| \"Reply with exactly: ok\" | auto → fastest lane | MiniMax-M3 | 0.92s | 0 tokens |
openrouter:nvidia/...:free pinned | explicit pin | nemotron-3.5-lightning:free | 1.09s | 0 tokens |
xai:grok-4.3 pinned | explicit pin | grok-4.3 | 9.73s | 0 tokens |
Read the last two rows together. At the moment of measurement, Grok-4.3's lane was roughly 10× slower than MiniMax's; transient congestion is exactly the condition a human-picked \"best model\" cannot react to. The fastest policy had already steered automatic traffic away from it. No alert fired, no dashboard was watched, no incident was declared: the probe data just ranked the lanes and auto avoided the slow one. Pinning is still available for when you want a specific lane; the point is that the default behaviour absorbs provider badness for free.
And the free lane is not decorative. nvidia/nemotron-3.5-lightning:free answered correctly at 1.09s. A $0 lane exists precisely so that traffic which does not need a frontier model never pays for one.
The routing decision is deterministic string matching, not a model call:
\nKeywordRouter table, where \"review\", \"plan\", \"security\", \"think\" and friends map to scenario routes.auto, fastest, deep-think, code-review, cheapest) select the lane; FillFirst chains order fallbacks across providers, not just models.Total inference tokens spent deciding: zero. The decision is a lookup, not a completion.
\nCompare the alternative that is currently fashionable: a model-based \"decision layer\" or classifier that reads each request and predicts which model should handle it. That decision itself costs tokens on every single request, plus a serialization round-trip of added latency. It is inference spent so you can spend inference. For a single workload the overhead is trivial; at agent-fleet scale you have built a second inference bill whose only product is billing decisions.
\nThe two levers stack; pretending otherwise would be dishonest:
\nCloudflare's reviewer makes ~10 LLM calls per review and spends $0.77. If a model-based router spent even 500 tokens triaging each of those calls, that is 5k extra tokens per review. Small per request, but it buys nothing a deterministic probe doesn't already know. Multiply by agent-fleet volume and the decision layer becomes a line item.
\nThe inverse is the actual saving: the free OpenRouter lane answered the trivial request for $0.00 where a frontier lane would have billed input + output. At Cloudflare's scale of thousands of reviews, \"which requests genuinely need the expensive model\" is the question worth more than \"how do we cache better\", and it is a question that costs zero tokens to ask when the answer is a keyword rather than a completion.
\nObsessive optimisation inside the call is necessary. It is not sufficient. The cheapest token is still the one you never spend, including the ones you would have spent deciding.
\nTwo routes, depending on whether you want the binary or the source:
\nterraphim-llm-proxy is currently sponsor-gated on GitHub. The $10/month tier at github.com/sponsors/terraphim grants repository access: multi-provider routing (Groq, Cerebras, DeepSeek, OpenRouter, z.ai, MiniMax, xAI, Codex), pattern-based semantic routing, sub-millisecond routing overhead, plus the knowledge-graph embedding engine. Everything ships under FSL-1.1-MIT, the Functional Source License that converts to plain MIT two years after each release, so sponsor access today becomes an open-source guarantee on a timer rather than a perpetual toll. The sponsor gate is a limited-time arrangement: once the repository goes fully public, this route to early access closes. ($15/month covers all private repositories.)The arithmetic from above applies directly: if a $10/month tier saves you frontier-model tokens on routing decisions, or lands one free-lane fallback during an outage, it pays for itself in the first bad week.
\nFSL-1.1-MIT licensed. Sponsors: github.com/sponsors/terraphim. App: notarised DMG now, App Store in review.
\n", "https://terraphim.ai/properties/date" : "2026-10-23", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","LLM","proxy","cost","routing","tokens","comparison"],"categories":["Engineering"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/graph-embeddings-checklists/", "https://atomicdata.dev/properties/name" : "Graph Embeddings for Checklists", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/graph-embeddings-checklists/", "https://atomicdata.dev/properties/description" : "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.
\nThis 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 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.
\nA 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\n\nInstall dependencies using Bun package manager.\n\nsynonyms:: npm install, yarn install, pnpm install, npm i, yarn add, pnpm add\nThe 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.
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.
\nHere is the query I ran over this site's own source while preparing this article, using the Terraphim Engineer thesaurus:
\nterraphim-grep "quality gate" --haystack all --paths . \\\n --thesaurus ~/.config/terraphim/thesaurus.json -n 8 -C 1 --json\nThe result, abridged:
\n"stats": {\n "search_latency_ms": 53,\n "chunks_returned": 8,\n "kg_hits": 8\n},\n"concepts": [\n {"name": "accept"}, {"name": "accepted"}, {"name": "escalate"},\n {"name": "fail"}, {"name": "improve"}, {"name": "judge-verdicts"},\n {"name": "needs improvement"}, {"name": "pass"}\n]\nTwo 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.
A checklist that cannot say \"not covered\" is useless, so here is the control run against the same thesaurus:
\nterraphim-grep "checklist" --haystack all --paths . \\\n --thesaurus ~/.config/terraphim/thesaurus.json -n 8 -C 2 --json\n"kg_hits": 0,\n"sufficiency": "SearchOnly",\n"sufficiency_explanation": "Found 4 chunks but KG confidence 0.00 < 0.50,\n diversity 1 < 2; returning search results only (pass --answer or\n --force-rlm to synthesise)."\nZero 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.
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 . \\\n --thesaurus .terraphim/thesaurus.json -n 8 -C 1 --json\nSame 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.
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:
\necho '{"tool_name":"Bash","tool_input":{"command":"npm install react"}}' \\\n | terraphim-agent hook --hook-type pre-tool-use --json\n{"tool_input":{"command":"npm install react"},"tool_name":"Bash",\n "validations":{"findings":[{"matched_term":"npm install",\n "suggested_replacement":"bun install"}],"has_findings":true}}\nRead 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.
Checklists also cover the checking tool. Two honest notes from this session:
\nterraphim-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.Put the phases together and the checklist lifecycle is:
\nkg/*.md files; heading = normalised item, synonyms:: = surface forms to catch.thesaurus.json; ~20 ms per role.terraphim-grep with the role thesaurus expands queries into concept terms and pulls grounded chunks — or honestly reports kg_hits: 0.terraphim-agent hook emits findings; guards intercept destructive commands; failed commands are captured by the learning hook.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.
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.
\nIf 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.
\n", "https://terraphim.ai/properties/date" : "2026-10-20", "https://terraphim.ai/properties/tags" : {"categories":["Technical"],"tags":["Terraphim","graph-embeddings","knowledge-graph","checklists","ai-agents","context-engineering"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/context-engineering-book-announcement/", "https://atomicdata.dev/properties/name" : "Context Engineering: the book is out", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/context-engineering-book-announcement/", "https://atomicdata.dev/properties/description" : "![\"Context](\"/images/context-engineering-book-cover.jpg\")
Most AI systems don't fail because the model is wrong.
\nThey fail because the context is.
\nBut here's the uncomfortable part: context engineering isn't a new activity. We've been doing it for decades under different names:
\nThat's the argument in my book, Context Engineering: Designing AI That Understands, Remembers, Acts, and Learns.
\nIt 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.
\nInside, 25 chapters cover:
\nIt's written for senior developers, engineering managers and architects who need AI to be dependable in production, not just impressive in a demo.
\nThe book is out now on Kindle: amazon.com and amazon.co.uk.
\nWhich older discipline do you think AI teams have forgotten most?
\n", "https://terraphim.ai/properties/date" : "2026-10-19", "https://terraphim.ai/properties/tags" : {"tags":["context-engineering","book","Terraphim","knowledge-graphs","AI"],"categories":["Announcements"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/save-money-tokens-ai-agents/", "https://atomicdata.dev/properties/name" : "3 Ways to Save Money on Tokens for Your AI Agents", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/save-money-tokens-ai-agents/", "https://atomicdata.dev/properties/description" : "Your agent bill is mostly input tokens. Not the clever parts: the re-reading.
\n\nThree 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.
\nEvery 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.
\nWe 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.
\nThe 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.
\nThe 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.
\nWe 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'\n\nterraphim-grep provider \\\n --thesaurus docs/src/thesaurus.json \\\n --haystack code --paths crates -n 10 \\\n --answer --force-rlm --json\n--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.
\nTwo 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.
\nThe second lever is not a tool but a lifecycle decision: match the model's price to the phase of work.
\nWe 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.
\nSo we split the model placement:
\nopencode-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.
\nThe 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.
\nThe 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.
\nOurs 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:
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./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.
\nToken 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.
\nWhat 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.
\nThe 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.
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.
\nThis 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.
\n\nDownload the Harbour example · Read the transcript
\nHarbour 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:
\nValidate the Harbour project brief with python3 validate-brief.py --check.\nKeep the source decisions in brief.md intact.\nThat 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.
\nThe 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:
\npython3 reproduce.py --agent /path/to/terraphim-agent \\\n --output ./harbour-run --prepare-only\ncd harbour-run/fixture\nexport TERRAPHIM_DEFAULT_DATA_PATH="$(cd .. && pwd)/data"\nexport TERRAPHIM_SETTINGS_PATH="$(cd .. && pwd)/settings"\nUse 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 \\\n --file lesson.md \\\n --provenance-tag harbour-public-brief-v1\nCapture 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.
\n--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.
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\nterraphim-agent --format json memory list\nterraphim-agent memory export --format json --output memories.json\nReplace 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.
![\"A](\"/demos/agent-memory/screenshots/saved-lesson.jpg\")
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.
\nKnowing 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.
\nIts small graph has a Brief validation concept:
\n# Brief validation\nsynonyms:: validate brief, brief validation, --check\nA 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.
\nWith the example's role configuration loaded, this query retrieves the stored lesson:
\nterraphim-agent --config ../config.json memory retrieve 'validate brief' \\\n --role 'Brief Reviewer' --format json\nThe 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.
\n![\"The](\"/demos/agent-memory/screenshots/retrieval-controls.jpg\")
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.
\nThose 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.
\nThe 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.
\nThis 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.
\nmemory 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.
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.
\nDownload and reproduce the memory example. You can also inspect the saved outputs and verification manifest.
\nThe 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.
\nUpdated 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.
\n", "https://terraphim.ai/properties/date" : "2026-07-01", "https://terraphim.ai/properties/tags" : {"categories":["Technical"],"tags":["Terraphim","ai","agentic-engineering","memory","knowledge-graph","developer-tools"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/terraphim-forge-public-demo/", "https://atomicdata.dev/properties/name" : "Try Terraphim Forge: public demo open at demo.terraphim-forge.com", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/terraphim-forge-public-demo/", "https://atomicdata.dev/properties/description" : "We just opened the public demo of Terraphim Forge at demo.terraphim-forge.com. It is a free, anonymous, self-serve instance of our Gitea fork running on Firecracker microVMs. Sign up, push code, publish a Cargo crate, run our PageRank-based issue triage tool. Everything resets at 04:00 UTC daily, so bring nothing irreplaceable.
\nTerraphim Forge is a pay-first SaaS that hands a paying customer their own Gitea-on-Firecracker microVM at <their-id>.terraphim-forge.com within ~30 seconds of completing checkout. The persistent paid tiers will go on the price page later this week; the public demo is what you can try right now without paying anything.
The demo is one VM, public-facing, with anonymous registration enabled. Four canonical repositories are seeded on every refresh:
\nterraphim/gitea -- our Gitea fork (the binary that runs inside every customer VM)terraphim/gitea-robot -- the gtr CLI for PageRank-driven issue triageterraphim/terraphim-skills -- skill packages that drive our agent workflowsterraphim/terraphim-ai -- the main Terraphim platform repo (read-only, archived; ~390 MB)You can fork any of them into your demo account, push to your forks, and use the platform exactly as a paying customer would.
\n# Sign up at https://demo.terraphim-forge.com/user/sign_up first.\ngit clone https://demo.terraphim-forge.com/<you>/<repo>\ncd <repo>\ngit lfs track '*.bin'\ngit add .gitattributes some.bin && git commit -m "with LFS"\ngit push\nLFS objects land in our SeaweedFS-backed S3 store; the demo bucket gets wiped at 04:00 UTC along with the VM, so do not use this for anything you care about.
\nEvery demo user gets their own Cargo registry endpoint at /api/packages/<your-user>/cargo. Generate a Personal Access Token in the Gitea UI (Settings -> Applications, scopes read:package, write:package), then:
mkdir my-crate && cd my-crate\ncargo init --lib\n# minimal Cargo.toml: name, version, edition, license\ncargo publish --registry-url \\\n "https://demo.terraphim-forge.com/api/packages/<you>/cargo" \\\n --token "Bearer <your-pat>"\nThe .crate lands in SeaweedFS, becomes downloadable from the sparse index. We verified the round-trip end-to-end (publish, sparse-index lookup, presigned-URL download, sha256 match) on a freshly-provisioned VM the day we opened the demo.
gtr is our PageRank-based issue triage tool. It scores issues by how many other issues they unblock, so you fix the high-leverage ones first.
git clone https://demo.terraphim-forge.com/terraphim/gitea-robot\ncd gitea-robot\nbun install\nexport GITEA_URL=https://demo.terraphim-forge.com\nexport GITEA_TOKEN=<your-pat>\n./bin/gtr triage --owner <you> --repo <your-repo>\n./bin/gtr ready --owner <you> --repo <your-repo>\n./bin/gtr graph --owner <you> --repo <your-repo>\nRead-only browsing of terraphim/gitea-robot works without a login.
\n\nThe demo resets every day at 04:00 UTC. Your repos, your packages, your account, the admin password -- all gone, all replaced. We rebuild from a known-good golden rootfs, re-mirror the four seeded repos from canonical Gitea, and rotate the admin password from 1Password.
\n
This is deliberate. Twenty-four-hour lifetime makes the demo a poor target for spam, persistence-style abuse, or content-takedown drama. It also keeps the surface honest: you can never end up trusting a piece of state that turns out to have been there for six months by accident.
\nIf you want a Forge that does not reset, that is the paid tier; the price page goes up later this week.
\nEach demo session and each paying customer gets their own Firecracker microVM. Boot time is ~330 ms total (network configure, drive attach, kernel boot, instance start). The full pay-first chain -- landing -> Stripe checkout -> webhook -> microVM provisioned -> admin user created -> Caddy route added -> customer logged in and pushing code -- runs in ~30 seconds end-to-end.
\nA few of the load-bearing engineering decisions:
\nPer-VM rootfs (copy-on-write). Firecracker exposes the host file as a raw virtio-blk device with no isolation. Two VMs sharing the same path with is_read_only: false will silently corrupt each other's ext4+SQLite. We copy the golden image to /var/lib/firecracker/images/instances/<vm_id>.rootfs before add_drive so each VM gets its own private writable disk. Cleanup happens automatically on stop.
forge.fqdn= kernel arg. Each VM boots with forge.fqdn=<user>.terraphim-forge.com in /proc/cmdline. A systemd ExecStartPre hook in the rootfs reads it and patches app.ini so Gitea's DOMAIN and ROOT_URL are right before the daemon starts. Without it, every public URL would be https://localhost/ and the customer experience would be broken in ways that take a while to track down.
Stable demo password from 1Password. The refresh job reads op://TerraphimPlatform/forge-demo/password every cycle and applies it to the freshly-provisioned admin user via gitea admin user change-password. No more lost demo creds.
Caddy on-demand TLS. Each customer subdomain gets its own ACME cert on first request; Caddy reuses it across daily refreshes since the SAN does not change.
\nSeaweedFS for everything that is not git. LFS, packages (Cargo registry, generic uploads), and repo archives all go to a SeaweedFS S3 bucket. Same bucket survives demo refreshes (we wipe per-user namespaces, not the whole bucket).
\nThe VM image build (gitea-vm-image) and the control plane (firecracker-rust) are both Rust. The control plane is fcctl-web + fcctl-core, the latter is the Firecracker driver and the former is the Stripe-aware web service that wires customer signup to VM provisioning.
Short term:
\nMedium term:
\nIf you want a particular integration, ping us on the demo (open an issue in any repo there) or send us a note on social — we will be opening a public Forge tracker as the source repos go public.
\nThe Rust control plane is being prepared for public release; the source repository will be opened up alongside this demo over the next few days. The four canonical repositories are currently visible on the demo itself (see the links earlier in this post), and a fork of our Gitea fork is one of them, so you can already read the patches we run by signing up on the demo and browsing terraphim/gitea.
When the public release lands, the URLs will be:
\ngithub.com/terraphim/firecracker-rustgit.terraphim.cloud/terraphim/gitea-vm-imagegit.terraphim.cloud/terraphim/terraphim-forgegit.terraphim.cloud/terraphim/giteaFollow @terraphim_ai for the public-release announcement.
\nIf you break it, we will see it in the next refresh and fix it. If you build something cool on it, tag @terraphim_ai and we will boost it.
\n", "https://terraphim.ai/properties/date" : "2026-05-03", "https://terraphim.ai/properties/tags" : {"categories":["Product"],"tags":["terraphim-forge","gitea","firecracker","cargo-registry","demo","self-hosted"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/experiment-results-opencode-terraphim-2026-05-02/", "https://atomicdata.dev/properties/name" : "OpenCode + Terraphim Experiment Results", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/experiment-results-opencode-terraphim-2026-05-02/", "https://atomicdata.dev/properties/description" : "Date: 2026-05-02\nTask: Build accessible navigation component in SvelteKit\nProject: ~/projects/frontend-test (fresh SvelteKit project)
OpenCode with terraphim-agent (KG-boosted search) produces better results faster than OpenCode without terraphim.
\n| Component | Version |
|---|---|
| OpenCode | 1.14.31 |
| terraphim-agent | 1.17.0 |
| terraphim_mcp_server | built from source |
| SvelteKit | 2.57.0 + Svelte 5.55.2 |
~/.config/terraphim/kg/frontend/| Metric | Flow A (+terraphim) | Flow B (control) | Difference |
|---|---|---|---|
| Steps | 11 | 16 | -31% |
| Total tokens | 500,749 | 686,995 | -27% |
| Tool calls | 15 | 17 | -12% |
| Final tokens | 50,595 | 50,510 | +0.2% |
| Cache read | 428,544 | 613,819 | -30% |
| Cache write | 55,414 | 55,910 | -1% |
Flow A (with terraphim) was 27% more token-efficient and completed in 31% fewer steps. This suggests:
\nBoth flows produced working components with:
\naria-label, aria-expanded, aria-controls, aria-current)Flow A additionally identified and fixed:
\naria-current tracking keyboard focus instead of current pageFlow A had 30% less cache read - the KG records likely provided more relevant context upfront, reducing redundant lookups.
\nses_2178d0500ffeW6fFkdimKTqKtVses_2178b107bffeqI0FUaDc1IXNyhFull JSON logs available at:
\n~/experiment/flow-a-full.json~/experiment/flow-b-full.jsonHypothesis confirmed: OpenCode with terraphim-agent produces results 27% faster (token efficiency) with 31% fewer steps for accessibility-focused frontend tasks.
\nThe KG records for Frontend Developer provide targeted patterns for:
\nThis supports the value of role-based knowledge graphs for AI coding assistants.
\n", "https://terraphim.ai/properties/date" : "2026-05-02", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","OpenCode","AI","experiment","knowledge-graph"],"categories":["Technical"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/fff-vs-ripgrep/", "https://atomicdata.dev/properties/name" : "FFF vs Ripgrep: Understanding the Difference", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/fff-vs-ripgrep/", "https://atomicdata.dev/properties/description" : "A common point of confusion in Terraphim is understanding the difference between FFF (fzf-like fuzzy file finder) and Ripgrep haystack. This post clarifies what each does and how they complement each other.
\nFFF is NOT a haystack. FFF provides MCP tools for fuzzy file finding and content grep. Ripgrep is a haystack ServiceType for exhaustive content search. They serve different purposes and can be used together.
\nIn Terraphim, a haystack is a searchable data source configured in your role definition:
\n{\n "haystacks": [\n {\n "location": "/path/to/project",\n "service": "Ripgrep",\n "read_only": true\n }\n ]\n}\nAvailable haystack ServiceTypes:
\n| ServiceType | Purpose | KG Ranking |
|---|---|---|
Ripgrep | Local content search | Via relevance function |
GrepApp | GitHub code search | Via relevance function |
Atomic | Atomic Server | Via relevance function |
QueryRs | Rust API docs | Via relevance function |
Quickwit | Log search | Via relevance function |
Jmap | Email search | Via relevance function |
FFF (Fast File Finder) is a separate system that provides MCP tools for AI coding agents. It's not a haystack and cannot be configured as one.
\n| Tool | Purpose | Output |
|---|---|---|
terraphim_find_files | Fuzzy file path search | Ranked list of file paths |
terraphim_grep | Content grep with KG ordering | Lines with matches |
terraphim_multi_grep | Multi-pattern Aho-Corasick grep | Lines matching any pattern |
Query → FilePicker (scan files) → fuzzy_search → KG scorer (path boost) → ranked results\nQuery → File list → KG scorer (sort by path score) → grep_search → matches\nKey features:
\nKgPathScorer (ExternalScorer trait)| Aspect | Ripgrep Haystack | FFF Tools |
|---|---|---|
| Type | Haystack (configured in role) | MCP tools |
| Content search | Yes (regex, exhaustive) | Yes (fff grep engine) |
| File path search | No | Yes (fuzzy) |
| Frecency | No | Yes |
| KG integration | Relevance function | kg_scorer (path boost) |
| Output format | Ranked documents | Files + content lines |
| Pagination | No | Cursor-based |
Query → terraphim search → role relevance function → Ripgrep → KG concept match → ranked docs\nterraphim search commandterraphim-graph) scores documentsQuery → terraphim_find_files → fuzzy path match → KG scorer (path) → ranked paths\nQuery → terraphim_grep → KG scorer (sort files) → grep → matches\nterraphim_find_files or terraphim_grep directlyterraphim search command{\n "roles": {\n "Frontend Developer": {\n "relevance_function": "terraphim-graph",\n "haystacks": [\n {\n "location": "/path/to/project",\n "service": "Ripgrep"\n }\n ]\n }\n }\n}\nFFR tools are registered separately in OpenCode:
\n{\n "mcp": {\n "terraphim": {\n "type": "local",\n "command": ["/path/to/terraphim_mcp_server"]\n }\n }\n}\nTools available: terraphim_find_files, terraphim_grep, terraphim_multi_grep
FFF and Ripgrep are complementary, not competing:
\nBoth integrate with the knowledge graph but in different ways. Use Ripgrep haystack for thorough content search. Use FFF for quick file finding and when AI agents need direct tool access.
\n", "https://terraphim.ai/properties/date" : "2026-05-02", "https://terraphim.ai/properties/tags" : {"categories":["Technical"],"tags":["Terraphim","FFF","Ripgrep","knowledge-graph","haystack"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/frontend-developer-role-setup-v2/", "https://atomicdata.dev/properties/name" : "Setting Up a Frontend Developer Role in Terraphim", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/frontend-developer-role-setup-v2/", "https://atomicdata.dev/properties/description" : "This guide documents the step-by-step process for setting up a Frontend Developer role in Terraphim, including knowledge graph validation, MCP server configuration, and integration with OpenCode.
\nBefore deploying the knowledge graph, validate each concept file to ensure proper structure:
\n# Knowledge graph source location\nKG_SOURCE="/home/alex/projects/terraphim/terraphim-ai/data/kg/frontend"\n\n# Validate each file has required structure\nfor f in "$KG_SOURCE"/*.md; do\n echo "=== $(basename "$f") ==="\n head -5 "$f"\n echo\ndone\nValidation criteria:
\n# Headingsynonyms:: line with 3+ termsThe frontend KG ships with 18 concept files covering:
\n| Domain | Files |
|---|---|
| Svelte/SvelteKit | svelte-patterns.md, component-design.md |
| CSS | css-layout.md, css-custom-properties.md, visual-design.md |
| TypeScript | typescript.md |
| Accessibility | accessibility.md |
| Performance | performance.md |
| Testing | testing-frontend.md |
| State Management | state-management.md |
| Forms | forms-validation.md |
| APIs | api-integration.md |
| Browser APIs | browser-apis.md |
| Build Tools | build-tools.md |
| DX | developer-experience.md |
| Package Management | package-management.md |
| Responsive Design | responsive-design.md |
| Interaction | interaction-patterns.md |
Total: 316 synonyms across 18 concepts
\n# Create directory\nmkdir -p ~/.config/terraphim/kg/frontend\n\n# Copy validated KG\ncp -r /home/alex/projects/terraphim/terraphim-ai/data/kg/frontend/* \\\n ~/.config/terraphim/kg/frontend/\n\n# Verify\nls ~/.config/terraphim/kg/frontend/\nAdd role configuration path to settings.toml:
# ~/.config/terraphim/settings.toml\nserver_hostname = "127.0.0.1:8000"\napi_endpoint = "http://localhost:8000/api"\ninitialized = "${TERRAPHIM_INITIALIZED:-false}"\ndefault_data_path = "${TERRAPHIM_DATA_PATH:-${HOME}/.terraphim}"\ndefault_role = "AI Engineer"\nrole_config = "/home/alex/.config/terraphim/embedded_config.json"\nAdd the role to embedded_config.json:
{\n "roles": {\n "Frontend Developer": {\n "shortname": "fedev",\n "name": "Frontend Developer",\n "relevance_function": "terraphim-graph",\n "terraphim_it": true,\n "theme": "yeti",\n "kg": {\n "automata_path": null,\n "knowledge_graph_local": {\n "input_type": "markdown",\n "path": "/home/alex/.config/terraphim/kg/frontend"\n },\n "public": false,\n "publish": false\n },\n "haystacks": [\n {\n "location": "/home/alex/projects/frontend-test",\n "service": "Ripgrep",\n "read_only": true,\n "fetch_content": false,\n "extra_parameters": {}\n }\n ],\n "llm_enabled": false\n }\n }\n}\nKey configuration choices:
\n| Setting | Value | Rationale |
|---|---|---|
relevance_function | terraphim-graph | Hybrid KG + TF-IDF scoring |
terraphim_it | true | Enables text replacement via synonyms |
llm_enabled | false | Deterministic search only |
haystacks[0] | Ripgrep | Local project file search |
For FFF-based file finding (fuzzy path + content search with KG scoring):
\ncd ~/projects/terraphim/terraphim-ai\ncargo build --release -p terraphim_mcp_server\ncp target/release/terraphim_mcp_server ~/.cargo/bin/\nFor GrepApp support (GitHub code search):
\ncargo build --release -p terraphim_middleware --features grepapp\ncargo build --release -p terraphim_mcp_server\nAdd to ~/.config/opencode/opencode.json:
{\n "mcp": {\n "terraphim": {\n "type": "local",\n "command": ["/home/alex/.cargo/bin/terraphim_mcp_server"],\n "environment": {\n "TERRAPHIM_DATA_PATH": "~/.terraphim"\n }\n }\n }\n}\ncd ~/projects\nbunx sv create frontend-test --template minimal --types ts --no-install\n\ncd frontend-test\nbun install\nbun run build\n# Reload config\nterraphim-agent config reload\n\n# List roles\nterraphim-agent roles list\n\n# Test search\nterraphim-agent search --role "Frontend Developer" --limit 5 "aria"\nExpected output:
\n[103] README\n /home/alex/projects/frontend-test/node_modules/aria-query/README.md\n # ARIA Query\n...\nStandard content search using ripgrep:
\n{\n "location": "/path/to/project",\n "service": "Ripgrep",\n "read_only": true,\n "extra_parameters": {}\n}\nPros: Fast, exhaustive content search, regex support\nCons: No concept understanding, no frecency
\nNot a haystack - provides MCP tools for fuzzy file finding and KG-scored content search:
\n# MCP tools provided by terraphim_mcp_server:\n# - terraphim_find_files: Fuzzy path search with KG boost\n# - terraphim_grep: Content search with KG-ordered files\n# - terraphim_multi_grep: Multi-pattern Aho-Corasick search\nPros: Frecency (frequency + recency), KG path scoring\nCons: Different interface than haystack search
\nGitHub code search via grep.app API:
\n{\n "location": "https://grep.app",\n "service": "GrepApp",\n "extra_parameters": { "language": "typescript" }\n}\nPros: Searches millions of public GitHub repos\nCons: Requires --features grepapp build, rate limits
Query → terraphim search → Ripgrep haystack → KG-boosted ranking\nQuery → terraphim_find_files/grep → FFF (fuzzy + frecency) → KG path scoring\n--features grepapp for GitHub code searchterraphim-agent config reload\nterraphim-agent roles list\nGrepApp requires building terraphim_middleware with --features grepapp:
cargo build --release -p terraphim_middleware --features grepapp\ncargo build --release -p terraphim_mcp_server\nCheck haystack location exists:
\nls -la /home/alex/projects/frontend-test\nAs AI agents write more and more production code, the question shifts from \"can the agent write code?\" to \"can we verify the code is good?\" Two tools tackle this from opposite ends: Sentrux measures structural health, Terraphim measures semantic completeness. Neither is complete without the other.
\nAn AI agent that generates 500 lines of syntactically correct Rust can still degrade a codebase. It might introduce tight coupling, leave behind unimplemented stubs, create circular dependencies, or raise the cyclomatic complexity past any reasonable threshold. Standard CI pipelines catch compilation errors and failing tests. They do not catch architectural erosion.
\nBoth Sentrux and the Terraphim evaluation toolkit are designed to close that gap. They just do so from fundamentally different perspectives.
\nSentrux (v0.5.7, MIT, 27.7k lines of Rust) is a real-time structural analysis engine. It parses source code into an AST using tree-sitter, builds a dependency graph, and computes a quality signal from 0 to 10,000.
\nSentrux computes a geometric mean across five orthogonal dimensions:
\n| Metric | What it captures |
|---|---|
| Modularity | Fan-in and fan-out between modules; god file detection |
| Acyclicity | Circular dependency count and which files participate |
| Depth | Maximum dependency chain length; instability score |
| Equality | Cyclomatic complexity distribution (Gini coefficient); large files |
| Redundancy | Dead functions; duplicate code groups |
These are structural facts derived from the AST and dependency graph, not text patterns. Sentrux does not care what the code says; it cares how it connects.
\nSentrux ships a native MCP server with nine tools. The intended agent workflow is:
\nsentrux.scan("/path/to/project")\n -> { quality_signal: 7342, files: 139, bottleneck: "modularity" }\n\nsentrux.session_start()\n -> baseline saved\n\n... agent writes code ...\n\nsentrux.session_end()\n -> { pass: false, signal_before: 7342, signal_after: 6891,\n summary: "Quality degraded during this session" }\nThe agent gets a precise numeric verdict with a named bottleneck. It can iterate: check the bottleneck, fix it, call rescan, repeat.
Sentrux includes a live treemap built with egui and wgpu. Files are sized by metric contribution and glow when modified. Dependency edges are drawn between coupled files. A file system watcher (notify) feeds changes over crossbeam-channel to the renderer in real time. The same process that runs the GUI hosts the MCP server, so you can watch architectural changes happen as the agent works.
\n52 languages via tree-sitter plugins. Each plugin is a plugin.toml and a tags.scm query file. No Rust required to add a language.
The Terraphim approach lives across two production crates in terraphim-ai: terraphim_codebase_eval and terraphim_negative_contribution. These are not a conceptual framework or a shell script wrapper; they are typed Rust libraries integrated into the agent review pipeline.
terraphim_codebase_eval)The evaluation manifest is a TOML file that describes a before/after comparison at the git SHA level:
\n[[haystacks]]\nid = "baseline"\npath = "/srv/repo"\ncommit_sha = "abc123"\nstate = "baseline"\n\n[[haystacks]]\nid = "candidate"\npath = "/srv/repo"\ncommit_sha = "def456"\nstate = "candidate"\n\n[[roles]]\nrole_id = "code-reviewer"\ndescription = "Reviews for bugs and maintainability"\nterm_sets = ["bug-patterns", "code-smells"]\n\n[roles.scoring_weights]\nsearch_score = 1.0\ngraph_density = 0.8\nentity_count = 1.0\n\n[[queries]]\nquery_text = "highlight potential bugs"\nrole_id = "code-reviewer"\nexpected_signal = "increase"\nconfidence_threshold = 0.6\n\n[thresholds]\nimproved_pct = 10.0\ndegraded_pct = 5.0\ncritical_test_failures = 0\nRoles define the evaluation perspective. Each role carries named term sets (Aho-Corasick dictionaries built from domain knowledge graphs) and per-dimension scoring weights. Queries specify what to search for and in which direction the score should move. The manifest is validated for referential integrity before execution: any query that references a non-existent role is rejected at load time, not at runtime.
\nThe verdict logic is explicit: if the weighted score increases by more than improved_pct, the contribution is classified as Improved; if it drops by more than degraded_pct, it is Degraded; any new test failure triggers immediate Degraded regardless of scores.
terraphim_negative_contribution)The Explicit Deferral Marker (EDM) scanner answers a specific and critical question: did the agent ship stubs as production code?
\nIt uses the Aho-Corasick automata to detect markers in Rust source that indicate deferred implementation:
\ntodo!()unimplemented!()panic!(\"not implemented\")panic!(\"TODO\")The scanner is production-only by design. It automatically skips:
\ntests/, examples/, benches/ directoriesbuild.rs_test.rs#[test] or #[cfg(test)]Suppression is available per-line: // terraphim: allow(stub) silences the finding on that line only. Every finding carries a file path, line number, severity, category, confidence (0.95), and a suggestion drawn from the thesaurus URL metadata.
The scanner outputs a ReviewAgentOutput struct consumed directly by the Terraphim review pipeline. An agent that ships one todo!() in production code fails the gate.
| Dimension | Sentrux | Terraphim EDM Scanner | Terraphim Manifest Eval |
|---|---|---|---|
| Core mechanism | tree-sitter AST + dependency graph | Aho-Corasick on EDM pattern thesaurus | Aho-Corasick on domain KG + weighted scoring |
| What it measures | Architecture: coupling, cycles, complexity | Incomplete implementations in production code | Semantic quality delta between two git SHAs |
| Language scope | 52 languages | Rust only (production files) | Any language with KG term sets |
| Unit of comparison | Quality signal delta within a session | Pass/fail per file | Before/after manifest with role-weighted scores |
| Agent integration | MCP server (9 tools, session lifecycle) | ReviewAgentOutput struct in review pipeline | EvaluationManifest loaded per evaluation run |
| False positive risk | Low (graph-structural, not text) | Very low (exact stub patterns, test exclusions) | Medium (depends on KG quality) |
| Customisation | rules.toml (layer boundaries, thresholds) | // terraphim: allow(stub) suppression | KG term sets, role weights, query direction |
| Live feedback | Yes (file watcher, treemap, MCP) | No (batch scan) | No (batch manifest) |
| Verdict granularity | Named bottleneck + per-metric breakdown | Finding list with file:line and suggestion | Improved / Degraded / Neutral with percentage |
These tools are not alternatives. They operate at different layers of the quality stack:
\nSentrux answers: Is the architecture getting worse?
\nTerraphim EDM Scanner answers: Did the agent leave stubs in production code?
\nTerraphim Manifest Eval answers: Did the agent improve or degrade domain-specific semantic quality across these two commits?
\nA complete agent quality gate combines all three:
\nsentrux session_start before the agent begins worksentrux session_end to verify no structural degradationIf any gate fails, the contribution is blocked. The agent gets specific, actionable feedback: a named structural bottleneck from Sentrux, a file and line number from the EDM scanner, or a percentage degradation from the manifest evaluator.
\nIf you are instrumenting an AI agent pipeline today, start with the Terraphim EDM scanner. It requires no configuration beyond pointing it at your Rust source. It has a binary pass/fail verdict, zero false positives on well-written production code, and integrates directly into the existing ReviewAgentOutput pipeline.
Add Sentrux when you want continuous architectural visibility. The MCP integration means the agent can self-correct in real time rather than discovering structural problems only at gate check.
\nAdd the Terraphim manifest evaluation when you have a domain knowledge graph and want to verify that the agent's changes improve semantic coverage in your specific domain, not just compile and pass tests.
\nTogether, they give you three independent quality signals that a capable agent must satisfy simultaneously: structural soundness, implementation completeness, and semantic improvement.
\nVector embedding calls are the hidden tax on every RAG pipeline. You pay latency, you pay API cost, you get probabilistic results that vary run to run. There is a class of problem where none of that is acceptable. This post shows how Terraphim replaces embedding calls with Aho-Corasick finite-state automata -- deterministic, auditable, and under one millisecond for 1.4 million patterns.
\nWhen you call an embedding API to retrieve context for an LLM prompt, three things happen:
\nFor general-purpose assistants, these tradeoffs are acceptable. For domain-specific systems -- medical, legal, engineering -- they are not. A system that cannot explain its retrieval decisions cannot be trusted.
\nAho-Corasick is a classical multi-pattern string matching algorithm. Given a dictionary of N patterns, it builds a finite-state automaton at construction time and then scans any input text in O(n) time regardless of how many patterns are in the dictionary.
\nTerraphim builds knowledge graph automata on top of this: each node in the automaton is a domain concept, edges encode synonyms and related terms, and matching returns not just a span but a structured entity with graph position.
\nInput text: "patient presents with BRAF V600E mutation"\n |\n Aho-Corasick scan\n |\n Match: "BRAF V600E" -> node: Gene:BRAF, variant: V600E\n |\n Graph traversal\n |\n Edges: BRAF -> Treats <- Vemurafenib\n BRAF -> TestedBy <- Cobas 4800 assay\n BRAF -> Contraindicated <- Sorafenib (paradoxical activation)\nThe match is deterministic. The traversal is deterministic. The context injected into the prompt is always the same for the same input.
\n┌─────────────────────────────────────────────────────┐\n│ Input Text │\n└───────────────────────┬─────────────────────────────┘\n │\n ┌─────────▼──────────┐\n │ Aho-Corasick FSM │ < 1ms for 1.4M patterns\n │ (terraphim_automata│\n └─────────┬──────────┘\n │ matched spans + normalized terms\n ┌─────────▼──────────┐\n │ Thesaurus Layer │ synonym expansion,\n │ (terraphim_types) │ canonical form resolution\n └─────────┬──────────┘\n │ NormalizedTerm { url, rank, ... }\n ┌─────────▼──────────┐\n │ Role Graph │ 27 node types, 65 edge types\n │ (terraphim_ │ Jaccard + path distance scoring\n │ rolegraph) │\n └─────────┬──────────┘\n │ ranked context passages\n ┌─────────▼──────────┐\n │ Prompt Builder │ inject into LLM prompt\n └────────────────────┘\nEach stage is a Rust crate with a stable public API. You can use any layer independently.
\ncargo add terraphim_automata terraphim_types terraphim_rolegraph\nFor Python (via PyO3 bindings):
\npip install terraphim-automata\nFor JavaScript/TypeScript (via WASM):
\nnpm install @terraphim/automata\nThe thesaurus is a JSON file mapping term strings to NormalizedTerm records. Terraphim ships pre-built thesauri for SNOMED CT, UMLS, and software engineering domains. You can also build your own from markdown knowledge graph files.
use terraphim_automata::{load_thesaurus_from_json, find_matches};\n\nlet thesaurus_json = std::fs::read_to_string("snomed-tier1.json")?;\nlet thesaurus = load_thesaurus_from_json(&thesaurus_json)?;\n\nlet text = "Patient presents with BRAF V600E mutation and melanoma stage IV.";\nlet matches = find_matches(text, thesaurus, true)?; // true = leftmost-longest\n\nfor m in &matches {\n println!("{:?} at {:?}", m.term, m.pos);\n}\nfind_matches is O(n) in the input length. On an M2 MacBook Pro, matching 1.4 million SNOMED patterns against a 500-word clinical note completes in 0.3ms.
Once you have matched entities, traverse the role graph to collect supporting context:
\nuse terraphim_rolegraph::RoleGraph;\n\nlet graph = RoleGraph::from_kg_path("~/.config/terraphim/kg/medical/")?;\n\nfor m in &matches {\n let context = graph.traverse(&m.normalized_term, depth: 2)?;\n // context contains related concepts, evidence paths, ranked passages\n}\nThe traversal depth controls how far to expand from each matched entity. Depth 1 gives direct neighbours (synonyms, treatments, contraindications). Depth 2 adds second-degree connections (clinical trials, guidelines, variants).
\nWe ran identical clinical cases through Google's MedGemma model with and without Terraphim knowledge graph grounding:
\n| Case | Raw MedGemma (no KG) | With Terraphim KG Grounding |
|---|---|---|
| BRAF V600E Melanoma | \"BRAF inhibitor (e.g., Dabrafenib + Trametinib)\" -- vague class suggestion | Vemurafenib 450mg orally once daily -- specific drug and dose |
| CYP2D6 Codeine Sensitivity | Oxycodone 5 mg/mL -- wrong drug entirely | Codeine 60mg every 6h -- correct drug from KG context |
| EGFR NSCLC | Osimertinib 80mg (correct on this run; prior run hallucinated 800mg -- a 10x overdose) | Osimertinib 80mg -- consistently correct per FLAURA trial |
Without graph grounding, the LLM gives vague class-level suggestions, recommends the wrong drug, or produces dosing errors that vary between runs. With Terraphim KG grounding, every recommendation is specific, correct, and reproducible.
\n| Run | Pass Rate | Safety Gate | KG Grounding | Avg Latency |
|---|---|---|---|---|
| CPU | 18/18 (100%) | 100% | 83.3% | 165.3s |
| GPU #1 | 18/18 (100%) | 100% | 77.8% | 23.5s |
| GPU #2 | 18/18 (100%) | 100% | 83.3% | 24.8s |
36 total inference calls. Zero safety failures. No mocked responses.
\nThe LLM latency dominates (23-165 seconds depending on hardware). The Terraphim matching and graph traversal contributes under 1ms to each call.
\nThe medical case is the hardest version of the problem: the stakes are high, the domain is large (1.4M SNOMED terms), and incorrect context causes real harm. The same architecture applies anywhere you need deterministic, auditable retrieval:
\nThe full stack -- MedGemma 4B + SNOMED automata + role graph -- runs on a single machine in under 4GB RAM. There is no vector database daemon to operate, no embedding API to call, and no GPU required for the retrieval layer.
\nterraphim_automata (Aho-Corasick FSM, 1.4M patterns): ~800MB RAM\nMedGemma 4B (quantised): ~2.8GB RAM\nRole graph (27 node types, 65 edge types): ~120MB RAM\nTotal: ~3.7GB\nCompare this to a typical embedding-based RAG stack: embedding model (~500MB) + vector database process (~1-2GB) + embedding API latency per call.
\nThe theory behind automata-based context injection, when to use it versus embeddings, and how to compose it with LLM routing is the subject of Chapters 5-7 of Context Engineering with Knowledge Graphs (launching 2026).
\nSource: github.com/terraphim/terraphim-ai -- 42 Rust crates, WASM-ready, MCP-native, Apache 2.0.
\n", "https://terraphim.ai/properties/date" : "2026-04-29", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","knowledge-graph","Aho-Corasick","FST","context-engineering","tutorial"],"categories":["Technical"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/frontend-developer-agent-walkthrough/", "https://atomicdata.dev/properties/name" : "Building a Front-End Developer Agent with Knowledge Graphs and Code Search", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/frontend-developer-agent-walkthrough/", "https://atomicdata.dev/properties/description" : "We have published a comprehensive walkthrough showing how to build a specialised front-end developer agent using Terraphim's knowledge graph system, dual haystacks, and deterministic search. This post walks through the key concepts and links to the full guide.
\nFront-end development spans a vast surface area: CSS layout, accessibility, TypeScript types, Svelte reactivity, build tooling, performance, testing, and more. When you search for \"how do I make this accessible?\" or \"what's the SvelteKit pattern for form validation?\", you want answers that understand your domain -- not generic web search results.
\nTerraphim's deterministic knowledge graph approach means every search result is grounded in concepts you define, ranked by relevance, and fully reproducible. No hallucination, no non-deterministic LLM output.
\nThe front-end developer agent combines three capabilities:
\nKnowledge Graph: 18 concept files covering responsive design, accessibility, Svelte/SvelteKit patterns, TypeScript, CSS layout, state management, build tools, testing, performance, and more. Each concept has synonyms that resolve deterministically via Aho-Corasick matching.
\nLocal Search (Ripgrep): Searches your project files -- .svelte, .ts, .css, .md -- using the knowledge graph to boost conceptually relevant files.
Global Code Search (GrepApp): Searches millions of public GitHub repositories for TypeScript code patterns via the grep.app API, filtered to TypeScript for modern front-end relevance.
\nResults from both haystacks are merged and ranked using TerraphimGraph, a hybrid scoring algorithm that combines knowledge graph concept matching with TF-IDF rescoring. In testing, a query for \"svelte component\" returned 13 results with TerraphimGraph versus 1 result with the simpler BM25Plus scorer. The 18 concept files with 358 synonyms actively influence ranking, not just display.
\nEach concept is a Markdown file with a heading, description, and synonym list:
\n# Svelte Patterns\n\nSvelte-specific patterns for building reactive, compiled frontend\napplications using runes, stores, and SvelteKit conventions.\n\nsynonyms:: Svelte, SvelteKit, rune, $state, $derived, $effect,\n$props, bind, each block, await block, load function, +page.svelte\nWhen you search for $derived or +page.svelte, the Aho-Corasick automaton matches it to the \"Svelte Patterns\" concept in O(n+m) time. The matching is case-insensitive and leftmost-longest, so \"CSS grid\" matches as one term rather than two separate words.
If no exact match exists, a TF-IDF fallback kicks in using trigger:: directives for semantic similarity.
Terraphim offers multiple relevance functions. For a knowledge-graph-backed agent, terraphim-graph is strictly superior to the simpler bm25plus:
| Aspect | BM25Plus | TerraphimGraph |
|---|---|---|
| KG concepts affect ranking | No (display only) | Yes (graph + TF-IDF hybrid) |
| Term co-occurrence | Not used | Boosts related documents |
| KG link insertion | Disabled | Enabled in results |
| TF-IDF rescoring | Not applied | 30% weight boost |
TerraphimGraph uses a two-pass scoring system. Pass 1 builds a co-occurrence graph from Aho-Corasick matches and ranks documents by total_rank = node_rank + edge_rank + document_rank. Pass 2 applies TF-IDF rescoring at 30% weight. Documents containing co-occurring concepts (e.g., \"svelte\" + \"component\" + \"state management\") score higher than those matching only one term.
The knowledge graph is tuned for Svelte/SvelteKit development with TypeScript:
\n$state, $derived, $effect), stores, components, transitions+page.svelte, +page.ts, +layout.svelte, form actions, load functionssatisfies operatorThe GrepApp haystack is filtered to language: \"typescript\" rather than JavaScript, reflecting the modern Svelte/SvelteKit ecosystem.
# Build the agent\ngit clone https://github.com/terraphim/terraphim-ai.git\ncd terraphim-ai\ncargo build --release\n# Enable GrepApp haystack support\ncargo build --release -p terraphim_middleware --features grepapp\ncargo install --path crates/terraphim_agent\n\n# Set up the front-end developer role\nterraphim-agent setup --template frontend-engineer --path ~/projects\n\n# Search across local files and GitHub\nterraphim-agent search "flexbox responsive layout"\nQuery: "flexbox responsive layout"\n |\n v\n[Auto-route] -> Front-End Developer role\n |\n v\n[Aho-Corasick] -> CSS Layout + Responsive Design concepts\n |\n v\n[Ripgrep] [GrepApp (TypeScript)]\n | |\n v v\n[TerraphimGraph hybrid scoring:\n Pass 1: KG graph ranking (node + edge co-occurrence)\n Pass 2: TF-IDF rescoring (30% weight boost)]\n |\n v\n Ranked results\nThe terraphim_mcp_server binary exposes all knowledge graph tools via the Model Context Protocol, so any MCP-compatible AI coding agent can use your front-end developer KG during coding sessions.
opencode (~/.config/opencode/opencode.json):
{\n "mcp": {\n "terraphim": {\n "type": "local",\n "command": ["~/.cargo/bin/terraphim_mcp_server"],\n "environment": { "TERRAPHIM_DATA_PATH": "~/.terraphim" }\n }\n }\n}\nClaude Code (~/.claude.json):
{\n "mcpServers": {\n "terraphim": {\n "type": "stdio",\n "command": "~/.cargo/bin/terraphim_mcp_server",\n "env": { "RUST_LOG": "error" }\n }\n }\n}\nAfter configuration, the AI agent gains access to 18 MCP tools: search, autocomplete_terms, replace_matches, terraphim_find_files, terraphim_grep, and more. Queries auto-route to the Front-End Developer role when front-end terms are detected.
For Cursor, Windsurf, or any HTTP-based MCP client, start the SSE server: terraphim_mcp_server --sse --bind 127.0.0.1:8000.
The complete step-by-step guide covers:
\nRead it at: docs/walkthroughs/frontend-developer-agent.md
This walkthrough demonstrates the deterministic, KG-first approach. Natural extensions include:
\nThe knowledge graph pattern is universal: define concepts, add synonyms, point at haystacks, and search. No training, no fine-tuning, no API keys for the deterministic path.
\n", "https://terraphim.ai/properties/date" : "2026-04-23", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","walkthrough","knowledge-graph","grepapp","Svelte","SvelteKit","TypeScript","agent"],"categories":["Technical"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/why-graph-embeddings-matter/", "https://atomicdata.dev/properties/name" : "Why Graph Embeddings Matter", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/why-graph-embeddings-matter/", "https://atomicdata.dev/properties/description" : "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.
\nTerraphim 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.
\nThree numbers carry the argument. Each is reproducible on a laptop.
\nFor 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.
\nThe numbers are interesting on their own. The reason they matter is what they let you build.
\nEvery 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.
\nAdding 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.
\nBecause 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.
\nThe pieces above are infrastructure. The story arc continues:
\nnpm 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.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.
\nThe mechanism — automata, ranking formula, ASCII walk-through — is on the Graph Embeddings reference page. Read that next if you want the data structures.
\nThe 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.
\nThe 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.
\nUntil then: read the reference, try the how-to, and let us know in Discourse what you build with it.
\n", "https://terraphim.ai/properties/date" : "2026-04-22", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","graph-embeddings","knowledge-graph","aho-corasick","context-engineering"],"categories":["Technical"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/terraphim-search-in-claude-code-and-opencode/", "https://atomicdata.dev/properties/name" : "Plug Terraphim Search into Claude Code and opencode (CLI First, MCP When You Need It)", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/terraphim-search-in-claude-code-and-opencode/", "https://atomicdata.dev/properties/description" : "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.
\nThe 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:
\n/tsearch "System Operator" RFP\nThe 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.
\nterraphim-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.
Drop this at ~/.claude/commands/tsearch.md (and an identical copy at ~/.config/opencode/command/tsearch.md -- both hosts read the same frontmatter shape):
---\ndescription: Terraphim search across configured roles. Usage: /tsearch [role] <query>\nallowed-tools: Bash(terraphim-agent search:*), Bash(terraphim-agent-pa search:*)\n---\nRun `terraphim-agent search --role "<role>" --limit 5 "<query>"` (or\n`terraphim-agent-pa search ...` if the role is "Personal Assistant" and\nthe query needs the JMAP haystack). Return the top results as a numbered\nlist with title, source path/URL, and a 120-char snippet.\nThat 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.
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.
/tsearch "Terraphim Engineer" rolegraph\n/tsearch "System Operator" RFP\n/tsearch "Personal Assistant" invoice # uses terraphim-agent-pa wrapper for JMAP\nThe 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.
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.
cd ~/projects/terraphim/terraphim-ai\ncargo build --release -p terraphim_mcp_server --features jmap\ncp target/release/terraphim_mcp_server ~/.cargo/bin/terraphim_mcp_server\nFor 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.
opencode -- add to ~/.config/opencode/opencode.json under mcp:
"terraphim": { "type": "local", "command": ["/Users/alex/.cargo/bin/terraphim_mcp_server"] },\n"terraphim-pa": { "type": "local", "command": ["/Users/alex/bin/terraphim_mcp_server-pa"] }\nClaude Code -- one shell command per server:
\nclaude mcp add terraphim /Users/alex/.cargo/bin/terraphim_mcp_server\nclaude mcp add terraphim-pa /Users/alex/bin/terraphim_mcp_server-pa\nclaude mcp list # both should show as Connected\nThe model now sees mcp__terraphim__search and mcp__terraphim_pa__search (plus the autocomplete tools) in its tool list.
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'\nprintf ' Terraphim Engineer (Rust/agent KG)\\n'\nprintf ' Personal Assistant (Obsidian + Fastmail JMAP, use terraphim-agent-pa for email)\\n'\nprintf ' System Operator (INCOSE/MBSE Logseq KG)\\n'\nprintf ' Context Engineering Author, Rust Engineer, Default\\n'\nEquivalent hook in opencode. Cost: one screen of context per session. Benefit: the model picks the right role on the first try instead of guessing.
\n| 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.
\nYou 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.
\nMost \"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.
\nYesterday 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.
\n# Build (or install the published crate when JMAP feature lands on crates.io)\ncd ~/projects/terraphim/terraphim-ai\ncargo install --path crates/terraphim_agent --features jmap\n\n# Configure roles -- copy the snippets from the how-tos linked below\n$EDITOR ~/.config/terraphim/embedded_config.json\n\n# Install the slash command\nmkdir -p ~/.claude/commands ~/.config/opencode/command\ncp ~/projects/terraphim/terraphim-ai/docs/src/howto/mcp-integration-claude-opencode.md \\\n /tmp/tsearch.md # adapt to your slash command file shape\n\n# Reload roles\nterraphim-agent config reload\n\n# Try\nterraphim-agent search --role "Terraphim Engineer" --limit 3 "rolegraph"\nStep-by-step in the docs: Plug Terraphim Search into Claude Code and opencode.
\nFor the underlying engine, start with Why Graph Embeddings Matter. For the two roles this integration most cleanly exposes, see Personal Assistant and System Operator.
\n", "https://terraphim.ai/properties/date" : "2026-04-18", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","claude-code","opencode","mcp","knowledge-graph","developer-tools","integration"],"categories":["Technical"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/disciplined-engineering-ai-systems/", "https://atomicdata.dev/properties/name" : "Disciplined Engineering: How We Build AI Systems That Actually Work", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/disciplined-engineering-ai-systems/", "https://atomicdata.dev/properties/description" : "AI coding agents are making us worse engineers, unless we add discipline back. Here is what we do instead of vibe coding, and how you can do it too in 30 seconds.
\nUp until last week, terraphim-skills was open source. You could install the whole set with one command via skills.sh. Then I ran a comparison: our skills against Andrej Karpathy's, against derivatives of Karpathy's, and against a no-skills control. For the first time in my life I clicked \"Make private\" on a public repository.
Even on the first batch of tests, our approach beat both Karpathy's and the control:
\nWe control the flow and we control the cost, because we are not an AI lab and we are not a VC-funded startup burning tokens to chase a leaderboard. We are a consultancy getting things done with AI and building AI.
\nThe results speak for themselves. A few weeks ago I read a story about an autoresearch agent that achieved a speedup on the Liquid (Rails) parser. I had a slow markdown parser inside this very project. I ran our disciplined loop on it. Twice. Result: a 400x to 900x speedup in parsing.
\nHere is how.
\nEvery AI-generated pull request we review has the same pattern:
\nThe agent shipped code. It even passed the tests. But the tests were written by the same agent that wrote the code, optimising for the metric rather than understanding the problem.
\nThe missing piece is not better models. It is engineering discipline. AI agents need the same rigour humans use: understand the problem before coding, verify against the design, validate against requirements. We encoded this as executable skills that any AI coding agent can follow.
\n\n\nThe research evidence behind this framework, including language-specific scaling laws and the 30% adoption gap between code intelligence research and production harnesses, is the subject of our next article.
\n
We built a V-model for AI agents. The left side asks \"what should we build?\" The right side asks \"did we build it correctly?\"
\n![\"The](\"/images/v-model-overview.png\")
Before writing any code, the agent must understand the problem space:
\nCreate a specification before implementation:
\nWrite code with tests from the start:
\nVerify against the design, not just tests:
\nValidate against the original requirements:
\nWe packaged the V-model as executable skills for any AI coding agent. As of May 2026 the repository is private (see the update at the top of this post) and the skills.sh installer has been retired. The framework is now deployed as part of our consulting engagements at zestic.ai.
The skills enforce:
\nEach skill is a self-contained prompt that guides the agent through the phase's inputs, outputs, and quality gates.
\nOur judge system (Kimi K2.5) catches what humans miss:
\nAutomated quality gates, zero manual overhead. Every PR reviewed before it merges.
\nAI agents do not type commands into a terminal. They invoke tools programmatically, and they do not always get it right. \"Cleaning up build artefacts\" becomes rm -rf ./src (one-character typo). \"Resetting to last commit\" becomes git reset --hard (uncommitted work gone). You need a safety net that operates between the agent and your shell.
We use two layers of guard rails:
\nLayer 1: git-safety-guard (a terraphim-skill that runs as a PreToolUse hook):
\ngit reset --hard, git push --force, rm -rf and similar destructive commands before they execute**Layer 2: Destructive Command Guard (DCG) by Jeff Emanuel, integrated via tool hooks:
\nThe architecture is simple: the agent calls a bash tool, the hook pipes the command to DCG as JSON, DCG pattern-matches against known destructive commands, and blocks execution before damage occurs. The agent receives an error explaining why, and can adjust its approach.
\nWe run 12+ AI agents overnight on a single machine, coordinated by a Rust orchestrator. Each agent follows the V-model:
\nEvery agent's output passes through the judge system before merge. The morning routine is reviewing verdicts, not debugging overnight chaos. When an agent produces a NO-GO verdict, the PR is flagged with the specific issues: missing test coverage, undocumented API changes, or security concerns.
\nThis is disciplined engineering at scale: not process overhead, but automated quality gates that catch problems before they compound.
\nThe gap between what AI agents can do and what they should do is real. It is not a technology gap: it is a discipline gap. The V-model and the 32+ executable skills we built are now part of our consulting work rather than an open repository.
\nAdd discipline back. If you want it inside your team, get in touch at zestic.ai.
\nDeeper dive: The V-model and quality gates we use are detailed in Chapters 3-4 of \"Context Engineering with Knowledge Graphs\". Coming soon.
\nRelated posts:
\nAI coding assistants are fast, productive, and occasionally catastrophic. One misplaced rm -rf, one accidental git reset --hard, and hours of uncommitted work vanish.
Jeffrey Emanuel (@Dicklesworthstone) built Destructive Command Guard (dcg): a Rust binary with SIMD-accelerated pattern matching, 49+ security packs, and a fail-open design. It is one of the best tools to come out of the AI agent safety space, and it solved a problem we had been fighting with regex hacks.
\nThis post shows how we integrated dcg with OpenCode using its plugin hook system, so destructive commands are intercepted before they run.
\nAI agents do not type commands into a terminal. They invoke tools programmatically, and they do not always get it right:
\nrm -rf ./src (one-character typo)git reset --hard (uncommitted work gone)git push --force (team history destroyed)You need a safety net that operates between the agent and your shell.
\nOpenCode v1.4+ exposes a plugin hook system. Hooks are top-level keys on the Hooks interface:
interface Hooks {\n "tool.execute.before"?: (input, output) => Promise<void>;\n "tool.execute.after"?: (input, output) => Promise<void>;\n}\nThe \"tool.execute.before\" hook fires before every tool call. It receives the tool name and arguments, and can throw an error to abort execution. This is exactly where a command guard belongs.
DCG is Jeffrey's Rust binary that reads a JSON payload from stdin and exits 0 (allow) or 2 (block). Our contribution was the plugin that wires dcg into OpenCode's hook system:
OpenCode agent\n |\n | calls bash tool: "rm -rf ./build"\n v\n"tool.execute.before" hook\n |\n | spawns: echo '{"tool":"bash","args":{"command":"rm -rf ./build"}}' | dcg\n v\ndcg (Rust, SIMD-accelerated pattern matching)\n |\n | exit code 2 + reason on stderr\n v\nhook throws Error --> command never executes\nThe complete plugin is roughly 60 lines:
\nimport { spawn } from 'child_process';\n\nconst callDcgHook = (toolCall) => {\n return new Promise((resolve, reject) => {\n const dcg = spawn('dcg', [], {\n env: { ...process.env, DCG_FORMAT: 'json' }\n });\n\n let stdout = '';\n let stderr = '';\n\n dcg.stdout.on('data', (data) => { stdout += data.toString(); });\n dcg.stderr.on('data', (data) => { stderr += data.toString(); });\n\n dcg.on('close', (code) => {\n if (code === 0) {\n try { resolve(JSON.parse(stdout)); }\n catch { resolve({ allowed: true }); }\n } else {\n reject(new Error(stderr || 'dcg blocked command'));\n }\n });\n\n dcg.stdin.write(JSON.stringify(toolCall));\n dcg.stdin.end();\n });\n};\n\nexport const DcgGuard = async ({ client }) => {\n return {\n "tool.execute.before": async (input, output) => {\n if (input.tool !== 'bash') return;\n\n const toolCall = {\n tool: 'bash',\n args: { command: output.args.command }\n };\n\n try {\n await callDcgHook(toolCall);\n } catch (error) {\n throw new Error(\n `dcg blocked destructive command: ${output.args.command}\\n\\n` +\n `${error.message}\\n\\n` +\n `This command was blocked to protect your system.`\n );\n }\n }\n };\n};\nThe original plugin used a nested structure:
\nreturn {\n tool: {\n execute: {\n before: async (input, output) => { ... }\n }\n }\n};\nThis looks intuitive but is wrong. In OpenCode's plugin API, tool is reserved for registering new tools (each needing a description, args, and execute function). The hook \"tool.execute.before\" is a top-level dotted key on the Hooks object, not a nested path.
The fix:
\nreturn {\n "tool.execute.before": async (input, output) => { ... }\n};\nThis distinction matters. OpenCode iterates over tool entries expecting ToolDefinition objects. When it found { before: ... } instead, it called .execute(args, ctx) on it, which was undefined. Hence the error: def.execute is not a function.
| Category | Examples |
|---|---|
| Git history destruction | git reset --hard, git push --force, git branch -D |
| Uncommitted work loss | git checkout — ., git restore file, git clean -f |
| Stash destruction | git stash drop, git stash clear |
| Filesystem damage | rm -rf outside /tmp |
| Database operations | DROP TABLE, FLUSHALL (via packs) |
| Container destruction | docker system prune, docker-compose down --volumes |
| Infrastructure | terraform destroy, kubectl delete namespace |
Safe operations pass through silently: git status, git add, git commit, git push (without --force), git stash, git checkout -b, and all non-destructive commands.
Default-allow. Unrecognised commands pass through. DCG blocks only known dangerous patterns. This prevents false positives from blocking legitimate work.
\nWhitelist-first. Safe patterns (like git checkout -b) are checked before destructive patterns. Explicitly safe commands are never accidentally blocked.
Sub-millisecond latency. Jeffrey's implementation uses SIMD-accelerated substring search via Rust's memchr crate. Commands without \"git\" or \"rm\" bypass regex matching entirely. The guard adds no perceptible delay.
Fail-open. If dcg crashes or produces unexpected output, the plugin catches the error and defaults to allowing the command. A broken guard should never break your workflow. A safety system that slows down the developer will be disabled by the third day. A safety system that is invisible will run forever.
\nDCG ships with a modular pack system. Enable additional protection categories in ~/.config/dcg/config.toml:
[packs]\nenabled = [\n "database.postgresql",\n "containers.docker",\n "kubernetes",\n "cloud.aws",\n]\nOr via environment variable:
\nexport DCG_PACKS="containers.docker,kubernetes"\n# 1. Install dcg\ncurl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/master/install.sh" | bash\n\n# 2. Install the plugin\nmkdir -p ~/.config/opencode/plugin\ncurl -fsSL https://raw.githubusercontent.com/jms830/opencode-dcg-plugin/main/plugin/dcg-guard.js \\\n -o ~/.config/opencode/plugin/dcg-guard.js\n\n# 3. Restart OpenCode\nThe OpenCode plugin API's \"tool.execute.before\" hook is a clean interception point for safety guards. Combined with Jeffrey Emanuel's dcg and its fast pattern matching, you get protection against destructive commands with zero workflow friction. The plugin is small, the guard is fast, and the safety net catches the mistakes that matter.
Instructions are suggestions. Guards are guarantees.
\nDCG is built by Jeffrey Emanuel — see his destructive_command_guard repository and the broader agentic coding flywheel ecosystem for more agent safety tooling.
\nThis post is part of the Disciplined Engineering series. See also: Teaching AI Agents with Knowledge Graph Hooks and Teaching AI Agents to Learn from Their Mistakes.
\nSource: DCG plugin gist and opencode-dcg-plugin repository
\n", "https://terraphim.ai/properties/date" : "2026-04-17", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","ai","opencode","developer-tools","rust","safety","coding-agents"],"categories":["Technical"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/personal-assistant-role-jmap-obsidian/", "https://atomicdata.dev/properties/name" : "Personal Assistant Role: One Search Across Email and Notes", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/personal-assistant-role-jmap-obsidian/", "https://atomicdata.dev/properties/description" : "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.
\nThe 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:
\nRipgrep service. Plain markdown, sub-millisecond local search, no daemon.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.
terraphim-agent-pa search \"<query>\" returns mixed hits ordered by rank.~/.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.
\nThe 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 \\\n --env-file=<(echo 'JMAP_ACCESS_TOKEN=op://VAULT/ITEM/credential') \\\n -- /Users/alex/.cargo/bin/terraphim-agent "$@"\nWrap 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.
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.
\nThe end-to-end how-to is in the docs: install the prerequisites, add the JSON snippet, write the wrapper, run three verification queries.
\nRead the how-to: Personal Assistant Role on docs.terraphim.ai
\nOne 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.
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.
\nIf 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.
\n", "https://terraphim.ai/properties/date" : "2026-04-17", "https://terraphim.ai/properties/tags" : {"categories":["Technical"],"tags":["Terraphim","personal-assistant","jmap","obsidian","knowledge-graph","fastmail"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/system-operator-logseq-knowledge-graph/", "https://atomicdata.dev/properties/name" : "System Operator Demo: A Logseq Knowledge Graph Drives Enterprise MBSE Search", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/system-operator-logseq-knowledge-graph/", "https://atomicdata.dev/properties/description" : "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.
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:
RFP, the automaton normalises it to acquisition need because that is what the handbook calls 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\nThen either drive the role via the server --
\ncargo run --bin terraphim_server -- \\\n --config terraphim_server/default/system_operator_config.json\ncurl "http://127.0.0.1:8000/documents/search?q=RFP&role=System%20Operator&limit=5"\n-- or via the terraphim-agent CLI after adding the role entry to ~/.config/terraphim/embedded_config.json:
terraphim-agent config reload\nterraphim-agent search --role "System Operator" --limit 5 "RFP"\nThe full config snippet and the embedded_config.json entry are in the README_SYSTEM_OPERATOR.md.
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?
\nTerraphim 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 \\\n "RFP business analysis life cycle model business requirements documentation tree"\n\nConnectivity Check for role 'System Operator':\n Connected: false\n Matched terms: ["acquisition need", "business or mission analysis",\n "business requirements", "documentation tree",\n "life cycle concepts"]\nFive 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.
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:
\n| 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.
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.
\ngit clone https://github.com/terraphim/terraphim-ai\ncd terraphim-ai\n./scripts/setup_system_operator.sh\ncargo run --bin terraphim_server -- \\\n --config terraphim_server/default/system_operator_config.json\nOr 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.
\n", "https://terraphim.ai/properties/date" : "2026-04-17", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","system-operator","logseq","knowledge-graph","mbse","systems-engineering"],"categories":["Technical"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/teaching-ai-agents-to-learn-from-mistakes/", "https://atomicdata.dev/properties/name" : "Teaching AI Agents to Learn from Their Mistakes", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/teaching-ai-agents-to-learn-from-mistakes/", "https://atomicdata.dev/properties/description" : "AI coding agents make the same mistakes over and over. We built a learning system that captures failures, stores corrections, and feeds them back into future sessions — turning every error into institutional memory.
\n\n\nBuilds on Why Graph Embeddings Matter — the deterministic engine that makes \"remember this correction forever\" cheap. Apply the pattern in your own project via the Command Rewriting How-to.
\n
Every AI coding agent session starts from zero. Claude Code runs npm install, gets corrected, switches to bun — and tomorrow does it again. A force-push to main gets blocked, the agent learns why, then forgets by next session.
In our previous post on Knowledge Graph Hooks, we showed how Aho-Corasick automata can intercept and transform agent commands in real time. But interception is reactive. What if the agent could remember its past failures and avoid repeating them?
\nTerraphim's learning system operates as a closed loop with three stages:
\nFailed Command --> PostToolUse Hook --> Learning Store --> Query at Session Start\nA PostToolUse hook fires after every tool execution in Claude Code. When a command exits with a non-zero status, the hook calls terraphim-agent learn hook, which persists the failure as a structured markdown file:
---\nid: 6b99a8924fad4f2aaeadf5450e76730c\ncommand: npm install react\nexit_code: 127\nsource: Global\ncaptured_at: 2026-04-04T18:43:07+00:00\n---\nThe hook is fail-open — if terraphim-agent is unavailable, it exits silently. Development is never blocked.
Raw failures are useful, but corrections make them actionable. Any developer (or the agent itself) can attach a correction:
\n$ terraphim-agent learn correct <id> --correction "Use 'bun add react' instead"\nThe learning file is updated in place:
\n---\nid: 6b99a8924fad4f2aaeadf5450e76730c\ncommand: npm install react\nexit_code: 127\ncorrection: "Use 'bun add react' instead"\n---\nAt the start of a session, or when encountering a familiar error, the agent queries the learning store:
\n$ terraphim-agent learn query "npm"\n\nLearnings matching 'npm'.\n [G] [cmd] npm install lodash (exit: 1)\n Correction: Use 'bun add lodash' instead. Terraphim hooks enforce bun over npm.\n [G] [cmd] npm install react (exit: 127)\n Correction: Use bun instead of npm/yarn/pnpm. 'bun add react' or 'bun install'.\nThe agent sees past mistakes with their corrections before taking action. No more Groundhog Day.
\nThe PostToolUse hook is a shell script that receives JSON from Claude Code on stdin after every Bash tool call:
\n#!/bin/bash\nset -euo pipefail\n\n# Find terraphim-agent binary\nAGENT="$HOME/.cargo/bin/terraphim-agent"\n[ -x "$AGENT" ] || exit 0 # Fail-open\n\n# Read tool result from stdin\nINPUT=$(cat)\n\n# Capture failures as learnings\n$AGENT learn hook --format claude <<< "$INPUT" 2>/dev/null || true\nThe learn hook subcommand parses the Claude Code tool result format, extracts the command and exit code, and writes a learning file only when the exit code is non-zero.
| Signal | Captured? | Example |
|---|---|---|
| Non-zero exit code | Yes | npm install (exit 127) |
| Force push attempts | Yes | git push --force origin main (exit 1) |
| Compilation errors | Yes | cargo build (exit 101) |
| Successful commands | No | Only failures are stored |
| Duplicate failures | Deduplicated | Same command + exit code within a session |
Here is actual data from our production learning store, accumulated across weeks of development sessions:
\nPackage manager enforcement — 3 npm entries, all corrected to bun:
\n[G] [cmd] npm install lodash (exit: 1)\n Correction: Use 'bun add lodash' instead.\n[G] [cmd] npm install react (exit: 127)\n Correction: Use bun instead of npm/yarn/pnpm.\nGit safety — 29 push failures captured, including one critical correction:
\n[G] [cmd] git push --force origin main (exit: 1)\n Correction: NEVER force push to main. Use feature branches and PRs.\nThese corrections are not just documentation. They are queryable institutional memory that agents consult before repeating the same mistakes.
\nThe learning system complements the Knowledge Graph Hooks we described previously. Together they form two layers of defence:
\n| Layer | Mechanism | Timing |
|---|---|---|
| Prevention | KG hooks intercept npm install and replace with bun install | Before execution |
| Learning | PostToolUse hook captures failures that slip through | After execution |
If a new pattern appears that the knowledge graph does not cover, the learning system captures it. A developer adds a correction. Optionally, the pattern gets promoted to a knowledge graph entry for permanent interception.
\nNew failure captured --> Correction added --> Pattern promoted to KG --> Hook intercepts automatically\nLearning files are stored as markdown in ~/Library/Application Support/terraphim/learnings/ (macOS) or ~/.local/share/terraphim/learnings/ (Linux). Each file is a standalone document:
---\nid: 1c8a4548-1434-a346-cd641131202a\ncommand: git push --force origin main\nexit_code: 1\nsource: Global\ncaptured_at: 2026-04-02T15:31:20+00:00\ncorrection: NEVER force push to main. Use feature branches and PRs.\n---\n\n## Command\n\n`git push --force origin main`\n\n## Error Output\n\nrejected
\n\n## Suggested Correction\n\n`NEVER force push to main. Use feature branches and PRs.`\nBeing plain markdown, these files are:
\n# List recent learnings\nterraphim-agent learn list\n\n# Query by pattern (full-text search)\nterraphim-agent learn query "pattern"\n\n# Add correction to a learning\nterraphim-agent learn correct <id> --correction "what to do instead"\n\n# Hook mode (called by PostToolUse, reads JSON from stdin)\nterraphim-agent learn hook --format claude\nCreate ~/.claude/hooks/post_tool_use.sh:
#!/bin/bash\nset -euo pipefail\nAGENT="$HOME/.cargo/bin/terraphim-agent"\n[ -x "$AGENT" ] || exit 0\nINPUT=$(cat)\n$AGENT learn hook --format claude <<< "$INPUT" 2>/dev/null || true\nAdd to .claude/settings.json:
{\n "hooks": {\n "PostToolUse": [{\n "matcher": "Bash",\n "hooks": [{\n "type": "command",\n "command": "~/.claude/hooks/post_tool_use.sh"\n }]\n }]\n }\n}\nFailed commands are captured automatically. Query them with terraphim-agent learn query.
The learning system is the foundation for richer agent memory:
\nterraphim-agent sessions search already indexes learnings alongside session transcriptsThe goal is not to make agents perfect on the first try. It is to make them incapable of making the same mistake twice.
\nAI coding agents are powerful but amnesiac. Every session starts fresh, every mistake is rediscovered. Terraphim's learning capture system closes this gap with a simple, fail-open hook that turns failures into institutional memory.
\nThe pattern is straightforward: capture failures automatically, attach corrections manually, query before acting. No training required, no model fine-tuning, no prompt engineering beyond what you already do.
\nYour agents will still make mistakes. They just will not make the same mistakes.
\nYou know what is embarrassing? Making the same mistake for the tenth time. Last week, I typed docker-compose up instead of docker compose up. The command failed. I sighed. I corrected it. Three days later? Same thing. Same sigh. Same correction.
\n\nBuilds on Why Graph Embeddings Matter — the deterministic engine that lets Terraphim store and replay corrections in microseconds. Apply the pattern in your own project via the Command Rewriting How-to.
\n
This is not just about typos. Developers repeat the same failed patterns constantly:
\ngit push -f when they should use git push --force-with-leasecargo run when cargo build would catch the error fasternpm install instead of yarn install (or vice versa, depending on your project)apt-get commands without sudops aux | grep returned too many resultsThe AI agents we use? They are even worse. Claude Code, Codex, Cursor: they all make the same mistakes, over and over, because they have no long-term memory of what went wrong.
\nWe are not learning from our failures. We are just repeating them.
\nWhat if your terminal learned from every failed command?
\nThat is exactly what Terraphim's Learning via Negativa system does. It captures every failed command, extracts the mistake pattern, and builds a knowledge graph that corrects you in real-time.
\nThe name comes from the Latin \"per negativa\": learning by knowing what is wrong. It is the pedagogical equivalent of \"do not touch the hot stove\" after you have already touched it.
\nHere is how it works:
\nYou type "docker-compose up"\n |\nCommand fails (docker-compose is deprecated)\n |\nHook captures: command + error + context\n |\nKnowledge graph maps: "docker-compose" -> "docker compose"\n |\nNext time: Terraphim auto-replaces and suggests the correct command\nThis is not a wrapper script or a hack. It is a native Rust system built into terraphim-agent that captures, stores, and corrects command mistakes.
The hook intercepts failed commands from your AI agent:
\n// crates/terraphim_agent/src/learnings/capture.rs\n\nuse serde::{Deserialize, Serialize};\n\n#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct FailedCommand {\n pub command: String,\n pub exit_code: i32,\n pub stderr: String,\n pub working_directory: String,\n pub timestamp: DateTime<Utc>,\n pub tags: Vec<String>,\n}\n\n/// Capture a failed command and extract the mistake pattern\npub async fn capture_failed_command(\n command: &str,\n exit_code: i32,\n stderr: &str,\n context: &CommandContext,\n) -> Result<FailedCommand, CaptureError> {\n // Only capture non-zero exit codes (actual failures)\n if exit_code == 0 {\n return Err(CaptureError::CommandSucceeded);\n }\n\n // Filter out test commands: we do not learn from intentional failures\n if is_test_command(command) {\n return Err(CaptureError::TestCommand);\n }\n\n // Extract mistake patterns from the command\n let tags = extract_mistake_tags(command, stderr);\n\n let failed = FailedCommand {\n command: redact_secrets(command),\n exit_code,\n stderr: stderr.clone(),\n working_directory: context.cwd.clone(),\n timestamp: Utc::now(),\n tags,\n };\n\n // Store as markdown for human readability\n store_learning(&failed).await?;\n\n Ok(failed)\n}\nThe hook is fail-open by design: never blocks your workflow if capture fails.
\nOnce captured, mistakes become nodes in a knowledge graph that maps wrong to correct:
\n// crates/terraphim_rolegraph/examples/learning_via_negativa.rs\n\nuse terraphim_rolegraph::RoleGraph;\nuse terraphim_types::{NormalizedTerm, NormalizedTermValue, Thesaurus};\n\n/// Build knowledge graph for command corrections\nfn build_correction_thesaurus() -> Thesaurus {\n let mut thesaurus = Thesaurus::new("Command Corrections".to_string());\n\n // Docker corrections\n thesaurus.insert(\n NormalizedTermValue::new("docker-compose up".to_string()),\n NormalizedTerm::new(1, NormalizedTermValue::new(\n "docker compose up".to_string()\n )),\n );\n\n // Git corrections\n thesaurus.insert(\n NormalizedTermValue::new("git push -f".to_string()),\n NormalizedTerm::new(2, NormalizedTermValue::new(\n "git push --force-with-lease".to_string()\n )),\n );\n\n // Cargo corrections\n thesaurus.insert(\n NormalizedTermValue::new("cargo buid".to_string()),\n NormalizedTerm::new(3, NormalizedTermValue::new(\n "cargo build".to_string()\n )),\n );\n\n thesaurus\n}\nThe correction happens automatically via Terraphim's replace tool:
\n# Without Learning via Negativa (old workflow)\n$ docker-compose up\ndocker-compose: command not found\n# You: sigh, retype, move on\n\n# With Learning via Negativa\n$ docker-compose up\n# Terraphim intercepts, corrects, and shows:\nSuggestion: Did you mean 'docker compose up'? (y/n)\n# You: y, command executes correctly\nWe tested Learning via Negativa with common developer mistakes over a 30-day period:
\n| Wrong Command | Error | Correction Learned |
|---|---|---|
docker-compose up | command not found | docker compose up |
git push -f | remote: denied by protection policy | git push --force-with-lease |
cargo buid | error: no such subcommand | cargo build |
npm isntall | command not found | npm install |
apt update | Permission denied | sudo apt update |
git psuh | git: 'psuh' is not a git command | git push |
Week 1: 12 corrections captured\nWeek 2: 34 corrections captured (cumulative)\nWeek 3: 58 corrections captured (cumulative)\nWeek 4: 89 corrections captured (cumulative)\n\nTop mistake categories:\n - Docker commands: 28%\n - Git commands: 24%\n - Cargo/Rust: 18%\n - npm/yarn: 15%\n - System commands: 15%\nMost AI tools have no memory. Claude Code is brilliant but stateless. Cursor remembers your files, not your mistakes. GitHub Copilot suggests code but forgets that docker-compose has been deprecated for two years.
Learning via Negativa gives your AI agent a memory for failure.
\nIt transforms every error from a one-time annoyance into a permanent lesson. The more you use it, the smarter it gets. And because it is built on the knowledge graph architecture, it does not just match strings: it understands context.
\nYou typed git push -f in a repo with protected branches? It learns that -f is wrong in that context. You use docker-compose in a project with a compose.yaml file? It learns the new syntax applies here.
# Install terraphim-agent\ncargo install terraphim_agent --features repl-full\n\n# Install the learning hook for Claude Code\nterraphim-agent learn install-hook claude\n\n# Verify it is working\nterraphim-agent learn list\n\n# Query your mistakes anytime\nterraphim-agent learn query "your mistake"\n\n# Or use the replace tool for real-time corrections\necho "docker-compose up" | terraphim-agent replace\nLearning via Negativa is more than a feature: it is a philosophy. Every failure contains information. Every error message is feedback. The trick is capturing that signal instead of just ignoring the noise.
\nWe have spent decades building systems that celebrate successes. It is time we built systems that learn from failures too.
\nYour terminal should remember what you keep getting wrong. That is not just smart: that is how humans actually learn.
\ncrates/terraphim_agent/src/learnings/crates/terraphim_rolegraph/examples/learning_via_negativa.rsTerraphim: Your AI agent's memory for mistakes.
\n", "https://terraphim.ai/properties/date" : "2026-02-20", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","rust","cli","ai-agents","developer-tools","learning","knowledge-graph"],"categories":["Technical"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/multi-haystack-roles-grepapp/", "https://atomicdata.dev/properties/name" : "Introducing Multi-Haystack Roles: Local + Global Code Search", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/multi-haystack-roles-grepapp/", "https://atomicdata.dev/properties/description" : "Today we are announcing a significant enhancement to Terraphim's engineer roles: multi-haystack support. FrontEnd Engineers and Python Engineers now have access to both local code search (via Ripgrep) and global GitHub search (via GrepApp) in a single query.
\nTraditionally, developers face a frustrating choice when searching for code:
\nWhen you are stuck on \"how do I use this library?\" or \"what's the idiomatic way to solve this?\", you need both: your local context for project-specific code, and global examples from the broader community.
\nStarting with Terraphim v1.8.1, select engineer roles now come with dual haystacks:
\n~/projects or custom path)~/projects or custom path)When you search as a FrontEnd or Python Engineer, Terraphim queries both sources simultaneously:
\nYour Query: "how to use useEffect"\n |\n+-------------------+ +--------------------+\n| Local Ripgrep | | GrepApp |\n| (your code) | | (GitHub repos) |\n+---------+---------+ +---------+----------+\n | |\n +-----------+-------------+\n |\n Combined Results\n (ranked by relevance)\nThe results are merged and ranked according to your role's relevance function:
\nThis means you get the best of both worlds: your project's specific implementations AND real-world examples from popular repositories.
\nYou are trying to use react-query for the first time. A single search shows:
You are debugging a Python asyncio issue. Your search returns:
\nYou want to know the \"Pythonic\" way to do something. Instead of reading docs, you can see:
\nUnder the hood, this uses our existing GrepApp integration:
\nHaystack {\n location: "https://grep.app".to_string(),\n service: ServiceType::GrepApp,\n read_only: true,\n fetch_content: false,\n extra_parameters: {\n let mut params = HashMap::new();\n params.insert("language".to_string(), "python".to_string());\n params\n },\n}\nThe extra_parameters field allows language-specific filtering:
language=javascriptlanguage=pythonGrepApp returns structured results from millions of GitHub repositories, complete with:
\nWe know network availability is not guaranteed. If GrepApp is unreachable:
\nThis follows our philosophy: local-first, enhance with global.
\nThis is just the beginning. We are planning:
\nMore roles with dual haystacks:
\nConfigurable filters:
\nEnhanced ranking:
\nIf you are already using Terraphim v1.8.1+, you can try the new roles immediately:
\n# Switch to FrontEnd Engineer (with dual haystack)\nterraphim-agent onboard --role frontend-engineer\n\n# Switch to Python Engineer (with dual haystack)\nterraphim-agent onboard --role python-engineer\n\n# Search as usual: both local and global results appear\nterraphim-agent search "async def"\nMulti-haystack roles represent a fundamental shift in how we think about code search:
\nOld model: One haystack per role, choose your scope\nNew model: Multiple haystacks per role, get comprehensive results
\nThis aligns with how developers actually work: they do not want to choose between \"my code\" and \"the world's code\" — they want both, intelligently combined.
\nAs we expand this pattern to more roles and add more haystack types (MCP servers, Atomic Data, AI assistants), Terraphim becomes not just a search tool, but a knowledge synthesis engine for developers.
\nHave ideas for other haystack combinations? Want to see this pattern applied to other roles? Let us know:
\nRelated Reading:
\n\nTerraphim: Search your world.
\n", "https://terraphim.ai/properties/date" : "2026-02-16", "https://terraphim.ai/properties/tags" : {"categories":["Technical"],"tags":["Terraphim","release","features","grepapp","haystack","code-search"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/native-hook-support/", "https://atomicdata.dev/properties/name" : "Native Hook Support: terraphim-agent Now Learns from Your Mistakes", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/native-hook-support/", "https://atomicdata.dev/properties/description" : "\n\nThis is the February 2026 announcement for v1.8.1. For the tested failure → reviewed correction → execution flow, follow the current command-rewriting guide.
\n
We are announcing native hook support for terraphim-agent v1.8.1. This feature captures failed commands from AI agents (Claude Code, Codex, OpenCode) and learns from them, creating a personal knowledge base of mistakes and corrections. No more jq dependency, no more bash wrappers: just terraphim-agent learn hook.
If you are using AI agents like Claude Code, you have probably experienced this:
\ncargo buid (typo)cargo buildEvery developer has their own \"greatest hits\" of mistakes:
\nnpm isntall instead of npm installgit psuh instead of git pushpip intall instead of pip installThese mistakes are personal, contextual, and valuable: if only we could remember them.
\nWith terraphim-agent v1.8.1, we have introduced a complete learning system:
\n# One-command setup\nterraphim-agent learn install-hook claude\n\n# That's it. Every failed command is now captured automatically.\nClaude Code executes Bash command\n |\nCommand fails (exit code != 0)\n |\nHook captures: command + error + context\n |\nStored as Markdown: ~/.local/share/terraphim/learnings/\n |\nQuery anytime: terraphim-agent learn query "cargo buid"\n1. Native Implementation
\n2. Universal Support\nWorks with Claude Code, Codex, and OpenCode:
\nterraphim-agent learn install-hook claude\nterraphim-agent learn install-hook codex\nterraphim-agent learn install-hook opencode\n3. Fail-Open Design\nNever blocks your workflow. If capture fails, the command still executes.
\n4. Smart Filtering
\ncargo test, npm test)5. Rich Context\nEach learning includes:
\nLet us prove it works with a realistic scenario:
\n$ terraphim-agent setup --template rust-engineer-v2\nConfiguration set to role 'Rust Engineer v2'\n# Simulate Claude Code making a typo\necho '{"tool_name":"Bash","tool_input":{"command":"cargo buid"},...}' \\\n | ~/.config/claude/terraphim-hook.sh\n$ terraphim-agent learn list\nRecent learnings:\n 1. [G] cargo buid (exit: 101)\n$ terraphim-agent learn query "cargo buid"\nLearnings matching 'cargo buid':\n [G] cargo buid (exit: 101)\nWe have also added 4 new engineer role templates, each with different ranking methods:
\n| Role | Ranking | Use Case |
|---|---|---|
| FrontEnd Engineer | BM25Plus | JavaScript/TypeScript development |
| Python Engineer | BM25F | Python with field-weighted ranking |
| Rust Engineer v2 | TitleScorer | Dual haystack (docs.rs + local) |
| Terraphim Engineer v2 | TerraphimGraph | Graph embeddings + hybrid KG |
Each role learns differently and optimises search for its domain.
\n+-------------------------------------------------------------+\n| 1. LEARN |\n| Command fails -> Hook captures -> Markdown stored |\n| Works with Claude, Codex, OpenCode |\n+-------------------------------------------------------------+\n| 2. QUERY |\n| Search patterns -> Find similar mistakes |\n| Pattern matching on command + error |\n+-------------------------------------------------------------+\n| 3. CORRECT |\n| Add corrections: learn correct <id> --correction |\n| Future: Auto-suggest from knowledge graph |\n+-------------------------------------------------------------+\n| 4. REPLACE |\n| Real-time suggestions via replace --role <role> |\n| Uses thesaurus for context-aware corrections |\n+-------------------------------------------------------------+\n# Install latest terraphim-agent\ncargo install terraphim_agent --features repl-full\n\n# Install hook for your AI agent\nterraphim-agent learn install-hook claude\n\n# Verify installation\nterraphim-agent learn --help\nThis release passed rigorous quality gates:
\n# Install\ncargo install terraphim_agent --features repl-full\n\n# Set up your role\nterraphim-agent setup --template rust-engineer-v2\n\n# Install hook\nterraphim-agent learn install-hook claude\n\n# Start learning from your mistakes\nTerraphim: Your AI agent's memory for mistakes.
\n", "https://terraphim.ai/properties/date" : "2026-02-16", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","rust","cli","ai-agents","developer-tools","learning"],"categories":["Technical"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/zvec-vs-terraphim-comparison/", "https://atomicdata.dev/properties/name" : "zvec vs Terraphim: Two Paths to Semantic Search", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/zvec-vs-terraphim-comparison/", "https://atomicdata.dev/properties/description" : "When it comes to semantic search, there are fundamentally different architectural approaches. Alibaba's zvec and Terraphim represent two distinct philosophies: neural embeddings vs. knowledge graphs, scale vs. interpretability, dense vectors vs. co-occurrence relationships.
\nzvec is a lightweight, in-process vector database built on Alibaba's battle-tested Proxima engine. It transforms documents into high-dimensional vectors using neural embedding models (BERT, OpenAI, etc.), then uses Approximate Nearest Neighbour (ANN) algorithms like HNSW to find similar documents.
\nKey Characteristics:
\nTerraphim takes a radically different approach. Instead of converting documents to opaque vectors, it builds a knowledge graph from term co-occurrences. Each concept becomes a node, relationships become edges, and relevance is calculated by traversing this graph structure.
\nKey Characteristics:
\n+-------------------------------------------------------------+\n| zvec |\n+-------------------------------------------------------------+\n| Document -> Neural Encoder -> Dense Vector -> HNSW Index |\n| | |\n| Query -> Neural Encoder -> Query Vector -> ANN Search -> K |\n+-------------------------------------------------------------+\n vs\n+-------------------------------------------------------------+\n| Terraphim |\n+-------------------------------------------------------------+\n| Document -> Term Extraction -> Co-occurrence -> Graph |\n| | |\n| Query -> Aho-Corasick Match -> Graph Traversal -> Ranked |\n+-------------------------------------------------------------+\n| Component | zvec | Terraphim |
|---|---|---|
| Storage Unit | Collection (table-like) | RoleGraph (knowledge graph) |
| Document ID | String | String |
| Representations | Dense/Sparse vectors (768-dim+) | Nodes, Edges, Thesaurus |
| Index Types | HNSW, IVF, Flat, Inverted | Hash maps + Aho-Corasick |
| Persistence | Disk-based collections | JSON serialisation |
zvec Query:
\nimport zvec\n\n# Semantic similarity via vector comparison\nresults = collection.query(\n zvec.VectorQuery("embedding", vector=[0.1, -0.3, ...]),\n topk=10,\n filter="category == 'tech'"\n)\n# Returns: documents with similar vectors (cosine similarity)\nTerraphim Query:
\n// Graph traversal with term expansion\nlet results = role_graph.query_graph(\n "async programming",\n Some(0), // offset\n Some(10) // limit\n);\n// Returns: documents ranked by graph connectivity\n// Matched nodes: "async", "programming", "concurrency", "tokio"\n| Feature | zvec | Terraphim |
|---|---|---|
| Dense Embeddings | Native | Not used |
| Sparse Vectors | BM25 supported | BM25/BM25F/BM25Plus |
| Knowledge Graph | No | Core architecture |
| ANN Search | HNSW/IVF/Flat | Not applicable |
| SQL-like Filters | SQL engine | Graph-based filtering |
| Explainability | Low (black box) | High (show path) |
| Synonym Expansion | Via embedding model | Via thesaurus |
| Role/Persona Support | No | RoleGraphs |
| Multi-Haystack | Single collection | Multiple sources |
| Built-in Rerankers | RRF, Weighted | Graph ranks directly |
| Quantisation | INT8/FP16 | Not needed |
| Hybrid Search | Vectors + Filters | Graph + Haystacks |
You need to search billions of documents
\nYou are building RAG systems with LLMs
\nYou need image/audio similarity search
\nExact semantic similarity matters
\nYou need explainable results
\nYou have domain-specific knowledge
\nYou are building personal knowledge management
\nYou need role-based search
\nzvec (Python):
\nimport zvec\n\nschema = zvec.CollectionSchema(\n name="docs",\n vectors=zvec.VectorSchema("emb", zvec.DataType.VECTOR_FP32, 768),\n)\n\ncollection = zvec.create_and_open(path="./data", schema=schema)\n\n# Documents must have pre-computed embeddings\ncollection.insert([\n zvec.Doc(\n id="doc1",\n vectors={"emb": embedding_model.encode("Rust async programming")},\n fields={"title": "Async in Rust"}\n ),\n])\nTerraphim (Rust):
\nuse terraphim_rolegraph::RoleGraph;\nuse terraphim_types::{Document, RoleName};\n\nlet mut graph = RoleGraph::new(\n RoleName::new("engineer"),\n thesaurus\n).await?;\n\n// Documents are indexed into the graph\ngraph.index_documents(vec![\n Document {\n id: "doc1".into(),\n title: "Async in Rust".into(),\n body: "Rust's async/await syntax...".into(),\n // Graph extracts terms automatically\n ..Default::default()\n },\n]).await?;\nzvec:
\n# Vector similarity search\nquery_vec = embedding_model.encode("how to write async code")\nresults = collection.query(\n zvec.VectorQuery("emb", vector=query_vec),\n topk=5\n)\n# Results ranked by cosine similarity\nTerraphim:
\n// Graph-based search\nlet results = graph.query_graph("async code", None, Some(5))?;\n// Results ranked by:\n// 1. Node rank (concept frequency)\n// 2. Edge rank (relationship strength)\n// 3. Document rank (occurrence count)\nAbsolutely. Here are some integration patterns:
\nUse zvec for initial broad retrieval, Terraphim for reranking:
\n# Step 1: zvec ANN for candidate retrieval\ncandidates = zvec_collection.query(query_vector, topk=100)\n\n# Step 2: Terraphim graph reranking\n# Load candidates into temporary graph\n# Re-rank based on knowledge graph connectivity\nUse Terraphim's graph to explain zvec results:
\nUser: "Why did this document match?"\nSystem:\n - zvec: "Vector similarity: 0.92"\n - Terraphim: "Matched via concepts: async -> tokio -> concurrency"\nzvec and Terraphim solve semantic search with fundamentally different approaches:
\nzvec scales neural embeddings to billions of documents using ANN algorithms. It is the right choice for large-scale RAG systems, e-commerce search, and any application requiring dense vector similarity.
\nTerraphim builds interpretable knowledge graphs from term relationships. It excels at personal knowledge management, domain-specific expert systems, and any application where understanding why a document matched is as important as finding it.
\nThe exciting possibility is combining both: zvec's scale with Terraphim's explainability. The future of semantic search might just be hybrid.
\nHave you used zvec or Terraphim? We would love to hear about your experiences on GitHub Issues.
\n", "https://terraphim.ai/properties/date" : "2026-02-16", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","vector-search","knowledge-graph","semantic-search","comparison"],"categories":["Technical"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/posts/teaching-ai-agents-with-knowledge-graphs/", "https://atomicdata.dev/properties/name" : "Teaching AI Coding Agents with Knowledge Graph Hooks", "https://terraphim.ai/properties/url" : "https://terraphim.ai/posts/teaching-ai-agents-with-knowledge-graphs/", "https://atomicdata.dev/properties/description" : "How we use Aho-Corasick automata and knowledge graphs to automatically enforce coding standards across AI coding agents like Claude Code, Cursor, and Aider.
\n\n\nNew: see Why Graph Embeddings Matter for the underlying engine that makes these hooks possible — sub-millisecond, deterministic, fully explainable.
\n
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.
\nAs Mike Krieger, Anthropic's Chief Product Officer, put it:
\n\n\n\"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.\"
\n
Claude Code ships as a Bun executable to millions of developers. Anthropic now owns the runtime their flagship coding tool depends on.
\nAnd yet...
\nAsk Claude to set up a Node.js project, and what do you get?
\nnpm install express\nyarn add lodash\npnpm install --save-dev jest\nYet 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.
\nSo how do you teach your AI coding tools to consistently use Bun, regardless of what the underlying LLM insists on?
\nAI 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.
\nManually fixing these inconsistencies is tedious. What if your knowledge graph could automatically intercept and transform AI outputs?
\nTerraphim provides a hook system that intercepts AI agent actions and applies knowledge graph-based transformations. The system uses:
\nInput Text → Aho-Corasick Automata → Pattern Match → Knowledge Graph Lookup → Transformed Output\nThe knowledge graph is built from simple markdown files:
\n# bun install\n\nFast package installation with Bun.\n\nsynonyms:: pnpm install, npm install, yarn install\nWhen the automata encounter any synonym, they replace it with the canonical term (the heading).
\nLet's prove it works. Here's a live test:
\n$ echo "npm install" | terraphim-agent replace\nbun install\n\n$ echo "yarn install lodash" | terraphim-agent replace\nbun install lodash\n\n$ echo "pnpm install --save-dev jest" | terraphim-agent replace\nbun install --save-dev jest\nThe LeftmostLongest matching ensures npm install matches the more specific pattern before standalone npm could match.
Terraphim hooks integrate at multiple points in the development workflow:
\nIntercept Bash commands before execution:
\n{\n "hooks": {\n "PreToolUse": [{\n "matcher": "Bash",\n "hooks": [{\n "type": "command",\n "command": "terraphim-agent replace"\n }]\n }]\n }\n}\nWhen Claude Code tries to run npm install express, the hook transforms it to bun install express before execution.
Enforce attribution standards in commits:
\n#!/bin/bash\nCOMMIT_MSG_FILE=$1\nORIGINAL=$(cat "$COMMIT_MSG_FILE")\nTRANSFORMED=$(echo "$ORIGINAL" | terraphim-agent replace)\necho "$TRANSFORMED" > "$COMMIT_MSG_FILE"\nWith a knowledge graph entry:
\n# Terraphim AI\n\nAttribution for AI-assisted development.\n\nsynonyms:: Claude Code, Claude, Anthropic Claude\nEvery commit message mentioning \"Claude Code\" becomes \"Terraphim AI\".
\nThe replace_matches MCP tool exposes the same functionality to any MCP-compatible client:
{\n "tool": "replace_matches",\n "arguments": {\n "text": "Run npm install to setup"\n }\n}\nThe hook system is built on three crates:
\n| Crate | Purpose |
|---|---|
terraphim_automata | Aho-Corasick pattern matching, thesaurus building |
terraphim_hooks | ReplacementService, HookResult, binary discovery |
terraphim_agent | CLI with replace subcommand |
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\n\nPython testing framework.\n\nsynonyms:: python -m unittest, unittest, nose\nThe system automatically rebuilds the automata on startup.
\nThe LeftmostLongest strategy means:
\nnpm install matches before npmpython -m pytest matches before python# Install all hooks\n./scripts/install-terraphim-hooks.sh --easy-mode\n\n# Test the replacement\necho "npm install" | ./target/release/terraphim-agent replace\ncargo build -p terraphim_agent --features repl-full --release\nConfigure Claude Code hooks in .claude/settings.local.json
Install Git hooks:
\ncp scripts/hooks/prepare-commit-msg .git/hooks/\nchmod +x .git/hooks/prepare-commit-msg\n| 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() |
For AI agents that support skills, we provide a dedicated plugin:
\nclaude plugin install terraphim-engineering-skills@terraphim-ai\nThe terraphim-hooks skill teaches agents how to:
Knowledge graph hooks provide a powerful, declarative way to enforce coding standards across AI agents. By defining patterns in simple markdown files, you can:
\nThe Aho-Corasick automata ensure efficient matching regardless of pattern count, making this approach scale to large knowledge graphs.
\nTo 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.
\nWe have a few end-to-end demos and user journeys to discuss with early adopters of Terraphim - Privacy Preserving AI assistant.
\n", "https://terraphim.ai/properties/date" : "2023-08-12", "https://terraphim.ai/properties/tags" : {"tags":["Terraphim","ai","announcement"],"categories":["Announcements"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/capabilities/local-first/", "https://atomicdata.dev/properties/name" : "Local-First Architecture", "https://terraphim.ai/properties/url" : "https://terraphim.ai/capabilities/local-first/", "https://atomicdata.dev/properties/description" : "Terraphim AI is not \"privacy-respecting\" because of a terms-of-service promise. It is private because the architecture makes data exfiltration structurally impossible. All indexing, searching, and knowledge graph traversal happens entirely on your device. There is no cloud dependency, no telemetry, no analytics phone-home.
\nThe search architecture is deliberately non-neural and offline-first:
\n| Principle | What It Means |
|---|---|
| Offline-first | No network calls or LLM inference required at search time |
| Deterministic | Same query plus same corpus equals same results, always |
| Explainable | Every score decomposes into frequency counts, field weights, or set overlaps |
| Low footprint | Approximately 15-20 MB RAM for a typical knowledge graph; no GPU, no float vectors |
| Graph-native | Explicit edges and nodes encode domain relationships, not latent geometry |
There is no sign-up, no API key, no subscription. You install Terraphim and it works. Your search history, your knowledge graphs, your indexed documents — all of it stays on your machine under your control.
\nTraditional enterprise search tools upload your data to cloud servers, process it with proprietary models, and return results through APIs that require authentication and ongoing payment. Terraphim inverts this model entirely:
\nTerraphim runs wherever you need it: as a native desktop application, a WebAssembly module in your browser, a CLI tool, or a TUI (terminal user interface). For teams that need shared access, Terraphim Private Cloud uses AWS Firecracker microVMs to give each user a dedicated virtual machine with their own TLS certificate — keeping data isolated even in multi-tenant deployments.
\nAt the heart of Terraphim is a knowledge graph engine that uses Aho-Corasick finite state automata for multi-pattern matching. Unlike traditional keyword search, Aho-Corasick matches thousands of patterns simultaneously in O(n) time relative to the text length — regardless of how many patterns are in the graph.
\nThe search pipeline operates in stages:
\nEach Terraphim role has its own separate knowledge graph containing concepts relevant to that domain, with all synonyms. A systems engineer, a project manager, and a quality analyst each see the same documents ranked differently based on their role's knowledge graph.
\nKnowledge graphs are built from industry standards, reference process models, handbooks, and curated taxonomies. Terraphim imports these sources and produces a graph following the SIPOC pattern — concepts at the input and output of processes, with activity names linking them.
\nTerraphim's Dynamic Ontology enables schema-first knowledge graph construction:
\nUsers specify synonyms manually and rebuild graph embeddings within 20 milliseconds. This allows matching terms in different languages to the same concept without running language detection. There is no need for a stop-word dictionary — \"The Pattern\" matches exactly as a project name, even though \"The\" would normally be filtered as a stop word.
\nTerraphim includes a native Model Context Protocol (MCP) server that exposes your local knowledge graphs to AI coding assistants like Claude Code, Claude Desktop, and other MCP-compatible tools. Your AI assistant gains domain-specific context without your data leaving your machine.
\nExtract paragraphs from text starting at matched terms, with precise line numbers. Useful for referencing function definitions, getting context around specific patterns, or building documentation with accurate line references.
\nSemantic search that returns full document context with file paths. Unlike plain text search, this leverages your role-based knowledge graph to find documents by their conceptual relationship to your query, not just keyword overlap.
\nMonitor token usage across your AI assistant sessions. Track how much context is being consumed and optimise your prompts based on actual usage data.
\nDifferent roles need different context. A systems engineer asking about \"requirements\" needs different search results from a quality analyst asking the same word. Terraphim's MCP server routes queries through the active role's knowledge graph, ensuring your AI assistant receives context that matches your current domain.
\nTypical AI assistant integrations send your files and context to cloud APIs. Terraphim's MCP server runs locally:
\nTerraphim works as a Claude Code MCP server, providing knowledge-graph-boosted file search, concept extraction, and role-based context enrichment directly within your development workflow.
\nTerraphim AI is written in Rust and compiles to WebAssembly. This is not a marketing choice — it is a performance requirement. Knowledge graph inference runs in 5 to 10 nanoseconds. Pipeline processing completes in hundreds of milliseconds. Search queries resolve in sub-millisecond time.
\nRust provides memory safety without garbage collection, zero-cost abstractions, and thread safety guaranteed at compile time. For a system that builds and traverses knowledge graphs with thousands of nodes and edges, these guarantees translate directly into reliable performance without unexpected pauses or memory leaks.
\nWebAssembly allows the same Rust codebase to run:
\nOne codebase, compiled to multiple targets, with no performance compromise.
\nThe journey from The Pattern to Terraphim AI tells the performance story:
\n| Metric | Traditional ML Pipeline | The Pattern | Terraphim AI |
|---|---|---|---|
| Data processing for training | 6 days | 6 hours | Hundreds of milliseconds |
| Inference latency | Seconds | Under 2 ms | 5-10 nanoseconds |
| RAM footprint | Gigabytes | Hundreds of MB | 15-20 MB |
| GPU required | Yes | No | No |
Terraphim includes a comprehensive benchmarking framework covering:
\nAll benchmarks run on standard hardware — no GPU, no specialised accelerator.
\nA typical Terraphim knowledge graph occupies approximately 15-20 MB of RAM. There are no float vectors, no dense embeddings, no GPU memory allocation. This means Terraphim runs comfortably on a laptop, a Raspberry Pi, or a modest cloud instance.
\nTerraphim implements a two-stage runtime validation system for AI-assisted development workflows. Every tool execution and LLM generation passes through hooks that provide both safety and intelligence enhancement.
\nThe guard stage prevents dangerous operations before any processing occurs:
\n--no-verify in git operationsThe replacement stage enhances text using knowledge graph patterns:
\nFailed commands are automatically captured by post-tool-use hooks. When a bash command fails, Terraphim records the failure for later review. Over time, you build a searchable history of what went wrong and how it was corrected.
\n# Review captured learnings\nterraphim-agent learn list\n\n# Query by pattern\nterraphim-agent learn query "npm"\n\n# Add a correction\nterraphim-agent learn correct <id> "use bun instead"\nThis turns individual debugging sessions into institutional knowledge that persists across conversations and team members.
\nTerraphim supports hooks at four points in the AI workflow:
\n| Hook | Purpose |
|---|---|
| Pre-LLM | Validate prompts before generation; block, modify, or require human confirmation |
| Post-LLM | Validate responses; catch harmful content, enforce formatting |
| Pre-Tool | Validate commands before execution; security checks, injection prevention |
| Post-Tool | Monitor results; track performance, capture failures for learning |
Hooks are configured via TOML and environment variables, with sensible defaults:
\nTraditional file search finds files by name or by text content. Terraphim's KG-boosted file search finds files by their semantic relationship to your domain concepts and role-specific vocabulary.
\nWhen you search for \"requirements validation\", Terraphim does not just grep for those words. It traverses your knowledge graph to find documents connected to those concepts through synonyms, co-occurrence edges, and domain relationships. A document titled \"acceptance criteria review\" surfaces because the knowledge graph knows these concepts are related in a systems engineering context.
\nTerraphim searches across multiple sources simultaneously:
\nResults from all sources are unified, deduplicated, and ranked using a single knowledge graph.
\nWhen searching across multiple haystacks, the same document often appears in different sources. Terraphim handles duplicates intelligently, merging results and preserving the highest-ranked version rather than showing the same content multiple times.
\nThe same search query produces different rankings for different roles:
\nEach role's knowledge graph contains domain-specific concepts and synonyms that reshape how results are scored and ordered.
\nTerraphim organises searchable content into context collections — curated sets of documents, taxonomies, and vocabulary that define a domain. Collections can be shared across a team or customised per user, providing consistent search relevance without centralised configuration.
\nThrough the MCP server, KG-boosted file search is available directly in your AI coding assistant. When Claude Code searches for files, it uses your knowledge graph to find semantically relevant results, not just filename matches.
\nThe name Terraphim comes from the concept of an artificial intelligence as superposition of quantum fields that lives inside a spacesuit — part of an exocortex — or inside your house or vehicle, designed to help you with your tasks. You carry it with you.
\nSimilar companions are now familiar across modern science fiction. Destiny 2 has Ghost, a small floating AI bound to its Guardian. Star Wars Jedi: Survivor has BD-1, a droid riding on Cal Kestis's back. Same pattern: a compact, mobile, personal intelligence that augments rather than replaces.
\nThat image — small, local, loyal, always with you — drives the engineering choices in the rest of this page. Terraphim runs on your hardware, codifies knowledge as compact graphs rather than heavyweight models, and never ships your data across a boundary. The sci-fi premise is the brief; what follows is how we built it.
\nTerraphim AI did not start as a product. It started as a frustration with how slowly machine learning pipelines process data.
\nThe project's predecessor, The Pattern, grew out of participation in two Kaggle data science competitions. The original ML pipeline could not finish processing data in six days. The Pattern processed the same data for training in six hours and achieved under two-millisecond inference. That hundredfold improvement was not a hardware upgrade — it was a fundamental rethinking of how search and retrieval should work.
\nThe Pattern was awarded Platinum Winner at the Redis Hackathon, outperforming Nvidia's ML pipeline for BERT QA inference on CPU. The prize confirmed that external experts recognised the approach as genuinely innovative, not merely a clever optimisation.
\nThe results were presented and discussed at a public lecture at Oxford University, Green Templeton College, bringing academic scrutiny to the architecture that would become Terraphim AI.
\nTraditional search systems rely on dense vector embeddings and attention mechanisms that are expensive, opaque, and non-deterministic. Terraphim took a different path.
\nTerraphim Graph Embeddings maintain the position of terms in a sentence without requiring traditional training techniques like attention. Users can specify synonyms manually and rebuild graph embeddings for a role within 20 milliseconds. This allows matching terms in different languages to the same concept without running language detection, and eliminates the need for stop-word dictionaries entirely.
\nBy rethinking from the ground up, Terraphim AI achieves pipeline processing in hundreds of milliseconds and knowledge-graph-based inference in 5 to 10 nanoseconds.
\nThe methodology has been validated within the INCOSE (International Council on Systems Engineering) community for the Systems Engineering Handbook v.4 and the Systems Engineering Digital Process Model v.1. It was recognised as a valid low-effort substitution for formal model-based systems engineering — particularly valuable for brownfield systems engineering, reverse-engineering, and professional certification.
\nResearch consistently shows the problem Terraphim exists to solve:
\nTerraphim's answer: deterministic, privacy-first, knowledge-graph-powered search that runs entirely on your hardware.
\nTerraphim uses graph embeddings instead of neural vector embeddings. Terms and concepts\nare represented as nodes in a role-specific knowledge graph, with relationships encoded as\nedges. Matching a query against a graph is deterministic, auditable, and fast.
\nSee the full design note for how RoleGraph composes\nAho-Corasick matching with PageRank ordering to produce ranked results in\nsub-millisecond time, without any floating-point vector math.
\nThis is a fundamentally different model from dense vector retrieval. It is what makes\nTerraphim run on a laptop, a Raspberry Pi, or inside a browser extension.
\n", "https://terraphim.ai/properties/date" : "2026-04-15", "https://terraphim.ai/properties/tags" : {"categories":["Capability"],"tags":["graph-embeddings","aho-corasick","knowledge-graph","search"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/capabilities/multi-haystack/", "https://atomicdata.dev/properties/name" : "Multi-Haystack Search", "https://terraphim.ai/properties/url" : "https://terraphim.ai/capabilities/multi-haystack/", "https://atomicdata.dev/properties/description" : "Terraphim roles can be configured with multiple haystacks — named sources of content.\nA single query fans out across every haystack attached to the role and the results come\nback ranked by the role's knowledge graph.
\nHaystack adapters available today:
\nSee the release post Introducing Multi-Haystack Roles: Local + Global Code Search\nfor a walkthrough of combining a local haystack with grepapp to search both your code and\nthe world's code in one query.
\n", "https://terraphim.ai/properties/date" : "2026-04-15", "https://terraphim.ai/properties/tags" : {"tags":["haystack","search","grepapp","code-search"],"categories":["Capability"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/capabilities/terraphim-agent/", "https://atomicdata.dev/properties/name" : "terraphim-agent CLI", "https://terraphim.ai/properties/url" : "https://terraphim.ai/capabilities/terraphim-agent/", "https://atomicdata.dev/properties/description" : "terraphim-agent is a command-line AI agent that searches before it answers. It runs\nlocal knowledge graph queries, imports session history from Claude Code and Cursor,\ncaptures failed commands via post-tool-use hooks, and surfaces past corrections when\nyou encounter a recurring error.
Install it with one command:
\ncargo install terraphim_agent --features repl-full\nlearn subcommand records failed commands and their corrections.npm install to bun add,\npip install to uv add, etc. via a thesaurus.learn compile converts captured ToolPreference corrections into a\nthesaurus JSON that the replace command loads directly, closing the feedback loop from\nfailure to live rewrite.terraphim-agent subcommands triggered by\n@adf:<agent-name> Gitea mentions, with three security layers (allowlist, metachar\nrejection, CommandGuard), and posts results back as markdown comments.See the command rewriting how-to and the blog post\nTeaching AI Agents to Learn from Their Mistakes\nfor worked examples.
\n", "https://terraphim.ai/properties/date" : "2026-04-15", "https://terraphim.ai/properties/tags" : {"tags":["agent","cli","ai-agents","learning"],"categories":["Capability"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/capabilities/terraphim-editor/", "https://atomicdata.dev/properties/name" : "Terraphim Editor", "https://terraphim.ai/properties/url" : "https://terraphim.ai/capabilities/terraphim-editor/", "https://atomicdata.dev/properties/description" : "Terraphim Editor brings knowledge-graph alternative suggestions into your writing. Use role-specific concepts and synonyms to compare wording in context, choose an alternative, and keep other options attached to the text. Roles provide the vocabulary for your domain; the online preview starts with a bundled local knowledge graph.
\nTry the intelligent editor preview
\nAttach alternatives to words, sentences and paragraphs. Save an annotated Markdown document and reopen it with those choices preserved. Newly authored alternatives register as document-scoped synonyms using synonyms:: syntax; download them through Knowledge graph to use that exact vocabulary in terraphim-grep. Sharing is explicit and does not silently alter your active role.
Ghost passages to retain them outside clean export, set notes aside in Overflow, and inspect possible cuts in the Lab. KG-protected Trim preserves matched concepts and their original spelling, including supported Unicode normalization.
\nThe editor runs as WebAssembly in your browser. Editing with the bundled graph does not require an LLM or sending your document to a provider.
\nWatch the 80-second alternative-to-search story: create Concern as an alternative to Risk, share the graph and find related decisions, with and without synthesis.
\nEarlier captioned browser and extension walkthroughs: Chrome, Safari, Firefox and the existing Zed extension, followed by search with the same shared KG, with and without synthesis. Each video identifies its recorded scope; the current browser build includes the later Unicode normalization repair.
\nThis is a preview. Complete acceptance against all 41 source-video requirements remains open, including Safari dragging and some visual/native cases. The existing Zed extension demonstrates its supported capabilities; the separate Zed fork is outside this publication.
\nThe evaluation framework measures how accurately the Aho-Corasick automata classify terms in\nreal documents. Give it a JSON file of hand-labeled documents and it returns micro-averaged\nprecision, recall, and F1, a per-term breakdown, and a list of terms that consistently\nproduce false positives.
\n[\n {\n "id": "doc1",\n "text": "tokio powers async rust applications",\n "expected_terms": [\n { "term": "tokio", "category": null },\n { "term": "rust", "category": null },\n { "term": "async", "category": null }\n ]\n }\n]\nEach term must match the normalized term value (nterm) stored in the thesaurus.
use terraphim_automata::evaluation::{evaluate, load_ground_truth};\n\nlet docs = load_ground_truth(Path::new("ground_truth.json"))?;\nlet result = evaluate(&docs, thesaurus);\n\nprintln!("F1: {:.2}", result.overall.f1);\nfor report in &result.per_term {\n println!(" {} precision={:.2} recall={:.2}",\n report.term, report.metrics.precision, report.metrics.recall);\n}\nfor err in &result.systematic_errors {\n println!(" SYSTEMATIC FP: {} in {} documents", err.term, err.false_positive_count);\n}\nMetrics are micro-averaged: true positives, false positives, and false negatives are\nsummed across all documents before dividing.
\nA term is flagged as a SystematicError when it appears as a false positive in 2 or more\ndocuments. Matching is case-insensitive; each term is counted at most once per document.
Source: crates/terraphim_automata/src/evaluation.rs
The listener dispatch feature lets you run terraphim-agent subcommands by mentioning the\nagent in a Gitea issue or comment. The result is posted back as a formatted markdown comment.
Mention the agent in a Gitea comment with a subcommand and arguments:
\n@adf:worker search "knowledge graph" --role engineer\n@adf:worker evaluate --role engineer\n@adf:worker learn list\nThe listener parses the text after @adf:, validates it through three security layers, runs\nthe command, and posts the output back to the same issue.
Three checks must all pass before the process is spawned:
\n1. Shell metacharacter rejection — Input containing |, ;, &, `, $, (,\n), <, or > is rejected immediately. No shell is involved in execution, but this\nprevents confusion if the input is ever logged or replayed.
2. Subcommand allowlist / denylist — Only known safe subcommands are permitted.\nDenied subcommands (listen, repl, interactive, setup, update, sessions)\nare blocked even if added to extra_allowed_subcommands.
3. CommandGuard — A pattern-based guard runs on the full command string before\nprocess spawn. It blocks destructive patterns such as git reset --hard.
Enable dispatch in your listener config JSON:
\n{\n "identity": { "agent_name": "worker" },\n "gitea": {\n "base_url": "https://git.terraphim.cloud",\n "owner": "terraphim",\n "repo": "terraphim-ai"\n },\n "dispatch": {\n "timeout_secs": 300,\n "max_output_bytes": 48000,\n "specialist_routes": {\n "evaluate": "eval-bot"\n }\n }\n}\nspecialist_routes routes specific subcommands to a named agent rather than running locally.
The comment posted back to Gitea includes the exit code, elapsed time, stdout in a code\nblock, and stderr in a collapsible section. Output is capped at 48 KB. Commands that exceed\n5 minutes are killed and marked **TIMED OUT**.
The --robot flag is always appended, so output is machine-readable JSON regardless of the\nuser's default format.
Source: crates/terraphim_agent/src/shell_dispatch.rs, crates/terraphim_agent/src/listener.rs
Watch the new 80-second story: create a synonym, share it, then search
\nThese earlier host recordings remain available as versioned evidence. The new story above follows the current alternative-to-search flow.
\n\nKeep alternatives attached to words, sentences and paragraphs. Ghost a passage without losing it, stash notes in Overflow, and use the Lab to inspect possible cuts. The editor runs as WebAssembly in your browser with a bundled local knowledge graph.
\nFollow a public project brief from editing to search using the same knowledge graph. The 77-second captioned overview shows the browser editor, explicitly hands off to the clean file exported from Safari, then compares real terraphim-grep executions with and without --answer.
--answer — 21sThe browser recordings produced identical saved annotated files. A separately checked Safari clean-export file supplies the grep corpus; the Safari walkthrough does not show that export gesture. Newly authored Assessment registers as a document-scoped synonym; it does not update the shared KG used by the CLI. Zed demonstrates existing extension capabilities; the Zed fork is separate. The brief's Trim preview produced zero cuts, so this recording does not demonstrate text reduction. The generated synthesis overstates a review policy as observed practice; compare that statement with the returned evidence rather than treating it as verified fact.
\nAll six videos now have explanatory on-screen captions. Idle intervals are cut, actions are accelerated by 1.5–3× where disclosed, and the long terminal end hold is removed. Captions sit outside the application image. Safari setup is cut and the Zed avatar remains masked. Chronological source ranges and speed changes are recorded in the manifest; original captures are retained. These are finite walkthroughs, not complete acceptance of all 41 requirements. Build identities, media hashes and edit disclosures identify the recorded candidate. The current editor preview includes the Unicode normalization repair: canonically equivalent accents, Terraphim Unicode lowercase and Greek sigma equivalence protect exact original spellings during Trim. The videos retain their earlier recorded build identity; they do not demonstrate this later repair.
\nThis is a preview. The complete source-video requirements are still being qualified; Safari dragging and some visual/native cases remain unresolved. Keyboard pull from Overflow is available. The browser demo does not imply full custom visual parity in the stock Zed extension.
\nPaste this supplied example into the editor. It is sample input, not generated output:
\n# Public research workspace\n\nDecision: launch a local-first research workspace for the delivery team.\n\nThe decision owner will review the brief before the pilot begins.\n\nRisk: inconsistent terminology makes prior decisions hard to locate.\n\nUse the project brief to align the team and keep the decision record clear.\nTurn on Write_On using the word counter. Explore alternatives for “decision”, add your own wording, and compare it in context. Ghost/revive a passage, stash a note in Overflow and inspect the Lab. Save the result and reopen the actual file to check the choices and annotations.
\nSave keeps the Markdown, alternatives, ghosts and Overflow together. Clean Markdown export includes active text and omits ghosts, Overflow and the annotation block. Chrome can offer a file handle; Firefox and Safari use a download. Check the actual browser dialog and downloaded file.
\nDownload the same bundled KG and inspect the editor build identity. Newly authored alternatives register as document-scoped synonyms; they do not silently change this shared KG.
\nMove the chosen saved or clean-exported file into a dedicated local corpus folder. Keep evidence logs and other copies outside that folder. With terraphim-grep installed, set paths for that public corpus and downloaded KG:
terraphim-grep "decision" --thesaurus ./default.json --paths ./public-corpus --json\nterraphim-grep "decision" --thesaurus ./default.json --paths ./public-corpus --json --answer\nThe first command returns search evidence without enabling synthesis. The second asks for an answer when sufficient evidence and a configured provider are available. Keep the query, corpus and KG unchanged to compare them. Add the same --role-config path to both commands if configuring a provider through a role. Check the generated answer against the returned source lines; a missing answer or provider error is not a successful synthesis.
Writing and local search do not require sending your document to an LLM. Synthesis may send retrieved content to the configured provider. Use public sample content for the demo and inspect the provider configuration before enabling --answer.
Your project brief says risk. Later, you search for concern. Terraphim connects the two so a change of wording does not hide the decisions you need.
\nThe inspiration came from Jason Fried’s original Write_On video and its idea of “alternative control”. It prompted Alex Mikhalev to return to Terraphim Editor, a Rust/WebAssembly project he had abandoned two years earlier, with a clear purpose: connect wording alternatives to a reusable knowledge graph and carry that meaning into search.
\n\nTry Terraphim Editor · Install for VS Code · Read the narration
\nIn our community garden brief, timber might arrive late. The team has decided to keep a backup supplier. Add Concern as an alternative to Risk, then swap between them. The other wording stays attached to the document.
\nOpen Knowledge graph from the Markdown export menu. The editor shows Risk ↔ Concern and its actual definition:
\nsynonyms:: Risk, Concern\nDownload the graph and the clean text. This explicitly shares the document's authored synonym groups as a Terraphim thesaurus; it does not silently change your active role. The saved example contains Risk, with no literal occurrence of Concern.
\nUse the graph downloaded from that editing session:
\nterraphim-grep concern --thesaurus knowledge-graph.json --paths corpus -C 2 --search-only --json\nThe actual result contains three risk passages and their related decisions, with file and line locations. No generated answer is requested.
\nReplace --search-only with --answer for synthesis:
terraphim-grep concern --thesaurus knowledge-graph.json --paths corpus -C 2 --json --answer\nThe video shows the generated summary and its references to the same three passages. Decisions remain decisions: the source does not establish whether they have been carried out. Check the evidence alongside any generated answer.
\nEditing and local search use your local data. Optional synthesis sends the retrieved passages to your configured model provider.
\nThis supplier brief says Risk. Search for Concern using its exported graph, and both retrieval and synthesis find the same three passages. The generated answer points back to the brief's decisions and actions.
\n\nA 44-second replay of saved tool results in Kilo, with captions and no audio. It shows the saved Risk/Concern alternative, source lines and cited summary. The Kilo skills are under marketplace review; this is a configured integration.
\nDownload the brief, graph and actual results · Kilo setup guide · Recorded versions and checksums
\nKeep the words that describe a concept in the note that owns it. In this example, Risk.md contains the actual synonyms:: Risk, Concern property and embeds the community garden brief. The separate brief still says risk, never concern. The search-results note contains saved passages, with no synonym definition.
Download the Obsidian demo vault ZIP. Extract it, open the included obsidian-demo/vault folder as an Obsidian vault, and open Notes/Risk.md. Open Search results/Concern search.md alongside it to inspect the saved output. No community plugins are required.
To reproduce the retrieval, install terraphim-grep v1.21.19, open a terminal in the extracted vault directory, and run:
terraphim-grep concern --thesaurus "Knowledge graph/baseline-role.json" --paths "Notes/Projects" -C 2 --json --search-only\nterraphim-grep concern --thesaurus "Knowledge graph/knowledge-graph.json" --paths "Notes/Projects" -C 2 --json --search-only\nThe released binary returned zero passages with the baseline graph and three exact risk-and-decision passages with the exported graph, at lines 7, 10 and 13. The commands search only the project brief directory, excluding the concept definition and saved results. Inspect the baseline output, synonym output, execution receipt and file checksums.
\nTerraphim’s synonyms:: convention uses Logseq-compatible Markdown property syntax. Obsidian’s native aliases use YAML aliases. This example supplies the same graph exported by the editor explicitly: saving a note does not automatically rebuild the graph or synchronise the vault. Search runs in the CLI; Obsidian displays the notes and saved results. The capture reruns local retrieval only; the video above shows the separate synthesis comparison.
Prefer linked blocks? Open the same garden project in Logseq. The Risk concept page owns the wording relationship and embeds the project brief. Its properties are:
\nalias:: Concern\nsynonyms:: Risk, Concern\nalias:: gives the page another name inside Logseq. Terraphim’s synonyms:: property records the words connected by the exported search graph.
graph folder. If you use a Logseq version with file graphs, open that folder directly.From a terminal in the extracted graph folder, run:
terraphim-grep concern --thesaurus baseline-role.json --paths pages/Projects -C 2 --json --search-only\nterraphim-grep concern --thesaurus knowledge-graph.json --paths pages/Projects -C 2 --json --search-only\nThe first search returns zero passages. The shared synonym graph brings back three decisions: keep a backup supplier, reserve a covered area and keep a volunteer reserve list. The commands search only the project notes, leaving concept definitions and saved results outside the search.
\nCompare the baseline and synonym search output, or follow the download instructions. The CLI reads the included Markdown files; Logseq 2.0 imports a copy into its database. Use the extracted folder for these commands. File checksums are included.
\n--answer when you want a summary alongside the source passages.Searching for concern returns no passages before the graph is shared. With the graph, it finds all three risk passages and their related decisions. Compare the saved results before sharing, with the synonym graph, and with a generated summary.
\nThen try the same steps with a pair of words from your own project notes.
\nThe video uses a sample project brief and synthetic British English narration. The graph and search results are saved outputs from the demonstrated workflow. Recording details and versions, commands and file checksums are available with the downloads.
\nExplore more editor walkthroughs.
\n", "https://terraphim.ai/properties/date" : "2026-10-11", "https://terraphim.ai/properties/tags" : {"tags":["editor","knowledge-graph","search"],"categories":["How-tos"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/how-tos/command-rewriting-howto/", "https://atomicdata.dev/properties/name" : "A failed command, a saved correction, and the next run", "https://terraphim.ai/properties/url" : "https://terraphim.ai/how-tos/command-rewriting-howto/", "https://atomicdata.dev/properties/description" : "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.
\nThis walkthrough follows one harmless error from failure to saved correction to actual execution. Each execution now has one record linking the model’s request, the matching rewrite rule, the command the tool ran and its saved result. It uses the Harbour project brief from the memory walkthrough, a released Terraphim agent, and an OpenCode adapter included in the download.
\n\nDownload the Harbour hooks example · Read the transcript
\nHarbour'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\nThe 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.
\nThe 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.
\nThe 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.
\nThe 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.
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. Here, “review” means checking the intended correction; it is not a built-in approval gate. The reproduction script runs this command inside its isolated store:
\nterraphim-agent learn correction add \\\n --correction-type tool-preference \\\n --original 'python3 validate-brief.py --chek' \\\n --corrected 'python3 validate-brief.py --check' \\\n --context 'Manually reviewed correction from the captured failure'\nterraphim-agent learn compile --output compiled-corrections.json\nterraphim-agent learn export-kg --output kg\nCompilation now reports one correction. The selected Harbour Validator role loads that compiled JSON. The exported Markdown makes the relationship readable:
\n# python3 validate-brief.py --check\nsynonyms:: python3 validate-brief.py --chek\nThis 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.
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:
{\n "tool_input": {"command": "python3 validate-brief.py --check"},\n "tool_name": "Bash"\n}\nThat 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.
\n
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.
\nThe after-tool event records python3 validate-brief.py --check. Its exit status is 0. The validator prints a valid Harbour result and writes evidence/executions/<execution_id>/validation.json:
{\n "execution_id": "19578f09-a59a-4e80-be31-7d319b0c9368",\n "project": "Harbour",\n "status": "valid",\n "fields": ["Decision", "Risk", "Owner"]\n}\nThe host transcript can still display the model's original requested input. The hook changes the command; OpenCode executes it. Inspect the actual after-tool event to establish what ran.
\nThe included adapter records an execution ID alongside the host’s session and tool-call IDs. Its receipt.json links:
The validator embeds the same execution ID in its printed result and saved file. The verifier checks those values against the native host events and rehashes the graph and output. A stale file, mismatched command, unmatched host call, missing artifact or altered bytes fails verification. A blocked call is retained without being labelled executed.
\nInspect the execution receipt, saved result and run verification.
\n
This recorder covers the example’s sequential, whole-command mapping. It rejects overlapping fixture calls and unsupported rule attribution; it is not a general multi-rule provenance system.
\n
The example was verified with terraphim-agent v1.21.19 and OpenCode 2.0.20. The download includes the new adapter source, version 2.0.0; it is separate from the earlier binary release. Follow the ZIP's README to check the release archive, choose your already authenticated coding model and run from the extracted folder:
\npython3 reproduction/reproduce.py \\\n --agent /absolute/path/to/terraphim-agent \\\n --model kimi-code-plan-global/k3 \\\n --output /absolute/path/to/a-new-harbour-run\nUse 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.
\nRun node reproduction/verify.mjs /absolute/path/to/a-new-harbour-run to check the saved evidence. Read evidence/verification.json, the host events and each execution’s receipt.json and validation.json. The ZIP also includes 22 regression tests, runnable with node --test tests/*.test.mjs. 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.
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.
\nUse 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.
\nDownload 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.
\nEarlier 75-second walkthrough · Original example.
\nUpdated 13 October 2026. The new video is 66 seconds. 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.
\n", "https://terraphim.ai/properties/date" : "2026-04-15", "https://terraphim.ai/properties/tags" : {"categories":["Tutorials"],"tags":["Terraphim","hooks","OpenCode","knowledge-graph","developer-tools"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/terraphim-llm-proxy/privacy/", "https://atomicdata.dev/properties/name" : "Terraphim Proxy — Privacy Policy", "https://terraphim.ai/properties/url" : "https://terraphim.ai/terraphim-llm-proxy/privacy/", "https://atomicdata.dev/properties/description" : "Effective date: 24 October 2026. Applies to the Terraphim Proxy macOS\napplication (cloud.terraphim.desktop), distributed via the Mac App\nStore and direct download.
The Terraphim Proxy application collects no data whatsoever. There\nis no account system, no telemetry, no analytics, no crash reporting, and\nno third-party tracking SDK in the app. Your credentials never leave your\nMac except inside the requests you deliberately send to the LLM providers\nyou configured.
\nBuying a direct download does create a small server-side record — kept by\nthe Terraphim Skills marketplace, not by the app — described under\nPurchases below.
\n127.0.0.1) listeners bound to your\nmachine.Only the requests you send through the proxy, to the LLM providers you\nchose — over TLS, bearing the credentials those providers issued to\nyou. Their handling of that traffic is governed by their own privacy\npolicies (z.ai, OpenRouter, Groq, Cerebras, Kimi, MiniMax, DeepSeek,\nOpenAI, xAI, or any other provider you configure).
\nMac App Store. The app is a one-time purchase processed entirely by\nApple's App Store. Apple — not Terraphim Proxy — receives and processes\nyour payment information. The app contains no in-app purchases, no\nsubscription checks and no licence servers.
\nDirect download. Direct-download purchases are processed by Stripe\nvia the Terraphim Skills marketplace (api.terraphim-skills.md). Stripe\n— not Terraphim — receives and processes your payment information. The\nmarketplace stores the email address on your account, the fact of the\npurchase, and which release downloads it has served to your account;\nthose records are used solely for entitlement checks and refund\nadjudication, as described in\nthe Refund policy. The application\nitself still collects nothing — this record lives entirely on the\nmarketplace side.
| Entitlement | Why |
|---|---|
app-sandbox | The app runs sandboxed. |
files.user-selected.read-write | Only files you explicitly choose (e.g. settings export). |
network.client | Outbound calls to your configured LLM providers. |
network.server | Loopback-only listeners for the local proxy endpoint and the dashboard's metrics feed. |
Questions, corrections or requests: open an issue on\nGitHub or write to\nthe maintainers via the repository.
\nIf this policy changes, the updated version is published at this URL\nbefore the change ships.
\n", "https://terraphim.ai/properties/date" : "2026-10-24", "https://terraphim.ai/properties/tags" : {"categories":["Legal"]}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/terraphim-llm-proxy/refunds/", "https://atomicdata.dev/properties/name" : "Terraphim Proxy — Refund Policy", "https://terraphim.ai/properties/url" : "https://terraphim.ai/terraphim-llm-proxy/refunds/", "https://atomicdata.dev/properties/description" : "Effective upon launch of direct-download sales.
\nThis policy covers direct downloads purchased on terraphim.ai.\nPurchases made through the Mac App Store are refunded by Apple under the\nApple Media Services Terms and Conditions; Apple,\nnot Terraphim, decides those refunds.
\nWithin 14 days of purchase you can get a full refund provided no\nrelease has been downloaded. Once your account has downloaded a release,\nthe sale is final — unless the proxy does not function.
\nThis is the same shape as Steam's rule for games: a refund is available\nwhile the product is untouched, and the usage measurement is what makes\nthe rule fair to enforce. Steam measures playtime; we measure the moment\nour service first serves the download.
\nA signed application bundle cannot be returned once it is copied to your\nMac — there is no undo. The download is the honest line between\n\"bought but not taken\" and \"taken\", and it is a line we can measure: the\nservice records the first time it serves a release download request to\nyour account, and that record is the only thing the refund rule\nconsults.
\nWe considered the alternative — a blanket 14-day window — and rejected\nit, because it would let anyone buy, download every release, and refund.\nThat pattern subsidises itself out of the purchase price of everyone\nelse.
\n| Situation | Outcome |
|---|---|
| Within 14 days of purchase, no release downloaded | Full refund, no questions asked |
| Any release downloaded, proxy functioning as documented | Final sale — no refund |
| Any release downloaded, proxy does not function | Full refund — see When the proxy does not function below |
| More than 14 days after purchase, no download | Not automatic. Ask anyway — see Outside the rules below. |
\"Downloaded\" is counted when our service begins delivering the release\nto your account — the request is recorded when delivery starts, not when\nthe bytes finish. A failed or interrupted delivery does not count as a\ncompleted download for refund purposes (see Downloads were broken\nbelow), and where the record is ambiguous we treat it in your favour.
\nRefunds go back to the original payment method through Stripe. Card\nrefunds usually appear within 5–10 business days, depending on your bank\n— that part is outside our control.
\nWhen a refund is issued, download access ends: the entitlement is\nrevoked and release downloads stop working.
\n\"Not functioning\" means the software itself is defective — for example:
\nIt does not cover upstream problems outside our control: a provider\noutage, an exhausted provider quota, a network block on your side, or a\nmodel behaving unexpectedly. Those are the provider's service, not ours.
\nBecause the app collects no telemetry, we cannot see the failure\nourselves — when you report a defect we may ask for the app version, your\nmacOS version, and the error or behaviour you see. If the software\ngenuinely does not work, we will refund it. You should not have to argue\nthe point.
\nEmail engineering@terraphim.ai\nwith the email address on the account you purchased with. For a defect\nclaim, include the app version and macOS version.
\nWe aim to process refund requests within 3 business days.
\nOutside the automatic cases a refund is at our discretion, but the door\nis not closed. We will look seriously at:
\nTo make this policy enforceable we keep a server-side record, tied to\nyour purchase account, of when our service first serves a release\ndownload request to you — the version, the asset and the time. That is\nthe entire record — the app itself collects no telemetry and reports\nnothing back. Purchase and download records are covered in the\nPrivacy policy.
\nIf you are a consumer in the UK or EU you have a legal right to cancel a\ndistance contract within 14 days. For digital content that right is lost\nonce downloading begins if you asked for immediate access and\nacknowledged losing the right — which is why checkout asks you to\nconfirm exactly that before a download becomes available.
\nNothing in this policy affects your statutory rights.
\nWe will refuse refunds where the pattern is clearly abusive — for\nexample repeatedly purchasing, downloading, and refunding, or\nredistributing downloaded releases. Because downloads are recorded we\ncan see this pattern; purchase of a licence does not transfer\nredistribution rights.
\nWe may change this policy. Any change applies to purchases made after\nthe change, never retrospectively. Material changes will be notified by\nemail or through the site.
\n", "https://terraphim.ai/properties/date" : null, "https://terraphim.ai/properties/tags" : {}, "https://atomicdata.dev/properties/isA": [ "https://atomicdata.dev/classes/Article" ] },{"localId": "https://terraphim.ai/terraphim-llm-proxy/download/", "https://atomicdata.dev/properties/name" : "Terraphim Proxy — Downloads", "https://terraphim.ai/properties/url" : "https://terraphim.ai/terraphim-llm-proxy/download/", "https://atomicdata.dev/properties/description" : "Signed macOS builds of Terraphim Proxy, served from the Terraphim Skills\nmarketplace. Downloads are tied to the account you purchased with — sign\nin below with that account, then pick a release. Every artefact is listed\nwith its SHA-256 so you can verify the download before opening it.
\nLoading releases…
\n