Memory and retrospective decisions¶
The harness keeps governed memory: records that a later run may receive as context, each with its provenance, validity and approval. Nothing enters a context because it was written once; a record enters when it is in scope, in force and, for the levels that carry authority, approved by a person. Every run stores a context manifest with the records it applied and the candidates it left out, so the memory behind a run can be audited afterwards.
This guide shows the commands with the output of a real session
(python scripts/demo_flows.py memory, checked in CI).
Levels¶
| Level | Holds | Enters a context when |
|---|---|---|
NORMATIVE |
Stable rules of the way of working | approved and in force |
PROJECT |
Knowledge and conventions of the repository | approved and in force |
TASK |
Notes of one task | the run belongs to that task |
EPHEMERAL |
Notes of one run | the run is that run |
RETROSPECTIVE |
Decided retrospective recommendations | accepted or edited by a person |
A record also declares who recorded it (provenance.actor), an optional validUntil, the record
it supersedes and whether it is sensitive.
Record, approve, invalidate¶
A proposal is recorded but stays out of every context until someone approves it:
harness memory add --level project --key money.rounding \
--value "Round money half up to two places." --actor human.author # exit 0
harness memory approve --memory mem_a0c4…84b4 --actor human.lead # exit 0
harness memory approve --memory mem_fecb…dff3 # exit 5: already approved
Approval and invalidation never edit a record. Each creates a new record that supersedes the previous one and carries the acting person, so the proposal, its approver and the reason of an invalidation all stay on record:
harness memory invalidate --memory mem_fecb…dff3 \
--reason "Rounding moved to the billing service." --actor human.lead # exit 0
harness memory list
memory list shows every record with its status for the given --task and --run:
| Status | Meaning |
|---|---|
active |
Enters the context |
superseded |
Replaced by a record that carries authority (supersededBy) |
expired |
validUntil is in the past |
unapproved |
A normative, project or retrospective record nobody approved |
limit |
Beyond the maximum number of records of a context |
out_of_scope |
A task or run record of another task or run |
An unapproved record never supersedes an approved one. --value takes a JSON object or plain
text (stored as {"text": …}); --sensitive withholds the value from the manifest and from the
agent; --approve records the entry as approved by the acting person. A TASK record needs
--task and an EPHEMERAL one needs --run (exit 2 otherwise); an unknown record is exit 3.
What a run applied¶
The manifest is built in PLANNING, stored as an artifact and referenced by the agent invocation
(contextManifestRef). harness memory manifest --run <run> prints it:
{
"executionId": "run_413a76005c1847fb983a53682d6c7d66",
"manifestRef": "artifact://sha256/4c7495165f9b79dd6e21fc73114d1bbba47aa128f91aa0d8f4b043e8311b0fb1",
"digest": "sha256:f9574120c7ff76dbc255165f1f12ccc051558b72beb93f3c8af01d38ec4749f3",
"records": [
{"memoryId": "mem_fecb…dff3", "level": "PROJECT", "key": "money.rounding",
"value": {"text": "Round money half up to two places."}, "provenance": {"…": "human.lead"}},
{"memoryId": "mem_a1f0…7531", "level": "RETROSPECTIVE",
"key": "recommendation/recommendation_b382…6b09", "value": {"decision": "ACCEPT", "…": "…"}}
],
"excluded": [
{"memoryId": "mem_baa8…3457", "level": "NORMATIVE", "key": "release.freeze", "reason": "expired"},
{"memoryId": "mem_a0c4…84b4", "level": "PROJECT", "key": "money.rounding",
"reason": "superseded", "supersededBy": "mem_fecb…dff3"}
]
}
The digest covers the applied records. The manifest is a record of the run: approving or
invalidating memory later does not change what a past run reports. Command agent providers receive
the applied records under context (see connecting an external agent); a
run without memory sends no context key.
Deciding a retrospective recommendation¶
Closing a run produces a retrospective with recommendations that require human review. A person decides each one:
harness recommendation list --run run_80dd…8c2f
harness recommendation decide --run run_80dd…8c2f --recommendation recommendation_b382…6b09 \
--decision ACCEPT --actor human.lead \
--rationale "No findings in this run; keep the controls as they are." # exit 0
harness recommendation decide … --decision REJECT --rationale "…" # exit 5: already decided
| Decision | Effect |
|---|---|
ACCEPT |
Stored as approved retrospective memory; enters the context of later runs |
EDIT |
Same, with the text given in --statement; the original text is kept |
REJECT |
Stored as history, expired and unapproved; never enters a context |
A recommendation takes one decision. The harness applies nothing else: rules, gates and
configuration change only through a versioned change made by a person, and
retrospectiveAutoApply is a locked false policy.
Limits¶
- Memory is local to the project state (
.harness/state.db); there is no sharing between repositories. - Selection is deterministic (level, key, creation time), not semantic: the harness does not rank records by relevance to the task.
- The simulated provider records the manifest but does not read the records; an agent sees them
only through a command provider that uses
context. - Actors are recorded, not authenticated.