Memory Reliability and Maintenance

Memory is useful only when it remains trustworthy. agent-qa combines trust scores, injection limits, curator review, security scanning, ablation, circuit breaker behavior, suite snapshot matching, and file locks to keep memory maintainable.

services.memory

Memory settings live under services.memory.

services:
  memory:
    enabled: true
    provider: local
    dir: agent-qa-memory
    minTrust: 0.3
    maxInjections: 3
    curatorEnabled: true
    curatorLockTimeout: 120000
    trustConfirmDelta: 0.05
    trustContradictDelta: 0.10
    ablationEnabled: true
    circuitBreakerEnabled: true
    circuitBreakerWindowSize: 20
    circuitBreakerBaselineSize: 3
    circuitBreakerThreshold: 0.15

enabled controls memory for the run. provider is currently local. dir sets the memory root; relative paths resolve from the config directory.

Retrieval controls

minTrust is the minimum trust an observation needs before it can be injected.

maxInjections limits how many observations can be injected into one step.

The local provider defaults to 0.3 minimum trust and 3 injected observations. Keeping those values conservative helps memory stay useful without overwhelming the step.

Curator controls

curatorEnabled controls post-run memory curation. When it is disabled, memory can still be queried, but the run does not create or update observations through the curator.

curatorLockTimeout controls the .curator.lock wait time for file-backed writes.

trustConfirmDelta increases trust for confirmed observations. trustContradictDelta reduces trust for contradicted observations. When deprecation pushes trust to zero, the observation is deleted.

Ablation

ablationEnabled controls the retry path for failures that used injected memory.

When a run fails and at least one observation was injected, agent-qa can retry without memory. If the retry passes, memory is treated as the likely cause and injected observations are deprecated. If the retry also fails, the failure is not attributed to memory.

Circuit breaker

circuitBreakerEnabled controls run-level protection against harmful memory.

The circuit breaker tracks outcomes with and without memory. It waits until both baseline and memory-backed samples reach circuitBreakerBaselineSize. Then it compares failure rates inside the circuitBreakerWindowSize window. If the memory-backed failure rate exceeds baseline by more than circuitBreakerThreshold, the breaker trips and memory injection is skipped for remaining steps.

Suite snapshot maintenance

Suite observations include position and suite_snapshot. Runtime injection uses both fields to avoid applying a suite memory to the wrong child test.

After suite curation, agent-qa also scans suite observations and deletes stale entries whose stored suite_snapshot no longer matches the current suite.

Security scanning

Before local memory writes an observation, security scanning checks the title and body. Suspicious instruction-changing text, secret-reading commands, invisible control characters, and similar risky content are blocked before the observation reaches disk.

Security scanning also runs while indexing memory. Unsafe observations are skipped instead of being injected into a step.

Manual maintenance

Because memory is file-backed markdown, maintenance can be done with normal repository tools:

• inspect observation diffs during review
• delete obsolete obs_*.md files
• lower trust by editing an observation only when your team intentionally manages memory by hand
• keep suite observations aligned with suite membership and order

Prefer deleting stale observations over rewriting them into something ambiguous. A clear memory file is easier to trust, review, and debug.