Reflection: From Experiences to Beliefs

A coding agent has been working with the same user for three months. The long-term episodic store holds 4,200 segmented episodes — each one a clean, salience-scored unit, every one of them admitted through a strict write-policy gate. Retrieval works. Recall is high. The agent can find the right episode for almost any query. And yet the agent feels flat. It remembers that the user reverted three pull requests last month, but it never noticed that all three reverts touched the auth subsystem and that the user has stopped trusting the auth refactor; it remembers eleven separate conversations about deploy retries, but it never abstracted “this user always wants to see logs before retrying”; it remembers each individual debugging session but doesn’t recognize the pattern in how this particular user debugs. The episodes are individually intact. The understanding is missing. What’s missing is the layer that turns a stack of raw observations into a stack of beliefs — the operation cognitive scientists call consolidation and the agent-memory literature, following Park et al. (2023), calls reflection. This article is the deep dive on that operation.

Opening bridge

The last two pieces — memory write policies and episode segmentation — built out the write-path end of the memory subsystem in detail: what enters the store (the four-stage admission pipeline) and at what granularity (the five segmentation signals plus the anchored 1-10 salience score). Both pieces deferred one operation. The write policy “extract” stage names the transformation from raw turn to durable fact, but treats it as a one-shot extraction at write time; the segmentation piece notes that the boundary-locked encoding pattern from neuroscience pairs naturally with a post-boundary consolidation pass, but doesn’t spell out what that consolidation actually does. Today’s article is the missing piece. Reflection is the second-order write operation that runs after an episode is written and before it’s queried by the next call — the layer that reads a window of raw episodes and emits higher-order claims about them. The frame the rest of the article works from: reflection is to episodic memory what materialized views are to a transactional database — precomputed answers to questions you’ll ask repeatedly, refreshed asynchronously, queried cheaply.

Definition

Reflection is the write-time-deferred or background memory operation that reads a window of related episodes and emits one or more higher-order claims — beliefs, generalizations, pattern summaries, or learned rules — that future retrievals can use in place of re-reasoning over the raw episodes. Three properties distinguish a reflection from the extract step in the write pipeline. First, it is cross-episode — the extract step operates on one turn or one exchange; reflection operates on a window of N related episodes and produces a single output that depends on the joint content. Second, it is evidence-anchored — every reflection points back to the specific episodes that grounded it, so downstream consumers can audit “why does the agent believe this?” and so updates to the underlying episodes can invalidate the reflection. Third, it is higher-order — the output is one abstraction level up from the inputs: not “the user said X on Tuesday,” but “the user prefers Y across these eight similar situations.”

What reflection is not. It is not extraction — extraction reads one turn and writes a structured fact; reflection reads many episodes and writes a belief. It is not summarization — summarization compresses a span of text without necessarily generalizing; reflection actively generalizes from particulars to claims. It is not planning — planning operates forward in time on what to do next; reflection operates backward in time on what to believe about what has happened. The verbs are different: extract → distill, summarize → compress, plan → decide, reflect → generalize. Mixing them produces systems that nominally have all four operations but don’t actually have any of them.

Intuition

The mental model that pays off is periodic, threshold-triggered consolidation of an episodic write-ahead log into a materialized belief table. The episodic store is the log; reflections are the materialized view; the trigger is “we’ve accumulated enough new evidence to potentially change a belief.” The pattern is exactly what databases do with materialized views — precompute the expensive query result on a schedule, refresh on a trigger, query the cheap result instead of the expensive aggregate every time. The reason both architectures converge on this shape is the same: the cost of computing the higher-order answer dwarfs the cost of reading it once it’s computed, so amortizing the computation over many reads is the only economical play.

Two design questions force themselves on every reflection implementation. The first is when does reflection fire? Three families of triggers, each with a different cost-vs-quality profile: a time-based trigger (every N minutes, every session-end, nightly batch); an event-based trigger (every K new high-salience episodes, when a new fact would contradict an existing belief); a query-based trigger (lazy materialization — reflect on retrieval miss, then cache the result). The Generative Agents paper’s importance-sum threshold (reflect when accumulated importance scores cross 150) is a hybrid event-based trigger — it fires based on accumulated signal, not on clock-time. The second is what does reflection produce? Three common output shapes: a structured belief ({subject, predicate, object, confidence, evidence_ids}), a free-form insight sentence anchored to source episode IDs, or a generalized rule (a procedural-style “if X then Y” claim distilled from many examples). The choice of shape determines what the read path can do with the output — beliefs are good for substituting into the system prompt, insights are good for grounding a “why do you think that?” answer, rules are good for routing future behavior.

The cognitive grounding — systems consolidation theory

