Memento Documentation

Memento uses a two-stage loop to solve tasks without updating LLM weights:

1. Meta-Planner: Uses a high-level model (e.g., GPT-4.1) to decompose a query into executable subtasks. It uses Case-Based Reasoning (CBR) to retrieve relevant past experiences from the Case Memory to guide planning.
2. Executor: Uses a reasoning model (e.g., o3) to execute subtasks. It acts as an MCP client, orchestrating tools (web search, code execution, etc.) and writing outcomes back to the system.
3. Case Memory: Stores experiences as tuples of (s_T, a_T, r_T) (state, action, reward) for future experience replay.

This approach reframes continual learning as memory-based online reinforcement learning over a memory-augmented MDP.

For Parametric Memory features, it is highly recommended to install PyTorch with GPU support. Choose the command corresponding to your CUDA version.

# CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CUDA 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# CPU only
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

Parametric Memory allows the agent to learn from past experiences using a trained neural retriever model. This is an advanced mode involving three steps:

1. Train the Memory Retriever: Use train_memory_retriever.py with your training data.
2. Configure Environment: Set the RETRIEVER_MODEL_PATH and memory parameters in your .env file.
3. Run the Agent: Execute parametric_memory.py from the client directory.

# Step 1: Train the retriever
cd memory
python train_memory_retriever.py \
  --train training_data.jsonl \
  --output_dir ./ckpts/retriever \
  --use_plan \
  --val_ratio 0.1 \
  --batch_size 32 \
  --lr 2e-5 \
  --epochs 10 \
  --save_best

# Step 2: Run the agent (after configuring .env)
cd client
python parametric_memory.py

If you already have a reverse proxy (e.g., Nginx, HAProxy) running, use this method:

1. Complete the initial setup steps.
2. Modify docker-compose.yaml to remove Caddy-related components (the caddy service and its volumes).
3. Configure your existing reverse proxy to point to the searxng service port (defaults to 8080).
4. Manage TLS certificates within your own reverse proxy.
5. Run the stack:

   docker compose up -d

**Note:** You can change the port the `searxng` container listens on by setting the `BIND_ADDRESS` environment variable (defaults to `0.0.0.0:8080`) inside `docker-compose.yaml`.

If you prefer using standard Python tools, you can install Memento using pip and a requirements.txt file.

1. Clone the repository.
2. Create and activate a virtual environment.
3. Install dependencies via pip install -r requirements.txt.

# Clone repository
git clone https://github.com/Agent-on-the-Fly/Memento
cd Memento

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

To update your installation to the latest version, pull the latest repository changes and pull the new Docker images:

git pull
docker compose pull
docker compose up -d

For older installations using docker-compose (v1), use:

git pull
docker-compose pull
docker-compose up -d

The fastest and most modern way to install Memento is using uv. This method automatically handles dependency syncing and virtual environment creation.

1. Clone the repository.
2. Install uv if you haven't already.
3. Run uv sync to set up the environment.
4. Activate the virtual environment.

# Clone repository
git clone https://github.com/Agent-on-the-Fly/Memento
cd Memento

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies and create virtual environment automatically
uv sync

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

To extend the agent's capabilities, you can add new tools by following these steps:

1. Create a new FastMCP server in the server/ directory.
2. Implement your tool functions with proper error handling.
3. Register the tool with the MCP (Model Context Protocol) protocol.
4. Update the client's server list in agent.py to include your new server.

If you want to manage the SearXNG stack via systemctl, follow these steps:

1. Copy the template: cp searxng-docker.service.template searxng-docker.service.
2. Edit WorkingDirectory in searxng-docker.service to match your installation path (default is /usr/local/searxng-docker).
3. Enable the service:

   systemctl enable $(pwd)/searxng-docker.service

4. Start the service:

   systemctl start searxng-docker.service

This method is recommended for beginners as it includes Caddy as a reverse proxy, which automatically handles TLS certificates via Let's Encrypt.

After completing the initial setup (cloning, .env configuration, and secret key generation), simply run:

docker compose up -d

FFmpeg is a required system-level binary for video processing functionality. The ffmpeg-python package depends on it.

# Windows (Conda)
conda install -c conda-forge ffmpeg

# macOS
brew install ffmpeg

# Linux (Debian/Ubuntu)
sudo apt-get update && sudo apt-get install ffmpeg