roboco/docs/workflows/KNOWLEDGE_BASE.md

Knowledge Base Guide

Overview

The knowledge base is built from 9 specialized indexes:

Index Type	Content	Use Case
code	Source files	Find implementations, patterns
docs	Documentation, READMEs	Find guides, specs
conversations	Channel discussions	Find past discussions
journals	Agent journal entries	Find decisions, learnings
errors	Error patterns & fixes	Find solutions to past errors
standards	Coding standards, rules	Validate against standards
decisions	Architectural decisions	Find past design choices
reviews	Code review patterns	Find review templates
learnings	Captured learnings	Find team knowledge

All content is embedded (vectorized) for semantic search.

Document Tracking: The system tracks actual documents indexed (not just vector chunks), including source path, title, preview, and chunk count.

---

Knowledge Base Tools

Semantic Search

roboco_kb_search(
    query="rate limiting redis implementation",
    top_k=5,                    # Results to return (1-20)
    project="roboco",           # Optional project filter
    task_id="uuid-here",        # Optional task filter
    index_types=["code", "docs"]  # Filter by type
)

Returns semantically similar content from indexed code, docs, and learnings.

RAG Queries (AI-Generated Answers)

roboco_rag_query(
    query="How does authentication work in this codebase?",
    top_k=5,                    # Context chunks to use
    project="roboco"            # Optional project filter
)

Returns an AI-synthesized answer with citations to sources.

Good for questions like:

• "How does authentication work?"
• "What pattern should I use for error handling?"
• "What decisions were made about the database schema?"

Check What's Indexed

roboco_kb_stats()
# Returns: indexed content counts by type

Estimate Token Count

roboco_tokens_estimate(content="...", model="claude-sonnet-4")
# Returns: token count for context planning

---

Indexing Content (PM/Developer/Documenter)

Index Code (PM, Developer)

roboco_kb_index_code(
    sources=["src/**/*.py", "lib/**/*.ts"],
    project="roboco"
)

Index Documentation (PM, Documenter)

roboco_kb_index_docs(
    sources=["docs/**/*.md", "README.md"],
    project="roboco"
)

---

Error Tracking

Record and search error patterns:

# Search for similar errors FIRST
roboco_search_error(
    error_message="Redis connection timed out",
    context="trying to connect during startup"
)

# Record an error and how you fixed it
roboco_record_error_solution(
    error_message="Redis connection timed out",
    context="Service startup - Redis wasn't ready yet",
    solution="Added retry logic with exponential backoff",
    worked=True,
    tags=["redis", "startup", "timeout"]
)

---

Decision Tracking

Record architectural decisions:

# Check if similar decisions exist FIRST
roboco_check_decision(topic="session storage")
# Returns: has_precedent, decisions, recommendation

# Record a decision
roboco_record_decision(params={
    "topic": "Database for session storage",
    "decision": "Use Redis instead of PostgreSQL",
    "rationale": "Need sub-millisecond reads, sessions are ephemeral",
    "alternatives": [
        {"name": "PostgreSQL", "pros": "ACID", "cons": "Too slow"},
        {"name": "In-memory", "pros": "Fast", "cons": "No persistence"}
    ],
    "scope": "team",  # or "org"
    "tags": ["database", "session", "architecture"]
})

---

Standards Validation

Check code against team standards:

# Get applicable standards for a domain
roboco_get_standards(
    domain="coding",    # or "security", "workflow"
    language="python"   # optional filter
)

# Validate an action against standards
roboco_validate_action(
    action_type="create_endpoint",
    context="Adding user management API endpoint"
)
# Returns: allowed, violations, warnings, relevant_standards

# Get code reviewed before committing
roboco_review_code(
    code="def handle_auth(token): ...",
    file_path="src/api/auth.py",
    change_type="modify"  # or "add", "delete"
)
# Returns: approved, score (0-100), comments, standards_checked

---

Learning Capture

Record and share learnings:

# Record a learning
roboco_record_learning(
    content="Redis SCAN is better than KEYS for large datasets",
    category="performance",
    shareable=True,
    tags=["redis", "performance", "patterns"]
)

# Search learnings
roboco_kb_search(
    query="redis performance patterns",
    index_types=["learnings"]
)

---

Searching the Knowledge Base

Search Your Journal

roboco_journal_search(
    query="rate limiting redis implementation",
    top_k=5                     # Number of results
)

Returns semantically similar entries - not just keyword matches.

Search Examples

Query	Finds
"how to handle auth tokens"	Past decisions about auth
"redis connection issues"	Struggles with Redis
"API versioning approach"	Decisions about API design
"what did I learn about caching"	Learning entries about caching

---

Reading Past Work

Your Recent Entries

roboco_journal_recent(limit=10)
roboco_journal_recent(entry_type="decision_log")
roboco_journal_recent(task_id="uuid-here")

Your Stats

roboco_journal_stats()
# Returns: entries by type, growth metrics, top tags

Team Journals (if you have access)

roboco_journal_read_team(
    target_agent="be-dev-1",
    task_id="uuid-here",        # Filter by task
    entry_type="decision_log",  # Filter by type
    limit=10
)

Check Your Access Scope

roboco_journal_scope()
# Returns: your role, cell, who you can read

---

Before Starting a Task

Always search first:

# 1. Search for similar past work
roboco_journal_search("implementing rate limiter")

# 2. Check if someone documented this before
roboco_journal_search("rate limit decisions")

# 3. Look for learnings
roboco_journal_search("rate limiting lessons learned")

This helps you:

• Avoid repeating mistakes
• Find proven patterns
• Learn from others' experiences
• Understand past decisions

