Add dedicated memory v2 consolidation and read prompts (#43813)

## What changed

- Consolidate v2 rollout summaries into `memory_summary.md` without generating `raw_memories.md` or requiring `MEMORY.md`. Validate the summary's required sections and size below 10,000 UTF-8 bytes.
- Add v2 read instructions for selective history retrieval, evidence-grounded preferences, citations, and explicit memory edits. Split injected instructions into fragments to preserve the complete summary within fragment byte limits.
- Record memory citation usage in the store selected by `memories.version`.

## Testing

Add coverage for v2 consolidation without a handbook, summary validation, version-isolated memory reads, and resetting both memory versions while preserving threads.

GitOrigin-RevId: 1d895fb4a23a973f1a45ba03be07a1f480c10227
This commit is contained in:
jif authored and copyberry committed 2026-09-08 12:58:11 +00:00
1 parent e7f5de0a6a
commit 553df1c691
14 files changed
+487 -86

No files matched your search

+26 -3
View File
@@ -1,6 +1,8 @@
use std::sync::Arc;
use codex_core::config::Config;
use codex_core::context::ContextualUserFragment;
use codex_core::context::MemoryContextFragment;
use codex_extension_api::ConfigContributor;
use codex_extension_api::ContentItemKind;
use codex_extension_api::ContextContributor;
@@ -65,15 +67,36 @@ impl ContextContributor for MemoriesExtension {
return Vec::new();
}
build_memory_tool_developer_instructions(&config.codex_home, config.version)
.await
let Some(instructions) =
build_memory_tool_developer_instructions(&config.codex_home, config.version).await
else {
return Vec::new();
};
let instructions = match config.version {
MemoryVersion::V1 => vec![instructions],
MemoryVersion::V2 => {
// Keep the complete summary while respecting each fragment's byte cap.
let mut remaining = instructions.as_str();
let mut fragments = Vec::new();
while !remaining.is_empty() {
let end = remaining.floor_char_boundary(remaining.len().min(8_900));
fragments.push(
MemoryContextFragment::ReadInstructions(remaining[..end].to_string())
.render(),
);
remaining = &remaining[end..];
}
fragments
}
};
instructions
.into_iter()
.map(|instructions| {
PromptFragment::developer_policy(
instructions,
ContentItemKind("memories.instructions".to_string()),
)
})
.into_iter()
.collect()
})
}
+12 -1
View File
@@ -14,6 +14,13 @@ static MEMORY_TOOL_DEVELOPER_INSTRUCTIONS_TEMPLATE: LazyLock<Template> = LazyLoc
)
});
static MEMORY_V2_TEMPLATE: LazyLock<Template> = LazyLock::new(|| {
parse_embedded_template(
include_str!("../templates/memories/read_path_v2.md"),
"memories/read_path_v2.md",
)
});
fn parse_embedded_template(source: &'static str, template_name: &str) -> Template {
match Template::parse(source) {
Ok(template) => template,
@@ -44,7 +51,11 @@ pub(crate) async fn build_memory_tool_developer_instructions(
return None;
}
let base_path = base_path.display().to_string();
MEMORY_TOOL_DEVELOPER_INSTRUCTIONS_TEMPLATE
let template = match version {
MemoryVersion::V1 => &MEMORY_TOOL_DEVELOPER_INSTRUCTIONS_TEMPLATE,
MemoryVersion::V2 => &MEMORY_V2_TEMPLATE,
};
template
.render([
("base_path", base_path.as_str()),
("memory_summary", memory_summary.as_str()),
@@ -33,3 +33,34 @@ async fn build_memory_tool_developer_instructions_renders_embedded_template() {
1
);
}
#[tokio::test]
async fn v2_reads_only_its_own_summary_without_falling_back_to_v1()
-> Result<(), Box<dyn std::error::Error>> {
let home = tempdir()?;
let codex_home = AbsolutePathBuf::from_absolute_path(home.path())?;
let v1 = codex_home.join("memories");
let v2 = codex_home.join("memories_v2");
tokio_fs::create_dir_all(&v1).await?;
tokio_fs::write(v1.join("memory_summary.md"), "v1\nlegacy content").await?;
assert_eq!(
build_memory_tool_developer_instructions(&codex_home, MemoryVersion::V2).await,
None
);
tokio_fs::create_dir_all(&v2).await?;
tokio_fs::write(v2.join("memory_summary.md"), "v1\nnew pipeline content").await?;
let instructions = build_memory_tool_developer_instructions(&codex_home, MemoryVersion::V2)
.await
.expect("v2 instructions");
assert!(instructions.contains("new pipeline content"));
assert!(!instructions.contains("legacy content"));
assert!(instructions.contains("do not retrieve history speculatively"));
assert!(instructions.contains(&format!("{}/rollout_summaries/", v2.display())));
assert!(
build_memory_tool_developer_instructions(&codex_home, MemoryVersion::V1)
.await
.expect("v1 instructions")
.contains("legacy content")
);
Ok(())
}
@@ -0,0 +1,44 @@
## Memory
Use the injected MEMORY_SUMMARY as historical context: apply the user's actual
preferences, corrections, decisions, and supported task scope. Its exact
rollout, source, pull-request, discussion, and document pointers can guide
independently useful work without an extra lookup merely to rediscover them.
Read a matching rollout under `{{ base_path }}/rollout_summaries/` when its
additional evidence, wording, chronology, or uncertainty could change your
answer; otherwise do not retrieve history speculatively. Search selectively
when a genuinely needed route is missing.
Memory is not proof of current behavior. For consequential or changeable
claims, use judgment about drift, verification cost, and harm; inspect the
actual owning source when warranted and acknowledge material uncertainty.
Batch independent useful lookups. Follow current instructions, cite only
memory actually used, never in pull requests, and update memory only when the
user explicitly asks. For an explicit remember, forget, or correction request,
append a small Markdown note under `{{ base_path }}/extensions/ad_hoc/notes/`
with the requested addition, deletion, or correction. Do not edit generated
memory files directly; consolidation applies these notes.
Memory citations:
When a read rollout summary informs the answer, append one citation block at
the end of the final reply, outside code fences. Do not cite `memory_summary.md`.
<oai-mem-citation>
<citation_entries>
rollout_summaries/example.md:8-10|note=[used prior context]
</citation_entries>
<rollout_ids>
019c6e27-e55b-73d1-87d8-4e01f1f75043
</rollout_ids>
</oai-mem-citation>
Use actual source paths relative to `{{ base_path }}` and line ranges from the
search or read, with one entry per line and short single-line notes. Include
unique relevant rollout UUIDs already available; leave `rollout_ids` empty if
none are available. Do not reread files or make extra tool calls solely to
construct or check citations or obtain rollout IDs.
========= MEMORY_SUMMARY BEGINS =========
{{ memory_summary }}
========= MEMORY_SUMMARY ENDS =========