aitbc/ai-memory/knowledge/environment.md

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:

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:

   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):

   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:

   cd apps/coordinator-api
   source venv/bin/activate
   python -m app.init_db
   uvicorn app.main:app --reload --port 8000
   

8. Start blockchain devnet:

   cd apps/blockchain-node
   source venv/bin/activate
   ./scripts/devnet_up.sh
   

9. Verify services:

   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.