​
Configuring MemMachine

MemMachine has two primary files that are required for operation:
  • config.yaml - This file contains the configuration settings for MemMachine’s Episodic Memory, including database connections, model settings, and memory parameters.
  • .env - This file is used to store environment variables for the MemMachine Server Configuration, such as API keys and sensitive information that should not be hardcoded in the configuration file.

​
Episodic Memory Configuration (config.yaml)

Understanding Configuration Settings You can customize your application’s settings with two types of configuration: Global and Local.
  • Global Configuration acts as the default setting for all your applications. Think of it as your standard setup that everything uses unless told otherwise. This file should reside in your Project root directory.
  • Local Configuration is used when you need to make specific, one-time adjustments for a single session or task. This is best for situations where you have multiple agents, and wish to configure each agent differently. The file should reside in the root directory for each individual agent.
When a local configuration is present, it will take priority and override the global settings, so you can easily make temporary changes without affecting your main setup. The only exception to this is for plugin configurations, which always use the global settings. You can set up both types of configuration using a YAML file.

​
Tailor MemMachine to Your Needs

Check out the following configuration options, an example of how to set, where to set, and a link to more information about the variable options.

​
Long-Term Memory

Parameters that pertain to Long-Term memory settings.
ParameterRequired?DefaultDescription
derivative_deriverNosentenceSets the method for deriving new, insightful information from a memory’s content (can choose identity or sentence).
metadata_derivative_formatNoN/AA template string for formatting derived metadata from memory content. Uses bracket notation to pull properties like user_metadata[source_timestamp] and isolation_properties[producer_id].
embedderNoN/AThe ID of the embedder model to use for generating vector embeddings for long-term memory.
rerankerNoN/AThe ID of the reranker to use for reordering search results to improve relevance.
vector_graph_storeNoN/AThe ID of the storage vendor to use for long-term memory and vector graph storage.
An example of these parameters in a config file would look like the following: 
long_term_memory:
  derivative_deriver: sentence
  metadata_derivative_format: "[{user_metadata[source_timestamp]}] {isolation_properties[producer_id]}: {content}"
  embedder: my_embedder_id
  reranker: my_reranker_id
  vector_graph_store: my_storage_id

​
Session Memory

ParameterRequired?DefaultDescription
model_nameNoN/AThe ID of the model to use for session memory.
message_capacityNo500The maximum number of messages to store in session memory.
max_message_lengthNo16000The maximum length of a message in session memory.
max_token_numNo8000The maximum number of tokens to store in session memory.
An example of these parameters in a config file would look like the following: 
sessionmemory:
  model_name: my_model_id
  message_capacity: 500
  max_message_length: 16000
  max_token_num: 8000

​
Sessiondb

ParameterRequired?DefaultDescription
uriYessqlitetest.dbThe connection URI for the session database. Defaults to an in-memory SQLite database for testing.
An example of these parameters in a config file would look like the following: 
sessiondb:
  uri: sqlitetest.db

​
LLM Model

The LLM Model to be used with the memory system.
ParameterRequired?DefaultDescription
<ID>.model_nameYesN/AThe name of a large language model to use (e.g., gpt-4o-mini).
<ID>.api_keyNoN/AThe API key for the specified model.
An example of these parameters in a config file would look like the following: 
model:
  my_model_id:
    model_name: "gpt-4o-mini"
    api_key: <YOUR_API_KEY>

​
Storage

The Storage database that can be chosen for our Memory to use.
Only graph database is supported at this time
ParameterRequired?DefaultDescription
<ID>.vendor_nameNoneo4jThe name of the database vendor to use (e.g., neo4j).
<ID>.hostNolocalhostThe hostname or IP address of the database server.
<ID>.portNo7687The port number for the database connection.
<ID>.userNoN/AThe username for database authentication.
<ID>.passwordNoN/AThe password for database authentication.
An example of these parameters in a config file would look like the following: 
storage:
  my_storage_id:
    vendor_name: neo4j
    host: localhost
    port: 7687
    user: neo4j
    password: <YOUR_PASSWORD_HERE>

​
Embedder

