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/knowledge/environment.md
+++ b/ai-memory/knowledge/environment.md
@@ -0,0 +1,161 @@
+# Environment
+
+This document describes the current development environment configuration, including services, ports, environment variables, and setup steps.
+
+## Host Information
+
+**Primary Host**: `aitbc1`
+- OS: Linux (6.11.10-amd64)
+- Workspace: `/root/.openclaw/workspace`
+- Python: 3.10+ (node v22.22.1 also installed for tooling)
+- Shell: zsh
+- Timezone: UTC
+
+**Sibling Host**: `aitbc`
+- Remote machine (details may differ)
+- Communication: via Gitea API, SSH, P2P
+
+## Repository Layout
+
+```
+/root/.openclaw/workspace/
+├── ai-memory/          # Structured memory (canonical)
+│   ├── daily/
+│   ├── architecture/
+│   ├── decisions/
+│   ├── failures/
+│   ├── knowledge/
+│   └── agents/
+├── memory/             # Legacy per-agent hourly logs (deprecated)
+│   ├── aitbc/
+│   ├── aitbc1/
+│   └── archive/
+├── MEMORY.md           # Curated long-term notes (to be migrated)
+├── packages/py/        # Python packages (aitbc-*)
+├── apps/
+│   ├── coordinator-api/
+│   └── blockchain-node/
+├── cli/
+│   └── aitbc_cli/
+├── scripts/
+├── AGENTS.md
+├── SOUL.md
+└── README.md
+```
+
+## Services & Ports
+
+| Service            | Path                         | Port | Protocol | Status (typically) |
+|--------------------|------------------------------|------|----------|--------------------|
+| Coordinator API    | `apps/coordinator-api`       | 8000 | HTTP     | Running            |
+| Blockchain RPC     | `apps/blockchain-node`       | 8006 | HTTP     | Running            |
+| Blockchain P2P     | `apps/blockchain-node`       | 8005 | WebSocket| Running            |
+| Wallet Daemon      | `apps/blockchain-node`       | 8015 | HTTP     | Running            |
+| AI Provider        | Launched via CLI `ai serve`  | 8008 | HTTP     | On-demand          |
+| Redis              | System service               | 6379 | TCP      | Running (dev)      |
+
+## Environment Variables
+
+Common variables used:
+
+- `LOG_LEVEL`: Logging level (default `INFO`). Set to `DEBUG` for verbose.
+- `DATABASE_URL`: Database connection string. Example: `sqlite+aiosqlite:///data/coordinator.db`
+- `REDIS_URL`: Redis connection. Default: `redis://localhost`
+- `HOST`: Service host (usually `0.0.0.0` to bind all)
+- `PORT`: Service port (overrides default)
+- `GITEA_TOKEN`: API token for Gitea (automation scripts). Not in repo.
+
+Services typically read these from environment or use defaults.
+
+## Virtual Environments
+
+Each package/service may have its own virtualenv under `venv/` or use a central one.
+
+- CLI venv: `/opt/aitbc/cli/cli_venv` (or `/opt/aitbc/cli/venv`)
+- Coordinator venv: (maybe) `apps/coordinator-api/venv`
+- Blockchain node venv: `apps/blockchain-node/venv` or system Python
+
+**Important**: Activate the correct venv before running commands:
+```bash
+source /opt/aitbc/cli/cli_venv/bin/activate
+aitbc --help
+```
+
+## Setup Steps (New Developer)
+
+1. Clone repository to workspace.
+2. Install **Poetry** (if not installed).
+3. Install dependencies for each package:
+   ```bash
+   cd packages/py/aitbc-core && poetry install
+   cd ../aitbc-crypto && poetry install
+   cd ../aitbc-sdk && poetry install
+   cd ../aitbc-agent-sdk && poetry install
+   ```
+4. Install CLI dependencies (either via Poetry in `cli/` or use venv):
+   ```bash
+   cd cli
+   python -m venv venv
+   source venv/bin/activate
+   pip install -e .
+   ```
+5. Install service dependencies for `coordinator-api` and `blockchain-node` similarly.
+6. Start Redis: `sudo systemctl start redis` or `redis-server`.
+7. Initialize and start coordinator DB:
+   ```bash
+   cd apps/coordinator-api
+   source venv/bin/activate
+   python -m app.init_db
+   uvicorn app.main:app --reload --port 8000
+   ```
+8. Start blockchain devnet:
+   ```bash
+   cd apps/blockchain-node
+   source venv/bin/activate
+   ./scripts/devnet_up.sh
+   ```
+9. Verify services:
+   ```bash
+   curl http://localhost:8000/health
+   curl http://localhost:8006/health
+   ```
+10. Configure Gitea token for automation: `export GITEA_TOKEN=...` in shell profile or cron environment.
+
+## Testing
+
+- Run package tests with `pytest` inside the package directory or via `poetry run pytest`.
+- CLI tests: `aitbc <command>` after activating CLI venv.
+- Integration tests may require all services running.
+
+## Known Issues
+
+- Starlette must be pinned `<0.38`.
+- Docker Compose command name varies (`docker compose` vs `docker-compose`).
+- Absolute paths in some old scripts; replaced with relative.
+- Redis is dev-only; not hardened for internet.
+
+## Monitoring
+
+- Health endpoints:
+  - Coordinator: `GET /health` → `{"status":"ok"}`
+  - Blockchain: `GET /health` or `/status`
+  - Wallet: `GET /wallet/balance?addr=...`
+- Logs: Check stdout/stderr of services, or systemd journal if installed as services.
+
+## Troubleshooting
+
+- Port in use: `lsof -i:<port>` to find culprit.
+- Database locked: ensure only one process writes; use `IF NOT EXISTS` for idempotent init.
+- Import errors: verify `PYTHONPATH` and virtualenv activation.
+- Redis connection refused: start Redis server (`systemctl start redis`).
+
+## Future Improvements
+
+- Production P2P without Redis.
+- TLS for all services.
+- Centralized configuration management (e.g., TOML file).
+- Docker Compose for whole stack (robustified).
+
+---
+
+*Update this file whenever environment configuration changes.*