# 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.*