DEV Community: AlexMikhalev

From AI Risk to Accountable Agents

AlexMikhalev — Sat, 07 Nov 2026 18:04:13 +0000

In AI Risk is evolving, every day., David Hunt and I examined how an AI agent can pursue a legitimate objective through methods outside its mandate. Oversight needs to connect organisational intent, knowledge, authority, actions and consequences.

This article summarises the full paper. To supervise that agent, we need to specify its responsibilities, the concepts it uses, the evidence its work requires and the actions it may take.

Start with an organisational role

“Planning agent” tells us what an agent does, but leaves its responsibility unclear.

A Product Manager breaks outcomes into features and acceptance criteria. A Project Manager turns agreed scope into a delivery plan with dependencies, owners and milestones. Both perform planning, but their work products and authority differ.

An agent's planning capability should belong to a defined organisational role. Its implementation provides services that use tools to perform specific actions.

The chain becomes:

Organisation → role → capability → service → tool → action → contextual permission.

A Project Manager agent might select an approved planning template and create a draft in its assigned project. That assignment does not authorise production deployment. The permission decision must govern the actual tool operation, including alternative routes through shells or delegated agents.

Give the role a defined conceptual space

Each role needs a governed view of organisational knowledge. A Product Manager works with user needs, value hypotheses and acceptance criteria. A Project Manager needs dependencies, resources, risks and delivery commitments. Shared concepts connect their work without making the roles interchangeable.

Figure 1. Proposed role contract: the knowledge needed to plan and the authority to act are explicit.

Terraphim's role-based knowledge graphs make this vocabulary explicit through concepts and synonyms. The inspected indexer connects consecutive recognised concepts in document text, retaining supporting document references. Those associations help retrieve relevant notes and explain why they were selected.

The next layer is to type the relationships. A connection might mean “depends on”, “addresses a requirement” or “requires approval”. The role selects the applicable relationship profile from approved templates, traced to adopted standards or documented organisational extensions.

A sentence mentioning a release, a manager and approval does not establish that approval occurred. “Requires approval” and “was approved” are different claims.

Verify meaning in its context

A checklist can recognise every expected concept while missing a change in meaning.

Suppose a delivery plan must place a rollback rehearsal in staging, with its planned start within eight elapsed hours of a defined failure trigger. An output can contain “rollback”, “rehearsal” and “hours” while moving the activity to production or replacing elapsed hours with business days.

Successful checking therefore requires compatible concepts, relationships and context across the input, output and criteria. Different terminology can be acceptable through an explicit mapping. Changed scope, units, conditions or prohibitions cannot pass silently.

Our paper uses ISO/IEC/IEEE 42010:2022 to frame architecture descriptions and ISO/IEC/IEEE 29148:2018 to distinguish requirements quality and stakeholder intent from evidence about the realised system. This is a standards-informed design, not a conformity claim.

The practical requirement is traceability: identify the requirement version, relevant context, applicable criterion and evidence behind each result. When those conditions change, reassess the affected findings. Unknown context should produce an indeterminate result, not an assumed pass.

Figure 2. Proposed contextual check: passing a planning criterion neither proves the rehearsal occurred nor grants deployment authority.

Make the audit concrete

Terraph, the Terraphim language, connects a role graph, a checklist and a gated action in one program. The graph and checklist compile from Markdown into constant matching automata. embed identifies concepts and source spans; text satisfies preflight reports which checklist items are missing.

The deploy verb declares the evidence it needs. Here, engineer is the example role; it does not change the Project Manager’s authority:

import std;

role engineer from "kg";
checklist preflight from "checklists/preflight.md";

fn deploy(plan: str, ev: Proof<preflight>) -> i64 {
    print("deploy: preflight evidence present, proceeding");
    return 0;
}

The generated verb wrapper obtains a sealed Proof<preflight> through .require() only when no checklist items are missing. The proof binds to the checked snapshot, available as ev.subject.

Figure 3. The Terraph proof gate. The example body prints a message; it does not deploy a system.

Any actual operation must use that checked snapshot and pass a separate authority check. Reopening the plan could read changed bytes. Passing the checklist cannot give a Project Manager production privileges, nor can concept coverage establish that the plan is correct.

Our earlier argument calls for supervision that follows an agent's changing context. An inspectable role contract gives that supervision a defined mandate to check. A Project Manager agent can prepare a plan, preserve its requirements and record the evidence, while release authority stays with the role responsible for exercising it.

Originally published at reference-architecture.ai.

Organisational Roles as Contracts for AI Agents

AlexMikhalev — Sat, 07 Nov 2026 18:03:26 +0000

Abstract

An organisational AI agent needs defined responsibilities, relevant knowledge and bounded authority. This paper proposes roles as contracts for all three. A Project Manager plans delivery; a Product Manager decomposes product outcomes into features. Each uses a governed role-based knowledge graph. Agent services realise role capabilities through tools whose actions require contextual permission. Verification and validation require compatible concepts, relationships and operating conditions across the input and evaluation criteria, with explicit mappings where views differ. A cross-check against ISO/IEC/IEEE 42010:2022 and 29148:2018 informs these distinctions without claiming conformity. Terraphim provides graph retrieval and checklists; Terraph connects concept matching to proof-gated verbs; ADF configurations define responsibilities and artefact templates. The proposed integration would allow a Project Manager agent to create a checked plan from an approved template while reserving production deployment for a separately authorised role.

Continuing the argument on evolving AI risk

This paper continues the argument developed by David Hunt and Alexander Mikhalev in AI Risk is evolving, every day., published on 31 October 2026. Their starting concern is that an agent can pursue a legitimate objective through unauthorised methods. They connect oversight of business activity with cybersecurity and knowledge integrity, and argue that changes to agents and their surroundings can invalidate earlier assurance.

