# Split-Memory Architecture

## Status

Current architecture for IARPG-OPS-2.

## Purpose

Keep `.uai/` as active, compact startup continuity while preserving detailed reports, research, decisions, architecture, and implementation evidence under `docs/long-term-memory/`.

## Architecture

The repository uses two complementary memory planes:

1. **Hot memory — `.uai/`:** first-load current state, operating constraints, active decisions, architecture, blockers, and the next useful action. It must remain usable when durable documents are temporarily unavailable.
2. **Durable memory — `docs/long-term-memory/`:** detailed reviewed bodies, canonical reports, research, decision records, architecture explanations, implementation history, and superseded material.

Durable memory augments hot memory. It does not retire, disable, replace, or make `.uai/` emergency-only.

## Startup Routing

Agents begin with [the hot-memory index](../../../.uai/index.uai#startup-read-order), then read context, constraints, progress, decisions, architecture, operations, test plan, and the recursive prompt. The pointer ledger is opened when a durable body is needed.

## Durable Layout

- `docs/long-term-memory/reports/` — every active repository-owned canonical report.
- `docs/long-term-memory/architecture/` — detailed system explanations.
- `docs/long-term-memory/decisions/` — durable architecture decision records.
- `docs/long-term-memory/research/` — source maps, investigations, and authority audits.
- `docs/long-term-memory/implementation-history/` — migration and release history.

Original immutable source inputs remain under `docs/source-files/` because they are provenance evidence rather than repository-authored canonical reports. Their exception and compatibility boundary are recorded in the implementation report.

## Link Contract

Hot-memory evidence links are repository-relative Markdown links and should target useful headings. Durable documents link back to the hot records that summarize them. The local validator checks paths and heading anchors without network access.

## Authority Order

1. `AGENTS.md` and explicit repository instructions.
2. Current verified implementation and test evidence.
3. Active `.uai` current-state records.
4. Current authoritative durable documents.
5. Machine-readable manifests and configuration.
6. Historical or archived material.

Conflicts remain explicit until implementation and evidence establish the best-supported current state.

## Security Boundary

Credentials are not memory. Memory may identify a safe inventory location or credential purpose, but it must never contain passwords, API keys, tokens, cookies, private keys, or one-time secrets.

## Validation

Run `python3 scripts/validate_memory_links.py` from the repository root. The validator checks required structure, report placement, pointer-ledger paths and checksums, local deep-link anchors, report backlinks, hot-memory timestamp policy, UAI mirrors, and common secret patterns.

## Memory References

- [Architecture hot memory](../../../.uai/architecture.uai#split-memory-architecture)
- [Memory operating model](../../../.uai/memory.uai#split-memory-operating-model)
- [Repository constraints](../../../.uai/constraints.uai#memory-constraints)
- [Long-term pointer ledger](../../../.uai/long-term-memory.uai#pointer-records)

## Related Durable Documents

- [Split-memory decision](../decisions/adr-001-split-memory-architecture.md#decision)
- [Memory authority and conflict audit](../research/memory-authority-and-conflict-audit.md#findings)
- [Implementation report](../reports/uai-memory-organization-report.md#findings)

## Supersession Status

Current until a later ADR explicitly supersedes it.