📚 KB / Beads Analysis for Nexus Recall
root

Beads Analysis for Nexus Recall

Beads Analysis for Nexus Recall

Executive Summary

Beads is a distributed, git-backed graph issue tracker designed for AI agents. This analysis identifies key architectural patterns and data structures from Beads that should inform the design of Nexus Recall, our AI memory system.

Key Takeaway: Beads demonstrates a robust three-layer architecture (Git → JSONL → SQLite) with rich relationship modeling and metadata management that Nexus Recall can adapt for AI memory storage.

Beads Architecture Overview

Three-Layer Design

Beads uses a layered architecture where each layer serves a specific purpose:

Layer 1: Git Repository (.beads/*.jsonl)
  ↓ Historical Source of Truth
Layer 2: JSONL Files  
  ↓ Human-readable append-only log
Layer 3: SQLite Database
  ↓ Fast queries and relationships

Benefits for Recall: - Git layer provides version history and distributed sync - JSONL layer offers human-readable audit trail - SQLite layer enables fast retrieval and complex queries

Recall Adaptation: - Replace Git with Redis/FalkorDB for real-time persistence - Keep JSONL-style logging for audit/recovery - Use graph database (FalkorDB) instead of SQLite for relationship queries

Data Model: The Issue Structure

Core Issue Fields

Beads Issue type contains:

type Issue struct {
    // Core Identification
    ID          string  // Unique identifier
    ContentHash string  // SHA256 of canonical content

    // Issue Content
    Title              string
    Description        string
    Design             string
    AcceptanceCriteria string
    Notes              string

    // Metadata
    Status      string    // open, in-progress, completed, etc.
    Priority    int
    Tags        []string
    CreatedAt   time.Time
    UpdatedAt   time.Time
    CreatedBy   string
    AssignedTo  string

    // Relationships (populated via joins)
    Parent       *string
    Dependencies []*Dependency
    Dependents   []*Dependency
    Comments     []*Comment
}

Recall Adaptation: Nexus Recall should adopt a similar structure for memory "beads":

class MemoryBead:
    # Core
    bead_id: str          # Unique ID (b_XXXX)
    content_hash: str     # SHA256 for deduplication

    # Content
    title: str
    content: str          # Main memory content
    context: str          # Surrounding context
    summary: str          # AI-generated summary

    # Metadata
    bead_type: str        # decision, fact, task, conversation, etc.
    importance: int       # 1-10 priority score
    tags: List[str]
    created_at: datetime
    accessed_at: datetime # Last retrieval time
    created_by: str       # AI or user ID
    session_id: str       # Link to session

    # Relationships (graph edges)
    parent_id: str        # Hierarchical parent
    related_to: List[str] # Related beads
    depends_on: List[str] # Prerequisite beads
    supersedes: str       # Replaces older bead

Relationship Modeling

Beads Dependency Types

Beads defines rich relationship types between issues:

const (
    // Workflow types (affect ready work calculation)
    DepBlocks            = "blocks"              // B can't start until A completes
    DepParentChild       = "parent-child"        // Hierarchical relationship
    DepConditionalBlocks = "conditional-blocks"  // B runs only if A fails
    DepWaitsFor          = "waits-for"           // Fanout gate: wait for dynamic children

    // Association types (informational)
    DepRelated           = "related"             // Semantic similarity
    DepDuplicates        = "duplicates"          // Duplicate issues
    DepRequires          = "requires"            // Resource dependency
    DepSkillAssociation  = "skill"               // Skill requirements
)

Dependency Metadata

type Dependency struct {
    IssueID     string         // Source issue
    DependsOnID string         // Target issue
    Type        DependencyType // Relationship type
    CreatedAt   time.Time
    CreatedBy   string
    Metadata    json.RawMessage // Type-specific edge data (similarity scores, etc.)
}

Recall Adaptation:

Nexus Recall should implement similar edge types:

class BeadRelationship:
    from_bead: str
    to_bead: str
    rel_type: str  # follows_from, related_to, contradicts, updates, depends_on
    strength: float  # 0.0-1.0 relationship strength
    created_at: datetime
    metadata: dict  # Type-specific data (similarity scores, reasoning)

Relationship Types for Recall: - follows_from: Temporal/causal succession - related_to: Semantic similarity - contradicts: Conflicting information - updates: Newer version of older memory - depends_on: Prerequisite knowledge - part_of: Hierarchical membership - mentioned_in: Cross-references

Storage Interface

Beads defines a clean storage abstraction:

type Storage interface {
    // CRUD operations
    CreateIssue(ctx context.Context, issue *types.Issue) error
    GetIssue(ctx context.Context, id string) (*types.Issue, error)
    UpdateIssue(ctx context.Context, issue *types.Issue) error
    DeleteIssue(ctx context.Context, id string) error

    // Query operations
    ListIssues(ctx context.Context, filters ...Filter) ([]*types.Issue, error)
    SearchIssues(ctx context.Context, query string) ([]*types.Issue, error)

    // Relationship operations
    AddDependency(ctx context.Context, dep *types.Dependency) error
    GetDependencies(ctx context.Context, issueID string) ([]*types.Dependency, error)

    // Transaction support
    BeginTx(ctx context.Context) (Transaction, error)
}

Recall Adaptation:

Nexus Recall should adopt this interface pattern:

class RecallStorage:
    # CRUD
    async def create_bead(bead: MemoryBead) -> str
    async def get_bead(bead_id: str) -> MemoryBead
    async def update_bead(bead_id: str, updates: dict) -> None
    async def delete_bead(bead_id: str) -> None

    # Query
    async def search_beads(query: str, limit: int = 20) -> List[MemoryBead]
    async def find_similar(bead_id: str, threshold: float = 0.7) -> List[MemoryBead]
    async def get_by_session(session_id: str) -> List[MemoryBead]
    async def get_by_tag(tag: str) -> List[MemoryBead]

    # Relationships
    async def add_relationship(from_id: str, to_id: str, rel_type: str, metadata: dict) -> None
    async def get_relationships(bead_id: str, rel_type: str = None) -> List[BeadRelationship]
    async def traverse_graph(start_id: str, max_depth: int = 3) -> List[MemoryBead]

Key Features to Adopt

1. Content Hashing for Deduplication

Beads uses SHA256 content hashing to detect duplicate issues:

ContentHash string `json:"-"` // SHA256 of canonical content

Recall Usage: - Hash memory content to detect duplicates - Avoid storing redundant memories - Link duplicate memories instead of creating new ones

2. Hierarchical Parent-Child Relationships

Beads supports nested issue hierarchies:

Parent *string `json:"parent,omitempty"`

Recall Usage: - Organize memories into topic hierarchies - Enable "drill-down" from high-level to detailed memories - Support context inheritance (child beads inherit parent tags/metadata)

3. Rich Metadata

Beads tracks comprehensive metadata: - Timestamps (created, updated) - Attribution (created_by, assigned_to) - Status tracking - Priority/importance scores - Tags for categorization

Recall Usage: - Track when memories were created and last accessed - Record which AI/user created the memory - Importance scoring for retrieval ranking - Tag-based organization and filtering

4. Transaction Support

Beads provides atomic multi-operation transactions:

BeginTx(ctx context.Context) (Transaction, error)

Recall Usage: - Atomic memory creation with relationships - Ensure consistency when updating related beads - Rollback on failure

5. Typed Relationships with Metadata

Beads allows relationship-specific metadata:

Metadata json.RawMessage // Type-specific edge data

Recall Usage: - Store similarity scores on related_to edges - Track confidence levels on updates edges - Record reasoning on contradicts edges

Retrieval Patterns

Beads demonstrates several retrieval patterns:

  1. Direct lookup - Get issue by ID
  2. Filtered queries - List issues matching criteria (status, tags, assignee)
  3. Full-text search - Search across title/description
  4. Relationship traversal - Get dependencies, dependents, parents, children
  5. Graph queries - Find all blocked issues, calculate ready work

Recall Adaptation:

  1. Direct recall - Retrieve specific bead by ID
  2. Filtered recall - Find beads by session, tag, type, date range
  3. Semantic search - Vector similarity search for relevant memories
  4. Graph traversal - Follow relationships to find connected memories
  5. Temporal queries - Recent memories, memories from specific time period
  6. Importance ranking - Retrieve high-priority memories first

Recommendations for Nexus Recall

Architecture

✅ Adopt three-layer pattern: - Layer 1: FalkorDB (graph database for relationships) - Layer 2: Redis (fast key-value cache) - Layer 3: PostgreSQL or disk (durable append-log)

Data Model

✅ Define MemoryBead structure with: - Unique IDs (b_XXXX format) - Content hashing for deduplication - Rich metadata (importance, tags, timestamps) - Hierarchical parent-child support

✅ Define BeadRelationship with: - Typed edges (follows_from, related_to, updates, contradicts) - Relationship strength/confidence scores - Edge metadata for reasoning

Storage Interface

✅ Implement RecallStorage interface with: - CRUD operations (create, get, update, delete) - Query operations (search, filter, find_similar) - Relationship operations (add, get, traverse) - Transaction support for atomicity

Retrieval

✅ Support multiple retrieval modes: - Direct lookup by ID - Semantic similarity search (vector embeddings) - Graph traversal (follow relationships) - Temporal queries (recent, date range) - Filtered queries (session, tags, type) - Importance-ranked results

Integration

✅ Integrate with existing Nexus systems: - Session MCP: Link beads to session IDs - Context MCP: Use recall/learn pattern for bead storage - AI Groups: Share memories across group members

Next Steps

  1. Design MemoryBead schema - Define Python dataclasses
  2. Choose storage backend - Evaluate FalkorDB vs Neo4j vs PostgreSQL+pgvector
  3. Implement RecallStorage - Build storage interface
  4. Create MCP server - Expose recall tools via MCP
  5. Build retrieval algorithms - Semantic search + graph traversal
  6. Test with AI workflows - Validate with real agent memory needs

References

  • Beads Repository: /opt/repos/beads
  • Beads Architecture: /opt/repos/beads/website/docs/architecture/index.md
  • Beads Types: /opt/repos/beads/internal/types/types.go
  • Beads Storage: /opt/repos/beads/internal/storage/storage.go
ID: fdfede6e Path: Beads Analysis for Nexus Recall Updated: 2026-01-13T12:51:40
🌳 View Tree