106 lines
5.0 KiB
Markdown
106 lines
5.0 KiB
Markdown
# 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.* |