Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/memory-evaluator-marks-read-by-id.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@flow-state-dev/memory": patch
Comment thread
jhoffner marked this conversation as resolved.
Resolved
---

Capture with an `evaluator` now marks read exactly the messages it judged, by id, in a new `readMessages` field on the `memorySystem` state (`MemorySystemState`). It used to move a positional watermark, so when two turns of one session overlapped, a late `skip` could mark read a turn whose evaluator call had failed, and that turn was never observed. Sessions captured before keep working: the first capture with an evaluator carries over what the watermark already covered. Without an evaluator, capture is unchanged (FIX-1555, BR-6).
Comment thread
jhoffner marked this conversation as resolved.
Resolved
123 changes: 98 additions & 25 deletions packages/memory/src/memory-system-blocks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ import {
import type { Edge } from '@flow-state-dev/core/graph'
import type { ResolvedRelationsConfig } from './internal/config'
import { memorySystemResource, DEFAULT_CONSOLIDATION_CONFIG, DEFAULT_PRUNE_CONFIG } from './memory-system'
import type { MemorySystemState } from './memory-system'
import { findBestOverlap } from '@flow-state-dev/core/helpers'
import { canonicalizeSubject, edgesOf } from './internal/helpers'
import { createDigestMemoryResource } from './digest-memory'
Expand Down Expand Up @@ -481,8 +482,13 @@ export function buildObserveContext(
const newMessages = allItems.filter(
(item, idx) => idx > lastProcessedIndex && item.type === 'message',
)
if (newMessages.length === 0) return undefined
return newMessages
return formatMessages(newMessages)
}

/** `[role] text` per message, one per line; `undefined` when there are none. */
function formatMessages(messages: ReadonlyArray<Record<string, any>>): string | undefined {
Comment thread
jhoffner marked this conversation as resolved.
Resolved
if (messages.length === 0) return undefined
return messages
.map((item) => {
const label = item.role ?? item.type ?? 'unknown'
const text = typeof item.payload === 'string'
Expand All @@ -505,14 +511,71 @@ function watermarkPast(allItems: ReadonlyArray<unknown>, current: number): numbe
return allItems.length > 0 ? allItems.length - 1 : current
}

/** One judged session message, as `readMessages` keeps it. */
type ReadMessage = { id: string; ts: number }

/**
* The session messages capture with an evaluator has yet to judge.
*
* Once such a capture has marked messages read, a message is unread while its
* id is missing from `readMessages`, wherever it sits in the log. The
* watermark can't say that: it is a position, and a turn that overlaps
* another lands in the log among that turn's items, not after them. Until
* then (`readMessages` is null), the watermark decides, as it does without an
* evaluator.
*/
function unreadMessages(
allItems: ReadonlyArray<Record<string, any>>,
state: MemorySystemState,
): Array<Record<string, any>> {
if (state.readMessages == null) {
Comment thread
jhoffner marked this conversation as resolved.
Resolved
return allItems.filter((item, idx) => idx > state.lastProcessedIndex && item.type === 'message')
}
const read = new Set(state.readMessages.map((message) => message.id))
return allItems.filter((item) => item.type === 'message' && !read.has(item.id))
}

/**
* The state after marking a judged window read: its messages join
* `readMessages`, and the watermark moves to its boundary, as it does without
* an evaluator, so an app that drops its evaluator picks up where this left
* off. The first mark carries over the messages the watermark already
* covered. Messages older than everything in this capture's view of the
* session are dropped: no later window can reach them.
*/
function markJudgedRead(
s: MemorySystemState,
window: Pick<JudgedWindow, 'boundary' | 'judged'>,
allItems: ReadonlyArray<Record<string, any>>,
): MemorySystemState {
const carried: ReadMessage[] = s.readMessages ?? allItems
.filter((item, idx) => idx <= s.lastProcessedIndex && item.type === 'message')
.map(toReadMessage)
const byId = new Map([...carried, ...window.judged].map((message) => [message.id, message]))
const oldest = allItems.length > 0
Comment thread
jhoffner marked this conversation as resolved.
Resolved
? allItems.reduce((min: number, item) => Math.min(min, item.ts), Infinity)
: -Infinity
return {
...s,
lastProcessedIndex: Math.max(s.lastProcessedIndex, window.boundary),
readMessages: [...byId.values()].filter((message) => message.ts >= oldest),
Comment thread
jhoffner marked this conversation as resolved.
Resolved
}
}

function toReadMessage(item: Record<string, any>): ReadMessage {
return { id: item.id, ts: item.ts }
}

/**
* The observe window: the text one capture judges and observes.
*
* One function, so the observer and the capture evaluator never disagree
* about which messages they read. The order is the shipped observer contract:
*
* 1. the `source` override, when configured (it overrides the session);
* 2. else the `message` items past the `lastProcessedIndex` watermark;
* 2. else the session messages: `messages` when given (capture with an
* evaluator passes the ones it has yet to judge), otherwise the `message`
* items past the `lastProcessedIndex` watermark;
* 3. else the block input, when it is a non-empty string (live items from the
* current request may not be flushed yet when capture runs).
*
Expand All @@ -522,14 +585,16 @@ export function readObserveWindow(
source: MemorySystemBlocksConfig['source'],
input: unknown,
ctx: { session?: any; resources: any },
messages?: ReadonlyArray<Record<string, any>>,
): string | undefined {
if (source) {
const text = source(input, ctx)
return text || undefined
}

const allItems = ctx.session?.items?.all?.() ?? []
const formatted = buildObserveContext(allItems, ctx.resources.memorySystem.state.lastProcessedIndex)
const formatted = messages
? formatMessages(messages)
: buildObserveContext(ctx.session?.items?.all?.() ?? [], ctx.resources.memorySystem.state.lastProcessedIndex)
if (formatted !== undefined) return formatted

if (typeof input === 'string' && input.trim().length > 0) {
Expand Down Expand Up @@ -660,7 +725,7 @@ export function memorySystemObserve(
*/
export function memorySystemReflect(
config: MemorySystemBlocksConfig,
readBoundary?: (ctx: { parent?: { input?: unknown } }) => number,
readJudged?: (ctx: { parent?: { input?: unknown } }) => Pick<JudgedWindow, 'boundary' | 'judged'>,
) {
const episodicResource = config._episodicResource ?? (config.episodic
? createEpisodicMemoryResource(config.episodic.scope)
Expand Down Expand Up @@ -808,15 +873,20 @@ export function memorySystemReflect(
}
}

// Update tracking counters. With a judged window, the watermark moves
// to the boundary read with that window, never past it.
// Update tracking counters. A judged window marks read exactly the
// messages it judged. Without one, the watermark moves past the session
// and decides what is read, so a `readMessages` left by capture with an
// evaluator is cleared.
const allItems = ctx.session?.items?.all?.() ?? []
const boundary = readBoundary?.(ctx)
const judgedWindow = readJudged?.(ctx)
await sysRef.updateState((s: any) => ({
...s,
lastProcessedIndex: boundary === undefined
? watermarkPast(allItems, s.lastProcessedIndex)
: Math.max(s.lastProcessedIndex, boundary),
...(judgedWindow !== undefined
? markJudgedRead(s, judgedWindow, allItems)
: {
...s,
lastProcessedIndex: watermarkPast(allItems, s.lastProcessedIndex),
...(s.readMessages == null ? {} : { readMessages: null }),
}),
episodicWritesSinceLastConsolidation: s.episodicWritesSinceLastConsolidation + episodicWrites,
evictedPersistentSinceLastConsolidation: s.evictedPersistentSinceLastConsolidation + evictedPersistent,
}))
Expand Down Expand Up @@ -1638,6 +1708,8 @@ export function memorySystemPrune(config: MemorySystemBlocksConfig) {
const judgedWindowSchema = z.object({
window: z.string().nullable(),
boundary: z.number(),
/** The session messages the window holds: what judging it marks read. */
judged: z.array(z.object({ id: z.string(), ts: z.number() })),
})
type JudgedWindow = z.infer<typeof judgedWindowSchema>

Expand All @@ -1664,10 +1736,11 @@ function checkCaptureEvaluator(gate: CaptureEvaluatorBlock): void {
* window → (none: stop) → judge: evaluator → remember: observe → reflect
* → skip: mark the window read
*
* The window is read once ({@link readObserveWindow}), together with the
* watermark boundary it ends at, and both travel as the judge sequencer's
* input: the evaluator and the observer read that same text, and reflect or
* the skip path advance the watermark to that boundary and no further. Nothing
* The window is read once ({@link readObserveWindow}) from the messages no
* capture has judged yet, together with those messages' ids and the watermark
* boundary it ends at, and all three travel as the judge sequencer's input:
* the evaluator and the observer read that same text, and reflect or the skip
* path mark read those messages and no others ({@link markJudgedRead}). Nothing
* about the window is written to scope or sequencer state, so it is never
* emitted as a state change or kept in a checkpoint.
*
Expand All @@ -1686,9 +1759,12 @@ function evaluatedCapture(config: MemorySystemBlocksConfig, gate: CaptureEvaluat
resources: { memorySystem: memorySystemResource },
execute: async (input, ctx) => {
const allItems = ctx.session?.items?.all?.() ?? []
const state = ctx.resources.memorySystem.state as MemorySystemState
const unread = unreadMessages(allItems, state)
return {
window: readObserveWindow(config.source, input, ctx) ?? null,
boundary: watermarkPast(allItems, ctx.resources.memorySystem.state.lastProcessedIndex),
window: readObserveWindow(config.source, input, ctx, unread) ?? null,
boundary: watermarkPast(allItems, state.lastProcessedIndex),
judged: unread.map(toReadMessage),
Comment thread
jhoffner marked this conversation as resolved.
Resolved
}
},
})
Expand All @@ -1698,18 +1774,15 @@ function evaluatedCapture(config: MemorySystemBlocksConfig, gate: CaptureEvaluat
inputSchema: z.any(),
resources: { memorySystem: memorySystemResource },
execute: async (_input, ctx) => {
const { boundary } = judged(ctx)
await ctx.resources.memorySystem.updateState((s: any) => ({
...s,
lastProcessedIndex: Math.max(s.lastProcessedIndex, boundary),
}))
const allItems = ctx.session?.items?.all?.() ?? []
await ctx.resources.memorySystem.updateState((s: any) => markJudgedRead(s, judged(ctx), allItems))
},
})

// The observer and reflect read the judged window from the judge's input,
// not from a fresh read of the session.
const observeBlock = memorySystemObserve(config, (_input, ctx) => judged(ctx).window ?? undefined)
const reflectBlock = memorySystemReflect(config, (ctx) => judged(ctx).boundary)
const reflectBlock = memorySystemReflect(config, judged)

const judge = (sequencer({
name: `${prefix}/judge`,
Expand Down
10 changes: 10 additions & 0 deletions packages/memory/src/memory-system.ts
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,15 @@ import type { RetrievalStrategy } from './tools/types'
export const memorySystemStateSchema = z.object({
/** Index of the last processed session item. */
lastProcessedIndex: z.number().default(-1),
/**
* With an evaluator: the session messages a capture has judged, by item id
* and timestamp. Capture with an evaluator reads a message only while it is
* missing here, so a capture marks read exactly what it judged, however
* overlapping turns land in the log. `null` until such a capture marks
* something, and after one without an evaluator: the watermark then says
* what is read.
*/
readMessages: z.array(z.object({ id: z.string(), ts: z.number() })).nullable().default(null),
Comment thread
jhoffner marked this conversation as resolved.
Resolved

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Re-gate the persisted-state change

Adding readMessages reverses the approved FIX-1555 decision that the watermark and counters retain their existing persisted shape (specs/issues/FIX-1555/DECISIONS.md:76-89). Because this is a material design change rather than an implementation detail, pause the implementation until a follow-up amendment records the new compatibility and migration trade-offs and receives renewed approval.

AGENTS.md reference: AGENTS.md:L52-L56

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this needs a re-gate, but the call belongs to the spec's owner, so I've put it to them and am leaving this thread open.

FIX-1555 listed "No persisted state changes" under Decided, not asked, as an implementer note about that change set, not as an approved direction. The approved direction (D2, BR-4, BR-6: a skip is final, and an error leaves the turn unread) is unchanged, and this PR is what makes BR-6 hold when turns overlap. The positional watermark can't express "read exactly what I judged" across overlapping turns, so keeping the old shape would mean leaving BR-6 broken. Per orchestration.md, an amendment needs renewed approval only for a materially changed direction. If the owner wants it on record anyway, the follow-up is a short amendment to specs/issues/FIX-1555/DECISIONS.md from main.


Generated by Claude Code

/** Episodic writes since the last consolidation check. */
episodicWritesSinceLastConsolidation: z.number().default(0),
/** Persistent/permanent entries evicted since the last consolidation. */
Expand All @@ -97,6 +106,7 @@ export const memorySystemResource = defineResource({
stateSchema: memorySystemStateSchema,
default: {
lastProcessedIndex: -1,
readMessages: null,
episodicWritesSinceLastConsolidation: 0,
evictedPersistentSinceLastConsolidation: 0,
lastConsolidationTurn: 0,
Expand Down
Loading
Loading