Skip to content

Advanced

Best Practices

When to Use Relationships

✅ Do use relationships for: - Project main memory → Decisions, modules, tasks - Decisions → Implementation details, configurations - Problems → Solutions → Related issues - Tasks → Subtasks → Implementation notes - Functions → Dependencies → Related functions - Modules → Components → Implementation details

❌ Don't use relationships for: - Unrelated memories (creates noise) - Temporary or test memories - Memories that are already well-connected - Circular dependencies (A → B → A)

Organizing Hierarchies

Recommended Structure:

Project Main (Level 0)
├── Decisions (Level 1)
│   ├── Configurations (Level 2)
│   │   └── Details (Level 3)
│   └── Implementations (Level 2)
├── Modules (Level 1)
│   ├── Components (Level 2)
│   │   └── Implementation Notes (Level 3)
│   └── APIs (Level 2)
└── Tasks (Level 1)
    ├── Subtasks (Level 2)
    │   └── Notes (Level 3)
    └── Dependencies (Level 2)

Performance Considerations

  • Depth Limit: Keep hierarchies to 3 levels for optimal performance
  • Related Count: Limit to 5-10 related memories per memory
  • Search Performance: search_memory loads 1 level deep (faster)
  • Retrieve Performance: retrieve_memory loads 3 levels deep (more complete)

Maintaining Relationships

  • Update when needed: If a memory becomes related to another, update related_memory_ids
  • Remove outdated links: Clean up relationships that are no longer relevant
  • Use bidirectional awareness: The system maintains bidirectional links automatically
  • Verify relationships: Use retrieve_memory to verify relationship structure

Troubleshooting

Memories Not Loading

Issue: Related memories not appearing in results

Solutions: 1. Verify related_memory_ids are correct memory IDs 2. Check that related memories exist and are accessible 3. Ensure memories belong to the same owner 4. Verify collection names if using collection-specific search

Circular Dependencies

Issue: Memory A links to B, B links to A (circular)

Solution: The system handles circular dependencies by tracking visited IDs. No infinite loops occur, but be aware of the relationship structure.

Performance Issues

Issue: Slow retrieval with many related memories

Solutions: 1. Reduce depth (use search_memory instead of retrieve_memory for 1 level) 2. Limit number of related memories per memory 3. Use include_files: false in search if files not needed 4. Consider splitting large hierarchies into multiple collections