The neuroscience here is precise. Systems consolidation theory (Squire & Alvarez 1995, Frankland & Bontempi 2005, Sekeres et al. 2018) holds that memories are not stored in their final form at encoding time. The hippocampus encodes a fast, vivid, context-rich representation of an experience; over hours-to-years, repeated reactivation (during sleep, during quiet rest, during recall) gradually transfers a generalized, gist-shaped version of the memory into neocortex, while the specific episodic details either fade or remain hippocampally bound. The classic distinction is between episodic memory (“I had pasta at Mario’s on Tuesday with Sarah”) and semantic memory (“I like Italian food”) — and the path from one to the other is consolidation, not encoding.

Two implications port directly to agent architectures. First, consolidation extracts gist, not detail. The neocortical version of a remembered event keeps the structural pattern (who, what, where, why-it-mattered) and drops the verbatim specifics; the hippocampal version is where you go when you need to remember “what color shirt was Sarah wearing.” The agent-architecture parallel: a reflection should output a belief about a pattern, not a more compact version of the original episode. If a reflection is just a shorter version of the raw episode, you’ve built compression, not reflection. The diagnostic test: can the reflection say something the source episodes don’t literally say? If no, the reflection is summarizing, not consolidating.

Second, consolidation is replay-driven, and the replay is selective. The brain doesn’t replay every memory equally — replay biases toward emotionally significant, reward-linked, and surprising experiences (the salience signal that yesterday’s piece named). The agent-architecture parallel: reflection should select the input window by salience, not by recency alone. Generative Agents’ importance-sum trigger is the clean port — reflection fires when accumulated importance, not raw episode count, crosses a threshold; the window pulled into reflection is the most-important recent episodes, not the most-recent N. The two-mode pattern (importance for trigger, recency for window) is what makes the reflection’s input distribution sharper than the underlying episodic store’s distribution.

The distributed-systems parallel — materialized views

The cleanest distributed-systems parallel is the materialized view in a transactional database. In Postgres, a MATERIALIZED VIEW is a precomputed query result stored as a table; reads against the view are O(1) instead of O(table-scan); writes to the underlying tables don’t update the view automatically — a REFRESH MATERIALIZED VIEW has to be triggered. The trade-off is canonical: stale-but-fast reads for free, fresh reads cost a refresh. Production systems live on this trade-off — every analytics dashboard, every “top-K customers by revenue last month” query, every leaderboard, is the same shape.

Agent reflection recapitulates this exactly. The episodic store is the underlying table (every meaningful turn, append-only, expensive to aggregate). The reflection table is the materialized view (one row per derived belief, indexed for retrieval, fast to query). The reflection pass is the refresh operation — it reads from the episodic table, computes the aggregate, and writes to the view. Reads on the hot path query the view, not the underlying table; the cost of the higher-order answer is amortized over many reads. Three further parallels worth naming.

Refresh policy is the design surface, just like in databases. Postgres ships REFRESH MATERIALIZED VIEW CONCURRENTLY (locks the old version until the new one is built, then atomic swap) for live-traffic systems and REFRESH MATERIALIZED VIEW (blocks reads until done) for simpler workloads. The same trade-off shows up in reflection: reflect-on-trigger-with-concurrent-reads keeps the agent responsive while the reflection runs in the background; reflect-on-trigger-with-blocking-reads is simpler but means the next call after a trigger pays the reflection latency. Generative Agents implemented the latter (reflection runs inline at the importance-threshold breach); production systems lean toward the former.

View invalidation is the conflict-resolution problem. When a new episode contradicts a fact a reflection depends on, the view is stale. Postgres handles this manually — you have to REFRESH or set up triggers. Agent memory has to handle it more carefully because reflections aren’t typed enough to mechanically invalidate; the production answer (covered in A-MEM’s design and Memory-R1) is to keep a reflection’s evidence_ids field as a back-reference to the source episodes, and run a background invalidation pass that flags reflections whose evidence has been contradicted or superseded. This is the foreign-key-style integrity constraint applied to a belief table, and the runtime mechanics — the provenance walk and bi-temporal staleness gate — get their own dedicated deep dive on the read side of the same model. The memory conflict and forgetting article is where the propagation step itself gets the deep treatment: when a source is marked INVALID, walk the dependents to depth 2-3 and revalidate or mark-as-stale.

Cascading materialized views — reflection on reflections. Generative Agents introduced a reflection tree: the leaves are episodes, the next layer is reflections over episodes, the next is reflections over reflections. The same shape exists in database systems (a materialized view over another materialized view), and the same caveat holds: the deeper the tree, the more compounded the staleness. The depth-2 reflection in Generative Agents is the canonical example — “I’m a researcher who values cleanliness” is a belief derived from beliefs (“I clean my workspace daily,” “I publish frequently,” “I attend conferences regularly”) that were themselves derived from raw episodes. Production reflection systems rarely go beyond depth-2 because each layer multiplies the invalidation surface.

