Read, correct and verify memory

Compatibility and authority

Use the tools advertised by the intended Mind connection. This procedure describes the released memory tools; a connector may narrow their inputs. The connected principal needs read and propose access to the relevant area. It does not gain approval authority from this page.

Discover and read

1. Call orient with {}. Verify the intended Mind and principal.
2. Follow the relevant first_reads map with read.
3. If needed, call list_files with {"dir":"<authorised folder>"}. The field is dir.
4. Read the current record. Follow its sources and any superseding record before stating what applies now.

Example input to read:

{"path":"<authorised folder>/decision.md"}

Angle-bracket values are placeholders to replace after discovery. Never infer the contents of a missing or denied record.

Prepare one change

Read the entire current record before replacing it. Preserve unrelated wording and required metadata. For an ordinary record, an edit can target a section. A whole-file replacement that does not supply the record's current base is always held for review ("replacement base missing"), and a read of an ordinary note does not return a revision to use as that base. Memory lifecycle entries require the revision/base contract supplied by their read.

The compatibility form below was exercised through the hosted connector. It replaces one ordinary record without a base, so expect it to be held for review rather than saved straight away. Replace both placeholders with the actual authorised path and the complete proposed text.

{
  "changes": [
    {
      "path": "<authorised folder>/decision.md",
      "content": "<complete corrected record, preserving required metadata>"
    }
  ]
}

Submit that object to check_write first. A passing dry run is not a write and does not reserve the state. Its result includes would_hold and hold_reason, which tell you whether the write will be held and why; for the form above it typically reports a hold because the replacement base is missing. With the user's authority, submit the same object once to propose_write, adding a concise rationale explaining the source for the correction.

To correct one passage in a way that can be saved under the Mind's rules, use a typed edit change instead of replacing the whole file. It names the section by its heading in anchor and replaces that section's body, keeping the heading. Check it with check_write the same way.

{
  "changes": [
    {
      "path": "<authorised folder>/decision.md",
      "op": "edit",
      "anchor": "<heading of the section to correct>",
      "mode": "replace_section",
      "content": "<corrected text for that section>"
    }
  ]
}

If the connector advertises typed op changes, use its actual schema. A client validation error before dispatch is different from a service denial or an uncertain submitted write. Do not silently change a submitted request to evade a gate.

Interpret and verify

1. Require ok: true; retain the returned proposal_id.
2. For status: "held", report pending review. The proposed text has not landed.
3. For status: "applied", read the source again and verify the intended change.
4. For a held proposal, inspect it with get_proposal {"proposal_id":"<returned id>"}. An authorised reviewer checks the exact diff and uses the supported review surface.
5. After approval, read the source again. Report the readback separately from approval.

An ordinary review card can use act with action: "queue.answer", the card's card_id as item_id, and answer as the JSON string {"decision":"approve"}. propose_write returns only the proposal id, branch, status and files; the card_id comes from get_proposal or list_review_queue. act is an administrative tool, so only an owner, an admin or someone holding approval authority for the area can use it. This is only for an authorised review. Human approval requests have a separate exact confirmation/content-hash contract; never fabricate that confirmation.

Recovery and cleanup

After interruption, inspect the original proposal and current source before another submission. On a conflict, reread and reconcile. On denial, stop with the missing access and authorised handoff. A rejected proposal is not an applied correction.

Remove only disposable test records, through the supported authorised deletion/review path. Keep the evidence needed to explain any held cleanup.

Verification boundary

The hosted connector completed a synthetic correction through held review, approval and source readback on a development build. That test did not cover every coding client or every installation, so check the result with your own client.

Related

Correct saved information in your Mind · Agent interface reference