The Embedder model that we choose to use.
ParameterRequired?DefaultDescription
<ID>.model_vendorYesN/AThe name of an embedding model to use (e.g., text-embedding-3-small).
<ID>.api_keyNoN/AThe API key for the specified embedding model.
<ID>.typeNoN/AThe type of reranker (e.g., rrf-hybrid, identity, bm25, cross-encoder).
<ID>.reranker_idsNoN/AA list of other reranker IDs to combine for hybrid reranking.
<ID>.model_nameYesN/AThe name of a model to use for cross-encoder reranking (e.g., cross-encoder/qnli-electra-base).
An example of these parameters in a config file would look like the following: 
embedder:
  my_embedder_id:
    model_name: "text-embedding-3-small"
    api_key: <YOUR_API_KEY>

​
Reranker

Parameters to set for the chosen Reranker
ParameterRequired?DefaultDescription
typeYesrrf-hybridThe type of reranker you choose to use.
An example of these parameters in a config file would look like the following: 
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"

​
Example Config.YAML File

Below is a complete example of the Config.YAML file that you can use for default settings when deploying MemMachine. This example comes with the MemMachine package within the samples directory. 
long_term_memory:
  derivative_deriver: sentence
  metadata_derivative_format: "[{user_metadata[source_timestamp]}] {isolation_properties[producer_id]}: {content}"
  embedder: my_embedder_id
  reranker: my_reranker_id
  vector_graph_store: my_storage_id

sessiondb:
  uri: sqlitetest.db

model:
  my_model_id:
    model_name: "gpt-4o-mini"
    api_key: <YOUR_API_KEY>
storage:
  my_storage_id:
    vendor_name: neo4j
    host: localhost
    port: 7687
    user: neo4j
    password: <YOUR_PASSWORD_HERE>

sessionmemory:
  model_name: my_model_id
  message_capacity: 500
  max_message_length: 16000
  max_token_num: 8000

embedder:
  my_embedder_id:
    model_name: "text-embedding-3-small"
    api_key: <YOUR_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"

​
MemMachine Server Configuration (.env)

To get the MemMachine Server up and running, we use a simple .env file to manage configuration settings. This approach keeps sensitive information—like database credentials and service URLs—separate from the core codebase. This guide explains each of the required variables. File Location: This file should be saved as .env and placed in the same directory as your app.py file. Reference File: 
# This configuration file should be named as .env
# It must be located under the same directory as the app.py
POSTGRES_HOST="10.0.0.59"
POSTGRES_PORT="5432"
POSTGRES_USER="postgres"
POSTGRES_PASS="YOUR PASSWORD"
POSTGRES_DB="DBNAME"
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="Configuration file of memory"

​
Variable Definitions

Here is a breakdown of each variable in your .env file:
  • POSTGRES_HOST
    • Purpose: Specifies the network address (IP address or hostname) of your PostgreSQL database server.
    • Example: "10.0.0.59" refers to a specific IP on your network.
  • POSTGRES_PORT
    • Purpose: The port number on which the PostgreSQL server is listening for connections. The default port is 5432.
    • Example: "5432"
  • POSTGRES_USER
    • Purpose: The username used to authenticate with the PostgreSQL database.
    • Example: "postgres"
  • POSTGRES_PASS
    • Purpose: The password for the specified PostgreSQL user. Important: Replace "YOUR PASSWORD" with your actual, secure password.
    • Example: "my_s3cr3t_p@ssw0rd"
  • POSTGRES_DB
    • Purpose: The name of the specific database you want to connect to on the PostgreSQL server.
    • Example: "memmachine_db"
  • MCP_BASE_URL
    • Purpose: The base URL for the Model Content Protocol (MCP) service. This is used for internal communication within your MemMachine services.
    • Example: "http://127.0.0.1:8080" is a common local development address.
  • GATEWAY_URL
    • Purpose: The URL for the public-facing gateway or reverse proxy that routes traffic to your API.
    • Example: "http://localhost:8080"
  • FAST_MCP_LOG_LEVEL
    • Purpose: Sets the logging level for the Fast MCP module. This controls the verbosity of the log output. Common levels include INFO, DEBUG, WARNING, ERROR, and CRITICAL.
    • Example: INFO provides general information without excessive detail.
  • MEMORY_CONFIG
    • Purpose: This variable should point to the file path of your memory configuration file, which defines how MemMachine’s memory components are structured and initialized.
    • Example: "config/memory_config.yaml"
You can copy and paste the code above to create your own .env file, making sure to replace placeholder values with your actual configuration details. The same file is also included in the MemMachine package within the samples directory.