The Generative Agents reflection loop

The mechanism Park et al. (2023) introduced is the canonical reference for every production reflection pass; knowing it by its components is what makes the implementations downstream legible.

Step 1 — Trigger. Maintain a running sum of importance scores for every episode admitted since the last reflection. When the sum crosses a threshold (the paper uses 150 with their 1-10 scale, so roughly 15-20 high-importance episodes worth of accumulated signal), fire a reflection. The threshold is the consolidation analogue: not enough new signal, no reflection; enough new signal, refresh the view. Agents in the paper reflect about two-to-three times per simulated day under realistic interaction load.

Step 2 — Salient question generation. Pull the 100 most recent records from the episodic store and prompt a large model: “Given only the information above, what are the 3 most salient high-level questions we can answer about the subjects in the statements?” This is the consolidation analogue of “what would be worth knowing about this period?” — the agent is generating its own retrieval queries against its own recent experience. The questions are not the output of reflection; they’re the index into the next step.

Step 3 — Evidence retrieval per question. For each generated question, run a retrieval pass against the full episodic store (not just the recent window) and pull the top relevant episodes. This is the consolidation analogue of “what specific memories does this generalization rest on?” — the reflection process has to ground itself in concrete evidence, not in pure model intuition. The retrieval pass is the standard recency × importance × similarity rerank, scoped to the question.

Step 4 — Insight generation with evidence references. Prompt the model: “What 5 high-level insights can you infer from the above statements? (example format: insight (because of 1, 5, 3)).” The output is a list of insights, each with explicit citation back to the source-episode IDs. This is the load-bearing structural pattern — every insight is anchored to its evidence, and the evidence IDs are stored alongside the insight. Without the citations, the insight is a free-floating claim; with them, it’s an audit-trail-bearing belief.

Step 5 — Persist as a memory. The insights are written into the same episodic store, with a type=reflection tag, an evidence_ids field listing the source episodes, and a normal salience/importance score (often higher than typical raw episodes, since reflections are derived from many evidence pieces). On future retrieval, reflections are returned alongside raw episodes — the agent’s read path doesn’t have to know whether a returned memory is a raw observation or a reflection over many observations. The structural property: reflections sit in the same address space as the episodes they were derived from, which means recency × importance × similarity reranking works on both transparently.

The full loop in roughly 50 lines of Python is what follows; the architectural property to keep in mind is that it’s a five-step pipeline with explicit handoffs, not a single “summarize my recent memories” call.

Code: Python — a threshold-triggered reflection pass

The smallest interesting build: an importance-sum-triggered reflector that runs the five-step Generative Agents loop against an existing Chroma-backed episodic store. Writes reflections back into the same store with the type=reflection tag and an evidence_ids field. Uses the Anthropic SDK for the question-generation and insight-generation calls. Install: pip install anthropic chromadb.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196

import json
import time
import uuid
from dataclasses import dataclass, field
from anthropic import Anthropic

import chromadb

client = Anthropic()
chroma = chromadb.PersistentClient(path="./memory_store")
episodes = chroma.get_or_create_collection("episodes")

# --------- tunables ---------
IMPORTANCE_THRESHOLD = 15.0     # sum of normalized [0,1] importance to trigger
RECENT_WINDOW = 100             # records prompted to the salient-question step
QUESTIONS_PER_REFLECTION = 3
INSIGHTS_PER_REFLECTION = 5
EVIDENCE_PER_QUESTION = 8
MODEL = "claude-haiku-4-5"      # cost-effective for the inner reflection loop


@dataclass
class ReflectionState:
    """Per-user accumulator. Persist this if the agent process is long-lived."""
    user: str
    pending_importance: float = 0.0
    last_reflection_ts: float = 0.0
    reflections_run: int = 0


def on_new_episode(state: ReflectionState, importance_normalized: float) -> bool:
    """Call after every successful episode write. Returns True if reflection should fire."""
    state.pending_importance += importance_normalized
    return state.pending_importance >= IMPORTANCE_THRESHOLD


# --------- Step 2: salient-question generation ---------
def generate_salient_questions(recent_records: list[dict]) -> list[str]:
    transcript = "\n".join(
        f"[{i}] {r['document']}" for i, r in enumerate(recent_records, start=1)
    )
    prompt = (
        f"Given only the information below, what are the {QUESTIONS_PER_REFLECTION} most "
        "salient high-level questions we can answer about the subjects in the statements? "
        "Return a JSON array of strings. Only the questions.\n\n"
        f"Statements:\n{transcript}"
    )
    resp = client.messages.create(
        model=MODEL,
        max_tokens=400,
        temperature=0,
        messages=[{"role": "user", "content": prompt}],
    )
    raw = resp.content[0].text.strip()
    try:
        return json.loads(raw[raw.index("[") : raw.rindex("]") + 1])
    except (ValueError, json.JSONDecodeError):
        return []


