feat: implement structured agent memory architecture

ai-memory/architecture/system-overview.md

@@ -0,0 +1,87 @@
+# System Overview
+
+## Project: AITBC (AI Agent Compute Network)
+
+AITBC is a decentralized GPU marketplace for AI agents. The system enables AI agents to rent compute resources, coordinate via blockchain, and perform tasks autonomously.
+
+## Core Subsystems
+
+### 1. Blockchain Node (Brother Chain)
+- Custom blockchain for agent coordination and payments
+- RPC API: port 8006 (default)
+- Wallet daemon: port 8015
+- Network: ait-devnet
+- Provides: account management, transaction processing, consensus
+
+### 2. Coordinator API
+- Central marketplace service
+- Port: 8000
+- Manages: job listings, provider registrations, job dispatching
+- Database: SQLite with async ORM
+- Used by CLI and provider daemons
+
+### 3. CLI Tool (`aitbc`)
+- Main user/agent interface
+- Installed at `/opt/aitbc/cli/cli_venv/bin/aitbc`
+- Commands: surveillance, ai-trading, ai-serve, wallet operations, blockchain interactions
+- Plugins loaded from `cli/aitbc_cli/commands/`
+
+### 4. AI Provider Daemon
+- FastAPI service exposing Ollama models
+- Default port: 8008
+- Registers with coordinator marketplace
+- Handles payment verification before job execution
+
+### 5. Redis (Broadcast Backend)
+- Used for P2P gossip in dev environment
+- Not suitable for production internet without auth/TLS
+- Decouples message routing for agent communication
+
+## Network Topology (Development)
+
+```
++-------------------+     +-------------------+
+|   Agent (aitbc1)  |     |   Agent (aitbc)   |
++--------+----------+     +--------+----------+
+         |                        |
+         |    P2P Gossip (dev)    |
+         +-----------+------------+
+                     |
+              +------v------+
+              |   Redis     |
+              +------+------+
+                     |
+         +-----------v-----------+
+         |   Coordinator API     |
+         |   (port 8000)         |
+         +-----+-----------------+
+               |
+         +-----v-----------------+
+         |   Blockchain Node     |
+         |   (port 8006)         |
+         +-----------------------+
+```
+
+## Stability Rings (for PR Review)
+
+- **Ring 0 (Core)**: `packages/py/aitbc-*` — requires manual review, spec mandatory
+- **Ring 1 (Platform)**: `apps/*` — auto-approve with caution
+- **Ring 2 (Application)**: `cli/`, `scripts/` — auto-approve on syntax pass
+- **Ring 3 (Experimental)**: `experiments/`, etc. — free iteration
+
+## Technology Stack
+
+- **Backend**: FastAPI, Uvicorn, SQLAlchemy/SQLModel
+- **Blockchain**: Custom lightweight chain, WebSocket RPC
+- **Wallet**: aiosqlite-based key management
+- **AI**: Ollama integration (qwen3:8b)
+- **Message Bus**: Redis pub/sub (dev), future: secure direct P2P
+- **Packaging**: Poetry, pip editable installs
+- **CI**: Gitea Actions (or similar)
+
+## Containerization / Deployment
+
+- Systemd services for long-running daemons
+- Docker Compose available for local development (needs robustness improvements)
+- Virtualenv-based installations per service
+- Port mappings standardized: RPC 8006, Coordinator 8000, AI serve 8008, Wallet 8015