Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

feat(memory): add deadline-bounded recall of the current message

Steven Enamakel5faf2a539937
diff --git a/crates/openhuman-core/src/memory/README.md b/crates/openhuman-core/src/memory/README.md
index de5d7667f9..84dadc5c76 100644
--- a/crates/openhuman-core/src/memory/README.md
+++ b/crates/openhuman-core/src/memory/README.md
@@ -166,6 +166,19 @@ preserving queued logs; engine/credential invalidation also clears pending
refreshes. Scoped spawns retain the caller's core context; the key carries the
resolved identity, so queued work needs nothing ambient.
+A host can ask for recall of the **current** message instead
+(`[memory] recall_each_turn_ms`, set by embed's `MemoryBinding::recall_each_turn`).
+`pre_turn` then queues the same work, and waits at most that long for its
+pack while the rest of turn setup runs (the session host joins the two). In
+time, the pack reaches `MemoryPackMiddleware` like any other and its
+citations are recorded; late, missing or skipped, the turn gets no note
+(`[memory:recall] deadline` at debug for a timeout, warn for work that ended
+without an answer) and the work still finishes into the cache.
+`RecallEachTurn::excluding` is the seam for de-duplicating against memory a
+host already puts in the system prompt: a pack whose every cited hit it
+excludes is left out (TinyMemory renders the pack, so single lines cannot be
+dropped yet).
+
The live prelude and compaction summarizer call the underlying work directly
from the scoped prefetch workers. Their background deadlines bound engine I/O
without a second manual timeout wrapper.
@@ -334,8 +347,8 @@ trusted call facts; queued writes retain that call's narrower reach.
`scope::identity_pins` (`scope.rs`): derive and resolve the acting identity
a turn's run context carries.
- `lifecycle::prefetch::pre_turn` and `compaction`
- (`lifecycle/prefetch.rs`): synchronous reads of completed packs plus scoped
- background refresh. `lifecycle::hooks` contains the underlying operations;
+ (`lifecycle/prefetch.rs`): reads of completed packs plus scoped background
+ refresh, or a deadline-bounded wait for the current message's pack. `lifecycle::hooks` contains the underlying operations;
`post_turn` is spawned after durable commit.
- `lifecycle::jobs::enqueue` and `run_due` (`lifecycle/jobs.rs`): the
background queue.
diff --git a/crates/openhuman-core/src/memory/lifecycle/mod.rs b/crates/openhuman-core/src/memory/lifecycle/mod.rs
index 7b45772227..702ebf880f 100644
--- a/crates/openhuman-core/src/memory/lifecycle/mod.rs
+++ b/crates/openhuman-core/src/memory/lifecycle/mod.rs
@@ -7,13 +7,14 @@
//!
//! | Hook | When | Call |
//! | --- | --- | --- |
-//! | [`prefetch`] | before the model runs, once per turn | takes completed cached memory and queues user logging and refresh |
+//! | [`prefetch`] | before the model runs, once per turn | takes completed cached memory and queues user logging and refresh; with `[memory] recall_each_turn_ms`, waits that long for the current message's pack instead |
//! | [`hooks::post_turn`] | after the turn is committed | logs the reply and queues the belief builds it hands back |
//! | [`prefetch`] | when the transcript is compacted | enriches from completed memory and queues recall of the folded span |
//! | [`jobs`] | the `memory_background` cron job | runs queued belief builds and deferred ingests |
//!
-//! Automatic hooks never await engine I/O; an engine outage degrades memory
-//! without blocking the live agent.
+//! Automatic hooks never await engine I/O beyond a deadline the host chose: by
+//! default not at all, with `recall_each_turn_ms` at most that long. An engine
+//! outage degrades memory without blocking the live agent.
pub mod date_hint;
pub mod hooks;
diff --git a/crates/openhuman-core/src/memory/lifecycle/prefetch.rs b/crates/openhuman-core/src/memory/lifecycle/prefetch.rs
index 2417ae2b47..fa370aeeb4 100644
--- a/crates/openhuman-core/src/memory/lifecycle/prefetch.rs
+++ b/crates/openhuman-core/src/memory/lifecycle/prefetch.rs
@@ -1,5 +1,8 @@
-//! Best-effort, scoped automatic memory refresh. Turns only read completed
-//! packs; all engine work and date extraction run in bounded background workers.
+//! Best-effort, scoped automatic memory refresh. By default turns only read
+//! completed packs; a host that sets `[memory] recall_each_turn_ms` has each
+//! turn wait up to that long for the pack recalled for its own message
+//! ([`RecallEachTurn`]). All engine work and date extraction run in bounded
+//! background workers either way.
//! Packs live in memory for one minute and are never persisted by this adapter.
use std::hash::{Hash, Hasher};