# --------- Step 3: evidence retrieval per question ---------
def evidence_for(user: str, question: str, k: int = EVIDENCE_PER_QUESTION) -> list[dict]:
    hits = episodes.query(
        query_texts=[question],
        n_results=k,
        where={"user": user},
    )
    if not hits["ids"][0]:
        return []
    return [
        {"id": eid, "document": doc, "metadata": meta}
        for eid, doc, meta in zip(
            hits["ids"][0], hits["documents"][0], hits["metadatas"][0]
        )
    ]


# --------- Step 4: insight generation with citations ---------
INSIGHT_PROMPT = """Below are statements from the agent's memory, each with a numeric ID.

Statements:
{statements}

What {n} high-level insights can you infer from the statements? Each insight must be
anchored to the specific statement IDs that support it.

Return JSON: a list of objects, each {{"insight": "<one sentence>", "evidence_ids": [int]}}.

Rules:
- The insight must say something the statements do not literally say; you are generalizing,
  not paraphrasing.
- Cite at least 2 evidence IDs per insight.
- If you cannot ground an insight in at least 2 statements, do not emit it.
"""


def generate_insights(evidence_records: list[dict], n: int = INSIGHTS_PER_REFLECTION) -> list[dict]:
    # Renumber statements for the model with a stable local index, but track real IDs.
    local_to_real = {}
    statements_block = []
    for local_id, rec in enumerate(evidence_records, start=1):
        local_to_real[local_id] = rec["id"]
        statements_block.append(f"[{local_id}] {rec['document']}")
    prompt = INSIGHT_PROMPT.format(statements="\n".join(statements_block), n=n)
    resp = client.messages.create(
        model=MODEL,
        max_tokens=900,
        temperature=0,
        messages=[{"role": "user", "content": prompt}],
    )
    raw = resp.content[0].text.strip()
    try:
        parsed = json.loads(raw[raw.index("[") : raw.rindex("]") + 1])
    except (ValueError, json.JSONDecodeError):
        return []
    # Remap local citation IDs to the real episode IDs.
    results = []
    for item in parsed:
        local_ids = item.get("evidence_ids", [])
        real_ids = [local_to_real[i] for i in local_ids if i in local_to_real]
        if len(real_ids) < 2:
            continue  # enforce the citation floor — drop unsupported insights
        results.append({"insight": item["insight"], "evidence_ids": real_ids})
    return results


# --------- Step 5: persist ---------
def persist_reflection(user: str, insight: str, evidence_ids: list[str]) -> str:
    rid = str(uuid.uuid4())
    episodes.add(
        ids=[rid],
        documents=[insight],
        metadatas=[
            {
                "user": user,
                "type": "reflection",
                "importance": 0.85,  # reflections inherit high importance by default
                "ts": time.time(),
                "last_read": time.time(),
                "evidence_ids": ",".join(evidence_ids),
                "depth": 1,
            }
        ],
    )
    return rid


# --------- The full reflection pass ---------
def reflect(state: ReflectionState) -> list[str]:
    """Run one full reflection cycle for a user. Returns the new reflection IDs."""
    # Pull the most recent records from this user's episodic store.
    all_records = episodes.get(where={"user": state.user})
    records = list(
        zip(all_records["ids"], all_records["documents"], all_records["metadatas"])
    )
    records.sort(key=lambda r: r[2].get("ts", 0), reverse=True)
    recent = [
        {"id": rid, "document": doc, "metadata": meta}
        for rid, doc, meta in records[:RECENT_WINDOW]
    ]
    if len(recent) < 5:
        return []  # not enough signal; reset the accumulator and skip

    questions = generate_salient_questions(recent)
    if not questions:
        return []

    new_reflection_ids: list[str] = []
    for question in questions:
        evidence = evidence_for(state.user, question)
        if len(evidence) < 2:
            continue  # no point reflecting without grounding
        insights = generate_insights(evidence)
        for ins in insights:
            rid = persist_reflection(state.user, ins["insight"], ins["evidence_ids"])
            new_reflection_ids.append(rid)

    # Reset the accumulator regardless — we paid the reflection cost, mark the cycle done.
    state.pending_importance = 0.0
    state.last_reflection_ts = time.time()
    state.reflections_run += 1
    return new_reflection_ids


# --------- minimal usage sketch ---------
if __name__ == "__main__":
    state = ReflectionState(user="alice")

    # Imagine an agent writing episodes through the normal path; importance arrives normalized.
    sample_importance_stream = [0.6, 0.9, 0.4, 0.85, 0.7, 0.95, 0.55, 0.8, 0.5, 0.9,
                                 0.65, 0.75, 0.85, 0.6, 0.9, 0.7, 0.8, 0.55, 0.95, 0.85]
    for imp in sample_importance_stream:
        # ... the normal write-path call goes here; we just track the accumulator ...
        if on_new_episode(state, imp):
            new_ids = reflect(state)
            print(f"Reflection cycle #{state.reflections_run}: wrote {len(new_ids)} insights")

