simulating-agents-with-memory-reflection-and-planning

Imported from Articul-Research/genai-research-guide (methods/m8-generative-agents-interactive-simulacra-of-human-behavior/skill/SKILL.md). Install upstream with npx skills add Articul-Research/genai-research-guide --skill skill. Copyright stays with the author.

Simulating agents with memory, reflection, and planning

Treat generated responses as model outputs, not observations from people whom the study did not recruit.

Inputs to define

• Agent character descriptions (required): Initialize each agent's identity, traits, occupation, motivations, relationships, and other background information. Split structured natural-language descriptions into separate initial memory records.
• Environment representation and current state (required): Provide the places, objects, containment relations, object states, nearby entities, and operational constraints that an agent can perceive and act upon.
• Timestamped memory stream (required): Store observations, plans, and reflections as natural-language records. Each record carries creation and last-access times used in later retrieval.
• Current plan and agent status (required): Establish the action sequence the agent is following and provide the current time, location, and activity when deciding whether to continue or react.
• Language-generation and text-embedding models (required): Generate memory importance ratings, reflections, plans, reactions, dialogue, action descriptions, and summaries; embed memory and query text for relevance scoring.
• Natural-language user interventions (optional): Optionally introduce goals, direct an agent through an inner-voice persona, or change the state of environmental objects.

Workflow to implement

The steps below describe the transferable workflow. Select a suitable available UvA model and define the population, task, inputs, and benchmarks for the new study. Source-paper choices and examples are retained separately in references/method-record.json; do not copy them as universal requirements.

1. Create agents and encode the environment. Write a natural-language description for each agent and divide it into discrete initial memory records. Represent the environment as areas containing subareas and objects. Give each agent an initial, partial representation of the places and objects it is expected to know. Include operational constraints in object or location state when they are needed for behavior, because constraints that remain implicit may not be followed.
2. Perceive the current situation and append observations. At each simulation step, identify nearby agents, objects, and events within the agent's perceptual range. Convert these perceptions, including the agent's own activity, into natural-language observations. Append each observation to the memory stream with its creation time and last-access time. Update the agent's partial environment representation when it encounters new or changed areas and objects.
3. Retrieve memories relevant to the current decision. Use the current situation as a retrieval query. Score candidate memories by recency, importance, and semantic relevance. Recency depends on elapsed time since last access, importance is assigned when the memory is created, and relevance is based on similarity between embeddings of the query and memory description. Normalize the component scores, combine them with documented weights, rank the memories, and insert the highest-ranked records that fit within the model context. Update last-access times for retrieved records.
4. Synthesize higher-level reflections. Track the cumulative importance of recent observations and trigger reflection when a specified threshold is crossed. Supply a recent portion of the memory stream to the language model and ask it to formulate salient questions that can be answered from those records. Use each question as a new retrieval query. Ask the model to produce higher-level statements from the retrieved evidence and cite the supporting memory records. Store each reflection in the memory stream with pointers to those records. Later reflections may retrieve earlier reflections, creating progressively more abstract chains of inference.
5. Generate and progressively decompose plans. Construct a planning prompt from the agent summary, recent experiences or reflections, and a summary of the preceding period. Generate a broad sequence of future activities. For each activity, record its location, start time, and duration. Decompose near-future activities into increasingly specific actions only when they are approaching, rather than generating every detailed action at the start. Store plans in the memory stream so they can be retrieved and revised.
6. Choose whether to continue, react, or converse. Combine the agent summary, time, current status, current observation, retrieved relationship and topic memories, and current plan. Ask the language model whether the agent should continue its planned activity or react to the observation. If it reacts, regenerate the plan from the reaction time onward. If another agent is involved, generate dialogue conditioned on each speaker's summary, status, observations, retrieved memories, intended reaction, and dialogue history. Alternate speakers until one agent ends the exchange.
7. Execute the action and write the result back. Produce a natural-language description of the selected action. Resolve its location by traversing the agent's known environment representation and selecting a suitable leaf location. Use ordinary environment-control or pathfinding code to carry out movement. When the action affects an object, determine and apply the resulting object-state change. Preserve the action, updated plan, resulting perceptions, and any generated reflections in the memory stream, then repeat the perception-to-action cycle.
8. Evaluate individual and collective behavior. Evaluate individual agents with natural-language questions covering self-knowledge, memory, planning, reactions, and reflection. Compare the complete system with variants that disable memory types, planning, or reflection while holding available experience records as comparable as possible. For collective behavior, define observable measures before the simulation, such as verified information diffusion, mutual knowledge, or attendance at a coordinated event. Check factual agent answers against memory records rather than accepting self-reports at face value.

Source-paper walkthrough

Read references/implementation.md, then inspect the files in examples/. Their provenance is recorded in references/method-record.json: some values are direct transcriptions, while assembled files are explicitly labelled as reconstructions or UvA adaptations.

The command sequence for the included example follows below. For a live UvA run, read references/uva-llmproxy.md and select a model returned by /v1/models.

Checks to adapt

• Validity: Interview agents about self-knowledge, memory, plans, reactions, and reflections, and have evaluators compare the believability of responses across the complete and ablated conditions.
• Validity: Disable reflection, planning, and memory access in progressive ablations while providing comparable accumulated memories permitted by each condition.
• Validity: For claims of information diffusion or social knowledge, compare agent answers with the corresponding memory stream and label unsupported answers as hallucinations.
• Validity: Measure collective outcomes with predefined indicators, including the percentage of informed agents, mutual-knowledge network density, and attendance at the correct event time and location.
• Explainability: Preserve each memory's natural-language description, creation timestamp, and last-access timestamp.
• Explainability: Preserve pointers from generated reflections to the memory records cited as supporting evidence.
• Explainability: Maintain an audit log of agent inputs and generated outputs when the simulation could create misinformation, deepfakes, or tailored persuasion.
• Generalizability: Repeat evaluations over longer observation periods and compare different underlying models and agent hyperparameters.
• Generalizability: Evaluate behavior for populations that may be poorly represented in the underlying model's training data rather than assuming equivalent believability across groups.

API and records

• Read references/method-record.json before changing the implementation.
• Adapt examples/uva_adapter.py to the declared inputs; inspect it before a live call.
• Make one API call per unit stated in that record.
• Use https://llmproxy.uva.nl/v1/chat/completions and the x-litellm-api-key header for the included UvA adapter.
• Validate the response before analysis or state updates.
• Record the input, request, model identifier, settings, raw response, parsed response, retry, exclusion, and analysis row for every call.
• Read credentials from environment variables. Never add them to configuration or logs.

Boundaries

• Do not treat agent behavior as evidence that the system has genuine human-like agency.
• Do not use synthetic agents as substitutes for real participants or stakeholders. The paper positions them as a possible aid to early-stage prototyping when human testing is difficult or risky.
• Do not deploy the method in settings where incorrect inferences, fabricated memories, persuasion, or identity confusion would have material consequences without domain-specific safeguards and audit records.

Evidence

Use references/evidence.jsonl to check an instruction or adaptation. Each record contains an exact supporting span, its surrounding paragraph, PDF coordinates, and a source location. Check references/claim-ledger.jsonl before incorporating generated prose into the guide.