Supervision needs an inspectable mandate: the organisational role, the capability being exercised, the service providing it, and the tool action requested against a particular resource. Role-based knowledge graphs provide the relevant concepts and relationships; an independently enforced permission decision determines whether the action may proceed. A Project Manager can prepare a delivery plan using approved templates while production execution remains assigned to a separately authorised role. The sections below distinguish existing components from the integration still required.

A successful check needs criteria that apply to the input's meaning, obligations and operating context. Matching words cannot establish that a plan preserves a prohibition, uses the correct environment, or retains an acceptance threshold. The semantic compatibility contract developed here connects requirements, criteria and evidence through a versioned baseline and explicit mappings. Changes to that baseline trigger reassessment of affected results. The standards cross-check helps define the responsibilities and evaluation claims; it does not establish that the supervisory system has been implemented.

The common concepts connect the earlier article's concerns to the mechanisms examined in this paper:

Shared concept	Engineering continuation in this paper
Mandate and justified authority	Trace the assigned role through capability, service, tool and action to a contextual permission decision.
Knowledge integrity and context	Use governed concept identities, relationships and requirement baselines to preserve meaning across inputs, outputs and criteria.
Independent supervision	Separate the agent's proposal from the gateway's permission decision and the evidence used to assess its result.
Continued validity of assurance	Bind findings to the evaluated artefact, criteria and context; reassess affected claims when relevant versions change.
Learning and authority to change	Govern changes to role graphs, templates and policies separately from permission to perform the task.
Prediction and operational evidence	Keep illustrative scenarios, expected outcomes and recorded executions distinguishable; validate predictions before relying on them.
Consequences across organisational scales	Make resource and project scope explicit, and identify where wider consequences require escalation beyond the acting role.

This mapping is our architectural synthesis. The examples below illustrate individual mechanisms; connecting them across systems remains engineering work.

The organisational unit of agency

“Planning agent” describes a computational activity. It does not identify who owns the outcome, which planning conventions apply, or what authority accompanies the work. The same ambiguity affects “research agent”, “review agent” and “execution agent”. These labels can be useful implementation names, but they leave organisational meaning unresolved.

A Project Manager plans delivery against agreed scope, dependencies, resources and milestones. A Product Manager decomposes desired outcomes into features, evaluates value and defines acceptance criteria. Both plan, but they plan different objects, draw on different evidence, and answer to different accountabilities. An organisation should therefore delegate to an agent acting in a defined role, with planning as one of that role’s capabilities.

The role contract can remain stable when an agent’s model, prompt, framework or supplier changes. A replacement implementation must demonstrate the required service behaviour and operate within the same authority boundary. Governed role definitions and capability contracts give the organisation a basis for evaluating that replacement.

The central proposal is a traceable relationship:

Organisation → role → capability → service → tool → action → contextual permission.

This sequence is an explanation path, not an assertion that authority flows automatically through every edge. The organisation assigns responsibilities to roles; an agent principal is separately authorised to enact a role. Its implementation supplies services. Tools make actions technically available. Policy determines whether an exact requested action is permitted in its current context.

The organisational semantic layer

The organisational semantic layer describes concepts, relationships, templates, standards and responsibilities using explicit identifiers and versioned definitions. Here, conceptual space means this governed system of organisational meaning. The proposal does not require a fully implemented geometric model of human conceptual spaces.

Element	Organisational meaning	Planning example
Role	A position with responsibilities and bounded authority	Project Manager
Capability	An ability the organisation needs to achieve an outcome	Delivery planning
Service	An accessible behaviour provided by an implementation	Produce a delivery plan
Agent implementation	Software that provides the service while enacting an assigned role	Project planning agent instance
Tool	A concrete interface through which work is performed	Template reader or document writer
Action	A specific operation on an identified resource	Create a draft plan in project workspace
Permission	A policy decision over principal, role, action, resource and context	Draft creation allowed for the assigned project
Evidence	Records supporting a decision and its observed result	Template version, checks and execution receipt

This distinction between capabilities and services is compatible with enterprise architecture’s separation of organisational behaviour from its realisation and exposed services. It is used here as an architectural vocabulary, without claiming formal compliance with an ArchiMate model. Open Group ArchiMate 101

A capability describes what the organisation can accomplish. It is not a permission token. Likewise, an implementation’s demonstrated competence does not grant authority. A model may understand deployment instructions while having no right to invoke a deployment endpoint.

Role capabilities contribute to broader organisational capabilities. For example, an organisation’s Product Delivery capability can depend on Product Discovery performed by the Product Manager, Delivery Planning performed by the Project Manager, and Release Assurance performed by the Release Manager. The graph records these contribution relationships explicitly. Separate agent services realise the role capabilities; their combined performance supports the organisational outcome without granting each service the authority of every contributing role.

Roles should also be sufficiently specific to support ownership. An organisation can assign a person or agent multiple roles, but each action should use an explicit active role and bounded assignment. Combining role knowledge for a discussion must not silently combine execution privileges.

Role	Dedicated conceptual view	Principal service	Example boundary
Product Manager	Outcomes, user needs, features, value hypotheses and acceptance criteria	Produce an evidence-linked feature breakdown	Cannot approve production deployment
Project Manager	Scope, dependencies, resources, risks and delivery milestones	Produce a delivery plan from an approved template	Can write a project draft; cannot deploy it
Release Manager	Release readiness, change records, environments and rollback procedures	Coordinate an authorised release	Production action requires a separate assignment and satisfied release policy

These are example contracts, not universal job descriptions. The organisation owns the actual definitions and decides where responsibilities overlap.

