aitbc/ai-memory/README.md

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.