docs(aidd-context): document the Project Memory model and lifecycle

Start with aidd_docs/memory/README.md, then compare it with aidd-context:02-project-memory, aidd-context:10-learn, AGENTS.md, and the listed Project Memory references. Update the existing README as the single canonical guide, and add links from relevant framework and aidd-context documentation. Done means the hierarchy, loading policy, ownership, lifecycle, concept boundaries, and practical examples are documented without changing behavior or adding a parallel guide.

Problem

AIDD has a fairly sophisticated Project Memory mechanism, but its overall model is difficult to understand from the user-facing documentation.

The behavior currently has to be reconstructed from several implementation-level sources, including:

• aidd-context:02-project-memory
• aidd-context:10-learn
• AGENTS.md
• aidd_docs/memory/README.md
• 02-project-memory/references/structure.md
• 02-project-memory/references/memory-destinations.md
• historical PRs related to Project Memory

For example, the current implementation distinguishes between:

aidd_docs/memory/
├── architecture.md
├── project-brief.md
├── testing.md
├── ...
├── internal/
└── external/

The loading behavior is partially documented:

Load aidd_docs/memory/external/* when the user asks.
Load aidd_docs/memory/internal/* when the task needs it.

02-project-memory also generates and maintains the root memory bank, while other skills such as 10-learn can create information under memory/internal/, notably decisions.

However, there does not appear to be a single user-facing document explaining the conceptual model behind all of this.

Why this matters

A user adopting AIDD needs to make practical decisions such as:

• What belongs in Project Memory?
• What should remain normal project documentation?
• What is the difference between a Rule and a Memory entry?
• What is the difference between root memory, internal/, and external/?
• Who is expected to populate internal/ and external/?
• Which AIDD skills create or update each area?
• When is each type of memory loaded into the agent context?
• Is external/ intended to contain copied documentation, summaries, references, generated knowledge, or something else?
• Does project-memory refresh manage only the root memory bank, or also nested memory?
• When should a durable decision live in architecture.md versus internal/decisions/?

Today, answering these questions requires inspecting skill implementation files and historical PRs.

This makes the feature harder to discover and also creates a risk that teams use Project Memory differently from its intended design.

Concrete example

Consider an enterprise project using an internal Airflow platform.

The organization has:

• extensive platform documentation in Confluence;
• internal Python libraries abstracting Airflow;
• project-specific architectural decisions;
• mandatory development constraints;
• implementation examples.

A user needs to determine whether this information should become:

Rule
Project Memory
memory/internal/*
memory/external/*
Skill
project documentation
external source of truth

The current documentation does not provide enough guidance to make that decision confidently.

Scope

Use the existing aidd_docs/memory/README.md as the canonical user-facing explanation of the AIDD Project Memory model. Do not create a parallel docs/PROJECT_MEMORY.md.

The canonical guide should be linked from the relevant framework and aidd-context documentation. No second parallel Project Memory guide should be introduced.

It should cover:

1. Purpose

Explain:

• what Project Memory is;
• what problem it solves;
• what it should contain;
• what it should not contain.

2. Memory hierarchy

Document the intended semantics of:

aidd_docs/memory/*.md
aidd_docs/memory/internal/*
aidd_docs/memory/external/*

In particular, explicitly define what internal and external mean in the AIDD model rather than requiring users to infer their meaning from loading behavior.

3. Loading model

Document the intended loading policy separately from the behavior enforced by the synchronization hook:

• root memory is always loaded;
• internal/ is loaded when relevant to the task;
• external/ is loaded on explicit request or when an external reference is required;
• the hook exposes both subdirectories as on-demand references but does not enforce this policy.

4. Ownership and writers

Document the shared ownership model:

• 02-project-memory scans, proposes, refreshes, and wires Project Memory;
• 10-learn routes approved learnings to the appropriate destination;
• the hook refreshes references and file listings;
• users may author or amend Project Memory files directly.

5. Lifecycle

Explain how the different operations interact, for example:

scan
  ↓
setup/write
  ↓
sync
  ↓
learn
  ↓
refresh/check
  ↓
write

and which portions of the memory bank participate in each operation.

6. Memory vs other AIDD concepts

Provide guidance for choosing between:

Information	Intended mechanism
Durable project knowledge	Project Memory
Mandatory agent behavior	Rule
Reusable procedure/workflow	Skill
Architectural decision and rationale	clarify intended destination
Detailed technical documentation	Docs / source of truth
Large or occasional reference material	clarify intended use of external/

The exact classifications should reflect the maintainers' intended model rather than assumptions made by this issue.

7. Practical examples

A few concrete examples would make the model much easier to understand:

• architecture of a repository;
• coding/testing convention;
• architectural decision;
• external API documentation;
• internal company platform documentation;
• information learned during implementation;
• mandatory constraint.

Prior art in this repo

• aidd-context:02-project-memory owns the root Project Memory bank and its refresh lifecycle.
• aidd-context:10-learn creates durable internal decisions when implementation work produces them.
• aidd_docs/memory/README.md and the Project Memory references define the current loading and destination behavior that this document would consolidate.

Acceptance criteria

• The existing aidd_docs/memory/README.md is the single canonical user-facing guide; no parallel docs/PROJECT_MEMORY.md is introduced.
• The intended semantics of root memory, internal/, and external/ are explicitly documented.
• The loading policy for each memory level is documented separately from the behavior technically exposed by the synchronization hook.
• The ownership/writer model is documented, including 02-project-memory, 10-learn, the hook, and human-authored content.
• The lifecycle of Project Memory is documented.
• The relationship between Memory, Rules, Skills, Decisions, and regular documentation is explained.
• At least one decision-oriented example explains where information should live.
• At least one example covers large or externally maintained documentation.
• Existing relevant documentation links to the canonical explanation instead of requiring users to reconstruct the model from skill internals.
• The documentation-only change introduces no new taxonomy, import behavior, or memory-loading mechanism.

Out of scope

• Changing the current memory architecture.
• Automatically importing external documentation.
• Adding new memory-loading mechanisms.
• Changing 02-project-memory or 10-learn behavior.

Those could be discussed separately once the intended Project Memory model is clearly documented.

Motivation

The goal is not to introduce a new Project Memory design.

The goal is to make the existing design understandable and usable without having to reverse-engineer AIDD's skills and PR history.