motorhead

Motorhead (DEPRECATED)

Support is no longer maintained for this project.

Motorhead is a memory and information retrieval server for LLMs.

Why use Motorhead?

When building chat applications using LLMs, memory handling is something that has to be built every time. Motorhead is a server to assist with that process. It provides 3 simple APIs:

• GET /sessions/:id/memory returns messages up to MAX_WINDOW_SIZE.

…

• POST /sessions/:id/memory - Send an array of messages to Motorhead to store.

curl --location 'localhost:8080/sessions/${SESSION_ID}/memory' \
--header 'Content-Type: application/json' \
--data '{
    "messages": [{ "role": "Human", "content": "ping" }, { "role": "AI", "content": "pong" }]
}'

Either an existing or new SESSION_ID can be used when storing messages, and the session is automatically created if it did not previously exist.

Optionally, context can be send in if it needs to get loaded from another datastore.

• DELETE /sessions/:id/memory - deletes the session's message list.

A max window_size is set for the LLM to keep track of the conversation. Once that max is hit, Motorhead will process (window_size / 2 messages) and summarize them. Subsequent summaries, as the messages grow, are incremental.

• POST /sessions/:id/retrieval - searches by text query using VSS.

curl --location 'localhost:8080/sessions/${SESSION_ID}/retrieval' \
--header 'Content-Type: application/json' \
--data '{
    "text": "Generals gathered in their masses, just like witches in black masses"
}'

Searches are segmented (filtered) by the session id provided automatically.

Config

• MOTORHEAD_MAX_WINDOW_SIZE (default:12) - Number of max messages returned by the server. When this number is reached, a job is triggered to halve it.
• MOTORHEAD_LONG_TERM_MEMORY (default:false) - Enables long term memory using Redisearch VSS.
• MOTORHEAD_MODEL (default:gpt-3.5-turbo) - Model used to run the incremental summarization. Use gpt-3.5-turbo or gpt-4 - otherwise some weird things might happen.
• PORT (default:8000) - Motorhead Server Port
• OPENAI_API_KEY- Your api key to connect to OpenAI.
• REDIS_URL (required)- URL used to connect to redis.
• OPENAI_API_BASE (default:https://api.openai.com/v1) - OpenAI API Base URL

Azure deployment

Additional Environment Variables are required for Azure deployments:

• AZURE_DEPLOYMENT_ID
• AZURE_DEPLOYMENT_ID_ADA
• AZURE_API_BASE
• AZURE_API_KEY

How to run

With docker-compose:

docker-compose build && docker-compose up

Or you can use the image docker pull ghcr.io/getmetal/motorhead:latest directly:

docker run --name motorhead -p 8080:8080 -e PORT=8080 -e REDIS_URL='redis://redis:6379' -d ghcr.io/getmetal/motorhead:latest

Examples

• Chat JS Example
• Chat JS Vanilla Example
• Chat JS Vanilla Hosted Example
• Chat Python Example