# 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:

```python
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