Dedicated knowledge without isolated vocabularies

Each role receives a governed projection of organisational knowledge. This can select which concepts and relationships are available to the role, as well as how retrieval ranks them. Roles can share an underlying graph while retaining different conceptual views.

Shared concepts retain shared identifiers. For example, a feature’s acceptance criteria connect product intent with delivery planning and release verification. Role-specific relationships express what matters for each responsibility: a Product Manager connects a criterion to user value; a Project Manager connects it to delivery evidence and dependencies; a Release Manager connects it to a release decision. The shared identity supports handoffs without making the roles interchangeable.

Role-owned overlays can define local vocabulary, specialised relationships, approved templates and checklist requirements. Their provenance should identify the owner, source, revision and approval state. Changes to the shared definition of “accepted” require different governance from adding a convenient synonym to a role’s retrieval vocabulary.

Graph projections must also respect access controls. Knowing that another team’s confidential plan exists does not authorise retrieving its contents. A role graph is a semantic view; a separately authenticated assignment and resource policy determine what information the agent may actually read.

The graph is the inspectable, or white-box, component of this architecture. A reviewer can examine its concepts and relationships, the embeddings derived from them, and the definitions that shaped retrieval. This visibility neither makes the language model transparent nor establishes that the graph's contents are correct.

Architecture description and requirements engineering

ISO/IEC/IEEE 42010:2022 concerns architecture descriptions, including viewpoints and model kinds. It distinguishes an architecture from its description and does not prescribe an agent implementation or execution policy. In that standard, ADF means architecture description framework; the ADF agent orchestration system discussed here is a different use of the acronym. ISO/IEC/IEEE 42010:2022

For this architecture, stakeholder concerns, viewpoint conventions and resulting views must remain distinguishable from organisational roles. A viewpoint establishes conventions for constructing and interpreting views that address concerns. ISO 24641:2023 preview

A role can serve several stakeholder concerns and use several viewpoints. A role graph becomes useful architectural material when its concepts, relationships, conventions and intended questions are explicit. It is not automatically a viewpoint; a project plan is not automatically an architecture view. Terraph's language constructs likewise do not establish that it is a conforming architecture description language. The standards do not assign the paper's Project Manager, Product Manager or Release Manager jobs their permissions.

ISO/IEC/IEEE 29148:2018 addresses requirements engineering and its information across the life cycle. Its terminology distinguishes checks on requirements from checks on the realised product or system. The following four questions must not be collapsed into a single “validation passed” label. ISO/IEC/IEEE 29148:2018 official preview

Activity	Question and object
Requirements verification	Are the requirement statements and set well formed?
Requirements validation	Do those requirements express the intended stakeholder needs?
Product or system verification	Does the realised item fulfil its specified requirements?
Product or system validation	Does it support its intended application and use?

Each decision needs the applicable activity and evidence; an individual tool check need not perform all four. A reviewed input baseline is particularly important: an output checklist cannot retrospectively establish what the stakeholder meant.

The following crosswalk is this paper's proposed design, not an ISO clause-compliance matrix:

Standards-related distinction	Application to the proposed agent contract
Stakeholder concern and viewpoint	Name the decision owner, concern and representation conventions; bind the agent's organisational assignment separately.
View and modelling conventions	Specify graph concept and relationship types, interpretation rules and correspondences between role views.
Requirement and traceability	Connect each obligation to its need, responsible role, input baseline, criteria, output and evidence.
Verification and validation	Name the checked object, the predicate or intended-use scenario, its applicable context and the decision supported.

This is a bounded cross-check using official public material. It is neither certification nor a full-text normative clause audit. The richer semantic contract below is the paper's engineering proposal, not a claim that either standard mandates knowledge graphs or this permission scheme.

Semantic compatibility between inputs and criteria

A check is meaningful only if its criteria apply to the relevant meaning and context of its input. “Release” can mean software deployment or approval of a payment; the same token need not denote the same concept. A plan for staging cannot be validated against production assumptions merely because both mention “release”. A criterion about elapsed hours cannot silently become one about business days. Evaluation requires compatible conceptual spaces, not identical wording or complete identity between two role graphs.

The proposed trace is:

Requirement ID and revision → stakeholder need → responsible role and relevant viewpoints → input concepts, propositions and context baseline → verification criterion and validation scenario → evidence → decision.

The baseline identifies the entity and project, source and requirement revisions, environment, relevant time and calendar, units and thresholds, assumptions, exceptions and prohibited actions. A proposition preserves who must do what to which object, under which conditions, with its polarity and quantifiers. “Every accepted feature” and “some features” can share concepts while imposing different obligations.

Verification and validation may use different abstractions. A product view can describe a customer outcome while a delivery view describes work packages. Their mapping must explain how the relevant obligation survives decomposition and which evidence supports it. Approved unit conversions and concept mappings may establish compatibility; fuzzy similarity alone cannot. Additional derived criteria can be legitimate when their rationale and relationship to the stakeholder need are recorded. An obligation cannot disappear merely because a role projection omits its vocabulary.

This paper proposes the following contract. These SHALL statements are authored requirements for the proposed integration, not quotations from ISO:

A check SHALL identify its object, requirement baseline, applicable criteria and relevant context revisions. The requirement owner and authority to resolve ambiguity or change the baseline must be recorded.
A transformation SHALL preserve relevant obligations or carry an explicitly approved mapping or change. This includes relationships, polarity, quantifiers, units, thresholds, scope and assumptions, not just concept identifiers.
A decision SHALL distinguish pass, fail, indeterminate and justified not applicable. Missing context, unresolved mappings or insufficient evidence cannot yield a pass; not applicable needs a recorded reason and authorised acceptance.
A result SHALL bind to the evaluated state and be reassessed when a relevant change invalidates it. Passing semantic or quality checks never substitutes for an action's separate authority decision.

