MemPlan

Learning Knowledge Graph World Models with Episodic Memory for LLM Agents with PDDL solver

Due to dependencies required by TextWorld, our code can only be executed on Linux systems, specifically after installing certain system libraries. On a Debian/Ubuntu-based system, these can be installed with

sudo apt update && sudo apt install build-essential libffi-dev python3-dev curl git

And on macOS, with

brew install libffi curl git

To complete requirements installation, you need Python 3.11+ and to run

pip install -r requirements.txt

• config contains per-environment YAML configs for TextWorld, ALFWorld, and Robotouille runs.
• pipeline contains the MemPlan execution loop, state/memory modules, failure handling, diagnostics, and writeback logic.
• utils contains environment adapters, PDDL/domain utilities, planner execution, local LLM wrappers, semantic alignment, and experience logging.
• scripts contains shared Slurm submitters, token-comparison jobs, ablations, and log-analysis utilities for TextWorld-style configs.
• scripts_alfworld contains ALFWorld evaluation, ablation, component-ablation, aggregation, and Slurm submission scripts.
• scripts_robotuille contains Robotouille suite evaluation, ablation, and Slurm submission scripts.
• finetune contains data preparation, datasets, training scripts, and Slurm jobs for the unified observation-to-fact and PDDL-action-to-command interface model.
• envs contains bundled TextWorld task files used by the local TextWorld configs.
• fast-downward vendors the Fast Downward planner used by the PDDL loop.
• pddl_output contains generated PDDL domains/problems and planner artifacts from evaluation runs.
• logs contains evaluation, ablation, component, token-comparison, transfer, and analysis outputs.
• tools, graphs, agents, arigraph, and prompts contain supporting legacy and helper modules still used by parts of the pipeline.
• run_with_domain_guard.py is the main single-config entry point used by the environment-specific Slurm submitters.
• run_interaction_pipeline.py and pipeline_arigraph.py are legacy/direct TextWorld entry points kept for compatibility.

Run the following commands from the repository root. By default, the submit scripts use the local fine-tuned interface model and write logs under logs/.

Run one TextWorld config, for example hunt_hard:

sbatch scripts/submit_local_interation.sh config/pipeline_hunt_hard.yaml

Other TextWorld configs can be substituted, for example config/pipeline_clean.yaml, config/pipeline_cook.yaml, or config/pipeline_cook_hard.yaml.

Run ALFWorld with the default ALFWorld config. This example runs one game from each task type:

sbatch scripts_alfworld/submit_alfworld.sh config/pipeline_alfworld.yaml --task-types all --num-games 1

To run only one task type, replace all with a task id from 1 to 6.

Run a small Robotouille suite job:

sbatch scripts_robotuille/submit_robotouille.sh config/pipeline_robotouille.yaml --suite synchronous --limit 1 --output-dir logs/robotouille_suite_example

Use --suite asynchronous for asynchronous tasks, or --suite both to run both settings.

Token counts are prompt + completion model tokens. Local-model runs use the HuggingFace tokenizer; GPT-4o API runs use the token counts returned by the API.

GPT-4o API baselines cover 134/134 ALFWorld eval-out-of-distribution episodes. MemPlan currently covers 131/134 local episodes; the remaining 3 local Slurm jobs are held, and every completed MemPlan episode succeeded.