Pular para conteúdo

AUR-020: Escolher memória e mapa incremental mínimos

Documento histórico do board. Pode descrever componentes removidos; para uso atual, consulte o guia do produto.

This is a research/decision card. It does not ship an executable feature; it fixes a design contract that later O10-memory and O02-index cards implement against. The observable behavior is the acceptance lint itself: tests/acceptance/AUR-020.sh deterministically resolves the artifacts below and either passes or names exactly which one is incomplete.

Behavior

tests/acceptance/AUR-020.sh (selector AC-001) reads three artifacts this card owns and checks that they resolve to one consistent decision, without making any network request:

  1. .board/research/memory-design.md — an "Alternatives matrix" table that compares five named alternatives (Aider, Karpathy, Hermes, Tree-sitter, SCIP) plus the AurumCode baseline row, one criterion set per row: a [label](url) source, a Version, an ISO-8601 Date, and one cell per decision criterion (Indexing cost, Query scope, Network dependency).
  2. .board/decisions/ADR-0001-optional-local-memory.md — names each of the five alternatives under a ### Rejected: <name> heading and closes under ### Decision: ... on SQLite FTS5 plus a relation graph. Every justification line uses the fixed form - Criterion: <name> — <text>, and <name> must be one of the criterion columns from the matrix above.
  3. standards/memory/limits.yaml — declares a positive max_index_bytes under index_size: and a positive max_context_window_tokens under context_window:.

The lint also re-checks a small set of literal terms the outcome requires directly (off, ephemeral, local, the default database path, SQLite, FTS5, no vector database, typed status, graph) and scans all three files for language that would make a vector or embedding database mandatory in the baseline, independent of whether the positive "no vector database" claim is still present.

Contract

  • tests/specs/AUR-020/alternatives.txt and tests/specs/AUR-020/allowed-source-domains.txt are the single source of truth for, respectively, the exact five alternative names the matrix and the ADR must resolve, and the hostnames a matrix Source link may cite. Both the shell acceptance test and tests/integration/AUR-020.go read these two files instead of duplicating the lists.
  • A matrix row's Version cell must match a semantic-version-like pattern (v0.86.0, 3.53.3) or, for a non-versioned artifact such as a social media post, an immutable post identifier (post 1937902205765607626) paired with its Date.
  • Every - Criterion: <name> — <text> line in the ADR must resolve to a criterion column present in the matrix; a name outside that set, a missing criterion in a Rejected/Decision section, an alternative missing from the matrix, an unversioned source, or a non-allowlisted source host all fail with the same typed code: AUR-020/AC-001/undecided-criterion.
  • Introducing a mandatory vector/embedding database anywhere in the three artifacts fails with AUR-020/AC-001/vector-database-mandated, regardless of whether the existing "no vector database" sentence is also removed.
  • This card produces no executable index, database, or CLI surface. The SQLite FTS5 plus graph baseline it fixes is implemented by dependent O10-memory/O02-index cards, not here.

Limits

standards/memory/limits.yaml fixes the two bound families ADR-0001 (invariant 8) requires:

  • index_size: max_index_bytes (on-disk ceiling for .git/aurumcode/memory.sqlite3, including FTS5 shadow tables and the WAL file), max_entities, max_retained_snapshots, max_snippet_bytes.
  • context_window: max_augmentation_tokens (the slice of one provider call's context budget the memory augmenter may spend), max_context_window_tokens (the ceiling the augmenter plans against), and min_reserved_baseline_tokens (the unaugmented baseline the augmenter must never shrink).

A consumer repository may lower these through trusted base configuration; it may not raise them past the ceiling declared here without a separate, reviewed change to this file.

Example (no secret)

Running the acceptance test directly, with no network access and no secret material of any kind:

$ ./.board/bin/oci-run --profile bootstrap-readonly-v1 --card AUR-020
{"card":"AUR-020","scenario":"AC-001","selector":"AC-001","required_alternatives":5,"criteria_columns":3,"result":"pass"}

A failing example — a matrix row missing a criterion cell for SCIP:

$ tests/acceptance/AUR-020.sh
AUR-020/AC-001/undecided-criterion: alternative SCIP has an empty criterion cell

Diagnosis

  • AUR-020/AC-001/undecided-criterion: required artifact absent: <path> — one of memory-design.md, the ADR, standards/memory/limits.yaml, or a tests/specs/AUR-020/* fixture is missing or empty. Restore it from the card's owned paths.
  • AUR-020/AC-001/undecided-criterion: alternative <name> ... — the matrix row for that alternative is missing, duplicated, has no versioned source, has a non-ISO date, cites a non-allowlisted source host, or has an empty criterion cell. Fix the offending cell in the "Alternatives matrix" table.
  • AUR-020/AC-001/undecided-criterion: ADR cites a criterion outside the matrix: <label> — a - Criterion: line in the ADR names something that is not one of the matrix's criterion columns. Either fix the label to match the matrix or add the criterion as a matrix column and give every required alternative a value for it.
  • AUR-020/AC-001/undecided-criterion: "<section>" section has no justification for criterion: <name> — a Rejected/Decision section is missing a - Criterion: <name> — ... line for one of the matrix's criteria.
  • AUR-020/AC-001/vector-database-mandated: <path> mandates a vector/ embedding database in the baseline — remove the mandate; the baseline must stay free of a required vector or embedding database.
  • AUR-020/AC-001/undecided-criterion: <limits path> has no positive max_index_bytes ... (or max_context_window_tokens) — the corresponding bound in standards/memory/limits.yaml is missing, zero, or unparsable.
  • AUR-020/AC-001/infrastructure: ... — a required host tool is missing or the repository root could not be resolved; this is never a behavioral result and never counts as RED evidence for this card.