Skip to content

Relationships

Jump to bottom
Temp edited this page Oct 9, 2025 · 11 revisions

Entry Relationships

Build a knowledge graph by linking journal entries with typed relationships.

New in v1.1.3! 🔗

Overview

Entry relationships let you connect related journal entries to build a knowledge graph of your work. Track how ideas evolve, link implementations to specs, and document dependencies between entries.

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.

Use when:

  • Code implements a spec
  • Feature implements a design
  • Solution implements a 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: <-->

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: "development_note",
  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: "enhancement",
  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
Loading

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 Python 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 entry_id:42

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),
    FOREIGN KEY (to_entry_id) REFERENCES memory_journal(id)
);

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.

🏠 Home

Getting Started

Core Features

Knowledge Graph

GitHub Integration

Workflows

Deployment

Architecture

Clone this wiki locally