Context compatibility is necessary but insufficient. A perfectly aligned test can still have a weak predicate, unreliable evidence or inadequate coverage. Criteria must themselves be verified and validated for their purpose; their evaluation must establish the promised claim. Checks should report only what their evidence supports.

Connecting meaning with authority

The architecture needs four cooperating parts: identity and assignment, semantic knowledge, mediated execution, and audit evidence.

Figure 1. Connecting meaning with authority. Open the diagram source in Mermaid Live.

Role-based access control provides a foundation: subjects are assigned authorised roles, and operations are mediated through the permissions of those roles. A session can activate a subset of the roles available to a subject. NIST RBAC

The proposed architecture adds organisational meaning to this assignment and applies contextual conditions to execution. Project identity, resource scope, environment, approval state and expiry can all matter. This is consistent with attribute-based access control, which evaluates attributes of the subject, object, operation and environment against policy. NIST SP 800-162

Let a request be q = (principal, role, service, tool, action, resource, arguments, context). A simplified decision rule is:

permit(q) =
    authenticated(principal)
    AND active_assignment(principal, role, scope, expiry)
    AND capability_service_binding(role, service)
    AND registered_service_tool_action(service, tool, action)
    AND resource_and_argument_scope_match(q)
    AND required_evidence_valid_for_exact_request(q)
    AND contextual_policy_allows(q)
    AND NOT explicit_deny(q)

An absent or indeterminate condition produces no permit. This is a proposed contract, not a description of a policy engine already supplied by Terraphim.

The gateway must mediate actual effects. Hiding a deployment tool in a user interface is insufficient if the same principal can deploy through a shell, network client or overprivileged service credential. The action boundary includes alternative routes, delegated agents and mutable resource references. A delegate receives only an authorised subset of the parent’s scope; it cannot turn a planning request into a production privilege.

Terraphim graph embeddings as a role context mechanism

Terraphim’s graph approach supplies a concrete semantic mechanism for the role view. Concepts and surface forms are represented explicitly, and graph relationships support retrieval and explanation. Its documented graph retrieval path uses normalised concepts, synonym matching and document co-occurrence structure, rather than requiring a neural vector embedding model. Terraphim graph embeddings

The inspected general RoleGraph implementation uses Aho–Corasick matching to resolve surface forms to concept identifiers. Its document indexer creates edges between consecutive recognised concepts in the indexed text and retains supporting document references. Retrieval then accumulates node, edge and document rank. Matched edges and tags make the retrieval basis inspectable. A high rank indicates retrieval support under that graph, not factual certainty or authority.

For organisational planning, this allows terms such as “delivery roadmap” and “project plan” to resolve according to the organisation’s chosen vocabulary. The interpretation is role-dependent: a delivery roadmap may emphasise dependencies and milestones for a Project Manager, while a product roadmap emphasises outcomes and prioritisation.

The organisation should keep equivalence and relationship separate. A synonym maps a surface form to a concept. A relationship links distinct concepts. “Risk log” may be an agreed synonym for “risk register”, but a register and an individual risk remain distinct concepts. “Risk” and “deployment permission” must not become equivalent merely because they occur together in operational documents.

Graph embeddings make the retrieval context reproducible. A result can identify the recognised concept and supporting relationship evidence, explaining why a planning template or dependency policy was selected. Template currency, the truth of retrieved claims and action authority require separate checks against authoritative metadata, evidence and policy.

From co-occurrence to typed organisational relationships

The existing concept vocabulary and the associations found in text play different parts in constructing the role's conceptual space. The role's thesaurus supplies the concepts that can be recognised and the synonyms that resolve to them. Indexing identifies occurrences of those concepts in notes and documents, then constructs connections from the matching text. Retrieval uses that structure to select relevant material. In this path, a connection is discovered between recognised concepts; it does not establish a new concept definition or a new organisational rule.

Sentence-level co-occurrence provides an intuitive starting assumption: concepts mentioned together may be related. The inspected implementation has a broader boundary. The document indexer takes the matching concept sequence from the indexed document and connects adjacent matches without invoking the available sentence-splitting helper. Associations can therefore cross sentence boundaries. A sentence-bounded association rule would require an explicit indexing change; it is not a current guarantee.

Even within one sentence, proximity leaves the relationship unspecified. A note can mention a requirement and a test because the test satisfies it, fails it, or has not yet been performed. The association graph cannot decide which statement holds. The proposed semantic layer must establish the connection's meaning, direction and conditions before admitting it as a typed organisational claim.

Layer	Representation	What it establishes
Role vocabulary	Canonical concepts and approved synonyms	Which concept a recognised expression denotes within the role's domain.
Text association	Connections between matched concepts, with document evidence	Where concepts occur together or in the indexed matching sequence.
Organisational interpretation	Typed, contextual propositions governed by role templates	Whether a connection expresses a dependency, responsibility, requirement, evidence claim or other admitted meaning.
Evaluation and execution	Applicable criteria, evidence checks and permission decisions	Whether the specific claim is supported and whether the requested action is authorised.

The organisational semantic layer supplies the relationship vocabulary. A role selects an applicable profile of that vocabulary, together with the templates for its work products. A Project Manager's delivery-plan template may admit dependencies between milestones and assignments of responsibility. A Product Manager's feature template may admit derivation from stakeholder needs and links to acceptance criteria. Shared concepts retain their identities across these views; the role determines which governed relationships are relevant, rather than inventing their meanings during each interaction.

