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/dependencies.md
+++ b/ai-memory/knowledge/dependencies.md
@@ -0,0 +1,131 @@
+# Dependencies
+
+This document lists key dependencies across the AITBC project, including versions, purposes, and notes on compatibility.
+
+## Package Management
+
+- **Poetry** (recommended) – dependency resolution, virtualenv, packaging.
+- **pip** – can be used as fallback.
+
+Each package/service has its own `pyproject.toml`. Some dependencies are shared.
+
+## Core Runtime Dependencies
+
+### FastAPI Stack
+- `fastapi` – web framework for APIs
+  - Coordinator API, Blockchain Node, AI Provider Daemon
+  - Version: `>=0.104.0` (or latest stable)
+  - Requires `uvicorn` for serving
+- `uvicorn[standard]` – ASGI server
+  - Important: use `[standard]` for performance (uvloop, httptools)
+  - Version: `>=0.24.0`
+
+### Database
+- `sqlalchemy` – ORM
+- `sqlmodel` – Pydantic-friendly wrapper around SQLAlchemy (used in some packages)
+- `aiosqlite` – async SQLite driver
+- `alembic` – migrations (if used)
+
+### P2P / Networking
+- `websockets` – WebSocket client/server for P2P
+- `aiohttp` – async HTTP client (used in some modules, e.g., KYC/AML providers)
+
+### Redis
+- `redis` – Redis client (development broadcast backend)
+
+### Blockchain / Cryptography
+- `aitbc-core` – internal package: logging utilities, maybe crypto primitives
+- `aitbc-crypto` – internal package: wallet cryptography, signing
+- `aitbc-sdk` – internal package: SDK for interacting with the chain
+
+### AI / Inference
+- `ollama` – Python client (if used) or direct HTTP calls
+- Model: `qwen3:8b` (default)
+
+### Other Utilities
+- `pydantic` – data validation
+- `numpy`, `pandas` – analytics (optional)
+- `orjson` – fast JSON serialization (optional)
+
+## Known Version Constraints
+
+### Starlette
+- Must pin `<0.38` because `Broadcast` module was removed in 0.38.
+- In `pyproject.toml`:
+  ```toml
+  starlette = ">=0.37.2,<0.38"
+  ```
+- **Reason**: Dev broadcast backend depends on it; production will migrate to direct P2P.
+
+### Python Version
+- Target: Python 3.10+ (3.11 or 3.12 recommended)
+- Ensure compatibility of dependencies.
+
+## Per-Package Dependencies
+
+### CLI (`cli/aitbc_cli`)
+- Depends on packages from `packages/py/` (aitbc-core, aitbc-crypto, aitbc-sdk, aitbc-agent-sdk).
+- May import modules from `apps/coordinator-api/src` via sys.path hack (temporary).
+- Minimum dependencies:
+  - `aitbc-core`
+  - `aitbc-crypto`
+  - `aitbc-sdk`
+  - `aitbc-agent-sdk`
+  - `aiohttp` (some commands)
+  - `rich` (if used for pretty output)
+
+### Coordinator API (`apps/coordinator-api`)
+- Dependencies: `fastapi`, `uvicorn`, `sqlalchemy`, `sqlmodel`, `aiosqlite`, `pydantic`, `redis`, `aitbc-core` (maybe).
+- Installed as part of monorepo; not separately packaged.
+
+### Blockchain Node (`apps/blockchain-node`)
+- Dependencies: `fastapi`, `uvicorn`, `sqlmodel`, `aiosqlite`, `websockets`, `pydantic`, `orjson`, `aitbc-core`, `aitbc-crypto`.
+- Additional: `alembic` if using migrations.
+
+### AI Provider Daemon
+- Depends on `fastapi`, `uvicorn`, `ollama` client.
+- May use `aitbc-sdk` for payment verification.
+
+## Development Dependencies
+
+- `pytest` – testing
+- `pytest-asyncio` – async test support
+- `httpx` – async HTTP test client
+- `black` – formatting
+- `isort` – import sorting
+- `mypy` – type checking (optional)
+- `pre-commit` – git hooks
+
+## Installing Dependencies
+
+For a fresh workspace:
+```bash
+# Install package dependencies (per package)
+cd packages/py/aitbc-core && poetry install
+cd ../aitbc-crypto && poetry install
+# etc.
+
+# Or use a script to install all
+# (create install.sh that loops)
+
+# For apps/ and cli/, use their pyproject.toml similarly.
+```
+
+Alternatively, use pip with `-e` for editable installs after ensuring dependencies are satisfied.
+
+## Upgrading Dependencies
+
+- Use `poetry update` to get latest versions within constraints.
+- Test after upgrading, especially `starlette`, `fastapi`, `sqlalchemy`.
+- Pin critical versions in `pyproject.toml` to avoid accidental breakage.
+- Record breaking changes in `ai-memory/decisions/architectural-decisions.md`.
+
+## Dependency Health
+
+- Check for security vulnerabilities periodically (e.g., `safety check` or `dependabot`).
+- Remove unused dependencies to reduce attack surface.
+- Keep internal packages (`aitbc-*`) versioned and published consistently.
+
+---
+
+*Maintain this file as dependencies evolve.*