A wikilink says “these two notes are connected.” A typed relationship says how: this note supports that concept, supersedes that plan, contradicts that assumption. The question for an agent-facing knowledge base is what the extra typing buys: not a bigger graph, but a bounded, inspectable one, where every edge is a claim someone authored, and traversal is a budgeted lookup rather than an unbounded wander.
Wordcell’s model is the reference: the graph is built from exactly two authored edge kinds (contextual wikilinks in prose and typed relations in frontmatter), and everything else (backlinks, inverses, transitive closures, similarity neighborhoods) is a derived query result that is never written back into the notes.
two kinds of edges
The two edge kinds carry different meanings and live in different places. A wikilink ([[notes/context-engineering|context engineering]]) is contextual: it sits inside prose where the relationship is part of the argument, and its meaning is whatever the sentence says it is. A typed relationship is an assertion: it lives in the source note’s frontmatter under relations, uses a lower-kebab-case predicate, and targets an exact vault-root note ID without .md:
---
type: concept
title: Durable agent memory
relations:
supports:
- notes/context-engineering
contrasts-with:
- notes/conversation-history
---The source note is the implicit subject. Typed relations answer “what claims does this note make about others” as data (filterable, traversable, checkable) while wikilinks answer “where does the prose send a reader.” Treating them as interchangeable loses both: a Related section full of bare reciprocal links adds edges that mean nothing, and a typed related-to predicate asserts nothing.
a note owns its assertions
The ownership rule is the load-bearing design decision. A note owns its outbound assertions (the claims it makes about other notes live in that note’s frontmatter), so two agents can author relationships on different notes without contending on a central ontology file or edge database. wordcell relation add and relation remove edit one source note’s typed outbound relationship idempotently, and the single-note write path is atomic, revision-checked, and confined to the vault.
Local targets are exact note IDs. Cross-vault targets use canonical stable kb:// URIs, kb://hraness/sleepyland/sound-wellness-expansion, which resolve only against a declared document_id; a note without one keeps its path identity and never gains a stable URI by inference. The authority stays in the same place as the prose: if a relationship matters, the note that asserts it says so, in a file a person can read and git log can audit.
the vocabulary is advisory
The recommended predicate vocabulary covers the common claims (synthesizes, evidenced-by, informed-by, supersedes, contradicts) and it is deliberately not a closed ontology. A vault may author another canonical predicate when its prose and evidence define the claim. What does not choose a predicate: note type, directory location, chronology, shared tags, or semantic similarity. A relationship is a claim with an owner, and the predicate is part of the claim.
That constraint is what keeps the graph legible. When every edge was authored to mean something, a traversal result is a set of claims to inspect, not a statistical neighborhood that might mean something.
what stays derived
Four rules keep the graph honest, and they are all refusals:
- Backlinks and inverse relationships are derived, never written into source notes.
wordcell backlinksandwordcell relation listcompute inbound edges at read time; no tool injects a reciprocal section. - The catalog or authored front door is navigation, not context. Links to or from
index.mddo not count as contextual edges; otherwise the front door would make every note look connected. - A title, alias, recurring tag, shared neighborhood, or semantic match is a candidate, not an edge. It becomes an edge only after a person or agent reviews the evidence and authors the assertion.
wordcell percolateexists exactly for this: it reports recurring-concept and missing-relationship candidates with the authored evidence that produced them, and writes nothing. - Reciprocal, inverse, transitive, and similarity-derived relationships remain query results. They never silently become Markdown facts. Percolation Result V2 emits a missing relationship as an unordered endpoint pair with a required predicate: it does not present either endpoint as the source, draw a directional edge, or suggest
related-to; the reviewer reads both notes and authors a directed assertion only when the evidence determines owner, target, and predicate.
The candidate machinery is careful about what counts as a mention. Fenced code, inline code, frontmatter, and HTML comments are excluded from mention analysis (a note that quotes a title inside a code block has not mentioned it), and line breaks are preserved during masking so diagnostics still point at the authored line. Even the suggestion layer refuses to manufacture edges out of non-claims.
The payoff is reproducibility: inbound counts, outbound counts, backlinks, and orphans are all derivable from the same authored facts, and a disconnected vault cannot be made to look healthy by generated links.
what an agent actually gets
The practical answer to “what does the typed graph buy” is bounded graph context. An agent does not get to wander the whole vault; it gets focused, budgeted answers:
wordcell links <note>traverses incoming, outgoing, or bidirectional contextual links and typed relationships to an explicit depth and node limit, and reports when a high-degree neighborhood reaches the cap.wordcell graph queryruns six reviewed named programs over a bounded Oh projection (backlinks,reachability,relation-closure,scope-route,shared-tags,shared-concepts) with depth defaulting to 3 and bounded at 8,--limitup to 1,000 rows, and explicit budgets over rows, work units, derived tuples, rounds, result bytes, and proofs.relation-closurefollows one exact predicate through typed paths;reachabilityfollows positive contextual and typed paths;shared-tagsandshared-conceptssurface positive co-membership evidence.- Truncation is reported, not hidden: work exhaustion fails instead of claiming completeness, and a truncated result keeps its markers and exits the CLI with status 4.
- Proofs name their evidence (the source note, its content digest, the exact Oh record digest, and the applied rule), and
graphVerifyResultre-evaluates a result against the session snapshot and rejects stale or foreign evidence. - Cross-vault claims stay scoped: a
kb://relationship target is recorded as an external fact but never enters local path closure, so a traversal over the local vault cannot silently absorb another vault’s assertions.
The graph also rides along with retrieval without contaminating it. wordcell search can return the immediate links and typed relationships among results plus a bounded neighborhood around the strongest hits, but those neighbors arrive as a separate context collection. They do not enter the primary text rank and they do not become authored edges. Context is returned beside the ranking, as evidence to inspect, which is exactly what keeps “the graph suggested it” from becoming an unaccountable relevance boost.
What the graph does not buy is inference. An Oh proof shows how the bounded evaluator derived a tuple from the supplied facts; it does not prove an authored claim is true, and the programs are deliberately positive-rule: there is no arbitrary Datalog evaluator, no negation, no aggregation. Typed relationships give an agent findable claims; they do not give it conclusions.
when wikilinks are enough
The honest limit is the same one the agent-memory doc states: a small knowledge base may need only Markdown, Git, an index page, and ordinary file search. Typed relationships earn their keep when the relationships themselves help people make decisions, when “this plan supersedes that one” or “this note contradicts that assumption” is a claim someone will query, audit, or traverse. They are overhead when the honest answer to “how are these related” is “read the paragraph that links them.”
The guidance in the vault rules is symmetric: put a link in prose when the relationship carries part of the argument; use a ## Related section whose bullets state the relationship; and never author bare, reciprocal, or similarity-derived edges to improve graph counts. The graph is a set of claims: its value is that every edge means something because someone meant it.