---
title: Behavioral Memory Schema
description: Read and review the markdown observation files that back agent-qa behavioral memory.
---



Behavioral Memory is the reader-facing name for the observation files agent-qa stores on disk. Each observation is one markdown file named after its observation ID.

The file has YAML frontmatter for metadata, followed by markdown body text for the observation itself.

## File path [#file-path]

Observation files are stored under one of three tiers:

```txt
agent-qa-memory/products/<product>/obs_aster-bloom-cloud-drift-ember-field-glade-hollow-ivory-jasper.md
agent-qa-memory/suites/<suite-id>/obs_aster-bloom-cloud-drift-ember-field-glade-hollow-ivory-jasper.md
agent-qa-memory/tests/<test-id>/obs_aster-bloom-cloud-drift-ember-field-glade-hollow-ivory-jasper.md
```

The file name and frontmatter `id` must match.

## Base fields [#base-fields]

Every observation includes these fields:

* `id`: observation ID that starts with `obs_`.
* `title`: short summary used in search and injected context.
* `trust`: number from `0` to `1`.
* `created`: ISO datetime for when the observation was created.
* `last_confirmed`: ISO datetime for the latest confirmation or update.
* `confirmed_count`: number of times evidence confirmed the observation.
* `contradicted_count`: number of times evidence contradicted the observation.
* `source_test`: test ID or source name that produced the observation.

The markdown body is the observation content. Keep the body concise, factual, and safe to inject as context.

## Suite fields [#suite-fields]

Suite observations add:

* `position`: zero-based index of the child test in the suite.
* `suite_snapshot`: ordered list of suite entries, each with `test` and `id`.

The snapshot prevents a suite memory from being reused after the suite membership or order changes.

## Sample memory file [#sample-memory-file]

```md
---
id: obs_aster-bloom-cloud-drift-ember-field-glade-hollow-ivory-jasper
title: Hacker News first story title appears in the first row
trust: 0.55
created: "2026-05-14T12:00:00.000Z"
last_confirmed: "2026-05-14T12:10:00.000Z"
confirmed_count: 1
contradicted_count: 0
source_test: t_quad-adar-micro-magic-cross-cue-open-agog-rang-cours
position: 0
suite_snapshot:
  - test: tests/hacker-news-top-story.yaml
    id: t_quad-adar-micro-magic-cross-cue-open-agog-rang-cours
---
On the Hacker News homepage, the title returned as the first item from the Firebase topstories API appears in the first story row.
```

The sample includes suite fields because it represents a suite-position observation. Product and test observations use the same base fields without `position` or `suite_snapshot`.

## Validation rules [#validation-rules]

The parser requires frontmatter delimiters and a non-empty markdown body. If the frontmatter ID does not match the file name, the observation is ignored.

The body text is intentionally outside the frontmatter so long observations stay readable in markdown review.