docs: Update service READMEs with accurate documentation

## metacognitive_reflector/README.md (23 → 175 lines)
- Add Tribunal system (3 judges: VERITAS, SOPHIA, DIKĒ)
- Document all API endpoints (/reflect, /verdict, /agent/*)
- Add Self-Reflection Engine details
- Document Memory integration (4-tier)
- Add offense levels and punishment system

## episodic_memory/README.md (24 → 229 lines)
- Correct database: Qdrant (not ChromaDB)
- Document Memory Types (MIRIX: CORE, EPISODIC, SEMANTIC, etc)
- Add 4-tier Memory Fortress architecture
- Document all endpoints (12 total)
- Add Entity Index and decay curve details

## api_gateway/README.md (23 → 141 lines)
- Add service routing table (local + Docker)
- Document request flow diagram
- Add configuration options
- Document error responses

## consciousness/README.md
- Fix port: 8001 (was 8000)
- Add Neuromodulation System (4 modulators)
- Add Soul Configuration section
- Add Free Will Engine section
- Update date to 2025-12-12

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: JuanCS-Dev

backend/services/api_gateway/README.md

@@ -1,22 +1,140 @@
 # API Gateway Service
 
-Minimalist gateway to route external requests to internal services.
+**Port:** 8000
+**Status:** Production-Ready
+**Updated:** 2025-12-12
+
+Reverse proxy gateway that routes external requests to internal NOESIS microservices.
+
+---
+
+## Architecture
+
+```
+api_gateway/
+├── src/api_gateway/
+│   ├── core/
+│   │   └── proxy.py        # Service routing logic
+│   └── main.py             # FastAPI application
+```
+
+---
+
+## Service Routing
+
+### Local Development Mode
+
+| Route | Service | Port |
+|-------|---------|------|
+| `/api/consciousness/*` | maximus_core_service | 8001 |
+| `/api/memory/*` | episodic_memory | 8102 |
+| `/api/reflect/*` | metacognitive_reflector | 8002 |
+| `/api/ethics/*` | ethical_audit_service | 8006 |
+| `/api/executive/*` | prefrontal_cortex_service | 8005 |
+
+### Docker Mode
+
+In Docker, services use internal DNS names on port 8000:
+
+```python
+services = {
+    "maximus_core_service": "http://maximus_core:8000",
+    "episodic_memory": "http://episodic_memory:8000",
+    "metacognitive_reflector": "http://metacognitive_reflector:8000",
+    "ethical_audit_service": "http://ethical_audit:8000",
+    "prefrontal_cortex_service": "http://prefrontal_cortex:8000",
+}
+```
+
+---
+
+## Features
+
+- **Request Forwarding**: Routes to appropriate backend service
+- **Connection Pooling**: 20 keep-alive connections
+- **Timeout Management**: 30s total, 10s connect
+- **Error Handling**: 502 for upstream failures, 404 for unknown services
+
+---
+
+## API Endpoints
+
+```
+GET  /health                → Gateway health check
+ANY  /api/{service}/*       → Forward to service
+```
+
+---
 
 ## Quick Start
 
 ```bash
-# Run service
-python -m backend.services.api_gateway.main
-```
+# Run gateway
+cd backend/services/api_gateway
+PYTHONPATH=src python -m uvicorn api_gateway.main:app --port 8000
 
-## Architecture
+# Health check
+curl http://localhost:8000/health
 
-Acts as a reverse proxy. Handles authentication and rate limiting.
+# Forward to consciousness
+curl http://localhost:8000/api/consciousness/v1/health
 
-## API
+# Forward to memory
+curl http://localhost:8000/api/memory/v1/memories/stats
+```
 
-- Routes requests to `/api/v1/{service_name}`.
+---
 
 ## Configuration
 
-- `SERVICES_MAP`: Mapping of service names to internal URLs.
+```bash
+# Environment Variables
+API_GATEWAY_PORT=8000
+DOCKER_ENV=false           # Set to "true" in Docker
+
+# Timeouts (in proxy.py)
+REQUEST_TIMEOUT=30.0       # Total request timeout
+CONNECT_TIMEOUT=10.0       # Connection timeout
+MAX_KEEPALIVE=20           # Connection pool size
+```
+
+---
+
+## Request Flow
+
+```
+Client Request
+     │
+     ▼
+┌─────────────────┐
+│  API Gateway    │  Port 8000
+│  (FastAPI)      │
+└────────┬────────┘
+         │
+    Route by path
+         │
+    ┌────┴────┬──────────┬──────────┐
+    ▼         ▼          ▼          ▼
+┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
+│Maximus│ │Memory │ │Reflect│ │Ethics │
+│ :8001 │ │ :8102 │ │ :8002 │ │ :8006 │
+└───────┘ └───────┘ └───────┘ └───────┘
+```
+
+---
+
+## Error Responses
+
+| Code | Meaning |
+|------|---------|
+| 404 | Service not found in routing table |
+| 502 | Upstream service unavailable |
+| 500 | Internal gateway error |
+
+---
+
+## Related Documentation
+
+- [Maximus Core](../maximus_core_service/src/maximus_core_service/consciousness/README.md)
+- [Episodic Memory](../episodic_memory/README.md)
+- [Metacognitive Reflector](../metacognitive_reflector/README.md)

backend/services/episodic_memory/README.md

@@ -1,23 +1,228 @@
 # Episodic Memory Service
 
-Stores and retrieves past experiences to provide context for current actions.
+**Port:** 8102
+**Database:** Qdrant (Vector DB)
+**Status:** Production-Ready
+**Updated:** 2025-12-12
+
+Persistent memory storage for the NOESIS consciousness system. Implements a **4-tier Memory Fortress** architecture with semantic search capabilities.
+
+---
+
+## Architecture
+
+```
+episodic_memory/
+├── api/
+│   └── routes.py           # FastAPI endpoints
+├── core/
+│   ├── qdrant_client.py    # Vector database client
+│   ├── entity_index.py     # Entity extraction & indexing
+│   ├── memory_store.py     # Memory CRUD operations
+│   ├── persistent_store.py # Disk persistence
+│   ├── hierarchy.py        # 4-tier cache hierarchy
+│   └── context_builder.py  # Context assembly for LLM
+└── models/
+    └── memory.py           # Memory data models
+```
+
+---
+
+## Memory Types (MIRIX)
+
+| Type | Purpose | Persistence | Priority |
+|------|---------|-------------|----------|
+| **CORE** | Identity, immutable facts | Permanent | 5 (highest) |
+| **EPISODIC** | Specific events, experiences | Decayable | 10 |
+| **SEMANTIC** | General knowledge, facts | Long-term | 8 |
+| **PROCEDURAL** | Skills, how-to knowledge | Long-term | 5 |
+| **RESOURCE** | External references | Medium-term | 3 |
+| **VAULT** | High-confidence, consolidated | Permanent | 5 |
+
+---
+
+## 4-Tier Memory Fortress
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  L1: HOT CACHE (In-Memory LRU)                             │
+│  Latency: <1ms | Max: 1000 entries | TTL: 300s             │
+│  Contents: CORE + VAULT (critical memories)                 │
+├─────────────────────────────────────────────────────────────┤
+│  L2: WARM STORAGE (Redis + AOF)                            │
+│  Latency: <10ms | Persistence: AOF log                     │
+│  Contents: Recent EPISODIC + SEMANTIC                      │
+├─────────────────────────────────────────────────────────────┤
+│  L3: COLD STORAGE (Qdrant via HTTP)                        │
+│  Latency: <50ms | Semantic search enabled                  │
+│  Contents: All memory types, vector embeddings             │
+├─────────────────────────────────────────────────────────────┤
+│  L4: VAULT BACKUP (JSON + Checksums)                       │
+│  Sync: Every 5 min | Path: data/vault/                     │
+│  Contents: Disaster recovery snapshots                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## API Endpoints
+
+### Health
+
+```
+GET /health                         → Service health check
+```
+
+### Memory CRUD
+
+```
+POST   /v1/memories                 → Store new memory
+GET    /v1/memories/{id}            → Get memory by ID
+DELETE /v1/memories/{id}            → Delete memory
+GET    /v1/memories/type/{type}     → Get memories by type
+GET    /v1/memories/stats           → Memory statistics
+```
+
+### Search & Context
+
+```
+POST /v1/memories/search            → Semantic search (vector similarity)
+POST /v1/memories/context           → Build LLM context from memories
+```
+
+### Maintenance
+
+```
+POST /v1/memories/consolidate       → Move old memories to VAULT
+POST /v1/memories/decay             → Apply forgetting curve
+POST /v1/memories/sync              → Sync with persistent storage
+```
+
+---
+
+## Qdrant Configuration
+
+```python
+# Collection: maximus_episodic_memory
+# Vector size: 1536 (OpenAI embeddings)
+# Distance: Cosine similarity
+# Quantization: int8 (99th percentile) → 3x memory reduction
+
+QDRANT_URL = "http://localhost:6333"
+COLLECTION_NAME = "maximus_episodic_memory"
+VECTOR_SIZE = 1536
+```
+
+---
+
+## Entity Index
+
+Automatic entity extraction for fast retrieval:
+
+```python
+# Extracts:
+# - Proper nouns (capitalized words)
+# - Technical terms
+# - Quoted strings
+# - Keywords
+
+# Creates inverted index:
+# entity → [memory_id_1, memory_id_2, ...]
+
+# Storage: data/entity_index.json
+```
+
+---
+
+## Memory Decay (Forgetting Curve)
+
+Implements Ebbinghaus forgetting curve:
+
+```python
+# Decay formula
+retention = e^(-t/S)
+
+# Where:
+# t = time since last access
+# S = memory strength (based on access count)
+
+# Memories below threshold are candidates for:
+# 1. Consolidation to VAULT (if high value)
+# 2. Deletion (if low value)
+```
+
+---
 
 ## Quick Start
 
 ```bash
+# Start Qdrant
+docker run -p 6333:6333 qdrant/qdrant
+
 # Run service
-python -m backend.services.episodic_memory.main
-```
+cd backend/services/episodic_memory
+PYTHONPATH=src python -m uvicorn episodic_memory.main:app --port 8102
 
-## Architecture
+# Health check
+curl http://localhost:8102/health
 
-Uses a vector database (e.g., ChromaDB or Qdrant) to store embeddings of events.
+# Store memory
+curl -X POST http://localhost:8102/v1/memories \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": "User prefers dark mode",
+    "type": "SEMANTIC",
+    "importance": 0.8
+  }'
 
-## API
+# Search
+curl -X POST http://localhost:8102/v1/memories/search \
+  -H "Content-Type: application/json" \
+  -d '{"query": "user preferences", "limit": 5}'
+```
 
-- `POST /remember`: Store a new memory.
-- `GET /recall`: Retrieve relevant memories.
+---
 
 ## Configuration
 
-- `VECTOR_DB_URL`: URL of the vector database.
+```bash
+# Environment Variables
+EPISODIC_MEMORY_PORT=8102
+QDRANT_URL=http://localhost:6333
+EMBEDDING_MODEL=text-embedding-ada-002
+DATA_DIR=./data
+```
+
+---
+
+## Guarantees
+
+| Metric | Target |
+|--------|--------|
+| L1 Latency | <1ms |
+| L3 Latency | <50ms |
+| Durability | 99.99% |
+| Recovery Time | <30s |
+| Checksum Pass | 100% |
+
+---
+
+## Integration with Consciousness
+
+```
+Consciousness Pipeline:
+1. User input received
+2. Context built from relevant memories
+3. ESGT ignition with memory context
+4. LLM generates response
+5. New memories stored (insights, facts learned)
+6. Memories consolidated periodically
+```
+
+---
+
+## Related Documentation
+
+- [Memory Fortress](../../../docs/MEMORY_FORTRESS.md)
+- [Metacognitive Reflector](../metacognitive_reflector/README.md)
+- [Consciousness System](../maximus_core_service/src/maximus_core_service/consciousness/README.md)