# Durable Long-Term Memory

## Split-Memory Design

IARPG uses two complementary memory planes:

- **`.uai/` is active hot memory.** It is read at startup and handoff. It contains concise current facts, constraints, decisions, architecture, progress, blockers, operating instructions, and the next useful action.
- **`docs/long-term-memory/` is durable body memory.** It contains full reports, research, architecture explanations, ADRs, implementation history, migration evidence, and useful superseded material.

Durable memory augments `.uai`; it never replaces, disables, retires, or makes `.uai` emergency-only. The detailed architecture is in [Split-Memory Architecture](architecture/split-memory-architecture.md#architecture), and the accepted decision is [ADR-001](decisions/adr-001-split-memory-architecture.md#decision).

## What Belongs in `.uai/`

Keep only first-load current state:

- verified current facts and explicit assumptions;
- non-negotiable constraints and safety boundaries;
- active decisions and current architecture;
- open work, blockers, test expectations, and operating instructions;
- short routing summaries with repository-relative deep links.

Do not put dated changelogs, long research bodies, raw logs, copied reports, implementation narratives, or secret values in hot memory. Start with [`.uai/index.uai`](../../.uai/index.uai#startup-read-order).

## What Belongs in Durable Memory

- `reports/` — every active repository-owned canonical report and audit;
- `architecture/` — detailed system explanations;
- `decisions/` — durable ADRs and decision records;
- `research/` — investigations, source maps, intake audits, and methodological analysis;
- `implementation-history/` — migrations, release routing, deployment evidence, and superseded paths.

Original immutable source inputs remain under `docs/source-files/` as provenance evidence. They are not active repository-authored canonical report bodies, and they stay byte-preserved at their published source URLs.

## Report Location and Template

Create every new report under `docs/long-term-memory/reports/`. New reports must include:

`Status`, `Purpose`, `Scope`, `Executive Summary`, `Evidence Reviewed`, `Findings`, `Decisions or Recommendations`, `Risks and Limitations`, `Validation Performed`, `Memory References`, `Related Durable Documents`, and `Supersession Status`.

Do not create a root `reports/` directory or place report bodies back under the legacy `docs/reports/` path.

## Deep-Link Maintenance

From hot memory, use repository-relative Markdown links to a useful durable heading, not merely the file top. From durable documents, include a `Memory References` section linking back to the applicable `.uai` records. Update [the semantic pointer ledger](../../.uai/long-term-memory.uai#pointer-records) whenever a durable authoritative file is added, renamed, materially revised, superseded, or archived.

Each pointer record identifies a stable ID, path, useful deep link, routing summary, category, authority, source identity, review status, review evidence, truth boundary, checksum, supersession state, and related hot memory.

## Superseding Stale Documents

Never silently delete useful history or let obsolete files keep steering agents. Mark the old document’s state, add `supersedes` or `superseded_by` links in the pointer ledger, update the human index, and move detailed history to the appropriate durable category. Compatibility paths may remain only when external consumers rely on them; they must not contain a competing canonical body.

## Validation

From the repository root, run:

```bash
python3 scripts/validate_memory_links.py
```

The validator checks required structure, canonical report placement, hot-memory timestamp policy, local paths and heading anchors, pointer-ledger fields and checksums, report backlinks, durable-to-hot backlinks, UAI mirror parity, and common secret patterns. Also run the repository’s PHP, JavaScript, JSON, sitemap, fixture, route-render, ZIP, and external-checksum checks before release.

## Memory References

- [Hot memory index](../../.uai/index.uai#startup-read-order)
- [Memory operating model](../../.uai/memory.uai#split-memory-operating-model)
- [Repository constraints](../../.uai/constraints.uai#memory-constraints)
- [Current progress](../../.uai/progress.uai#current-state)

## Supersession Status

Current until a reviewed architecture decision supersedes ADR-001.

## Current Inventory

- 95 active `.uai` records and 95 byte-identical public mirrors.
- 349 preserved source files across five collections.
- 220 canonical reports under `docs/long-term-memory/reports/`.
- 229 authoritative durable documents indexed by `.uai/long-term-memory.uai`.
- The latest 94-file collection is fully extracted; 64 files are exact duplicate evidence and 30 supply new canonical report bodies.

Source preservation and canonical routing do not verify external claims. Use report review status, evidence, and truth boundaries before public synthesis.