vi/docs/SERVICES.md

Vi Services

Oracle Service

Purpose: The brain. Wraps Qwen3 30B for reasoning, synthesis, and decision-making.

Location: services/oracle/

NATS Topics:

• vi.services.oracle.process - Process a reasoning request
• vi.services.oracle.health - Health check

How It Works:

1. Receives requests from Think service
2. Builds prompts with Vi's identity and context
3. Calls local Qwen3 30B model
4. Returns structured responses

Dependencies:

• Qwen3 30B model running on Daemoness
• NATS for messaging

---

Think Service

Purpose: The orchestrator. Coordinates multi-step reasoning by asking Oracle what to do next, executing steps, and synthesizing results.

Location: services/think/

NATS Topics:

• vi.services.think.process - Process external input
• vi.services.think.communication - Handle communication requests
• vi.external.input - Legacy input handler
• vi.output.send - Sends responses to plugins

How It Works:

1. Receives input (e.g., Matrix message)
2. Asks Oracle: "What should I do next?"
3. Oracle returns a function call (e.g., short_memory(n=5))
4. Think executes the step
5. Loop until Oracle says ready()
6. Ask Oracle to synthesize final response
7. Send response to output

Stopping Criteria:

• Max 10 steps
• Max 2 minutes
• Max 3 calls to same service
• Goal satisfaction confirmed
• Convergence detected (no new info)

Submodules:

• reasoning/ - Oracle client, step executor, orchestrator
• handlers/ - Input and communication handlers
• memory/ - Memory manager integration

---

Memory Service

Purpose: Three-layer memory system for persistence and recall.

Location: services/memory/

NATS Topics:

• vi.services.memory.short_memory - Recent interactions
• vi.services.memory.long_memory - Consolidated memories
• vi.services.memory.facts - Query facts
• vi.services.memory.save_fact - Store new fact
• vi.services.memory.update_fact - Update existing fact
• vi.memory.store - Store new memory
• vi.memory.search - Search memories

Three Layers:

Short-Term Memory

• Last N literal interactions
• Fast retrieval by recency
• SQLite storage

Long-Term Memory

• Consolidated, summarized memories
• Vector search via ChromaDB
• Patterns that persist

Facts

• Explicit knowledge (birthdays, preferences, etc.)
• Categories: personal, preferences, knowledge, general
• Mutable vs immutable facts
• SQLite with embeddings for search

Storage:

• SQLite for structured data
• ChromaDB for vector embeddings
• NATS KV for hot cache

---

Service Patterns

All services follow the same pattern:

class MyService(BaseService):
    def __init__(self):
        super().__init__('my_service')
    
    def get_service_manifest(self) -> ServiceManifest:
        # Define operations, health check topic, metadata
        pass
    
    async def initialize_service(self):
        # Set up handlers, connections
        pass
    
    async def cleanup_service(self):
        # Clean shutdown
        pass
    
    async def perform_health_check(self):
        # Return health status
        pass

Lifecycle:

1. start() - Connect to NATS, register with health service, start heartbeats
2. initialize_service() - Service-specific setup
3. Run until shutdown
4. cleanup_service() - Clean up resources
5. stop() - Deregister, close connections