Skip to content

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

docs(memory): document the memory block in the system prompt

Steven Enamakel9372271f18c1
diff --git a/crates/openhuman-core/src/agent/session_host/README.md b/crates/openhuman-core/src/agent/session_host/README.md
index 7727b6088a..3c1bade16e 100644
--- a/crates/openhuman-core/src/agent/session_host/README.md
+++ b/crates/openhuman-core/src/agent/session_host/README.md
@@ -59,6 +59,22 @@ the live state it renders changes, but never from integrations the session has
not read yet. A prompt that fails to render, or a recorded prompt of unknown
extent, keeps the recorded prompt. The recorded tool list is unaffected.
+An agent whose definition sets `memory_block` ends its system prompt with
+what long-term memory knows about the user, a `<memory>` … `</memory>`
+system message after every static prompt byte
+(`runtime_session/memory_block.rs`). The block belongs to the frozen prefix,
+so it is rendered only when a transcript generation starts: a new thread, a
+resumed thread recorded without one, a turn whose prefix changes anyway (a
+replaced prompt, a changed permanent-tool catalogue), and the first turn of a
+generation that carried its parent's block over unchanged (an in-turn or
+out-of-band compaction). Every other turn re-sends the recorded block
+verbatim. The block is excluded from the "did the prompt change" comparison
+like the catalogue, so a memory change alone never seals a generation or adds
+the note. Code that opens a generation outside a turn can put a fresh block
+into the successor's prefix with
+`OpenHumanSessionHost::memory_block_for_new_generation` and
+`memory_block::with_memory_block`; without it the next turn renders one.
+
Compaction never erases history. It seals the current generation and opens
the next one, recording the sealed generation as the new one's parent; the
sealed file stays on disk. TinyAgents owns the generation chain and its
diff --git a/crates/openhuman-core/src/memory/README.md b/crates/openhuman-core/src/memory/README.md
index 84dadc5c76..4891cf34aa 100644
--- a/crates/openhuman-core/src/memory/README.md
+++ b/crates/openhuman-core/src/memory/README.md
@@ -194,7 +194,9 @@ module to forget only that channel's conversations. With
in `lifecycle::date_hint` for one small model call to work out which days the
user means; a late or bad answer just leaves the pack in its normal order.
The web chat citation sink records citations only when a cached pack is
-returned to the turn and drained for the chat's memory chips.
+returned to the turn and drained for the chat's memory chips. An agent with a
+`memory_block` also gets beliefs then learnings rendered into its system
+prompt by [`lifecycle/memory_block.rs`](./lifecycle/memory_block.rs), only when a transcript generation starts.
### Background work
@@ -314,6 +316,7 @@ trusted call facts; queued writes retain that call's narrower reach.
| [`lifecycle/hooks.rs`](./lifecycle/hooks.rs) | Lifecycle operations and bounded manual wrappers; `TurnPack`, `MemoryTurn`. |
| [`lifecycle/prefetch.rs`](./lifecycle/prefetch.rs) | Host adapter over `tinymemory_tools::prefetch::Prefetcher`: the key (workspace, config fingerprint, identity, thread), the per-context cache registry, the tokio runtime port and the turn-pack work. |
| [`lifecycle/jobs.rs`](./lifecycle/jobs.rs) | Host adapter over `tinymemory_tools::queue::JobQueue`: a file `QueueStore` over `memory/jobs.json`, one queue per workspace, the engine and build delay, and the `memory_background` cron run. |
+| [`lifecycle/memory_block.rs`](./lifecycle/memory_block.rs) | Reads beliefs then learnings for an identity and renders the system prompt's `<memory>` block within a token budget. |
| [`lifecycle/views.rs`](./lifecycle/views.rs) | Policy get/set, pack preview, agents list, jobs list/run for the UI. |
| [`lifecycle/sender.rs`](./lifecycle/sender.rs) | Maps a channel message's sender to an observed actor. |
| [`lifecycle/date_hint.rs`](./lifecycle/date_hint.rs) | Optional model call that works out which days a turn refers to. |
diff --git a/crates/openhuman-embed/src/agent/README.md b/crates/openhuman-embed/src/agent/README.md
index 659b680915..2df6a740f2 100644
--- a/crates/openhuman-embed/src/agent/README.md
+++ b/crates/openhuman-embed/src/agent/README.md
@@ -89,6 +89,14 @@ directories; transcripts and memory persist with the workspace.
`tools(ToolScopeSpec::Named(..))` or `disallow_tools`. Also sets
`sandbox` (`None`, `ReadOnly`, `Sandboxed`), `max_iterations`,
`temperature`, `display_name` and `when_to_use`.
+ `memory_block(MemoryBlockSpec { max_tokens })` ends the system prompt with
+ what the agent's memory binding knows about the user (beliefs, then
+ learnings, between `<memory>` and `</memory>`). It is rendered only when a
+ transcript generation starts (a new thread, a resumed thread without one, a
+ replaced prompt, the first turn after a compaction) and re-sent byte for
+ byte on every other turn, so a memory change never costs the prefix cache
+ or adds the prompt-update note. Empty memory sends no block; a read error
+ sends the recorded one, or none.
- `MemoryBinding` (`spec.rs`): the memory agent id the turns are logged
under, optionally a layout root such as `team:acme`, and optionally
`recall_each_turn(timeout)`: recall for the current message on every turn,