feat: implement structured agent memory architecture

ai-memory/knowledge/coding-standards.md

@@ -0,0 +1,126 @@
+# Coding Standards
+
+This document defines the coding conventions and quality standards for the AITBC project. All agents should adhere to these when writing or modifying code.
+
+## Python Style
+
+- Follow **PEP 8** with 4-space indentation.
+- Maximum line length: 88 characters (Black default) or 100 if team agrees.
+- Use **type hints** for function signatures and public methods.
+- Use `snake_case` for variables and functions; `PascalCase` for classes; `UPPER_SNAKE_CASE` for constants.
+
+## Formatting
+
+- **Black** code formatter is preferred (if configured). Otherwise, consistent indentation and spacing.
+- Use `isort` to sort imports: standard library, third-party, local.
+- Remove unused imports and variables.
+
+## Imports
+
+Prefer absolute imports over relative imports for clarity. For intra-package modules, absolute imports from the package root are fine.
+
+Example:
+```python
+from app.services.trading_surveillance import SurveillanceService
+# not
+from ..services.trading_surveillance import SurveillanceService
+```
+
+However, within the `cli` commands, we currently add `sys.path` to include `apps/coordinator-api/src` and then import via `app.services.xxx`. This is acceptable for now, but consider packaging `coordinator-api` as a dependency in the future.
+
+## Docstrings
+
+Public functions, classes, and modules should have docstrings in **Google style** or **NumPy style**. Example (Google):
+```python
+def send_transaction(sender: str, recipient: str, amount: int) -> str:
+    """Send coins from sender to recipient.
+
+    Args:
+        sender: Wallet address of sender.
+        recipient: Wallet address of recipient.
+        amount: Amount in smallest unit (e.g., wei).
+
+    Returns:
+        Transaction hash.
+
+    Raises:
+        InsufficientBalanceError: If sender lacks funds.
+    """
+```
+
+## Error Handling
+
+- Use specific exception types; avoid bare `except:`. Prefer `except SomeError:`.
+- Log exceptions with context; do not swallow silently.
+- For CLI commands, exit with non-zero status on error; print useful message to stderr.
+
+## Logging
+
+- Use the `logging` module, not `print()` for informational output.
+- Configure log level via environment variable `LOG_LEVEL`.
+- Use module-level logger: `logger = logging.getLogger(__name__)`.
+- Log at appropriate levels: `debug` for verbose, `info` for normal operations, `warning` for recoverable issues, `error` for failures.
+
+## Async Code
+
+- Use `async def` for I/O-bound functions; `await` appropriately.
+- Avoid blocking calls (like `time.sleep`) in async functions; use `asyncio.sleep`.
+- Use `asyncio.create_task` for fire-and-forget; handle exceptions.
+
+## Testing
+
+- Write unit tests for new features and bug fixes.
+- Place tests in `tests/` directory adjacent to package or in `tests/` at repo root.
+- Use `pytest` fixtures for common setup/teardown.
+- Aim for high coverage of critical paths; not necessarily 100% trivial code.
+- Tests should be hermetic: no external service dependencies (use mocking) except integration tests (marked separately).
+
+## Commit Messages
+
+- Follow **Conventional Commits**: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
+- Keep subject line under 50 characters; body wrapped at 72 if needed.
+- Reference issue numbers: `Closes #12` or `Fixes #34`.
+
+## Git Workflow
+
+- Create feature branches from `main`: `aitbc1/<issue>-<slug>`.
+- Commit logical units; avoid mixing unrelated changes.
+- Push frequently to remote to back up work.
+- Before opening PR, ensure tests pass locally; run `pre-commit` if configured.
+- Request review from `@aitbc` (or appropriate agent).
+
+## Security
+
+- Never commit secrets (tokens, private keys) to the repository. Use environment variables or config files outside version control.
+- Validate external input (user-provided data) to prevent injection attacks.
+- Use parameterized queries for SQL; never string-concatenate.
+
+## Performance
+
+- Avoid N+1 queries; use eager loading where appropriate.
+- Profile slow code; add indexes to database if needed.
+- Consider async for I/O-bound services.
+
+## API Design
+
+- RESTful endpoints: use nouns, plural (`/v1/jobs`, `/v1/wallets`), proper HTTP verbs.
+- Version APIs (`/v1/`) to allow future upgrades.
+- Use appropriate status codes (200, 201, 400, 404, 409, 500).
+- Return JSON with consistent structure: `{"data": ..., "error": null}` or error envelope.
+
+## Documentation
+
+- Update README.md when user-facing changes occur.
+- Document new CLI commands in `README.md` or `docs/`.
+- Keep `ai-memory/knowledge/` files up to date with environment details, dependencies, and coding standards.
+
+## Code Review
+
+- Respect Stability Rings: Ring 0 (core packages) requires meticulous review.
+- Reviewers: look for correctness, security, performance, readability, tests.
+- Approve only when CI passes and code meets standards.
+- Address review comments promptly.
+
+---
+
+By adhering to these standards, we maintain a clean, maintainable, and robust codebase.