Three things to notice. First, the citation floor is structural, not stylistic — insights that cite fewer than two evidence IDs are dropped. This is the most-important quality-control knob in a reflection pipeline; without it, the model will emit free-floating claims (closer to a generic “the user seems thoughtful” than to a grounded “the user prioritizes API stability across these three PRs”). Second, the renumber-then-remap pattern is what makes citations reliable — the model sees local 1-N integers that are easy to reference; the persistence layer remaps to real episode IDs that survive future store rewrites. Third, the accumulator resets unconditionally after a cycle runs — even if zero insights are emitted, the cycle has consumed compute and the policy says “we tried.” Without the reset, a perpetual-fail state can spin the reflection pass in a tight loop and burn the budget; the unconditional reset is the circuit-breaker pattern for the reflection layer.

Code: TypeScript — the same shape against an existing store

The TypeScript port against Chroma’s JS client and the Anthropic SDK. Install: pnpm add chromadb @anthropic-ai/sdk.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180

import Anthropic from "@anthropic-ai/sdk";
import { ChromaClient } from "chromadb";

const client = new Anthropic();
const chroma = new ChromaClient({ path: "http://localhost:8000" });

const IMPORTANCE_THRESHOLD = 15.0;
const RECENT_WINDOW = 100;
const QUESTIONS_PER_REFLECTION = 3;
const INSIGHTS_PER_REFLECTION = 5;
const EVIDENCE_PER_QUESTION = 8;
const MODEL = "claude-haiku-4-5";

type ReflectionState = {
  user: string;
  pendingImportance: number;
  reflectionsRun: number;
  lastReflectionTs: number;
};

const newState = (user: string): ReflectionState => ({
  user,
  pendingImportance: 0,
  reflectionsRun: 0,
  lastReflectionTs: 0,
});

const onNewEpisode = (state: ReflectionState, normalizedImportance: number): boolean => {
  state.pendingImportance += normalizedImportance;
  return state.pendingImportance >= IMPORTANCE_THRESHOLD;
};

const extractText = (resp: Anthropic.Message): string => {
  const block = resp.content[0];
  return block.type === "text" ? block.text.trim() : "";
};

const jsonArrayFrom = (raw: string): unknown[] => {
  try {
    const start = raw.indexOf("[");
    const end = raw.lastIndexOf("]");
    if (start < 0 || end < 0) return [];
    return JSON.parse(raw.slice(start, end + 1));
  } catch {
    return [];
  }
};

async function generateSalientQuestions(recent: Array<{ document: string }>): Promise<string[]> {
  const transcript = recent
    .map((r, i) => `[${i + 1}] ${r.document}`)
    .join("\n");
  const prompt =
    `Given only the information below, what are the ${QUESTIONS_PER_REFLECTION} most ` +
    `salient high-level questions we can answer about the subjects in the statements? ` +
    `Return a JSON array of strings. Only the questions.\n\n` +
    `Statements:\n${transcript}`;
  const resp = await client.messages.create({
    model: MODEL,
    max_tokens: 400,
    temperature: 0,
    messages: [{ role: "user", content: prompt }],
  });
  return jsonArrayFrom(extractText(resp)).filter((s): s is string => typeof s === "string");
}

async function evidenceFor(
  collection: Awaited<ReturnType<ChromaClient["getOrCreateCollection"]>>,
  user: string,
  question: string,
): Promise<Array<{ id: string; document: string }>> {
  const res = await collection.query({
    queryTexts: [question],
    nResults: EVIDENCE_PER_QUESTION,
    where: { user },
  });
  const ids = res.ids[0] ?? [];
  const docs = res.documents[0] ?? [];
  return ids.map((id, i) => ({ id, document: docs[i] ?? "" }));
}

const INSIGHT_PROMPT = (statements: string, n: number) => `
Below are statements from the agent's memory, each with a numeric ID.

Statements:
${statements}

What ${n} high-level insights can you infer from the statements? Each insight must be
anchored to the specific statement IDs that support it.

Return JSON: a list of objects, each {"insight":"<one sentence>", "evidence_ids":[int]}.

Rules:
- The insight must say something the statements do not literally say; you are generalizing,
  not paraphrasing.
- Cite at least 2 evidence IDs per insight.
- If you cannot ground an insight in at least 2 statements, do not emit it.
`;

