claudiomaradonna/agent-foundry
claudiomaradonna/agent-foundry
Template
1
0
Fork 0
Code Issues Pull requests Activity

feat(memory): tighten LocalRecall contract and validator #2

Merged
claudiomaradonna merged 4 commits from feat/memory-contract-review into main 2026-09-30 19:31:04 +02:00
Conversation 0 Commits 4 Files changed 9 +261 -109
claudiomaradonna commented 2026-09-30 19:30:47 +02:00
Owner
Copy link

Why

A review of the memory profile rules and docs/LOCALRECALL.md found
problems that would cause wrong behavior once a workstation enables
localrecall-automatic:

  • Records went stale by commit ancestry, which breaks under the rebase
    and squash integration this repository prefers.
  • A normal revision-ordering conflict was reported as unavailable,
    which suspends memory until the operator reruns the preflight.
  • The validator checked only one line of each curator adapter.
  • Rules were repeated between AGENTS.md and the contract, and every
    session read the retrieval and completion-packet rules, even with
    memory disabled.

What changed

  • One home per rule. The Project memory section of AGENTS.md keeps
    only what every agent needs under every profile. Retrieval, staleness,
    the completion packet, triggers, and unavailability move to a new
    "Primary agents" section of the contract, which now serves every agent
    with memory enabled. Skills point at the contract.
  • Staleness by content. Record schema 4 stores Verified-Against as
    <path>@<object-hash>, so a record's freshness survives rebase and
    squash and can be checked without the verifying commit. Version-3
    records stay valid under the old rule.
  • superseded status. A newer revision of the stem reports
    superseded and suspends nothing. Verified-replace lists the stem
    again before deleting and stops if a concurrent writer appeared. The
    contract states the remaining last-writer-wins window; a conditional
    write in LocalRecall would close it.
  • Default memory triggers. The contract's good-candidate list is the
    default trigger list, plus the phrases "remember this" and "save to
    memory", so routine work sends no completion packet. A
    ## Memory triggers section in AGENTS.local.md replaces the default.
  • Preflight record. A new Memory preflight field in
    AGENTS.local.md holds the date of the last passing preflight. With
    memory enabled and no date, memory is unavailable.
  • preference records belong only in a global collection.
  • Validator checks:
  • an enabled profile requires a Memory operator;
  • the preflight date must be YYYY-MM-DD, and absent under profile
    none;
  • the Codex adapter must disable localrecall-reader and enable only
    localrecall-curator;
  • the Claude adapter's mcpServers must list only
    localrecall-curator;
  • Memory support: none rejects a leftover ## Project memory
    section.
  • Upgrade path. foundry-upgrade gains a migrati
    the preflight date.

Verification

  • bash tests/verify-agent-config.sh: all 81 tests pass. The 9 new
    cases include 8 that failed before the validator change.
  • bash scripts/verify-agent-config.sh: the source validates as
    state=template.
  • git diff --check: clean.
  • Not run: nothing ran against a live LocalRecall service, and nothing
    tested the new rules with a real agent.

Risks and follow-ups

  • Workstations with memory enabled stay unavailable until the operator
    reruns the preflight and records Memory preflight
  • Local selections with an enabled profile and no Memory operator now
    fail validation.
  • Follow-up: a conditional write in the LocalRecall MCP server fork, to
    close the concurrent-replace window.
## Why A review of the memory profile rules and `docs/LOCALRECALL.md` found problems that would cause wrong behavior once a workstation enables `localrecall-automatic`: - Records went stale by commit ancestry, which breaks under the rebase and squash integration this repository prefers. - A normal revision-ordering conflict was reported as `unavailable`, which suspends memory until the operator reruns the preflight. - The validator checked only one line of each curator adapter. - Rules were repeated between `AGENTS.md` and the contract, and every session read the retrieval and completion-packet rules, even with memory disabled. ## What changed - **One home per rule.** The Project memory section of `AGENTS.md` keeps only what every agent needs under every profile. Retrieval, staleness, the completion packet, triggers, and unavailability move to a new "Primary agents" section of the contract, which now serves every agent with memory enabled. Skills point at the contract. - **Staleness by content.** Record schema 4 stores `Verified-Against` as `<path>@<object-hash>`, so a record's freshness survives rebase and squash and can be checked without the verifying commit. Version-3 records stay valid under the old rule. - **`superseded` status.** A newer revision of the stem reports `superseded` and suspends nothing. Verified-replace lists the stem again before deleting and stops if a concurrent writer appeared. The contract states the remaining last-writer-wins window; a conditional write in LocalRecall would close it. - **Default memory triggers.** The contract's good-candidate list is the default trigger list, plus the phrases "remember this" and "save to memory", so routine work sends no completion packet. A `## Memory triggers` section in `AGENTS.local.md` replaces the default. - **Preflight record.** A new `Memory preflight` field in `AGENTS.local.md` holds the date of the last passing preflight. With memory enabled and no date, memory is unavailable. - **`preference` records** belong only in a global collection. - **Validator checks:** - an enabled profile requires a `Memory operator`; - the preflight date must be `YYYY-MM-DD`, and absent under profile `none`; - the Codex adapter must disable `localrecall-reader` and enable only `localrecall-curator`; - the Claude adapter's `mcpServers` must list only `localrecall-curator`; - `Memory support: none` rejects a leftover `## Project memory` section. - **Upgrade path.** `foundry-upgrade` gains a migrati the preflight date. ## Verification - `bash tests/verify-agent-config.sh`: all 81 tests pass. The 9 new cases include 8 that failed before the validator change. - `bash scripts/verify-agent-config.sh`: the source validates as `state=template`. - `git diff --check`: clean. - Not run: nothing ran against a live LocalRecall service, and nothing tested the new rules with a real agent. ## Risks and follow-ups - Workstations with memory enabled stay unavailable until the operator reruns the preflight and records `Memory preflight` - Local selections with an enabled profile and no `Memory operator` now fail validation. - Follow-up: a conditional write in the LocalRecall MCP server fork, to close the concurrent-replace window.
Move retrieval, staleness, the completion packet, memory triggers, and
unavailability from AGENTS.md into docs/LOCALRECALL.md, which now
serves every agent under an enabled profile. AGENTS.md keeps the
selection, the trust rule, and the primary-agent tool boundary, so
sessions with profile none stop reading rules that never apply to them.
Skills point at the contract instead of the moved section.
Records move to schema 4, whose Verified-Against lists repository
paths with their object hashes, so staleness survives the rebase and
squash integration this repository prefers; version-3 records keep the
ancestry rule. A newer revision of the stem now reports superseded,
which suspends nothing, instead of unavailable, and verified-replace
re-lists the stem before deleting to catch a concurrent writer.

The good-candidate list becomes the default memory triggers, so routine
work sends no completion packet. Preference records live only in a
global collection, and a Memory preflight date in AGENTS.local.md
records the last passing preflight; without it memory is unavailable.
An enabled profile now needs a Memory operator, and a Memory preflight
date in AGENTS.local.md must be YYYY-MM-DD, absent under profile none.
The Codex curator adapter must disable localrecall-reader and enable
only localrecall-curator, the Claude adapter's mcpServers must list only
localrecall-curator, and Memory support none rejects a leftover Project
memory section in AGENTS.md.
claudiomaradonna deleted branch feat/memory-contract-review 2026-09-30 19:31:07 +02:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
claudiomaradonna/agent-foundry!2
No description provided.