Skip to main content

​
Installation

Our fastest method to get started with MemMachine is by using Docker and Docker Compose. This approach bundles all necessary components into containers, simplifying the setup process.

​
Prerequisites

Before installing MemMachine, ensure you have the following prerequisites:
  • Python 3.12+ - MemMachine requires Python 3.12 or higher
  • OpenAI API Key - For language models and embeddings
    MemMachine itself is free to install, but please note that tokens are consumed when you use the software.

​
Download and Start Using MemMachine

This method is recommended for most users.
1

Have Docker and Docker Compose Installed

Make sure that you have Docker and Docker Compose installed on your machine.
2

Download MemMachine and Run the Script

  • Windows
  • MacOS
  • Linux
If you’re using Windows, you can use Powershell. If you are using WSL, see the Linux tab.
# One-block install for Windows PowerShell
$latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/MemMachine/MemMachine/releases/latest"; `
$tarballUrl = $latestRelease.tarball_url; `
$destination = "MemMachine"; `
if (Test-Path $destination) { Remove-Item $destination -Recurse -Force }; `
New-Item -ItemType Directory -Force -Path $destination; `
Invoke-WebRequest -Uri $tarballUrl -OutFile "MemMachine-latest.tar.gz"; `
tar -xzf "MemMachine-latest.tar.gz" -C $destination --strip-components=1; `
Set-Location $destination; `
./memmachine-compose.sh
That’s it! The script will walk you through all of the remaining steps and check the health of your memmachine installation and configuration.
3

The MemMachine-compose.sh Script

The MemMachine-compose.sh script does more than simply install memmachine, although that is it’s default behavior. As the commands associated with this script (shown below) describe, it can be used for stopping, restarting, viewing logs, and cleaning up your memmachine installation.
  ./memmachine-compose.sh --help
    MemMachine Docker Startup Script

    Usage: ./memmachine-compose.sh [command]

    Commands:
      (no args) | start [<image>:<tag>]                      Start MemMachine services
      stop                                                   Stop MemMachine services
      restart                                                Restart MemMachine services
      logs                                                   Show service logs
      clean                                                  Remove all services and data
      build [<image>:<tag>] [--gpu true/false] [-f|--force]  Build a custom MemMachine image
      help                                                   Show this help message

​
Hello World Examples

Validate that your installation is working by following one of the examples below. Each example demonstrates how to add, search, and delete memory episodes using different interfaces: RESTful API, MCP Server, and Python SDK.
  • RESTful API
  • MCP Server
  • PythonSDK

​
Hello World: A Guide to the MemMachine RESTful API

This guide provides a quick and simple way to get started with the MemMachine RESTful API using curl commands.

​
Prerequisites

First, make sure your FastAPI application is running. Open your terminal, navigate to the directory containing your app.py file, and run the following command. The output should confirm that the server is listening for requests.
uvicorn app:app --reload
1

Get All Sessions

The simplest way to start is by checking for existing sessions. This GET request doesn’t require any data. You will likely see an empty list since no sessions have been created yet.
curl http://127.0.0.1:8080/v1/sessions
2

Add a New Memory

This is where you’ll create your first memory episode. The POST /v1/memories endpoint requires a JSON body that includes session details, a producer, a recipient, and the content of the memory itself.Command:
curl -X POST "http://127.0.0.1:8080/v1/memories" \
-H "Content-Type: application/json" \
-d '{
  "session": {
    "group_id": "test_group",
    "agent_id": ["test_agent"],
    "user_id": ["test_user"],
    "session_id": "session_123"
  },
  "producer": "test_user",
  "produced_for": "test_agent",
  "episode_content": "This is a simple test memory.",
  "episode_type": "message",
  "metadata": {}
}'
Expected Output:You will receive an empty 200 OK response, confirming the memory was added successfully.
3

Search for the Memory

Now that a memory has been added, let’s try to find it. The POST /v1/memories/search endpoint also requires a JSON body to specify the search query and session.Command:
curl -X POST "http://127.0.0.1:8080/v1/memories/search" \
-H "Content-Type: application/json" \
-d '{
  "session": {
    "group_id": "test_group",
    "agent_id": ["test_agent"],
    "user_id": ["test_user"],
    "session_id": "session_123"
  },
  "query": "simple test memory",
  "filter": {},
  "limit": 5
}'
Expected Output:You should see a 200 OK response containing the search results, including the memory episode you just added. The output will be formatted as a JSON object, confirming that your memory was successfully found.
4

Delete the Session Data

To clean up after your test, you can use the DELETE /v1/memories endpoint. This also requires a JSON body to specify which session’s data should be removed.Command:
curl -X DELETE "http://127.0.0.1:8080/v1/memories" \
-H "Content-Type: application/json" \
-d '{
  "session": {
    "group_id": "test_group",
    "agent_id": ["test_agent"],
    "user_id": ["test_user"],
    "session_id": "session_123"
  }
}'

​
Troubleshooting

​
Common Issues

  1. Configuration File Names: In some earlier versions of MemMachine, the configuration file within Docker Compose was named configuration.yml. This name still works. However, the preferred name is now cfg.yml.
  2. Neo4j Connection Error: Ensure the Neo4j host in cfg.yml is set to memmachine-neo4j-custom (not localhost)
  3. OpenAI API Key Error: Make sure you have a valid OpenAI API key and it’s correctly set in the cfg.yml file.
  4. Port Access Issues: If you can’t access the API, ensure the MemMachine container is running on the memmachine-network and port 8080 is accessible
  5. Container Network Issues: Make sure both containers are on the same Docker network (memmachine-network)

​
Useful Commands

  • Check container status: docker ps
  • View container logs: docker logs <container_id>
  • Stop containers: docker stop <container_id>
  • Remove containers: docker rm <container_id>