​
Installation

​
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

Download MemMachine.git from GitHub, navigate to the project directory, and run the memmachine-compose.sh script:
$ git clone https://github.com/MemMachine/MemMachine.git
$ cd MemMachine
$ ./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 MemMachine services
    stop       Stop MemMachine services
    restart    Restart MemMachine services
    logs       Show service logs
    clean      Remove all services and data
    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.

​
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:8000/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:8000/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:8000/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:8000/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. Neo4j Connection Error: Ensure the Neo4j host in configuration.yml is set to memmachine-neo4j-custom (not localhost)
  2. OpenAI API Key Error: Make sure you have a valid OpenAI API key and it’s correctly set in both the .env file and configuration.yml
  3. 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
  4. 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>
  • Check available API endpoints: `curl -s http://localhost:8080/openapi.json | jq ‘.paths | keys’