MIA

The Problem

Deep‑research agents quickly hit a memory bottleneck: context windows balloon, attention drifts, and the system spends most of its compute handling stale or irrelevant records. MIA aims to replace a naïve “memory dump” with a managed, strategy‑driven store that evolves during inference, keeping the agent’s reasoning focused and computationally tractable.

What This Does

MIA implements a Manager‑Planner‑Executor pipeline.

• The Manager (under Memory-Serve/ and Executor-Train/Train/verl/utils/hdfs_io.py) deduplicates and prunes stored tensors.
• The Planner (Planner-Train/mem-plan/verl/tools/) learns a retrieval policy via continual test‑time reinforcement learning.
• The Executor (Executor-Train/Train/verl/tools/base_tool.py and the agent_loop/ package) consumes the Planner’s blueprint and runs the task on a large language model (LLM) from the models/mcore/qwen2_5_vl/ family.

Key files:

• Executor-Train/Train/verl/model_merger/__main__.py – CLI entry that assembles model shards and launches training.
• Planner-Train/mem-plan/verl/model_merger/__main__.py – analogous entry for Planner training.
• TTRL/TTRL/verl/model_merger/__main__.py – entry for the TTRL streaming variant.
• Executor-Train/Train/verl/experimental/agent_loop/agent_loop.py – high‑level loop that repeatedly calls the Planner and Executor.

How It Is Wired

Execution begins in Executor-Train/Train/verl/model_merger/__main__.py (line 52 → main). main parses CLI arguments, builds a configuration (generate_config_from_args), and creates a ModelMerger instance. The merger invokes the model forward path (forward in models/mcore/qwen2_5_vl/model.py), which ultimately calls to (torch tensor conversion) on up to 88 distinct callers.

From the agent loop side, run (line 219 in agent_loop.py) drives the process:

1. run → generate → call_image_search → exists (filesystem check via os.path.exists).
2. run → compute_acc_score → client.chat.completions.create (LLM inference).
3. run → call_replan → requests.post (network call to the Planner service).

The most‑connected internal symbols are:

• to – called from 88 places, central for tensor handling.
• get_torch_device – 61 callers, determines device placement.
• create – 29 callers, used for constructing model components.

Circular imports involve the profiler utilities (utils/profiler/profile.py) across all four major sub‑projects, meaning a change there can trigger recompilation of many dependent modules (15 modules participate in cycles). The hub module verl/tools/schemas.py is imported by 12 other modules; any API change ripples widely.

File‑level responsibilities (high‑impact examples):

The import graph shows 1,465 internal modules with 819 edges and 15 circular dependencies; 12 schema modules sit at the top of the fan‑in hierarchy, making them high‑blast‑radius change points.

How To Use It

# Clone the repo (use the exact URL as requested)
git clone https://github.com/moses-y/MIA
cd MIA

# Install Python dependencies for the Executor train path
python -m pip install -e Executor-Train/Train   # runs setup.py in that directory

# (Optional) Install web‑tool dependencies if UI is needed
python -m pip install -e web_tools

Configuration files live under Executor-Train/Train/local_search/configs/ (e.g., mm_search_tool_config.yaml). Adjust paths or model checkpoints there before launching.

To start a training run for the Executor:

python -m Executor-Train.Train.verl.model_merger __main__ \
    --config Executor-Train/Train/local_search/configs/mmsearch.yaml

For inference with the full agent loop:

python Executor-Train/Train/verl/experimental/agent_loop/agent_loop.py \
    --model-dir path/to/qwen2_5_vl/checkpoint

The repository does not contain a Dockerfile or Makefile; containerizing would require a custom Dockerfile based on the Python version (≥3.10) and the installed packages.

Real‑World Use

A research lab can embed MIA as the memory backend for an autonomous literature‑review bot. The bot calls Memory-Serve/a-mem/memory.py to retrieve relevant passages, the Planner (Planner-Train/mem-plan/) refines the retrieval policy on‑the‑fly, and the Executor runs the LLM to generate a summary. The loop runs entirely within the agent_loop.run call chain, persisting any new memory artifacts via hdfs_io.py.

Code Health & Issues

• High – No LICENSE – repository root lacks a licence file; legal reuse is blocked.
• High – No lockfile – web_tools/pyproject.toml has no accompanying lockfile; builds are non‑reproducible.
• High – No CI – no .github/ workflow; changes are not automatically built or tested.
• Medium – Dependabot missing – single manifest, no automated dependency updates.
• Medium – Large binary – readme_en/MIA-OpenClaw3.mov (12 MB) should be stored via Git LFS.
• Medium – Test coverage low – 13 test files for ~1,557 source files (≈0.4 % coverage).

Additional observations: broad except: blocks and import cycles in utils/profiler/profile.py increase fragility; duplicated shell scripts across Memory-Serve and Serve suggest DRY violations.

The Bottom Line

MIA delivers a concrete, modular memory framework for LLM‑based research agents, with clear separation of manager, planner, and executor responsibilities. The codebase is extensive but suffers from missing licensing, reproducibility safeguards, and limited automated testing, which raises risk for production adoption. Teams with strong Python devops capability can extract the Planner‑Executor core, but should first address the high‑severity hygiene gaps before integrating at scale.