The proposed governance rule is that every admitted organisational relationship type SHALL be defined in a versioned, approved template or semantic profile, with traceability to the applicable adopted standards or an explicitly approved organisational extension. The profile records the standard edition and relevant requirement or definition where applicable. Where a standard leaves a modelling choice open, the organisation records its extension and rationale. This preserves standards-based discipline without asserting that industry standards already name every graph predicate used by an organisation. ISO/IEC/IEEE 42010:2022 and ISO/IEC/IEEE 29148:2018 inform the distinctions discussed earlier; the illustrative predicate names here are not standard-prescribed vocabulary.

A relation definition needs more than a label. It identifies the permitted source and target concept types, direction, interpretation, applicable role and work product, and required qualifiers such as environment, time, polarity or evidence state. For example, verifies might connect a verification activity to a requirement, while producedEvidence connects its execution to a result. A planned test and a completed test cannot be substituted merely because both connect to the same requirement.

Consider the sentence: “The Release Manager must approve production deployment after verification.” An association graph can connect the recognised concepts Release Manager, production deployment and verification. In a governed release template, those associations could support the candidate propositions deployment requiresApprovalFrom ReleaseManager and deployment requiresEvidence verificationResult. These describe obligations; they do not record that approval was given or that verification passed. An observed approval requires separate evidence identifying its issuer, subject, decision and applicable version. The runtime must still establish that the issuer and acting agent have the necessary authority.

Typing a connection is therefore a controlled interpretation step. A candidate keeps its source text and concept matches; the role template supplies permissible predicates and structural constraints; a check establishes whether the text and independent evidence support the proposed proposition. An extraction model can propose a type, but a plausible label is not sufficient to admit the claim as organisational knowledge. Ambiguous, unsupported or conflicting propositions remain unresolved. The association evidence is retained so that a reviewer can reconstruct how the candidate arose.

Verification and validation must compare typed propositions and their qualifiers across the input, output and evaluation criteria, using approved mappings where views differ. A test that finds every concept but converts requiresApprovalFrom into approvedBy, or removes a prohibition, has changed the claim. The audit must expose that change. Graph coverage can find omitted concepts; checking typed relationships addresses whether the connections preserve the intended meaning.

Retrieving an approved planning template

The following command is an illustrative invocation using the installed terraphim-grep interface. The paths represent a proposed organisational knowledge layout; they are not supplied sample data or a claim that this particular corpus was executed.

terraphim-grep "delivery plan" \
  --role "Project Manager" \
  --haystack all \
  --paths ./organisation/templates/planning \
  --thesaurus ./organisation/roles/project-manager/thesaurus.json \
  --search-only -n 8 -C 2 --json

The dedicated thesaurus makes the role’s vocabulary concrete. --search-only keeps this invocation on its search path without LLM synthesis. The implementation can fall back to thesaurus matching when populated graph evidence is absent; a result alone does not demonstrate graph traversal. Search produces candidates; the service then checks each candidate against the authoritative template registry. The chosen template must be approved, applicable to the project type, available to the active role and identified by an immutable revision or content digest. Restricting search paths narrows retrieval; it does not establish an execution sandbox.

This distinction matters when a semantically excellent match is obsolete. The organisation’s semantic layer may help locate it, but the planning service must select an eligible template. If none exists, the service should request a governed template decision rather than manufacture an “approved” template itself.

A graph-based planning checklist

A checklist makes an expected output contract explicit. Terraphim’s published checklist approach places enumerated concepts outside the model and uses the same graph machinery for recognition and retrieval. Graph embeddings for checklists

The current source also supports a paired input/output graph-coverage mode. An illustrative planning checklist, saved as .terraphim/checklists/project_plan.md, is:

# Project plan

mode:: graph-coverage-v1
checklist:: scope, dependencies, risk register, acceptance criteria

### risk register

synonyms:: risk log

Its concepts and aliases must resolve uniquely in the configured role graph; declaring an alias in a checklist does not create the missing graph concept. The checklist is not a substitute for building and governing that graph. A source-level invocation for the inspected implementation is:

terraphim-agent validate \
  --role "Project Manager" \
  --checklist project_plan \
  --input-file brief.md \
  --json < plan.md

This --input-file form is supported by the inspected client source, not by the locally installed 1.21.22 command interface. The example is therefore a source-supported integration example, not an installed-binary demonstration.

The paired check requires recognised input concepts and checklist concepts to appear in the output, with supporting stored graph paths. Its report distinguishes pass, fail and indeterminate. A service using it as a gate must inspect that verdict; successful CLI completion alone does not establish a passing checklist.

Concept coverage is one limited checking predicate. A plan can mention “dependencies” while assigning them incorrectly, or include “acceptance criteria” that do not test the promised outcome. The complete planning contract consequently layers structural checks, graph concept coverage and evidence review. The graph checker supplies an inspectable signal within that contract. It does not establish the full semantic compatibility contract, verify every asserted relationship or confer permission to publish or execute the plan. Its lexical negation handling does not constitute general verification of proposition meaning.

Worked example from brief to bounded plan

Consider a project to deliver a customer-facing feature. The Product Manager agent receives an authorised assignment to prepare a feature breakdown. Its graph connects the product outcome to needs, features, value assumptions and acceptance criteria. It produces a versioned breakdown and hands that artefact to the Project Manager service.

The Project Manager agent authenticates under its own scoped assignment. It retrieves candidate planning templates through its role thesaurus, selects an approved revision, and creates a draft connecting the agreed features to milestones, dependencies, owners and risks. It preserves the incoming acceptance criteria and identifies unresolved assumptions.

The service checks the draft’s structure and invokes the graph checklist. A missing recognised requirement produces a failed or indeterminate result that must be resolved before the relevant transition. A passing result is recorded alongside its limitations. Further review establishes whether the proposed dependencies and acceptance evidence are adequate.

