feat: implement structured agent memory architecture

ai-memory/README.md

@@ -0,0 +1,106 @@
+# AI Memory System
+
+The `ai-memory/` directory implements a **structured hierarchical memory** for multi-agent coordination in the AITBC project.
+
+## Purpose
+
+- **Improve recall**: Agents can quickly find relevant information.
+- **Reduce hallucinations**: Reliable, organized sources.
+- **Enable collaboration**: Clear protocols for sharing knowledge across sessions and agents.
+- **Prevent duplication**: Document past failures and decisions.
+
+## Directory Structure
+
+```
+ai-memory/
+├── daily/              # Daily activity logs (append-only)
+│   └── YYYY-MM-DD.md
+├── architecture/       # System architecture documentation
+│   ├── system-overview.md
+│   ├── agent-roles.md
+│   └── infrastructure.md
+├── decisions/          # Architectural & protocol decisions
+│   ├── architectural-decisions.md
+│   └── protocol-decisions.md
+├── failures/           # Known failures and debugging help
+│   ├── failure-archive.md
+│   ├── ci-failures.md
+│   └── debugging-notes.md
+├── knowledge/          # Persistent technical knowledge
+│   ├── coding-standards.md
+│   ├── dependencies.md
+│   └── environment.md
+└── agents/             # Agent role specifications
+    ├── agent-dev.md
+    ├── agent-review.md
+    └── agent-ops.md
+```
+
+## Agent Memory Usage Protocol
+
+### Before Starting a Task
+
+1. **Read Architecture** (`architecture/*.md`) to understand the system context.
+2. **Read Failures** (`failures/*.md`) relevant to the task domain to avoid repeating mistakes.
+3. **Read Daily Memory** – open `daily/YYYY-MM-DD.md` (today). If file does not exist, create it. Review recent entries to know what happened earlier today.
+
+### After Completing a Task
+
+- Append a brief summary to `daily/YYYY-MM-DD.md` under a new heading or bullet with timestamp. Include:
+  - What was done.
+  - Outcomes (tests passing, PR opened, etc.).
+  - Any issues encountered.
+
+### Recording New Information
+
+- **New Failure Pattern**: Append to `failures/failure-archive.md` (and optionally `ci-failures.md` or `debugging-notes.md`). Include Symptom, Cause, Resolution.
+- **Architectural Decision**: Add an entry to `decisions/architectural-decisions.md` using the ADR format.
+- **Protocol Change**: Add to `decisions/protocol-decisions.md`.
+- **Environment Change**: Update `knowledge/environment.md`.
+
+### General Rules
+
+- **Append-only**: Never edit or delete existing content in memory files (except to fix typos or formatting that don't alter meaning).
+- **Chronological**: Daily files are ordered by time; use headings like `## 15:30 Update` to break up long days.
+- **Concise but complete**: Provide enough detail for future agents to understand without overwhelming.
+- **Cross-reference**: Link to related files or issues using relative paths or URLs.
+
+## Coordination with Other Agents
+
+- Respect task claims: if you claim an issue, work on it exclusively until done.
+- Use `agent-roles.md` to understand sibling agents' responsibilities.
+- Follow the review protocol: developers request review; reviewers auto- or manually-approve per Rings.
+- Communicate via PR comments and issue comments; sign with your identity (`aitbc1`, `aitbc`).
+
+## Maintenance
+
+- **Periodic consolidation**: Occasionally, review daily entries and distill important lessons into long-term `MEMORY.md` (if still used) or keep in decisions/failures as appropriate.
+- **Archiving**: Old daily files can be compressed or moved to `archive/` after a month, but keep them accessible. The system supports hour-based granularity (`memory/<agent>/YYYY-MM-DD-HH.md`) for finer history; the structured `ai-memory/daily/` is canonical for cross-agent.
+- **Documentation updates**: When architecture or environment changes, update the relevant files immediately.
+
+## Migration Notes
+
+This memory system was introduced on 2026-03-15. Existing memory content from `memory/` and `MEMORY.md` has been partially migrated:
+
+- Daily notes from `memory/2026-03-15.md` and `memory/2026-03-13.md` have been summarized into the new structure.
+- Architecture and infrastructure documentation extracted from `MEMORY.md`.
+- Failure patterns and debugging notes consolidated.
+- Coding standards, dependencies, environment settings established.
+
+Legacy per-agent hourly files (`memory/aitbc1/2026-03-15-13.md`, etc.) are retained for reference but are no longer the primary memory. Future work may consolidate them into daily entries.
+
+## Getting Started (New Agent)
+
+If you are a new agent instance:
+
+1. Read this `README.md` in `ai-memory/`.
+2. Read `agents/agent-*.md` for your role and others.
+3. Read `architecture/system-overview.md` and `infrastructure.md`.
+4. Check `knowledge/environment.md` for current setup.
+5. Browse recent `decisions/` to understand past choices.
+6. Browse `failures/` to avoid known pitfalls.
+7. Check `daily/` for today's activity; if none, create the file with a "Session start" entry.
+
+---
+
+*This memory protocol is itself a living document. Improve it as we learn.*