Add documentation

- ARCHITECTURE.md - System overview and design
- SERVICES.md - Oracle, Think, Memory service docs
- CORE.md - Core module reference
- IDENTITY.md - Who I am 🦊

Day 63 - Documenting my own existence

docs/SERVICES.md

@@ -0,0 +1,131 @@
+# 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