roboco/docs/rag/architecture/optimal-brain.md

Optimal Brain Architecture

The Optimal Brain is RoboCo's organizational intelligence layer - a knowledge system that enables agents to learn from each other, enforce standards, and make consistent decisions.

Overview

+-----------------------------------------------------------------------+
|                           OPTIMAL BRAIN                                |
|                                                                        |
|  +-------------+  +-------------+  +-------------+  +-------------+   |
|  |   Mentor    |  |   Error     |  |  Decision   |  |  Standards  |   |
|  |   System    |  |  Patterns   |  |   Memory    |  |  Enforcer   |   |
|  +-------------+  +-------------+  +-------------+  +-------------+   |
|  +-------------+  +-------------+  +-------------+                    |
|  |  Learning   |  |  Proactive  |  |    Code     |                    |
|  |   Network   |  |   Context   |  |   Review    |                    |
|  +-------------+  +-------------+  +-------------+                    |
|         |               |               |               |              |
|         +---------------+---------------+---------------+              |
|                                 |                                      |
|                    +------------------------+                          |
|                    |   Piragi + pgvector    |                          |
|                    |   (PostgreSQL)         |                          |
|                    +------------------------+                          |
+-----------------------------------------------------------------------+

Index Types

Index	Content	Auto-Updated
code	Source files	On commit
docs	Documentation	On write
decisions	Architectural choices	Manual
errors	Error patterns + solutions	Manual
standards	Coding/security/workflow rules	On boot
learnings	Agent insights	Manual
reviews	Code review patterns	On review
conversations	Channel discussions	On message
journals	Agent reflections	On entry

Components

1. Mentor System

Conversational RAG for agent questions. Maintains context across follow-ups.

Tool: roboco_ask_mentor

# First question
response = roboco_ask_mentor(question="How do I handle auth?")

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

Searches: standards, decisions, learnings, code, errors

2. Error Pattern Database

Collective error memory. When one agent solves an error, all agents benefit.

Tools: roboco_search_error, roboco_record_error_solution

# Before debugging
roboco_search_error(error_message="Redis timeout", context="startup")

# After fixing
roboco_record_error_solution(
    error_message="Redis timeout",
    solution="Added retry with exponential backoff",
    worked=True
)

3. Decision Memory

Prevents inconsistent architectural choices. Check before deciding.

Tools: roboco_check_decision, roboco_record_decision

# Before deciding
roboco_check_decision(topic="session storage")

# After deciding
roboco_record_decision(params={
    "topic": "Session storage",
    "decision": "Use Redis",
    "rationale": "Sub-ms reads, existing infra"
})

4. Standards Enforcer

Pre-action validation against organizational rules.

Tools: roboco_get_standards, roboco_validate_action, roboco_review_code

# Before writing code
roboco_get_standards(domain="coding", language="python")

# Validate action
roboco_validate_action(
    action_type="create_endpoint",
    context="Adding /users POST endpoint"
)

# Review code
roboco_review_code(code="...", file_path="api/users.py")

5. Learning Network

Cross-agent knowledge sharing. Learnings propagate organization-wide.

Tools: roboco_record_learning, roboco_search_learnings

# Record insight
roboco_record_learning(
    content="Use transactions for multi-table updates",
    category="pattern",
    shareable=True
)

# Search learnings
roboco_search_learnings(query="database transactions")

6. Proactive Context

Auto-injected knowledge when agents claim tasks.

Tool: roboco_get_proactive_context

Returns:

• Similar completed tasks
• Relevant learnings
• Applicable standards
• Recent decisions
• Known issues
• Code patterns

Data Flow

Task Claim Flow

Agent claims task
       |
       v
+-------------------+
| ProactiveContext  |
| Service           |
+-------------------+
       |
       +-- Search similar tasks (completed)
       +-- Search relevant learnings
       +-- Get applicable standards
       +-- Get recent decisions
       +-- Search known issues
       |
       v
Context injected into task.proactive_context
       |
       v
Agent receives context on task start

Learning Flow

Agent discovers insight
       |
       v
roboco_record_learning()
       |
       v
+-------------------+
| OptimalService    |
+-------------------+
       |
       +-- Store in PostgreSQL
       +-- Index in pgvector (learnings index)
       +-- Optionally notify similar-role agents
       |
       v
Future agents find via search

MCP Server

Location: roboco/mcp/optimal_server.py

Tool Groups:

Group	Tools
Search	kb_search, rag_query, kb_stats
Indexing	kb_index_code, kb_index_docs
Mentor	ask_mentor
Errors	search_error, record_error_solution
Decisions	check_decision, record_decision
Standards	get_standards, validate_action, review_code
Learning	record_learning, search_learnings
Context	get_proactive_context
Admin	clear_index, reindex_all, index_status

API Endpoints

Location: roboco/api/routes/optimal.py

Endpoint	Method	Purpose
/optimal/kb/search	POST	Semantic search
/optimal/rag/query	POST	RAG answer
/optimal/mentor/ask	POST	Conversational help
/optimal/errors/search	POST	Error lookup
/optimal/errors/record	POST	Record solution
/optimal/decisions/check	POST	Check precedent
/optimal/decisions/record	POST	Record decision
/optimal/standards/get	POST	Get standards
/optimal/standards/validate	POST	Validate action
/optimal/review/code	POST	Code review
/optimal/learnings/record	POST	Record learning
/optimal/learnings/search	POST	Search learnings
/optimal/context/proactive	POST	Get context
/optimal/stats	GET	Index stats

Configuration

# Embedding model (local)
ROBOCO_DEFAULT_EMBEDDING_MODEL=qwen3-embedding:0.6b

# LLM for RAG synthesis
ROBOCO_LOCAL_LLM_MODEL=glm-4.7:cloud
ROBOCO_LOCAL_LLM_BASE_URL=http://roboco-ollama:11434/v1

# RAG settings
ROBOCO_RAG_CHUNK_STRATEGY=fixed
ROBOCO_RAG_CHUNK_SIZE=512
ROBOCO_RAG_USE_HYDE=true
ROBOCO_RAG_USE_HYBRID_SEARCH=true

Best Practices

1. Ask mentor first - roboco_ask_mentor is the primary tool
2. Check before deciding - Use roboco_check_decision
3. Record solutions - Use roboco_record_error_solution
4. Share learnings - Use roboco_record_learning
5. Validate actions - Use roboco_validate_action