Connecting
A list of facts is a notebook. Links are what turn it into a reasoning web the advisor can traverse — why a choice was made, what depends on it, what it replaced. This repo's own graph carries 802 edges: 45 asserted by hand, 757 derived from anchors and git history.
Relationships — engrams link add
engrams link add \
--source-type system-pattern --source-id 2 \
--target-type decision --target-id 7 \
--rel implements \
--description "JWT middleware implements the auth decision"
Entity types are hyphenated: decision, progress-entry,
system-pattern, custom-data. Every canonical link is validated
against the ontology below — symmetry, direction, transitivity, domain/range,
same_type, functional_to cardinality, and
disjoint_with. A violation is rejected unless you pass --force,
which records it as an intentional override rather than dropping it silently.
Inspect an item's neighborhood with engrams link list:
engrams link list --item-type decision --item-id 7
# only patterns that implement decision 7
engrams link list --item-type decision --item-id 7 --rel implements --linked-type system-patternThe relationship ontology
| Relationship | Symmetry | Transitive | Notes |
|---|---|---|---|
relates_to | symmetric | — | generic link; any→any |
depends_on | directed | ✓ | has conflicts_with disjoint sibling |
part_of | — | ✓ | hierarchical composition |
refines | — | ✓ | one item sharpens another |
supersedes | directed | ✓ | functional: a decision has at most one successor |
implements | directed | — | e.g. pattern implements decision |
implemented_in | directed | — | range: pr/commit |
conflicts_with | symmetric | — | mutually exclusive |
co_changes | symmetric | — | derived from git co-change history |
anchored_to | directed | — | derived from file anchors |
Inverse edges (superseded_by, depended_on_by, …) are materialized
automatically by engrams graph rebuild, so consumers never need to know which
direction a link was asserted in. The four transitive rels — supersedes,
depends_on, part_of, refines — are the ones
engrams graph chain can walk to answer reachability questions like "what
transitively breaks if I revisit this decision?"
--rel also accepts custom labels. They pass through untouched, are treated as
symmetric for analytics, and are surfaced by engrams doctor for vocabulary
review. This repo's own graph mixes canonical rels (refines,
depends_on) with custom ones (uses, extends,
supports) — allowed, but the canonical vocabulary is what gets validated.
File anchors — engrams anchor add
Anchors bind a decision or pattern to the code it governs. They power
engrams relevant — the "what do I need to know before editing this file?" query —
and the doctor's drift detection.
engrams anchor add --type decision --id 7 --path src/db.rs --path src/models.rs
engrams anchor add --type system-pattern --id 2 --path src/ops
engrams anchor list --type decision --id 7
engrams anchor remove --type decision --id 7 --path src/models.rs
Anchors can also be attached inline at log time with --anchor. Paths are
normalized (./ prefixes stripped), and a directory anchor matches every file
under it recursively — anchoring src/ops covers
src/ops/graph/rel.rs.
PR links — engrams pr add
PR links tie a decision or pattern to the pull request where it was implemented, so the agent can jump from a stored rationale straight to the diff and discussion. A bare number is resolved against your git remote into a full URL automatically.
engrams pr add --type decision --id 7 --pr 42 --pr 43
engrams pr add --type system-pattern --id 2 --pr "https://github.com/org/repo/pull/101"
engrams pr list --type decision --id 7
engrams pr remove --type decision --id 7 --url "https://github.com/org/repo/pull/42"
PRs can also be attached inline with --pr at log time. The doctor flags active
decisions that carry a commit but no PR link, so traceability gaps surface on their own.