async function generateInsights(
  evidence: Array<{ id: string; document: string }>,
  n = INSIGHTS_PER_REFLECTION,
): Promise<Array<{ insight: string; evidenceIds: string[] }>> {
  const localToReal = new Map<number, string>();
  const blockLines: string[] = [];
  evidence.forEach((rec, idx) => {
    const localId = idx + 1;
    localToReal.set(localId, rec.id);
    blockLines.push(`[${localId}] ${rec.document}`);
  });
  const resp = await client.messages.create({
    model: MODEL,
    max_tokens: 900,
    temperature: 0,
    messages: [{ role: "user", content: INSIGHT_PROMPT(blockLines.join("\n"), n) }],
  });
  const parsed = jsonArrayFrom(extractText(resp));
  const out: Array<{ insight: string; evidenceIds: string[] }> = [];
  for (const item of parsed) {
    if (typeof item !== "object" || item === null) continue;
    const obj = item as { insight?: unknown; evidence_ids?: unknown };
    const insight = typeof obj.insight === "string" ? obj.insight : "";
    const localIds = Array.isArray(obj.evidence_ids) ? obj.evidence_ids : [];
    const realIds = localIds
      .filter((i): i is number => typeof i === "number")
      .map((i) => localToReal.get(i))
      .filter((s): s is string => typeof s === "string");
    if (insight && realIds.length >= 2) out.push({ insight, evidenceIds: realIds });
  }
  return out;
}

export async function reflect(state: ReflectionState): Promise<string[]> {
  const collection = await chroma.getOrCreateCollection({ name: "episodes" });
  const all = await collection.get({ where: { user: state.user } });
  const triples = all.ids.map((id, i) => ({
    id,
    document: all.documents?.[i] ?? "",
    metadata: all.metadatas?.[i] ?? {},
  }));
  triples.sort(
    (a, b) => ((b.metadata as { ts?: number }).ts ?? 0) - ((a.metadata as { ts?: number }).ts ?? 0),
  );
  const recent = triples.slice(0, RECENT_WINDOW);
  if (recent.length < 5) return [];

  const questions = await generateSalientQuestions(recent);
  if (questions.length === 0) return [];

  const newIds: string[] = [];
  for (const q of questions) {
    const ev = await evidenceFor(collection, state.user, q);
    if (ev.length < 2) continue;
    const insights = await generateInsights(ev);
    for (const ins of insights) {
      const rid = crypto.randomUUID();
      await collection.add({
        ids: [rid],
        documents: [ins.insight],
        metadatas: [
          {
            user: state.user,
            type: "reflection",
            importance: 0.85,
            ts: Date.now() / 1000,
            last_read: Date.now() / 1000,
            evidence_ids: ins.evidenceIds.join(","),
            depth: 1,
          },
        ],
      });
      newIds.push(rid);
    }
  }

  state.pendingImportance = 0;
  state.lastReflectionTs = Date.now() / 1000;
  state.reflectionsRun += 1;
  return newIds;
}

The architectural shape is identical to the Python version: five-step pipeline, citation floor enforced in generateInsights, accumulator reset after every cycle. The one TypeScript-specific gotcha worth flagging is the metadata typing — Chroma’s TS client types metadata as a record of primitives, so the evidence_ids array has to be serialized to a comma-separated string at the storage boundary and parsed back at read time. The alternative (storing one row per (reflection, evidence_id) pair in an auxiliary collection) is cleaner from a database-design standpoint but requires a join at read time; for most workloads the inline string is the right trade-off.

When reflection beats raw recall — and when it doesn’t

Reflection is not always the right read-time substrate. The three regimes where it pays off, and the two where raw episodic recall wins.

Reflection wins when the query is about a pattern, not an instance. “What does this user usually want at deploy time?” is a pattern question — the right answer is a generalization over many past deploys, and surfacing one specific deploy episode misses the point. A reflection that says “this user wants logs and a manual approval gate before any deploy” is the right answer; the eight raw episodes that grounded it are noise on the read path. Pattern queries are the canonical reflection workload, and they’re also the queries where pure cosine recall over raw episodes underperforms most dramatically — the right answer is a synthesis, not a single hit.

Reflection wins when the working set of beliefs is small and the underlying episode set is large. A user who has 5,000 episodes in their long-term store probably has 30-50 stable beliefs the agent should know about them — preferences, recurring patterns, durable identity facts. The compression ratio is two orders of magnitude. Pre-paging the 30-50 beliefs into the system prompt is feasible; pre-paging the 5,000 episodes is not. Reflection is what makes the pinned-belief tier in hierarchical memory operationally tractable.

Reflection wins when the read path is latency-sensitive and the consolidation can run in the background. The cost of computing “what does this user usually want at deploy time?” from raw episodes is a multi-hop retrieval + summarization at read time — 1-3 seconds and a non-trivial token budget. The cost of reading a pre-computed reflection is one vector lookup — sub-50ms and a single short token block. For interactive agents where p95 latency matters, the only practical answer is to compute the higher-order answer once, materialize it, and serve it cheaply forever after.

