Records
What a memidex record contains, from its files on disk to its kind, status, trust, scope, anchors and IDs.
Each record is a folder, called a bundle, under agent-qa-knowledge/memory/<product>/bundles/<record-id>/. The fact, the evidence for it and where it came from travel together.
Files in a record
| File | Committed | What it holds |
|---|---|---|
record.md | Yes | The record itself: identity in the frontmatter, then a summary and a detail section. |
evidence/outcomes.jsonl | Yes | The append-only log of outcomes. Trust and status are worked out from it. |
provenance.json | Yes | Where the record came from: the run, the step, and how it was written. |
observations.jsonl | Yes | The structured evidence the record was distilled from. |
relations.json | Yes | Links to other records, such as supersedes or conflicts-with. |
manifest.json | Yes | Content hashes of every file, used to check the record has not been altered. |
evidence/evidence.md | Yes | The distilled observations, written out for people. |
evidence/gates.jsonl | Yes | Results of the checks the record passed, when it has any. |
evidence/measurements.json | Yes | The baseline for a numeric measurement. |
artifacts.index.json | Yes | A list of the screenshots and snapshots the record points to. |
artifacts/ | No | The screenshots and page snapshots themselves. |
An example
---
schemaVersion: 2
id: "fact-el-button-place-order-36-00-dd75ab371443d7b6"
kind: "fact"
subtype: "behavioral"
anchors: [{"raw":{"t":"el","role":"button","name":"place order · $36.00","ordinal":0},"normalized":{"t":"el","role":"button","name":"place order · $36.00","ordinal":0}},{"raw":{"t":"platform","platform":"web"},"normalized":{"t":"platform","platform":"web"}}]
scope: {"tier":"product","key":"komazon"}
createdAtOrdinal: 1
originClass: "agent-verified"
evidenceIncomplete: false
---
## Summary
button "place order · $36.00" resolved as a verified element
## Detail
Verified button "place order · $36.00" from the recorded screen state.Three runs later, its outcome log holds three confirmations:
{"buildOrdinal":1,"origin":"agent-verified","type":"confirmed", …}
{"buildOrdinal":3,"origin":"agent-verified","type":"confirmed", …}
{"buildOrdinal":5,"origin":"agent-verified","type":"confirmed", …}The frontmatter holds identity only. Trust, status and counters are never written into record.md; they are worked out from the log each time the record is read.
Kinds
| Kind | Meaning | Can become active |
|---|---|---|
fact | Something true about the app. Subtypes: selector, behavioral, navigational, measurement. | Yes |
caution | A known failure mode, learned from a test whose root cause was a timeout, a flaky failure or the environment. | Yes |
procedure | A flow that passed end to end, with typed parameters, stored as a replayable list of actions. | No, it is served by a separate matcher |
unknown | An open question, such as an anchor whose facts keep changing. Never served as a hint. | No |
policy | A QA rule held as a record. Accepting it appends the rule to your policies. | No |
Status
| Status | Meaning |
|---|---|
candidate | Recorded, not yet promoted. Every record starts here. |
active | Promoted. Served as a normal hint. |
superseded | Replaced by a newer record. Kept for history. |
deprecated | Retired, rejected or forgotten. Kept as a tombstone. |
Nothing is deleted when a record changes status. agent-qa does clean up long chains: it keeps the three most recent superseded generations of a record and removes older ones, never touching records that came from you. That cleanup shows up in git status.
Trust
Trust is a number between 0 and 1, worked out from the outcome log:
trust = (confirmed + ¼·helpful + α) / (confirmed + ¼·helpful + contradicted + ¼·harmful + α + β)The starting values α and β depend on where the record came from:
| Origin | α | β | Trust after one confirmation |
|---|---|---|---|
user: a person, through a mark or a review | 3 | 1 | 0.80 |
agent-verified: learned from a run | 2 | 1 | 0.75 |
A record that later runs stop confirming fades. After 5 runs without a confirmation (3 for measurements) its trust is multiplied by 0.6 when it is served, and the brief notes unconfirmed since build N.
Scope
A record's scope says where it applies: global, product, suite or test. In v0.2 everything agent-qa learns is scoped to the product of the run's target. A product is the target's product field, or the target name when it has none, and it also names the record's folder.
A run is served records from the global scope, its own product, the suite it runs in and the test itself. Sibling suites and tests never see each other's records.
Anchors
Anchors tie a record to something concrete in the app. The first anchor is the record's main anchor and part of its ID.
| Anchor | Points at |
|---|---|
page | A route or URL |
flow | A named flow, such as a test |
el | An element, by role, accessible name and position |
platform | web, android or ios, so web and mobile facts stay apart |
selector | A literal selector |
error | An error message |
Validity
Each record knows the run count at which it was created and, when replaced, the count at which it stopped being true. A run is served a record only inside that window, which is how agent-qa knowledge inspect --as-of-build <n> can show the store as it was.
Relations
relations.json links records: supersedes, superseded-by, derived-from, conflicts-with, relates-to, renamed-from, equivalent-to and proposed-supersession-of. The last one appears when a CI run proposes a replacement without applying it.
Outcome events
The outcome log uses a small, fixed vocabulary: confirmed, contradicted, helpful, harmful, promoted, superseded, deprecated, window-close, retracted and overturned. A rollback appends retracted events that cancel earlier ones, so the history is never rewritten.
IDs and addresses
- Record ID, such as
fact-el-button-place-order-36-00-dd75ab371443d7b6: the kind, a short slug of the main anchor, and a hash of the record's identity. Stable across machines, so use it in commits and conversations. - Short ID, such as
MEM-001: a handy address assigned the first time a record is listed or resolved on your machine. It is local and never reused.MEM-1works too. - URI, such as
agentqa://memory/MEM-001: the same address as an MCP resource.
npx agent-qa entities resolve "place order button" finds a record from free text, and npx agent-qa entities get MEM-001 shows its card.