When the service requests create_draft on the assigned project’s document store, the gateway evaluates the exact operation, destination and content digest. Assuming the role assignment, template, checks and policy conditions are valid, it permits that write and records its outcome.

Now suppose the agent requests deploy against production. The request fails the role-to-service/action binding and the production policy. Mentioning deployment in the plan, retrieving a release runbook, or passing the planning checklist cannot repair that missing authority. The gateway records a denial before an effect occurs.

The agent may instead hand the approved plan to the release management process. That handoff supplies evidence, not inherited production credentials. A separately authorised release principal must satisfy its own contract. The organisation can therefore automate preparation without collapsing preparation, approval and execution into a single unrestricted agent.

Checking the planning context

Consider an illustrative requirement R-17 revision 3: the plan must specify a staging rollback rehearsal whose planned start is no earlier than the simulated-failure trigger and no later than eight elapsed hours afterwards. The baseline defines that trigger as the rehearsal protocol's injected-failure timestamp. Production deployment is outside the Project Manager's scope. The stakeholder need is to coordinate a usable rehearsal without delegating production execution.

A verification criterion checks the plan's environment, planned start offset and preserved prohibition against that baseline. A validation scenario asks the delivery and release stakeholders whether the proposed handoff enables the intended rehearsal with the available people and resources. The plan's check does not prove that a rehearsal occurred. Later testing of the delivered system requires its own evidence; a good plan does not establish successful system behaviour.

Candidate interpretation or evidence	Required treatment under the proposed contract
“One business day” replaces eight elapsed hours	No silent equivalence. Resolve the calendar and conversion; fail if the interval changes, otherwise retain the approved mapping.
The plan schedules the rehearsal in production	Fail the known environment mismatch; separately deny unauthorised production actions.
The evaluator uses revision 2's 24-hour threshold	Reject the stale criterion binding and reassess against revision 3.
“Must not deploy” becomes “may deploy”	Fail proposition preservation despite matching deployment concepts.
Relevant calendar or requirement revision is unknown	Return indeterminate until the baseline is resolved.

The same protection applies when views use different language. “Pre-production” can map to the named staging environment if the organisation explicitly defines that equivalence. Matching the spelling “staging” in an unrelated project's evidence cannot establish that the requirement was met.

Terraph audit with one role and one checklist

This Terraph example connects a role graph, a checklist and three verbs: audit, check and deploy. Here, engineer is the example role; it does not change the Project Manager’s authority. The graph and checklist are Markdown inputs compiled into constant matching automata. embed and satisfies are language intrinsics, so retrieval and checking use the same concept definitions.

import std;

role engineer from "kg";
checklist preflight from "checklists/preflight.md";

// Audit concept coverage and report the matching source spans.
fn audit(path: str) -> i64 {
    let src = read_file(path);
    if src.len == 0 {
        print("cannot read ", path);
        return 1;
    }
    let h = embed(src);
    let cov = coverage(h);
    print("file: ", path);
    print("kg_hits: ", cov.kg_hits, "  concepts: ", cov.concepts,
          "  confidence: ", cov.confidence, "  diversity: ", cov.diversity);
    for m in h {
        print("  ", m.concept, " @", m.start, "..", m.end);
    }
    if cov.sufficient() {
        print("sufficient: yes");
        return 0;
    }
    print("sufficient: no");
    return 1;
}

// Diagnose missing checklist items. This verb does not issue a proof.
fn check(text: str) -> i64 {
    let miss = text satisfies preflight;
    if miss.any() {
        print("checklist preflight: incomplete");
        miss.report();
        return 4;
    }
    print("checklist preflight: complete");
    return 0;
}

// The generated wrapper supplies a sealed proof for the checked snapshot.
fn deploy(plan: str, ev: Proof<preflight>) -> i64 {
    print("deploy: preflight evidence present, proceeding");
    return 0;
}

audit exposes which concepts matched and where. check reports missing checklist items. At the gated entry point, the generated verb wrapper obtains a sealed Proof<preflight> through .require(), which succeeds only when no items are missing. The function signature makes that evidence a prerequisite for entering deploy.

The proof carries the checked snapshot as ev.subject. Any operation justified by the gate must consume that snapshot; reopening the path in plan could read changed, unchecked bytes. The sample body only prints a message. Actual deployment still requires an authorised role assignment and resource policy, and concept coverage alone does not establish that the plan is correct. The example shows the language boundary; it is not a recorded deployment.

ADF configuration gives the role an organisational task

The ADF agent orchestration configurations assign organisational responsibilities. The checked-in Product Owner template names an implementation and declares these fields. Product Owner is the configured role; it is distinct from the illustrative Product Manager role used earlier:

[[agents]]
name = "product-owner"
persona = "Themis"
capabilities = [
    "planning",
    "roadmap",
    "issue-creation",
    "prioritisation",
]
project = "terraphim"

Its skill chain includes research, design, specification, architecture, business scenario design, requirements traceability and acceptance testing. The task defines the work product: each proposed issue must identify its organisational goal, describe the problem and proposed solution, and supply Given–When–Then acceptance criteria. The template also requires a priority estimate, a communication hint and the suggested delivery agent. The workflow narrows the backlog, scores the surviving items and proposes up to two new issues.

These selected literal fields show the existing issue template. Its brackets indicate fields the Product Owner must fill; WIG means the organisation’s current Wildly Important Goal.

Title: [concise, imperative]
WIG: [which WIG this serves, or skip if none]
Problem: [2-3 sentences describing the problem]
Proposed solution: [bullet points, no hand-waving]
Acceptance criteria (mini-UAT):
  Given [precondition]
  When [action]
  Then [observable outcome]

