Explicit, auditable promotion of operator feedback into Memories

[markgerrard]

Summary

Please expose and document an explicit, user-directed way to promote durable operator feedback into Codex Memories, with scoped upsert/deduplication, provenance, and a visible write receipt.

The public Memories documentation describes background extraction and consolidation from eligible prior chats. That is useful for passive recall, but repeated operational corrections benefit from an intentional path such as:

“Remember this globally: long-running jobs must use event-driven completion rather than foreground polling.”

This should create or update one inspectable memory entry immediately, rather than relying on eventual background extraction or encouraging users to put personal operational preferences into every repository's AGENTS.md.

Motivation

There is a useful middle layer between:

• a one-turn instruction, and
• mandatory repository policy in AGENTS.md.

Examples include personal review style, preferred wait/monitoring behavior, recurring recovery procedures, and corrections to mistakes that occur across repositories.

In a real multi-agent workflow, explicit promotion produced two useful outcomes:

1. A repeated correction about foreground polling was saved as a global operator preference. A later clarification expanded the same entry to ordinary multi-seat panels rather than creating another overlapping memory.
2. A failed sandboxed-agent run was distilled into a reusable recovery entry: keep evidence inside the sandbox the agent actually runs in, distinguish human-facing display labels from machine routing identifiers, preserve failed-run provenance, and require the normal review gates before reuse.

The value was not specific to the multi-agent framework. The general pattern was:

observed repeated failure → explicit user request to remember → dedupe/upsert → receipt → later application.

This reduced repeated prompting and made the stored rule inspectable.

Proposed behavior

Provide a supported explicit memory-promotion surface for local Codex clients, usable from natural language and/or a documented command/tool:

• Save: create a durable entry only when the user explicitly asks, or when Codex proposes a write and the user confirms.
• Update/upsert: check for an overlapping entry first and update it instead of creating duplicates.
• Forget: remove an obsolete or incorrect entry intentionally.
• Scope: at minimum distinguish global/user scope from project scope.
• Type: optionally distinguish user preference/feedback, project context, and reference material.
• Provenance: record origin thread/session, timestamp, reason for promotion, and last update.
• Receipt: report whether the operation created, updated, or deduplicated an entry and show its stable name/identifier — e.g. updated user/operational-preferences/event-driven-completion (created=false).
• Inspection: make promoted entries visible through the existing memory-management surface.
• Precedence: explicit current instructions and applicable AGENTS.md guidance continue to override memories.

A model-callable interface could be conceptually equivalent to:

memory_save(name, scope, type, description, content)
memory_forget(name, scope)

The precise API is less important than the guarantees: intentional writes, inspectability, dedupe, provenance, and clear precedence.

Safety constraints

• Never store secrets or credentials.
• Do not silently promote transient task state.
• Do not treat memories as mandatory team policy or a replacement for AGENTS.md.
• Make global writes harder than project-local writes where appropriate.
• Honor per-chat and global memory controls.
• Preserve the existing ability to exclude chats that used external context from automatic memory generation.
• Explicitly identify conflicts with current instructions rather than resolving them invisibly.

Non-goals

• Importing the multi-agent framework that motivated the example.
• Automatically turning every correction into permanent policy.
• Replacing repository documentation, skills, hooks, or enforcement.
• Sharing personal memories across users or organizations.

Prior art in this tracker

I searched existing Memories issues before filing. The closest are #30299 (official CLI commands to inspect, prune, delete, and scope existing memories — a management surface for entries that already exist), #29430 (synchronously generating memories for a specific session — still extraction from a transcript, not user-authored content), and #26684 (dedupe/concurrency defects in background consolidation — which explicit upsert semantics would sidestep for intentional entries). None of them proposes an explicit, user-directed save/update/forget path with a write receipt; this issue is complementary to #30299 rather than overlapping it.

Why an issue rather than a PR

The Memories subsystem is active roadmap territory and external contributions are invitation-only. I am opening this proposal first, as requested by the contribution guide, to establish whether this interaction model aligns with the intended architecture.

Questions

1. Is an explicit save/update/forget path already planned for local Memories?
2. Should explicit promoted entries share the generated-memory store, or occupy a separately identified operator-authored layer?
3. Would a small UX/API proposal with acceptance tests be useful before any implementation work?

[hjqcan]

One boundary I would make explicit in this design: a candidate learning is not yet durable memory. If operator-authored entries and background-generated entries land in one undifferentiated store, the receipt can say “saved” while still losing the authority distinction this feature is meant to create.

A minimal lifecycle could be:

candidate -> classified -> accepted/rejected -> active -> revised/retired

For an explicit operator write, the receipt should probably include at least:

• outcome: created / updated / deduplicated / rejected
• stable memoryId and scope
• origin: operator-authored / reflected / imported
• supersedes or the overlapping entry that was updated
• a content hash or revision so later edits are auditable
• the policy/reason that admitted or rejected the write

Then retrieval should preserve the same distinction. A trace that only says “memory X matched” is less useful than one that also says which authority tier it came from, why it was eligible in this scope, and whether a newer instruction overrode it.

As a third-party reference implementation, GoodMemory uses a local-first governed remember path plus inspect/revise/forget surfaces. Its standalone MCP starts read-only and only registers the write tool when the user explicitly enables --allow-write; the standalone setup guide shows that boundary. It is not a substitute for a native Codex API, but it has been useful for testing the receipt/provenance/scope shape before baking it into a host.

I agree that explicit current instructions and AGENTS.md should stay above every memory tier; otherwise “remember this” silently becomes a second policy system.