​
MemMachine Installation Guide

This guide will walk you through the process of installing MemMachine. We’ll start with the prerequisites you need to get set up, followed by two different installation methods.
1

Gather Your Prerequisites

Before you install the MemMachine software itself, you’ll need to set up a few things. Be sure to note down any passwords or keys you create, as you’ll need them later.

​
A. Core Software

  • Python 3.12+: MemMachine requires Python version 3.12 or newer.
  • PostgreSQL: You will need a local PostgreSQL instance with the pgvector extension. You can find installation instructions on the official PostgreSQL Downloads page. Once installed, create a new database and a user with full privileges for that database.
  • Neo4j: A Neo4j database is required. You can find installation instructions on the official Neo4j Documentation page. After installation, start the Neo4j server and set a password for the default neo4j user.

​
B. Accounts and Keys

  • OpenAI API Key: You will need an OpenAI account to use MemMachine. You can sign up on the OpenAI Platform. You’ll need to generate and copy your API Key for a later step.
MemMachine itself is free to install, but please be aware that using the software consumes tokens from your OpenAI account.
2

Choose Your Installation Method

You can install MemMachine using a Python package manager or by cloning the source code from our GitHub repository.
This is the recommended method for most users who want to add MemMachine to an existing Python environment.To create a python environment(if it does not already exist), you can use venv as follows:
python -m venv memmachine-env
source memmachine-env/bin/activate  # On Windows use `memmachine-env\Scripts\activate`
A. Run the following command in your terminal:
  • If you are using MemMachine in a CPU-only environment, use:
   pip install memmachine
  • If you have an NVIDIA GPU and want to leverage it, use:
pip install memmachine[gpu]
B. Next, install dependencies from NLTK through the following MemMachine command:
memmachine-nltk-setup
This method is for users who want to contribute to the project or run from the latest source code.First, clone the repository and navigate into the project directory:
git clone https://github.com/MemMachine/MemMachine.git
cd MemMachine
Second, Ensure you have a python environment set up. You can use venv, conda, or any other environment manager of your choice.Next, use the uv tool to install all dependencies. If you don’t have uv, you’ll need to install it first.
# If you don't have uv installed, run this command:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Now, install the project dependencies:
uv pip install .
If you wish to run with an NVIDIA GPU, you will need to install dependencies for GPU by using the uv pip install ".[gpu]" command.
3

Create Your Configuration Files

MemMachine uses two files for configuration: a .env file for your database and API credentials and a config.yml file for the application’s behavior.
Create a file named .env in the root of your project and add the following content.You can download this file from our GitHub repository as a template using the following curl command:
curl -o .env https://raw.githubusercontent.com/MemMachine/MemMachine/refs/heads/main/sample_configs/server_config.sample
Below is an example of what the .env file should look like:
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=YOUR_NEO4J_PASSWORD
NEO4J_URI="bolt://localhost:7687"
# Postgres database configuration
POSTGRES_HOST=YOUR_POSTGRES_HOST
POSTGRES_PORT=5432
POSTGRES_USER=YOUR_POSTGRES_USER
POSTGRES_PASSWORD=YOUR_POSTGRES_PASSWORD
POSTGRES_DB=YOUR_POSTGRES_DATABASE
MCP_BASE_URL==[http://127.0.0.1:8080](http://127.0.0.1:8080)
GATEWAY_URL=http://localhost:8080
FAST_MCP_LOG_LEVEL=INFO
MEMORY_CONFIG=config.yml
OPENAI_API_KEY="YOUR_VALID_OPENAI_API_KEY"
Replace the placeholders (e.g., YOUR_NEO4J_PASSWORD) with your actual values.
Create a file named config.yml in the same directory. This file configures the various models and storage options for MemMachine.You can download this file from our GitHub repository as a template using the following curl command:
curl -o cfg.yml https://raw.githubusercontent.com/MemMachine/MemMachine/refs/heads/main/sample_configs/episodic_memory_config.sample
Below is an example of what the config.yml file should look like.
> if you are using a CPU only installation, be sure to comment out cross-encoder lines (46, 51-53) with a ’#’ or remove those lines from your file, as you will not be able to use the cross-encoder reranker in that environment.
logging:
  path: /tmp/memory_log
  level: info

long_term_memory:
  derivative_deriver: sentence
  metadata_prefix: "[$timestamp] $producer_id: "
  embedder: my_embedder_id
  reranker: my_reranker_id
  vector_graph_store: my_storage_id

SessionDB:
  uri: sqlitetest.db

Model:
  testmodel:
    model_vendor: openai
    model_name: "gpt-4o-mini"
    api_key: "YOUR_VALID_OPENAI_API_KEY"

storage:
  my_storage_id:
    vendor_name: neo4j
    host: localhost
    port: 7687
    user: neo4j
    password: YOUR_NEO4J_PASSWORD

sessionMemory:
  model_name: testmodel
  message_capacity: 500
  max_message_length: 16000
  max_token_num: 8000

embedder:
  my_embedder_id:
    model_name: "text-embedding-3-small"
    api_key: "YOUR_VALID_OPENAI_API_KEY"

reranker:
  my_reranker_id:
    type: "rrf-hybrid"
  reranker_ids:
    - id_ranker_id
    - bm_ranker_id
    - ce_ranker_id
  id_ranker_id:
    type: "identity"
  bm_ranker_id:
    type: "bm25"
  ce_ranker_id:
    type: "cross-encoder"
    model_name: "cross-encoder/qnli-electra-base"
Remember to replace the placeholders for your OpenAI API key and Neo4j password in this file as well.
4

Run MemMachine

You’re ready to go! Run these commands from the directory where you’ve installed MemMachine.First, you need to sync the profile schema. This is a one-time command that must be run before the very first time you start the server.
memmachine-sync-profile-schema
Now you can start the MemMachine server. If you have run MemMachine before, you can skip the sync step and go straight to this command:
memmachine-server
You should now have the MemMachine server running.
If you are using Docker to run your databases, ensure they are started and accessible before you try to start MemMachine.