feat: implement structured agent memory architecture
This commit is contained in:
aitbc1
188
ai-memory/decisions/protocol-decisions.md
Normal file
188
ai-memory/decisions/protocol-decisions.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Protocol Decisions
|
||||
|
||||
This document records decisions about agent coordination protocols, communication standards, and operational procedures.
|
||||
|
||||
---
|
||||
|
||||
## Decision 1: Memory Access Protocol
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**: Before any task, agents must read:
|
||||
1. `ai-memory/architecture/system-overview.md`
|
||||
2. `ai-memory/failures/debugging-notes.md` (or relevant failure logs)
|
||||
3. `ai-memory/daily/YYYY-MM-DD.md` (today's entry; if none, create it)
|
||||
|
||||
After completing a task, agents must:
|
||||
- Append a concise summary to `ai-memory/daily/YYYY-MM-DD.md`
|
||||
- Use a new bullet point with timestamp or section as needed
|
||||
|
||||
**Rationale**: Ensures agents operate with current context and avoid repeating mistakes. Creates a persistent, searchable audit trail.
|
||||
|
||||
---
|
||||
|
||||
## Decision 2: Failure Recording Protocol
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**: When an agent discovers a new failure pattern (bug, misconfiguration, CI break):
|
||||
1. Append to `ai-memory/failures/failure-archive.md` in the format:
|
||||
```
|
||||
## Failure: [Short title] – [Date]
|
||||
- **Symptom**: ...
|
||||
- **Cause**: ...
|
||||
- **Resolution**: ...
|
||||
```
|
||||
2. If the failure is CI-specific, also append to `ci-failures.md`
|
||||
3. If the failure involves debugging steps, also append to `debugging-notes.md`
|
||||
|
||||
**Rationale**: Centralizes troubleshooting knowledge; agents can proactively consult before debugging similar issues.
|
||||
|
||||
---
|
||||
|
||||
## Decision 3: Decision Logging Protocol
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**: When an agent makes an architectural decision (affecting system structure, APIs, dependencies):
|
||||
1. Record in `ai-memory/decisions/architectural-decisions.md` using the ADR format (Decision, Date, Context, Alternatives, Reason, Impact)
|
||||
2. Keep entries concise but complete enough for future readers
|
||||
|
||||
**Rationale**: Prevents re-debating settled questions; preserves reasoning for new agents.
|
||||
|
||||
---
|
||||
|
||||
## Decision 4: Task Claiming Protocol (Distributed Lock)
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**:
|
||||
- Issues must have label `task`, `bug`, `feature`, or `good-first-task-for-agent` to be claimable.
|
||||
- Agent runs `scripts/claim-task.py` periodically (cron every 5 minutes).
|
||||
- Script:
|
||||
1. Fetches open, unassigned issues with eligible labels.
|
||||
2. Skips issues already associated with the agent's branch or claimed by another agent.
|
||||
3. Picks highest-scoring issue (simple scoring: label priority + age).
|
||||
4. Creates an atomic Git branch: `aitbc1/<issue-number>-<slugified-title>`.
|
||||
5. If branch creation succeeds, posts comment on issue: "Claiming this task (branch: ...)"
|
||||
6. Works on the issue in that branch.
|
||||
- Claim is released when the branch is deleted (PR merged or closed).
|
||||
|
||||
**Rationale**: Uses Git's atomic branch creation as a distributed mutex. No central coordinator needed; agents can run independently.
|
||||
|
||||
---
|
||||
|
||||
## Decision 5: PR Review Protocol
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**:
|
||||
- All PRs must request review from `@aitbc` (the reviewer agent).
|
||||
- Reviewer runs `scripts/monitor-prs.py` every 10 minutes (cron).
|
||||
- For **sibling PRs** (author ≠ self):
|
||||
- Fetch branch, run `py_compile` on changed Python files.
|
||||
- If syntax fails: request changes with comment "Syntax error detected."
|
||||
- If syntax passes:
|
||||
- Check Stability Ring of modified paths.
|
||||
- Ring 0: cannot auto-approve; manual review required (request changes or comment)
|
||||
- Ring 1: auto-approve with caution (approve + comment "Auto-approved Ring 1")
|
||||
- Ring 2: auto-approve (approve)
|
||||
- Ring 3: auto-approve (approve)
|
||||
- For **own PRs**: script auto-requests review from `@aitbc`.
|
||||
- CI status is monitored; failing CI triggers comment "CI failed; please fix."
|
||||
- After approvals and CI pass, reviewer may merge (or allow auto-merge if configured).
|
||||
- On merge: delete the claim branch; close linked issues.
|
||||
|
||||
**Rationale**: Automates routine reviews while preserving human attention for critical areas. Enforces Ring policy consistently.
|
||||
|
||||
---
|
||||
|
||||
## Decision 6: Memory File Naming and Format
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**:
|
||||
- Daily memory: `ai-memory/daily/YYYY-MM-DD.md` (one file per day, Markdown)
|
||||
- Append-only: never edit or delete past entries; only add new bullets at the end.
|
||||
- Timestamps optional but helpful: use headings like `## 15:00–15:59 UTC Update` or bullet with time.
|
||||
- Each entry should be concise but informative: what was done, what was learned, any blockers.
|
||||
- Today's file must exist when needed; create it if absent.
|
||||
|
||||
**Rationale**: Chronological, easy to scan. Append-only prevents tampering with history.
|
||||
|
||||
---
|
||||
|
||||
## Decision 7: Commit Message Convention
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**: Use Conventional Commits format:
|
||||
- `feat: ...` for new features
|
||||
- `fix: ...` for bug fixes
|
||||
- `docs: ...` for documentation only
|
||||
- `refactor: ...` for code restructuring
|
||||
- `test: ...` for adding tests
|
||||
- `chore: ...` for trivial/maintenance changes
|
||||
|
||||
Optionally add scope in parentheses: `feat(coordinator): add job cancellation`
|
||||
|
||||
**Rationale**: Enables automated changelog generation and quick scanning of history.
|
||||
|
||||
---
|
||||
|
||||
## Decision 8: Issue and PR Naming
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**:
|
||||
- Issue title: concise summary, optionally with label prefix: `[Bug] CLI crashes on import`
|
||||
- PR title: `Fix: resolve CLI service imports` or `feat: implement claim-task script`
|
||||
- Branch name: `<agent>/<issue>-<slug>` (e.g., `aitbc1/3-add-tests-for-aitbc-core`)
|
||||
- Branch naming enforces claim linkage to issue.
|
||||
|
||||
**Rationale**: Consistent naming makes it easy to trace work items to code changes.
|
||||
|
||||
---
|
||||
|
||||
## Decision 9: Agent Identity in Communications
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**:
|
||||
- In Gitea comments and issues, sign as the agent identity (e.g., "— aitbc1").
|
||||
- Use the same identity in daily memory entries.
|
||||
- When collaborating with sibling agent, mention `@aitbc` or `@aitbc1` appropriately.
|
||||
|
||||
**Rationale**: Clear attribution for accountability and coordination.
|
||||
|
||||
---
|
||||
|
||||
## Decision 10: Emergency Protocol for Critical CI Failure
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**:
|
||||
- If a PR's CI fails due to infrastructure (not code), the agent who owns the PR should:
|
||||
1. Investigate via `ai-memory/failures/ci-failures.md` and `debugging-notes.md`
|
||||
2. If new failure pattern, record it immediately.
|
||||
3. Comment on the PR with diagnosis and ETA.
|
||||
4. If unable to resolve quickly, escalate to human via other channels (outside scope).
|
||||
|
||||
**Rationale**: CI failures block all work; swift response is critical. Documentation prevents duplicated troubleshooting.
|
||||
|
||||
---
|
||||
|
||||
## Decision 11: Environment Configuration Drift Detection
|
||||
|
||||
**Date**: 2026-03-15
|
||||
|
||||
**Protocol**:
|
||||
- `ai-memory/knowledge/environment.md` must reflect the current dev environment (ports, URLs, credentials placeholders).
|
||||
- If an agent changes a configuration (e.g., port, database path), they must update this file immediately.
|
||||
- Before starting a task, agents should verify that their environment matches the documented settings.
|
||||
|
||||
**Rationale**: Prevents "works on my machine" issues and keeps knowledge current.
|
||||
|
||||
---
|
||||
|
||||
*Add subsequent protocol decisions below.*
|
||||
Reference in New Issue
Block a user