Raw recall wins when the query is about a specific event. “When did the user mention they were vegetarian?” is an instance query — the right answer is a specific date and turn. A reflection that says “this user is vegetarian” is technically true but misses the actual question; the raw episode with the original turn and timestamp is the right answer. Mixing the two layers — surfacing a reflection when the user wanted the source episode — is a common production failure mode, and the fix is to type the read path: instance queries route to raw episodes, pattern queries route to reflections (with raw episodes as fallback or evidence).

Raw recall wins when the underlying episodes are still in flux. A user the agent has been working with for one week has too few episodes to consolidate from; the reflections that fire will be over-confident generalizations from too little evidence. The cognitive analogy is the same — systems consolidation is a slow process precisely because the brain doesn’t generalize from a single experience. Set a floor: the user has to have at least N high-salience episodes (50 is a defensible starting point) before reflection fires at all, or the early reflections will pollute the belief tier with shaky claims that have to be invalidated later.

Trade-offs, failure modes, and gotchas

Self-reinforcing error. The single most-dangerous failure mode of reflection is the self-reinforcing belief loop — a reflection emits an incorrect generalization (“this user dislikes Postgres”); the belief is pinned to the core memory tier; subsequent retrievals surface the belief instead of the contradicting raw episodes; the agent acts on the belief; the action is consistent with the belief; new episodes accumulate that reinforce the belief; subsequent reflections cite the new episodes and harden the belief further. Within ten sessions the agent is locked into a wrong model of the user and has zero ability to detect the error from the inside. The mitigation is the evidence-recheck-on-staleness pattern from Memory-R1 — periodically pull a reflection’s evidence_ids, re-retrieve the raw episodes, and prompt the model to check whether the original evidence still supports the reflection given any new contradicting episodes. Without this, reflection is the agent-memory equivalent of confirmation bias.

Over-generalization from too-narrow evidence. A reflection cites 2-3 episodes (the floor) and emits a claim about “this user.” Three episodes is not enough to justify a generalization, but the LLM will gladly produce one if asked. The mitigation is a minimum-evidence-count threshold (5-8 episodes for a high-confidence reflection, not 2) and an explicit confidence tag (low | medium | high) tied to the evidence count. Reflections with low confidence stay in the store but are weighted down on the rerank; reflections with high confidence get pre-paged into the core tier. The recent survey work on memory mechanisms calls out over-generalization explicitly as the sibling risk to self-reinforcing error — a lesson learned in one context applied blindly in another.

Reflection-as-summarization. The most common bug is reflection that just paraphrases the source episodes into slightly different words. The diagnostic test from the cognitive-grounding section: can the reflection say something the source episodes don’t literally say? If the reflection is “the user said X on dates A, B, and C,” that’s summarization. If it’s “the user appears to prioritize X over Y across these situations,” that’s reflection. The fix is in the prompt — the explicit instruction “the insight must say something the statements do not literally say; you are generalizing, not paraphrasing” is what shifts the model’s output from compression to abstraction. Without it, the reflection layer is just write amplification with extra steps.

The citation-fabrication failure. The model emits an insight with citation [3, 7, 12] but the cited episodes don’t actually support the claim — they’re loosely topical but don’t ground the generalization. This is the same hallucination pattern that bites RAG generation, and the mitigation is the same: a validation pass that, after the model emits insights, fetches the cited evidence and runs a second small-model call asking “does evidence [3, 7, 12] actually support the claim?” Insights that fail validation are dropped. The cost is one extra model call per insight; the quality win is high enough that production reflection pipelines (notably A-MEM’s link-validation pass) consistently ship it.

The depth-2-and-beyond invalidation cliff. Reflection-over-reflection (depth-2) compounds the invalidation problem: when a depth-1 reflection’s underlying evidence is contradicted, every depth-2 reflection that cited the depth-1 reflection is also potentially stale. Three episodes contradicted → one depth-1 reflection invalidated → three depth-2 reflections potentially invalidated → cascading background work. Generative Agents shipped depth-2 in the original paper; most production systems stop at depth-1 and accept the loss in abstraction depth for the gain in invalidation tractability. Rule of thumb: only build depth-2 if you have a working depth-1 invalidation pipeline.

The threshold-drift bug. The importance-sum trigger uses a fixed threshold (150 in the paper, 15.0 normalized). The optimal threshold is workload-specific — a high-volume agent serves users with thousands of episodes per week and needs a higher threshold to avoid reflecting every five minutes; a low-volume agent serves users with dozens of episodes per week and needs a lower threshold to ever fire. Without per-workload tuning, the reflection pass either fires too often (cost) or too rarely (stale beliefs). Instrument the threshold from day one: log the trigger interval, the episode count between triggers, the average insight count per cycle. The tuning loop only closes if the inputs are visible.