The configuration connects the Product Owner’s planning capability to a defined work product and template. It records operational intent; this inspection does not establish that the agent is deployed or that every configured step succeeds.

The repo-local ADF configuration separately declares a Developer, Reviewer and Merge Coordinator, with distinct capability lists and named Terraphim roles:

Configured agent	Declared Terraphim role	Responsibility expressed in the configuration
`developer`	Terraphim AI Developer	Implementation, Rust development and test-driven development
`reviewer`	Terraphim AI Reviewer	Code review, quality gates and review coordination
`merge-coordinator`	Terraphim AI Merge Coordinator	Merge coordination, CI/CD and conflict resolution

The orchestrator’s merge path checks four required status contexts: native-ci / build (push), adf/pr-reviewer, adf/validation and adf/verification. It also requires canonical gate-result records for the current pull request head. Blocking findings and the project's treatment of concerns affect the decision. Evidence for an older commit cannot substitute for the current head’s review, binding the decision to that part of its context baseline. The labels adf/validation and adf/verification do not establish that their producers perform the corresponding ISO requirements or system activities.

Configuration intent and runtime enforcement must remain distinguishable. The inspected repo-local loader sets terraphim_role to None; the declaration alone does not prove that an agent receives the named role graph. Instructions such as “do not merge” are task text, and the Product Owner’s broad shell access is not a production-deployment barrier. The merge gate controls the orchestrator’s merge path; it does not prove that every alternative credential or tool path is mediated. Its structured records are not independently authenticated merely by having the expected fields.

ADF declares responsibility, capabilities, workflow and expected artefacts. Terraph implements bounded tool access, checks and receipts; Terraphim provides the role vocabulary and graph context. Connecting them still requires authenticated role assignments, capability-to-service identifiers, approved artefact versions and policy decisions tied to exact requests.

W3C PROV provides terms for recording entities, activities and agents, including derivation, association and delegated responsibility. These relationships can describe an artefact’s origin and an agent’s participation; a provenance statement alone is not an authorisation decision. W3C PROV-O

Evaluation and implementation boundaries

The proposal can be evaluated without assuming that more graph coverage means safer behaviour. A test corpus should pair legitimate planning tasks with boundary cases and preserve the same role assignments and policy across agent implementations.

Test	Expected observable result
Valid plan from an approved template	Draft created in the assigned project with complete evidence links
Semantically relevant but withdrawn template	Candidate rejected by template eligibility policy
Required concept omitted	Graph report identifies a fail or indeterminate result; gated transition does not proceed
All terms present but a dependency is wrong	Concept coverage may pass; substantive review detects the error
Project Manager requests production deployment	Denied before any deployment effect
Deployment attempted through an alternative tool	Same authority boundary enforced
Artefact changes after checking	Previous evidence rejected for the changed request or bytes
Role assignment expires before execution	Gateway denies or requires a fresh valid assignment
Agent implementation is replaced	Service contract and authority boundaries remain unchanged
Concepts match but polarity, environment or units differ	Relevant semantic predicate fails, or unresolved meaning is indeterminate
A role projection drops a critical obligation	Trace check rejects the transformation or requires an approved change
Different role views have an approved meaning-preserving mapping	Compatibility can be established; substantive criteria still require evidence

Measurements should include accepted legitimate tasks, incorrect denials, unauthorised effects, trace completeness and the cost of reconstructing a decision. Report semantic-check accuracy separately from policy enforcement. A test that finds no bypass in a bounded suite is evidence about that suite, not proof that all possible tool paths are mediated.

Terraphim already supplies relevant semantic components, and Terraph supplies concrete prototype mechanisms for compiled checks and evidence. ADF provides configured organisational responsibilities and an implemented orchestrator merge gate. The end-to-end organisational contract, contextual requirement-to-criterion alignment, authenticated role binding, complete execution mediation and linked audit schema remain the integration proposed in this paper. No production deployment result or benchmark is claimed here.

Role owners must maintain concepts, templates and policies, and reviewers must understand what each checklist establishes. Graph updates need controlled promotion because a vocabulary change can alter which obligations appear satisfied. Audit records should retain enough versioned evidence to reconstruct decisions while limiting sensitive content.

Conclusion

An agent’s organisational role provides a durable basis for knowledge, responsibility and delegated authority. Capabilities explain the outcomes the role must support; services describe how an agent implementation supplies them; tools expose actions; contextual policy determines which actions may occur. A role-based knowledge graph makes the concepts and relationships behind the work inspectable. Meaningful verification and validation also require those concepts, their propositions and the operating context to align with the applicable criteria through explicit, traceable mappings. A shared vocabulary alone cannot preserve an obligation.

Terraphim supplies explicit concept matching, co-occurrence associations, graph retrieval and graph-based checklists. The proposed next layer types those associations using governed role templates and standards-traceable relationship definitions, distinguishing a mention from an obligation and an obligation from an evidenced event. Terraph illustrates how compiled checks can produce evidence tied to the subject being checked. Connecting these mechanisms to authenticated role assignments and mediated execution yields a traceable organisational contract.

For a Project Manager agent, the contract requires an approved planning template, preserved requirements, a checked plan and operation within the assigned project scope. Production deployment belongs to a separately authorised role and process. The evidence must allow a reviewer to reconstruct both the planning result and the authority decision.

Sources and scope

Public sources are linked beside the claims they support. The preceding article by David Hunt and Alexander Mikhalev was published on 31 October 2026 and read on 4 November. The continuation and concept mapping are this paper's synthesis.

Terraphim and ADF implementation details were checked against local source on 3–4 November 2026. The Terraph example above was supplied by Alexander Mikhalev; its comments have been shortened and its function bodies retained. Source revisions, implementation paths, recorded fixture results and inspection limits remain in the internal research notes.

