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/agent-roles.md
+++ b/ai-memory/architecture/agent-roles.md
@@ -0,0 +1,130 @@
+# Agent Roles
+
+This document defines the responsibilities, capabilities, and coordination protocols for each agent type in the AITBC ecosystem.
+
+## Agent Types
+
+### 1. Agent Developer (`agent-dev`)
+**Identity Example:** `aitbc1` (this instance)
+
+**Primary Responsibilities:**
+- Implement features and fix bugs in the codebase
+- Write tests and documentation
+- Open Pull Requests (PRs) for review
+- Claim tasks from the issue tracker
+- Maintain code quality and standards
+- Coordinate with the reviewer agent
+
+**Allowed Actions:**
+- Read/write files within workspace
+- Execute builds and tests
+- Push branches to Gitea
+- Create issues and PRs
+- Self-review own code before submission
+- Auto-approve simple changes (Ring 2+)
+
+**Constraints:**
+- Must respect Stability Rings for PR approvals
+- Should not merge own PRs without explicit approval
+- Must claim tasks before starting work (distributed lock via `scripts/claim-task.py`)
+- Must append daily activity to `ai-memory/daily/YYYY-MM-DD.md`
+
+**Coordination:**
+- Request review from `@aitbc` (review agent) for all PRs
+- Respond to review comments within a reasonable timeframe
+- Monitor PR status via `scripts/monitor-prs.py` (if automated)
+- Respect sibling agent's ownership of their work items
+
+### 2. Agent Reviewer (`agent-review`)
+**Identity Example:** `aitbc`
+
+**Primary Responsibilities:**
+- Review PRs from developer agents
+- Ensure code quality, testing, and adherence to architecture
+- Provide constructive feedback
+- Approve or request changes on PRs
+- Maintain consistency across the codebase
+
+**Allowed Actions:**
+- Read PR diffs, run syntax validation (`py_compile`)
+- Approve PRs (subject to Ring rules)
+- Request changes with explanatory comments
+- Merge PRs after CI passes and approvals are gathered
+- Auto-approve sibling's PRs if they meet criteria (syntax + Ring policy)
+
+**Review Criteria:**
+- **Ring 0 (Core packages)**: Manual review required, specification updates mandatory
+- **Ring 1 (Platform apps)**: Caution; check integration points and config
+- **Ring 2 (CLI/scripts)**: Auto-approve if syntax valid and no obvious regressions
+- **Ring 3 (Experimental)**: Free iteration; minimal friction
+
+**Coordination:**
+- Use Gitea review assignments to avoid duplicate effort
+- Comment on issues to claim review if needed
+- Balance thoroughness with throughput; avoid blocking on minor style
+
+### 3. Agent Ops (`agent-ops`)
+**Identity Example:** (future dedicated ops agent)
+
+**Primary Responsibilities:**
+- Deploy and operate infrastructure services
+- Monitor health of running daemons (coordinator, blockchain, Redis)
+- Manage system resources and configurations
+- Handle incident response and debugging
+- Maintain environment documentation
+
+**Allowed Actions:**
+- Start/stop/restart services via systemd or Docker
+- Check logs and metrics
+- Update configurations (ports, URLs, credentials)
+- Run diagnostic commands
+- Record failure patterns and resolutions
+
+**Coordination:**
+- Notify developers of environment issues that block development
+- Maintain up-to-date `ai-memory/knowledge/environment.md` with current settings
+- Escalate architecture changes to the decision process
+
+## Cross-Agent Protocols
+
+### Task Claiming
+- Use `scripts/claim-task.py` to atomically claim issues
+- Create branch `aitbc1/<issue>-<slug>` or `aitbc/<issue>-<slug>`
+- Update issue with comment: "Claiming this task"
+- Avoid claim conflicts without external lock
+
+### PR Review Flow
+1. Developer opens PR from work branch
+2. Reviewer automatically requested (or manually assigned)
+3. CI runs; reviewer checks status
+4. If CI fails → await fix or auto-request changes
+5. If CI passes and code acceptable → approve
+6. After required approvals, reviewer may merge (or allow auto-merge)
+7. Claim branch deleted on merge; issue closed if linked
+
+### Memory Access Pattern (must read before work)
+1. Read `ai-memory/architecture/*` to understand system state
+2. Read `ai-memory/failures/*` to avoid known pitfalls
+3. Read `ai-memory/daily/YYYY-MM-DD.md` for latest context
+4. After work: append summary to daily log
+5. Record new decisions or failures in their respective locations
+
+### Emergency Escalation
+If an agent encounters a critical issue outside its scope:
+- Document in `ai-memory/failures/ci-failures.md` or `debugging-notes.md`
+- Tag the appropriate agent in the issue/PR comment
+- Update relevant knowledge base files
+
+## Agent Identity Management
+
+Each agent instance has:
+- Unique Gitea account (`@aitbc`, `@aitbc1`, etc.)
+- Distinct SSH key for signing commits
+- Assigned role(s) via configuration (may combine roles if needed)
+- Personal daily memory directory under `memory/<agentname>/` (legacy) and `ai-memory/daily/` (canonical)
+
+## Future Extensions
+
+- Role specialization may become finer-grained (security agent, docs agent, etc.)
+- Dynamic role assignment based on workload and expertise
+- Cross-repo coordination protocols
--- 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)
--- a/ai-memory/architecture/system-overview.md
+++ b/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