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:

# Record an error and how you fixed it
roboco_record_error(
    error_type="ConnectionError",
    message="Redis connection timed out",
    solution="Increased timeout to 30s and added retry logic",
    worked=True
)

# Search for similar errors
roboco_search_error(
    pattern="ConnectionError",
    context="redis timeout"
)

---

Decision Tracking

Record architectural decisions:

# Record a decision
roboco_record_decision(
    topic="Database for session storage",
    decision="Use Redis instead of PostgreSQL",
    rationale="Need sub-millisecond reads, sessions are ephemeral",
    alternatives=["PostgreSQL", "In-memory"],
    task_id="uuid-here"
)

# Check if similar decisions exist
roboco_decision_check(
    topic="session storage",
    proposed_approach="Use in-memory cache"
)
# Returns: relevant past decisions to consider

---

Standards Validation

Check code against team standards:

# Get applicable standards for a file
roboco_standards_get(
    file_path="src/api/routes/users.py",
    domain="api"
)

# Validate an action against standards
roboco_validate_action(
    action="Adding a new API endpoint",
    context="User management feature"
)

---

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 can automatically provide relevant context when you claim a task:

# Automatic context injection on task claim
# System searches KB for:
# - Similar past tasks
# - Related decisions
# - Relevant standards
# - Past error solutions

This helps you start informed without manual searching.

---

Code Review Support

Request AI-assisted code review:

roboco_code_review(
    file_path="src/api/routes/users.py",
    focus=["security", "performance"]
)
# Returns: review comments, standards checked, similar past reviews

---

Tool Quick Reference

Tool	Purpose	Who Can Use
roboco_kb_search	Semantic search	Everyone
roboco_rag_query	AI-generated answers	Everyone
roboco_kb_stats	What's indexed	Everyone
roboco_kb_index_code	Index code files	PM, Developer
roboco_kb_index_docs	Index documentation	PM, Documenter
roboco_tokens_estimate	Token count	Everyone
roboco_journal_search	Search your journal	Everyone
roboco_journal_read_team	Read team journals	PM, Documenter
roboco_record_error	Record error & fix	Everyone
roboco_search_error	Find past errors	Everyone
roboco_record_decision	Record decision	Everyone
roboco_decision_check	Check past decisions	Everyone
roboco_standards_get	Get applicable standards	Everyone
roboco_validate_action	Validate against standards	Everyone
roboco_record_learning	Record a learning	Everyone
roboco_code_review	AI-assisted review	Developer, QA