Knowledge Graph & Relationships

Capture how decisions relate to patterns, how tasks track decisions, and how configurations depend on other entities. Build a queryable relationship network that gives your AI agent complete workspace topology.

Creating Links

Use the engrams link add command to connect any two entities in your database:

engrams link add \
  --source-type system_pattern --source-id 2 \
  --target-type decision --target-id 7 \
  --rel implements \
  --description "JWT token verification middleware"

Supported Entity Types

You can establish links between the following core entity types in the database:

decision — Architectural or design decisions (ADRs).
system_pattern — Codebase patterns or design standards.
progress_entry — Task tracking and status progress.
custom_data — Configuration key-value data.

Additionally, you can link decisions and patterns to external **Pull Request (PR)** URLs. The interactive HTML dashboard renders PR links as distinct visual nodes (under the relationship type implemented_in), allowing you to trace design decisions directly back to the pull request discussion thread.

Recommended Relationship Types

While the database allows any relationship string, the following standard values are recommended for best agent alignment:

Relationship type	Meaning
`implements`	A pattern or task implements a decision
`tracks`	A task progress entry tracks a decision
`blocks`	One progress entry blocks another
`depends_on`	General dependency relationship
`supersedes`	A new decision replaces/deprecates an older decision
`resolves`	A task progress entry completes a decision requirement
`clarifies`	Custom data clarifies a decision or pattern
`related_to`	General association

Listing and Querying Links

Retrieve all linked items for a specific entity using the list subcommand:

engrams link list --item-type decision --item-id 7

You can filter the query to only return specific relationship types or linked entity types:

# Find all patterns that implement decision 7
engrams link list --item-type decision --item-id 7 --rel implements --linked-type system_pattern

Practical Benefit

By building these relations, your AI assistant can recursively query the graph to understand why certain code files are written the way they are. For example, if it sees a pattern in place, it can retrieve the linked decision to understand the business logic and constraints behind it.