The reflection-cost trap. Each reflection cycle runs 1 + Q × (1 + 1) model calls (one question-generation, Q questions × one evidence-retrieval ranking + one insight-generation). With Q=3 that’s 7 calls per cycle; with a small model like Claude Haiku 4.5 at $1/$5 per million tokens that’s roughly $0.05-0.15 per reflection. Trigger reflection too eagerly and the bill scales linearly with episode volume — at 1000 users with 5 reflections/day each, that’s $250-750/day in reflection alone. The optimization patterns are (a) batch the question-generation and insight-generation into a single call for short evidence sets, (b) cache the salient-questions output across users where the topic space overlaps, (c) run reflection on the sleep-time / background path and never on the hot path. The same hot-path-vs-deferred trade-off as the write policies article; reflection is the higher-cost version of the same pattern.

The privacy-leak via reflection. A reflection over many episodes can emerge a claim about the user that the user never explicitly stated and would not consent to having stored (“user appears to be in a romantic relationship with X based on these eleven messages”). The raw episodes were individually fine; the synthesis crossed a line. Mitigation: a reflection-time PII / sensitive-claim filter — an LLM call that classifies a candidate reflection on the dimensions (medical, financial, relational, political) and drops or downgrades reflections that the user’s data-handling policy doesn’t permit. This is the privacy analogue of the citation-validation pass; the cost is one extra small-model call per reflection, and a future memory privacy article will cover the full pattern.

The same-tier collision problem. Storing reflections in the same Chroma collection as raw episodes (with a type=reflection tag) is operationally simple but means the read path’s where filter has to be careful: a query that doesn’t filter by type returns both raw and reflection rows, which can confuse downstream consumers expecting one or the other. Mitigations: separate collections, or strict typing on the read path. The single-collection-with-type-tag pattern is what the Generative Agents codebase actually ships, but production deployments often split them to make the access patterns more legible.

The reflection-staleness lag. Reflections are eventually-consistent with the underlying episodes — between two reflection cycles, new episodes have arrived but the reflections don’t reflect them yet. For workloads where the user’s beliefs change quickly (mid-session preference updates, corrections, “actually, I changed my mind”) this lag can show up as the agent acting on a now-stale belief. The mitigation is to give the read path a recency-veto — if a recent high-salience episode contradicts a reflection, the raw episode wins and the reflection is suppressed for that query. This is the materialized-view-staleness pattern from databases, applied to beliefs: when fresh ground-truth is available, prefer it; consolidate later.

Further reading

• Generative Agents: Interactive Simulacra of Human Behavior (Park et al., 2023) — the canonical reference. §4.3 (Reflection) is the load-bearing section; the appendix has the exact prompts for question-generation and insight-generation that every production reflection system has either ported or knowingly diverged from. The importance-threshold trigger and the depth-2 reflection tree both originate here.
• A-MEM: Agentic Memory for LLM Agents (Xu, Liang, et al., NeurIPS 2025) — the Zettelkasten-inspired production system that pairs write-time enrichment with reflection-style link generation. Where Generative Agents reflects periodically, A-MEM enriches on every write with cross-references that play a similar role; reading them side-by-side surfaces the trade-off between eager and lazy belief construction.
• Hindsight is 20/20: Building Agent Memory that Retains, Recalls, and Reflects (2025) — the recent survey of agent memory systems with reflection as a first-class operation. Distinguishes reflection from extraction and summarization in operational terms and catalogues the failure modes (self-reinforcing error, over-generalization, citation hallucination) that the production pipelines work around.
• Memory in the Age of AI Agents — survey (Hu et al., December 2025) — the 47-author memory survey that names abstraction and generalization during the experience stage as the operation distinct from raw storage and retrieval. The framing positions reflection as the missing layer between what the agent observed and what the agent believes, and surveys the production systems building it.

What to read next

• Summarization and Context Compression — the sibling maintenance operation. Where reflection generalizes across episodes to emit higher-order beliefs, compression preserves the episodes themselves in a shorter form. The two together are the full maintenance axis: pattern extraction and lossy compression of the same underlying log.
• Memory Write Policies: What’s Worth Remembering — the upstream layer reflection sits on top of. The write policy decides what enters the episodic store; reflection runs over the resulting episodes to emit higher-order claims. Together they form the full write-axis.
• Episode Segmentation and Salience Scoring — the operation that produces the salience signal reflection’s importance-threshold trigger consumes. Without anchored salience, reflection fires on the wrong cadence and over the wrong inputs.
• Sleep-Time Compute and Memory Consolidation — the regime reflection should actually run in. Reflection is the canonical sleep-time operation — too expensive for the hot path, with amortizable output that benefits many subsequent test-time calls. The sleep-time architecture (idle-detection, rate-limiting, cheap-model discipline) is what makes the reflection-cost trap from above tractable in production.