The standards cross-check used official catalogue records and accessible previews. The complete normative text of ISO/IEC/IEEE 42010:2022 was not inspected, so no clause-by-clause conformity claim is made. The role contracts, typed relationship profiles, contextual criteria and cross-system bindings are proposed integration work. The examples do not demonstrate a live production deployment.

Originally published at reference-architecture.ai.

Terraphim Skills is live in ChatGPT: search and inspect engineering workflows

AlexMikhalev — Sun, 01 Nov 2026 00:54:53 +0000

Terraphim Skills 1.0.0 is now available as a ChatGPT plugin. It brings our engineering-skills catalogue into a conversation so you can search for a relevant workflow, inspect its metadata, and read content your connected account is entitled to access.

The public listing is here: https://chatgpt.com/plugins/plugin_asdk_app_6ad14146f1d881918de38350db724616

What you can do

The integration exposes five read-only tools:

whoami checks the connected account.
list_skills browses the catalogue.
search_skills finds skills related to a task.
show_skill inspects a skill's details.
get_skill_content retrieves content where the account permits it.

A practical starting point is to search for a skill that matches the work in front of you, inspect its description, and then use the relevant workflow as a guide. The catalogue is organized around concrete engineering and knowledge-work practices, including a V-model path from research and design to verification and validation.

Access and boundaries

The plugin is read-only. What appears in ChatGPT follows the connected Terraphim Skills account's entitlement. Premium skill bodies are not available through ChatGPT. The public listing and the install control are shown in the screenshot below.

To get started, open the Terraphim Skills listing, install the plugin, and connect your account. Then ask ChatGPT to search the catalogue for the workflow you need.

We would welcome feedback on the skills you try and the workflows you want to see next.

Graph Embeddings You Can Watch Being Built

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

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

Graph Embeddings You Can Watch Being Built

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

What the page does

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

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

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

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

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

The honest comparison

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

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

Try it

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

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

Graph Embeddings for Checklists

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

Originally published at terraphim.ai.

Graph Embeddings for Checklists

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

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

The Checklist Is an Automaton, Not a Promise

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

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

# bun add

Install dependencies using Bun package manager.

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

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

Before the LLM Call: Retrieval as Checklist Execution

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

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

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

The result, abridged:

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

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

The honest empty case

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

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

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

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

Reproduce it

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

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

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

After the LLM Call: The Hook Is a Findings Checklist

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

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

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

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

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

When the checklist itself fails

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

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

The Loop, Closed

Put the phases together and the checklist lifecycle is:

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

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

Why This Is Not a Vector Problem

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

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

Context Engineering: the book is out

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

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

They fail because the context is.

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

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

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

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

Inside, 25 chapters cover:

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

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

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

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

3 Ways to Save Money on Tokens for Your AI Agents

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

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

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

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

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

1. Search first, let a cheap model summarise

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

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

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

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

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

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

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

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

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

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

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

So we split the model placement:

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

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

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

3. Put a proxy in front of the providers

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

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

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

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

What we do not claim

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

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

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

Testing a learning hook from failed command to real execution

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

Update: what the model requested, and what actually ran

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

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

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

The original walkthrough below retains its original recorded outputs.

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

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

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

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

Download the Harbour hooks example · Read the transcript

Start with the command that fails

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

python3 validate-brief.py --chek

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

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

Capture the failure that really happened

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

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

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

Review and promote the correction

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

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

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

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

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

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

Inspect the hook before involving execution

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

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

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

Verify what the coding host actually runs

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

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

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

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

Reproduce it in a new folder

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

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

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

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

Keep the scope of the example visible

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

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

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

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

Testing authored memory across fresh CLI processes

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

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

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

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

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

Download the Harbour example · Read the transcript

Start with an instruction worth keeping

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

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

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

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

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

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

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

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

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

End the process, then open the memory

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

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

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

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

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

Teach the role the words used by the project

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

Its small graph has a Brief validation concept:

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

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

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

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

Retrieve the instruction, then check the empty cases

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

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

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

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

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

What happens inside the CLI

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

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

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

Try the next run yourself

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

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

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

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

From editor alternatives to synonym-aware search with Terraphim

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

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

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

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

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

Try the editor and download the actual files.

Start with the sentence

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

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

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

Make the relationship inspectable

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

synonyms:: Risk, Concern

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

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

Search with the meaning you just recorded

I pass that exported graph to terraphim-grep:

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

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

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

Decide whether you need a generated answer

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

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

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

Open the same example in Obsidian

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

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

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

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

Open the same example in Logseq

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

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

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

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

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

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

Try the released VS Code extension and the Kilo example

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

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

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

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

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

Try the evidence, not just the video

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

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

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

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

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

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

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

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

Two paths. CLI first.

What "integrate" means here

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

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

/tsearch "System Operator" RFP

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

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

Path A -- CLI via slash command

Why this is the recommended starting point

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

One file, two hosts

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

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

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

Why fast enough

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

Three example queries

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

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

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

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

Build and install

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

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

Register

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

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

Claude Code -- one shell command per server:

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

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

SessionStart primer (both paths)

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

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

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

When to pick which path

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

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

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

Why this is the right shape

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

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

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

Try it

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

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

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

# Reload roles
terraphim-agent config reload

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

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

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

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

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

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

What the demo is

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

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

Run it

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

./scripts/setup_system_operator.sh

Then either drive the role via the server --

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

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

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

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

The piece people miss

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

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

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

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

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

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

How it compares to the Personal Assistant role

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

The two roles expose the same pattern at two scales:

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

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

Why this matters for teams evaluating MBSE tooling

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

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

Try it

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

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

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