Relationships

Entry Relationships - Building Knowledge Graphs for AI Context

Build a knowledge graph by linking project entries with typed relationships, enabling AI to understand how your work connects and evolves.

Overview

Entry relationships are critical for AI context management. By linking related entries (design → implementation → testing), you create a knowledge graph that AI can traverse to understand:

Decision chains - Why you made certain choices and their outcomes
Implementation history - How features evolved from concept to production
Failed approaches - What you tried that didn't work (prevents repeated mistakes)
Dependencies - How different parts of your project connect

Without relationships: AI sees isolated entries with no connection between design decisions and implementations.

With relationships: AI traces complete context chains: "Design decision" → "Implementation" → "Bug fix" → "Optimization"

Creating Relationships

The `link_entries` Tool

Link two entries with a typed relationship.

Basic Usage:

link_entries({
  from_entry_id: 42,
  to_entry_id: 40,
  relationship_type: "implements",
});

With description:

link_entries({
  from_entry_id: 43,
  to_entry_id: 42,
  relationship_type: "clarifies",
  description:
    "Adds detailed documentation for the lazy loading implementation",
});

Output:

✅ Created relationship: Entry #42 -implements-> Entry #40

Relationship Types

`references`

General connection between entries.

Use when:

Entries are related but no specific relationship
Mentioning related work
Cross-referencing topics

Example:

// Blog post references research notes
link_entries({
  from_entry_id: 101, // Blog post
  to_entry_id: 98, // Research notes
  relationship_type: "references",
});

Arrow in visualization: -->

`implements`

Implementation of a specification, plan, or design.

CRITICAL for AI context: This relationship type connects architectural decisions to their implementations, enabling AI to understand both the "why" and the "how".

Use when:

Code implements a design decision
Feature implements a specification
Solution implements an architectural plan

Example:

// Implementation links to specification
link_entries({
  from_entry_id: 42, // Implementation
  to_entry_id: 40, // Specification
  relationship_type: "implements",
});

Arrow in visualization: ==>

`clarifies`

Explanation or elaboration of another entry.

Use when:

Documentation explains code
Follow-up adds details
Explanation of complex topic

Example:

// Documentation clarifies implementation
link_entries({
  from_entry_id: 43, // Documentation
  to_entry_id: 42, // Implementation
  relationship_type: "clarifies",
});

Arrow in visualization: -.-> (dotted)

`evolves_from`

Iteration or improvement of previous work.

Use when:

V2 evolved from V1
Improved implementation
Refined approach

Example:

// New version evolved from previous
link_entries({
  from_entry_id: 55, // Version 2
  to_entry_id: 42, // Version 1
  relationship_type: "evolves_from",
});

Arrow in visualization: -->>

`response_to`

Reply or follow-up to another entry.

Use when:

Answer to a question
Follow-up to discussion
Response to feedback

Example:

// Answer to question
link_entries({
  from_entry_id: 67, // Answer
  to_entry_id: 66, // Question
  relationship_type: "response_to",
});

Arrow in visualization: <-->

`blocked_by`

Entry was blocked by another (causal).

Use when:

Development was blocked by a dependency
Issue prevented progress
Documenting blockers and their resolutions

Example:

// Fix was blocked by infrastructure issue
link_entries({
  from_entry_id: 75, // Fix entry
  to_entry_id: 70, // Blocker entry
  relationship_type: "blocked_by",
  description: "Database migration blocked deployment",
});

Arrow in visualization: --x

`resolved`

Entry resolved or fixed an issue (causal).

Use when:

Fix resolved a bug
Solution resolved a blocker
Implementation resolved an issue

Example:

// Fix resolved the blocker
link_entries({
  from_entry_id: 80, // Resolution entry
  to_entry_id: 75, // Bug/issue entry
  relationship_type: "resolved",
  description: "Connection pool fix resolved the timeout bug",
});

Arrow in visualization: ==>

`caused`

Entry caused or led to another outcome (causal).

Use when:

Root cause led to an issue
Change caused a side effect
Documenting cause-and-effect chains

Example:

// Memory leak caused the crash
link_entries({
  from_entry_id: 85, // Root cause
  to_entry_id: 90, // Consequence
  relationship_type: "caused",
  description: "Memory leak in cache layer caused OOM crash",
});

Arrow in visualization: -.->

Viewing Relationships

In Entry Details

Use get_entry_by_id with include_relationships: true:

get_entry_by_id({
  entry_id: 42,
  include_relationships: true,
});

Output:

**Entry #42** (technical_achievement)
...

**Relationships:**
  → implements: Entry #40 (Specification...)
  ← clarifies: Entry #43 (Documentation...)
  ← evolves_from: Entry #55 (Version 2...)

Symbols:

→ - Outgoing (from this entry to another)
← - Incoming (from another to this entry)

Visual Graphs

Generate Mermaid diagrams showing relationships:

visualize_relationships({
  entry_id: 42,
  depth: 2,
});

See Visualization page for complete guide.

Relationship Patterns

Pattern 1: Spec → Implementation → Documentation

The standard development flow:

// 1. Create specification
create_entry({
  content: "Spec: Lazy loading system...",
  entry_type: "planning",
  tags: ["spec", "planning"],
});
// Entry #100

// 2. Implement the spec
create_entry({
  content: "Implemented lazy loading...",
  entry_type: "technical_achievement",
  tags: ["implementation"],
});
// Entry #101

link_entries({
  from_entry_id: 101,
  to_entry_id: 100,
  relationship_type: "implements",
});

// 3. Document the implementation
create_entry({
  content: "Documented lazy loading pattern...",
  entry_type: "other",
  tags: ["documentation"],
});
// Entry #102

link_entries({
  from_entry_id: 102,
  to_entry_id: 101,
  relationship_type: "clarifies",
});

Visualization:

graph TD
    E100["#100: Spec"] --> E101["#101: Implementation"]
    E101 --> E102["#102: Documentation"]

    E101 ==>|implements| E100
    E102 -.->|clarifies| E101

Pattern 2: Research → Prototype → Production

Iterative development:

// 1. Research
create_entry({ content: "Researched lazy loading..." });
// Entry #110

// 2. Prototype
create_entry({ content: "Prototyped lazy import system..." });
// Entry #111

link_entries({
  from_entry_id: 111,
  to_entry_id: 110,
  relationship_type: "evolves_from",
});

// 3. Production
create_entry({ content: "Production-ready lazy loading..." });
// Entry #112

link_entries({
  from_entry_id: 112,
  to_entry_id: 111,
  relationship_type: "evolves_from",
});

Shows evolution: Research → Prototype → Production

Pattern 3: Bug → Investigation → Fix

Debugging workflow:

// 1. Bug report
create_entry({ content: "Bug: Database locking..." });
// Entry #120

// 2. Investigation
create_entry({ content: "Investigation: Found nested connections..." });
// Entry #121

link_entries({
  from_entry_id: 121,
  to_entry_id: 120,
  relationship_type: "clarifies",
});

// 3. Fix
create_entry({ content: "Fix: Single connection transactions..." });
// Entry #122

link_entries({
  from_entry_id: 122,
  to_entry_id: 120,
  relationship_type: "implements",
});

Tracks bug resolution: Report → Investigation → Fix

Pattern 4: Question → Answer

Knowledge base building:

// 1. Question
create_entry({ content: "How do module imports affect startup time?" });
// Entry #130

// 2. Research
create_entry({ content: "Research findings: Imports execute code..." });
// Entry #131

link_entries({
  from_entry_id: 131,
  to_entry_id: 130,
  relationship_type: "response_to",
});

// 3. Solution
create_entry({ content: "Solution: Use lazy imports..." });
// Entry #132

link_entries({
  from_entry_id: 132,
  to_entry_id: 130,
  relationship_type: "response_to",
});

Advanced Relationship Usage

Multi-Level Relationships

Build complex knowledge graphs with multiple levels:

// Sprint goal → Feature spec → Implementation → Tests → Docs
// Each linked with appropriate relationship types

Visualize with depth:

visualize_relationships({
  entry_id: 150, // Sprint goal
  depth: 3, // See full chain
});

Tag-Based Relationship Discovery

Find all relationships for a specific project:

visualize_relationships({
  tags: ["project-x"],
  limit: 50,
});

Temporal Relationships

Track how work evolved over time:

// Link chronological entries showing evolution
// V1 → V2 → V3 using evolves_from

Query pattern:

search_by_date_range({
  start_date: "2025-10-01",
  end_date: "2025-10-31",
  tags: ["feature-x"],
});

// Then visualize to see evolution
visualize_relationships({
  tags: ["feature-x"],
});

Finding Related Entries

The `find-related` Prompt

Discover entries related to a specific entry:

/find-related query:"database concurrency"

Output:

Directly linked entries (via relationships)
Semantically similar entries (via content)
Entries with shared tags

See Prompts Guide for details.

Semantic Similarity

Use semantic_search to find conceptually related entries:

semantic_search({
  query: "performance optimization techniques",
  limit: 5,
});

Then link related entries manually:

link_entries({
  from_entry_id: found_entry_id,
  to_entry_id: original_entry_id,
  relationship_type: "references",
});

Relationship Best Practices

When to Create Relationships

DO link entries when:

✅ One implements another
✅ One clarifies/explains another
✅ One evolved from another
✅ Entries are part of same project/feature
✅ Clear dependency exists

DON'T over-link:

❌ Every entry to every other entry
❌ Unrelated entries just because they share tags
❌ Relationships that don't add meaning

Choosing Relationship Types

Use specific types:

✅ implements for spec → code
✅ clarifies for docs → feature
✅ evolves_from for iterations

Not generic types:

❌ Everything as references
❌ Wrong relationship type

Link as You Go

Create relationships immediately:

// Right after creating an entry
create_entry({ ... })  // Returns #155
link_entries({
  from_entry_id: 155,
  to_entry_id: 154,
  relationship_type: "implements"
})

Document Complex Relationships

Use the description parameter:

link_entries({
  from_entry_id: 42,
  to_entry_id: 40,
  relationship_type: "implements",
  description:
    "Implements the lazy loading specification with additional error handling and graceful degradation",
});

Database Schema

Relationships are stored in the relationships table:

CREATE TABLE relationships (
    id INTEGER PRIMARY KEY,
    from_entry_id INTEGER NOT NULL,
    to_entry_id INTEGER NOT NULL,
    relationship_type TEXT NOT NULL,
    description TEXT,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (from_entry_id) REFERENCES memory_journal(id) ON DELETE CASCADE,
    FOREIGN KEY (to_entry_id) REFERENCES memory_journal(id) ON DELETE CASCADE
);

Indexes:

idx_relationships_from on from_entry_id
idx_relationships_to on to_entry_id

Cascading deletes:

Deleting an entry automatically deletes its relationships

Relationship Limits

No hard limits:

Create as many relationships as needed
Entry can have unlimited incoming/outgoing relationships
Visualization tools handle large graphs (though rendering may be slow)

Practical limits:

Visualization optimal: 20-30 entries
Can visualize up to 50+ entries
Beyond 50: Split into focused graphs

Troubleshooting

Can't Create Relationship

Check:

Both entries exist: get_entry_by_id
Entry IDs are correct
Entries aren't deleted
Not linking entry to itself

Relationship Not Showing

Check:

Use include_relationships: true in get_entry_by_id
Entries aren't soft-deleted
Relationship was created successfully

Too Many Relationships in Graph

Solution:

Reduce depth parameter
Use tag filtering
Focus on specific entry
Create multiple focused graphs

Examples

See Examples page for complete workflows using relationships.

Key examples:

Feature Development Lifecycle
Bug Investigation
Knowledge Base Building
Sprint Work Visualization

Next: Learn about Visualization or explore Examples.

Relationships

Entry Relationships - Building Knowledge Graphs for AI Context

Overview

Creating Relationships

The link_entries Tool

Relationship Types

references

implements

clarifies

evolves_from

response_to

blocked_by

resolved

caused

Viewing Relationships

In Entry Details

Visual Graphs

Relationship Patterns

Pattern 1: Spec → Implementation → Documentation

Pattern 2: Research → Prototype → Production

Pattern 3: Bug → Investigation → Fix

Pattern 4: Question → Answer

Advanced Relationship Usage

Multi-Level Relationships

Tag-Based Relationship Discovery

Temporal Relationships

Finding Related Entries

The find-related Prompt

Semantic Similarity

Relationship Best Practices

When to Create Relationships

Choosing Relationship Types

Link as You Go

Document Complex Relationships

Database Schema

Relationship Limits

Troubleshooting

Can't Create Relationship

Relationship Not Showing

Too Many Relationships in Graph

Examples

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

🏠 Home

Getting Started

Core Features

Knowledge Graph

GitHub Integration

Workflows

Deployment

Architecture

Clone this wiki locally

The `link_entries` Tool

`references`

`implements`

`clarifies`

`evolves_from`

`response_to`

`blocked_by`

`resolved`

`caused`

The `find-related` Prompt