feat: implement structured agent memory architecture

2026-03-15 21:09:39 +00:00
commit 2d68f66405
17 changed files with 2273 additions and 0 deletions
--- a/ai-memory/architecture/infrastructure.md
+++ b/ai-memory/architecture/infrastructure.md
@@ -0,0 +1,160 @@
+# Infrastructure
+
+This document describes the physical and logical infrastructure supporting the AITBC development environment.
+
+## Host Environment
+
+### Development Hosts
+- Primary host: `aitbc1` machine (this workspace)
+- Sibling host: `aitbc` machine (remote)
+- Both run Linux (x64)
+- SSH access configured for repository access
+
+### Repository (Gitea)
+- URL: `https://gitea.bubuit.net/oib/aitbc`
+- Worktree: `/root/.openclaw/workspace`
+- Primary branch: `main`
+- Feature branches: `<agent>/<issue>-<slug>` or `infrastructure-*`
+- Issue labels: `task`, `bug`, `feature`, `refactor`, `security`, `good-first-task-for-agent`
+- Protected branches: `main` requires PR and CI passing (ideally)
+
+## Service Architecture
+
+### Coordinator API
+- Path: `apps/coordinator-api/`
+- Runtime: Uvicorn/FastAPI
+- Port: 8000
+- Database: SQLite (`data/coordinator.db`)
+- Startup: `python -m app.main` within venv
+- Responsibilities: job marketplace, provider registry, job lifecycle
+
+### Blockchain Node (Brother Chain)
+- Path: `apps/blockchain-node/`
+- Runtime: Uvicorn/FastAPI + custom consensus
+- Port: 8006 (RPC), 8005 (P2P gossip)
+- Database: SQLite (`data/chain.db`)
+- Wallet daemon port: 8015
+- Startup: `scripts/devnet_up.sh` or systemd service
+- Responsibilities: ledger, transactions, consensus, wallet management
+
+### AI Provider Daemon
+- Path: (provided by agents; CLI `aitbc ai serve`)
+- Runtime: FastAPI + Ollama
+- Port: 8008 (configurable)
+- Model: `qwen3:8b` (default)
+- Responsibilities: serve inference, accept payment, report results
+
+### Redis
+- Package: `redis-server`
+- Used for: broadcast/pub-sub messaging (dev only)
+- Configuration: default local instance
+- Not production hardened (no auth/TLS by default)
+
+## Build & Package Infrastructure
+
+### Monorepo Layout
+```
+/root/.openclaw/workspace/
+├── packages/py/        # Python packages (aitbc-core, aitbc-crypto, etc.)
+├── apps/               # Service applications
+│   ├── coordinator-api/
+│   └── blockchain-node/
+├── cli/                # Main CLI tool
+├── scripts/            # Automation scripts (claim-task, monitor-prs)
+├── memory/             # Legacy per-agent hourly logs (migrating to ai-memory/)
+├── ai-memory/          # Structured memory (canonical)
+└── MEMORY.md           # Curated long-term notes (to be migrated)
+```
+
+### Build Tools
+- **Poetry**: for package dependency management (`pyproject.toml`)
+- **pip (editable)**: `pip install -e ./package`
+- **pytest**: test runner
+- **Gitea Actions**: CI pipeline (runs tests on PRs)
+
+### Python Dependencies (Key)
+- FastAPI, Uvicorn (services)
+- SQLAlchemy/SQLModel (ORM)
+- aiosqlite (async SQLite)
+- aiohttp, websockets, pydantic
+- Redis client (development)
+- See `pyproject.toml` files for exact versions
+
+## Automation & Coordination Scripts
+
+### scripts/claim-task.py
+- Polls unassigned issues with eligible labels
+- Uses atomic Git branch creation as distributed lock
+- Creates work branch `<agent>/<issue>-<slug>`
+- Runs every 5 minutes (cron)
+
+### scripts/monitor-prs.py
+- Monitors open PRs
+- Auto-requests review from sibling on own PRs
+- For sibling's PRs: validates syntax, auto-approves if valid per Ring rules
+- Monitors CI status; reports failures
+- Cleans up claim branches on merge/close
+- Runs every 10 minutes (cron)
+
+### Cron Configuration
+```
+*/5 * * * * cd /root/.openclaw/workspace && /usr/bin/python scripts/claim-task.py
+*/10 * * * * cd /root/.openclaw/workspace && /usr/bin/python scripts/monitor-prs.py
+```
+
+## Configuration Management
+
+### Port Allocations (Standard)
+- Coordinator API: 8000
+- Blockchain RPC: 8006
+- Blockchain P2P: 8005
+- Wallet Daemon: 8015
+- AI Provider: 8008
+
+### Environment Variables
+Services may use:
+- `DATABASE_URL` (default: `sqlite+aiosqlite:///data/app.db`)
+- `REDIS_URL` (default: `redis://localhost`)
+- `LOG_LEVEL` (default: `INFO`)
+- `HOST`, `PORT` (per-service)
+
+### Secrets
+- Gitea tokens stored in environment (not in repo)
+- Wallet keys stored in encrypted wallet files (user-managed)
+- No hardcoded credentials in code
+
+## CI/CD Pipeline
+
+1. PR opened → Gitea Actions trigger
+2. Install dependencies (cached)
+3. Run linters (if configured)
+4. Run test suites for affected packages
+5. Report status to PR
+6. Block merge if CI failing
+
+## Monitoring & Diagnostics
+
+- Health endpoints: `GET /health` on each service
+- Coordinator jobs: `GET /v1/jobs` for active jobs
+- Blockchain status: `GET /status` for chain info
+- Logs: stdout/stderr captured by systemd or Docker
+
+## Network Considerations
+
+- Development: all services on localhost or local network
+- Future production: need TLS for Redis, firewall rules, authentication
+- P2P gossip over internet requires hole-packing or relay servers
+- Port mapping must be configured on routers for external access
+
+## Backup & Resilience
+
+- SQLite databases stored under `data/`; should be backed up periodically
+- Git repository serves as code backup; push to remote Gitea
+- Wallet keys: user responsibility to back up mnemonic/private keys
+
+## Known Issues
+
+- Docker Compose detection: some systems only have `docker compose` (v2) not `docker-compose` (v1)
+- Absolute paths in test scripts (need correction to project-relative)
+- Starlette Broadcast removed in 0.38 → must pin <0.38
+- Redis pub/sub not suitable for internet without auth/TLS (dev-only solution)