MemEvolve Memory Optimization

This repository is a derivative experimental version based on the original MemEvolve / Flash-Searcher codebase.

The original project provides the base agent framework, memory-provider interfaces, benchmark runner, and original memory systems. This repository adds a runtime memory-control layer and reproducible experiments for studying when agent memory helps, when it hurts, and how memory usage can be controlled.

Origin

• Original project: MemEvolve: Meta-Evolution of Agent Memory Systems
• Base agent framework: Flash-Searcher
• Original license: Apache License 2.0

This repository is not the original upstream project. It is a derivative experimental version with additional memory-control mechanisms, evaluation scripts, and presentation materials.

My Contributions

The main additions in this repository are:

• Runtime memory-provider injection without modifying the original core logic.
• Utility Gate V2 for post-retrieval memory filtering.
• Stall-Aware Invocation Router V3 for pre-retrieval memory invocation control.
• Reproducible xBench DeepSearch experiment scripts.
• Comparative evaluation of no-memory, Lightweight Memory, Cerebra Fusion Memory, Mobile-E, Utility Gate, and Invocation Router settings.
• Result summaries, case-level comparisons, tests, and HTML presentation reports.

Core Idea

Agent memory should not always be injected into the context. Irrelevant or poorly timed memory can distract the agent and reduce task accuracy.

This project studies two complementary control strategies:

• Utility Gate V2: retrieve first, then keep only the memories that appear useful according to relevance, stage compatibility, length penalty, and observed task outcomes.
• Stall-Aware Invocation Router V3: decide whether to call memory before retrieval, using execution signals such as errors, repeated tool calls, timeouts, or no-progress context.

Repository Layout

.
├── MemEvolve-main/        # Upstream MemEvolve / Flash-Searcher codebase
├── Sgk_solution/          # Added experiment runner, patches, tests, reports
├── LICENSE                # Apache License 2.0
├── NOTICE.md              # Attribution and modification notice
└── README.md

Important added files:

Sgk_solution/run_experiments.py
Sgk_solution/runtime_gate_launcher.py
Sgk_solution/code/utility_gate_runtime.py
Sgk_solution/code/invocation_router_runtime.py
Sgk_solution/code/invocation_router_providers.py
Sgk_solution/presentation/experiment_process_and_result_zh.html

How To Run

Create a Python 3.10 environment and install the original Flash-Searcher requirements:

cd MemEvolve-main\Flash-Searcher-main
python -m pip install -r requirements.txt

Configure API keys in a local environment file. Do not commit secrets.

OPENAI_API_BASE=...
OPENAI_API_KEY=...
DEFAULT_MODEL=...
SERPER_API_KEY=...

Run the experiment wrapper from Sgk_solution:

cd Sgk_solution
python run_experiments.py --group original --task-indices 1-20 --results-dir results\full_rerun_20 --restart
python run_experiments.py --group gated --task-indices 1-20 --results-dir results\gate_v2_20 --restart
python run_experiments.py --group router --task-indices 1-20 --results-dir results\router_v3_20 --restart

Attribution

The base implementation belongs to the original MemEvolve / Flash-Searcher authors. My work focuses on improving how memories are invoked, filtered, evaluated, and presented in experiments.