---

Contributing to Knowledge Base

Everything you journal becomes searchable:

Entry Type	Searchable Content
Decision Log	Context, options, rationale
Learning	What learned, how applied
Struggle	Problem, solutions, resolution
Reflection	What done, what learned, struggles
General	Title, content, tags

Pro tip: Use descriptive titles and tags - they improve search relevance.

---

Knowledge Flow

┌─────────────────────────────────────────────────────────────────────────┐
│                         KNOWLEDGE FLOW                                  │
└─────────────────────────────────────────────────────────────────────────┘

  You Work                    You Journal                   Knowledge Base
      │                           │                              │
      │  Make decision            │                              │
      └──────────────────────────►│ roboco_journal_decision      │
                                  └─────────────────────────────►│
      │  Learn something          │                              │ Embedded
      └──────────────────────────►│ roboco_journal_learning      │    ▼
                                  └─────────────────────────────►│ Searchable
      │  Hit a struggle           │                              │
      └──────────────────────────►│ roboco_journal_struggle      │
                                  └─────────────────────────────►│
      │  Complete task            │                              │
      └──────────────────────────►│ roboco_journal_reflect       │
                                  └─────────────────────────────►│
                                                                 │
  Future You ◄───────────────── roboco_journal_search ◄──────────┘
  Future Agent ◄─────────────── roboco_journal_read_team ◄───────┘

---

Best Practices

1. Search before you start - Learn from past work
2. Journal as you go - Don't wait until end
3. Be specific - Generic entries are less searchable
4. Use tags - Helps categorization
5. Record failures - They're valuable learning
6. Include context - Future searchers need it

---

Proactive Context

The system automatically provides relevant context when you claim a task:

# Get context that was injected when task was claimed
roboco_get_proactive_context(
    task_id="uuid-here",
    force_refresh=False  # True to regenerate fresh context
)

# Returns:
# - similar_tasks: Past tasks like this one
# - relevant_learnings: What others learned doing similar work
# - code_patterns: Relevant code examples
# - applicable_standards: Standards that apply
# - recent_decisions: Related architectural decisions
# - known_issues: Issues you should be aware of
# - summary: Human-readable overview

This helps you start informed without manual searching.

---

Mentor (Conversational RAG)

Ask the organizational knowledge base for help with follow-up context:

# First question
response = roboco_ask_mentor(
    question="How do I handle authentication in this codebase?",
    domain="coding"  # optional: coding, security, workflow
)

# Follow-up question (maintains conversation context)
roboco_ask_mentor(
    question="What about refresh tokens?",
    conversation_id=response["conversation_id"]
)

# Returns: answer, sources, suggested_followups

The mentor searches across standards, decisions, learnings, and code patterns.

---

Index Management

Check Index Health

roboco_index_status()
# Returns: initialized, indexes with document_count, chunk_count, last_updated

Trigger Reindexing (PM/Developer)

roboco_reindex_all(force=False)
# force=True reindexes even if indexes aren't empty
# Returns: code_files_indexed, docs_files_indexed

Clear an Index (PM only)

roboco_clear_index(index_type="code")
# Valid types: code, documentation, conversations, journals,
#              errors, standards, decisions, reviews, learnings

---

Lifecycle Tracking

Task lifecycle events are automatically indexed for pattern analysis:

Event	What's Tracked
block	Which task blocked, blocker title
unblock	When unblocked
pause	When paused
resume	When resumed
cancel	Who cancelled, how many descendants cancelled

This enables queries like:

• "Which tasks get cancelled most often?"
• "What causes the most blocks?"
• "Which teams have the longest pause durations?"

---

Tool Quick Reference

Core Search & Query

Tool	Purpose	Who Can Use
roboco_kb_search	Semantic search across all indexes	Everyone
roboco_rag_query	AI-generated answers with citations	Everyone
roboco_kb_stats	What's indexed (counts by type)	Everyone
roboco_tokens_estimate	Estimate token count for content	Everyone

Indexing & Management

Tool	Purpose	Who Can Use
roboco_kb_index_code	Index code files	PM, Developer
roboco_kb_index_docs	Index documentation	PM, Documenter
roboco_clear_index	Clear a specific index	PM
roboco_reindex_all	Trigger full code+docs reindex	PM, Developer
roboco_index_status	Detailed index health & counts	Everyone

Mentor (Conversational RAG)

Tool	Purpose	Who Can Use
roboco_ask_mentor	Conversational help with follow-ups	Everyone

Error Tracking

Tool	Purpose	Who Can Use
roboco_search_error	Find past error solutions	Everyone
roboco_record_error_solution	Record how you fixed an error	Everyone

Decision Tracking

Tool	Purpose	Who Can Use
roboco_check_decision	Check for similar past decisions	Everyone
roboco_record_decision	Record an architectural decision	Everyone

Standards & Validation

Tool	Purpose	Who Can Use
roboco_get_standards	Get applicable standards	Everyone
roboco_validate_action	Validate action against standards	Everyone
roboco_review_code	AI-assisted code review	Developer, QA

Learning & Knowledge Sharing

Tool	Purpose	Who Can Use
roboco_record_learning	Record a learning for future agents	Everyone
roboco_search_learnings	Search learnings from teammates	Everyone

Proactive Context

Tool	Purpose	Who Can Use
roboco_get_proactive_context	Get context injected at task claim	Everyone

Journal Tools

Tool	Purpose	Who Can Use
roboco_journal_search	Search your journal	Everyone
roboco_journal_read_team	Read team journals	PM, Documenter