Configuration

MemMachine Configuration

MemMachine’s configuration is managed through a cfg.yml file, which allows for fine-tuning various aspects of the system. The new configuration structure, introduced in v0.2, emphasizes modularity and centralized resource definitions, making it easier to manage and scale your memory solutions. All configuration items are organized under top-level keys in the cfg.yml file. References between components are made using string IDs, promoting reusability and clarity. To see a complete example of a potential cfg.yml file, check out GPU-based Sample Config File.

Configuration Sections

Logging

Manages the path, format, and level of application logging.

Parameters
With Comments

  logging:
    path: mem-machine.log
    level: info #| debug | warning | error | critical
    format: "%(asctime)s [%(levelname)s] %(name)s - %(message)s"

  logging:
    path: mem-machine.log # Path to log file (empty logs to stdout only)
    level: info # Log level: debug, info, warning, error, critical (default: info)
    format: "%(asctime)s [%(levelname)s] %(name)s - %(message)s" # Log format string

Parameters:

Parameter	Description	Default
`path`	The file path to write logs to. If empty, logs are sent to stdout.	`MemMachine.log`
`level`	The minimum level of messages to log.	`info`
`format`	The logging format string. Must include `%(asctime)s`, `%(levelname)s`, and `%(message)s`.	`%(asctime)s [%(levelname)s] %(name)s - %(message)s`

Episode Store

Configuration for the database storing raw episode data.

Parameter
With Comment

episode_store:
  database: profile_storage
  with_count_cache: true

episode_store:
  database: profile_storage # ID of the database from 'resources.databases'
  with_count_cache: true # Enable in-memory episode count caching

Parameters:

Parameter	Description	Default
`database`	The ID of a database defined in `resources.databases` for episode storage.	Required
`with_count_cache`	Whether to maintain an in-memory cache for session message counts.	`true`

Episodic Memory

Configuration for the episodic memory service, which handles event-based memories.

Parameters
With Comments

  episodic_memory:
    session_key: user-session-id
    metrics_factory_id: prometheus
    long_term_memory:
      session_id: user-session-id
      vector_graph_store: my-neo4j-store
      embedder: my-openai-embedder
      reranker: my-rrf-reranker
      message_sentence_chunking: false
    short_term_memory:
      session_key: user-session-id
      llm_model: my-summarization-llm
      summary_prompt_system: episode_summary_system
      summary_prompt_user: episode_summary_user
      message_capacity: 64000
    long_term_memory_enabled: true
    short_term_memory_enabled: true
    enabled: true

episodic_memory:
  session_key: user-session-id # Unique session identifier
  metrics_factory_id: prometheus # Metrics exporter ID
  long_term_memory: # Configuration for long-term memory
    session_id: user-session-id # Reuses parent session_key
    vector_graph_store: my-neo4j-store # ID of the VectorGraphStore from 'resources.databases'
    embedder: my-openai-embedder # ID of the Embedder from 'resources.embedders'
    reranker: my-rrf-reranker # ID of the Reranker from 'resources.rerankers'
    message_sentence_chunking: false # chunk episodes by sentence before embedding
  short_term_memory: # Configuration for short-term memory
    session_key: user-session-id # Reuses parent session_key
    llm_model: my-summarization-llm # ID of the Language Model from 'resources.language_models'
    summary_prompt_system: episode_summary_system # System prompt for summary generation
    summary_prompt_user: episode_summary_user # User prompt for summary generation
    message_capacity: 64000 # Maximum length of short-term memory (default: 64000)
  long_term_memory_enabled: true # Enable long-term memory
  short_term_memory_enabled: true # Enable short-term memory
  enabled: true # Enable episodic memory subsystem

Parameter Descriptions:

Parameter	Description	Default
`session_key`	Unique session identifier for episodic ingestion and context tracking.	Required
`metrics_factory_id`	ID of the metrics exporter factory (e.g., `prometheus`).	`prometheus`
`long_term_memory_enabled`	Whether long-term episodic memory is enabled.	`true`
`short_term_memory_enabled`	Whether short-term episodic memory is enabled.	`true`
`enabled`	Whether episodic memory as a whole is enabled.	`true`
`long_term_memory.vector_graph_store`	The ID of a database defined in `resources.databases` for long-term storage.	Required
`long_term_memory.embedder`	The ID of an embedder defined in `resources.embedders` for creating embeddings.	Required
`long_term_memory.reranker`	The ID of a reranker defined in `resources.rerankers` for search result re-ranking.	Required
`long_term_memory.session_id`	The same `session_key` used for long-term memory operations.	Inherited from `session_key`
`long_term_memory.message_sentence_chunking`	If true, chunk messages into sentences before embedding.	`false`
`short_term_memory.session_key`	Session key for short-term memory summarization.	Inherited from `session_key`
`short_term_memory.llm_model`	The ID of a language model defined in `resources.language_models` for summarization.	Required
`short_term_memory.summary_prompt_system`	System prompt ID for short-term summarization.	Required
`short_term_memory.summary_prompt_user`	User prompt ID for short-term summarization.	Required
`short_term_memory.message_capacity`	The maximum character capacity for short-term memory.	`64000`

Retrieval Agent

Configuration for optional top-level retrieval-agent orchestration used by episodic search when agent_mode=true.

Parameters
With Comments

retrieval_agent:
  llm_model: my-agent-llm
  reranker: my-rrf-reranker

retrieval_agent:
  llm_model: my-agent-llm # ID of the Language Model from 'resources.language_models'
  reranker: my-rrf-reranker # ID of the Reranker from 'resources.rerankers'

Parameter Descriptions:

Parameter	Description	Default
`llm_model`	The language model ID used by retrieval-agent routing/rewrite steps.	Auto-resolved from configured memory models when omitted.
`reranker`	The reranker ID used by retrieval-agent result reranking.	Auto-resolved from episodic long-term-memory reranker when omitted.

Semantic Memory

Configuration for the semantic memory service, which handles declarative, knowledge-based memories.

Parameters
With Comments

semantic_memory:
  enabled: true
  llm_model: my-semantic-llm
  embedding_model: my-openai-embedder
  database: my-postgres-db
  config_database: profile_storage
  with_config_cache: true
  ingestion_trigger_messages: 5
  ingestion_trigger_age: 00:05:00

semantic_memory:
  enabled: true # Controls whether semantic memory is active
  llm_model: my-semantic-llm # ID of the Language Model from 'resources.language_models'
  embedding_model: my-openai-embedder # ID of the Embedder from 'resources.embedders'
  database: my-postgres-db # ID of the database from 'resources.databases'
  config_database: profile_storage # ID of the database to store semantic configs
  with_config_cache: true # Whether to use in-memory semantic config caching
  ingestion_trigger_messages: 5 # Number of un-ingested messages before ingestion runs
  ingestion_trigger_age: 00:05:00 # Time (HH:MM:SS) before ingestion runs when messages are pending

Parameters:

Parameter	Description	Default
`enabled`	Whether semantic memory is enabled. Auto-disabled when required fields are missing.	`true`
`llm_model`	The ID of a language model defined in `resources.language_models` for semantic processing.	Required
`embedding_model`	The ID of an embedder defined in `resources.embedders` for creating embeddings.	Required
`database`	The ID of a database defined in `resources.databases` for semantic storage.	Required
`config_database`	The ID of a database used for semantic configuration metadata.	Required
`with_config_cache`	Whether to use an in-memory cache for semantic memory configurations.	`true`
`ingestion_trigger_messages`	Number of pending messages before semantic ingestion triggers.	`5`
`ingestion_trigger_age`	Max age of pending messages before ingestion triggers (duration in HH:MM:SS).	`00:05:00`

Session Manager

Configuration for the session management database.

Parameter
With Comment

session_manager:
  database: profile_storage

session_manager:
  database: profile_storage # ID of the database from 'resources.databases'

Parameters:

Parameter	Description	Default
`database`	The ID of a database defined in `resources.databases` for session data storage.	Required

Server

API server host and port configuration.

Parameters
With Comments

server:
  host: localhost
  port: 8080

server:
  host: localhost # host to bind MemMachine API server
  port: 8080 # port to bind MemMachine API server

Parameters:

Parameter	Description	Default
`host`	API server interface host.	`localhost`
`port`	API server port.	`8080`

Prompt

Manages the default prompts used by semantic memory for organization and summarization.

Parameter
With Comment

prompt:
  default_org_categories:
    - profile_prompt
  default_project_categories:
    - profile_prompt
  default_user_categories:
    - profile_prompt
  episode_summary_system_prompt_path: default_episode_summary_system_prompt.txt
  episode_summary_user_prompt_path: default_episode_summary_user_prompt.txt

prompt:
  default_org_categories:
    - profile_prompt # Default prompts for organization-level semantic memory
  default_project_categories:
    - profile_prompt # Default prompts for project-level semantic memory
  default_user_categories:
    - profile_prompt # Default prompts for user-level semantic memory
  episode_summary_system_prompt_path: ./prompts/custom_episode_summary_system.txt # Path to system portion of episode summary prompt
  episode_summary_user_prompt_path: ./prompts/custom_episode_summary_user.txt # Path to user portion of episode summary prompt

Parameter Description:

Parameter	Description	Default
`default_org_categories`	List of prompt IDs used for organization-scoped semantic memory.	`[]`
`default_project_categories`	List of prompt IDs used for project-scoped semantic memory.	`["profile_prompt"]`
`default_user_categories`	List of prompt IDs used for user-scoped semantic memory.	`[]`
`episode_summary_system_prompt_path`	Path to the system prompt template for episode summarization.	`""`
`episode_summary_user_prompt_path`	Path to the user prompt template for episode summarization.	`""`

Resources

This section centralizes the definitions of various external resources, which can then be referenced by ID in other parts of the configuration.

Databases

Defines connections to various database backends (Neo4j, PostgreSQL, SQLite).

Parameters
With Comments

resources:
  databases:
    profile_storage:
      provider: postgres
      config:
        host: localhost
        port: 5432
        user: postgres
        db_name: postgres
        password: <YOUR_PASSWORD_HERE>
    my_storage_id:
      provider: neo4j
      config:
        uri: 'bolt://localhost:7687'
        username: neo4j
        password: <YOUR_PASSWORD_HERE>
    sqlite_test:
      provider: sqlite
      config:
        path: sqlite_test.db

resources:
    databases:
      profile_storage:
        provider: postgres # The database provider type: `neo4j`, `postgres`, or `sqlite`
        config: # A dictionary containing provider-specific configuration
          host: localhost # Hostname for the database
          port: 5432 # Port number for the database connection
          user: postgres # Username for database authentication
          db_name: postgres # Database name
          password: <YOUR_PASSWORD_HERE> # Password for database authentication
      my_storage_id: # he specific configuration for the system's internal graph store
        provider: neo4j #The database provider type: `neo4j`, `postgres`, or `sqlite`
        config: # A dictionary containing provider-specific configuration
          uri: 'bolt://localhost:7687' # The URI for the given database
          username: neo4j. # Username for internal graph store authentication
          password: <YOUR_PASSWORD_HERE> # Password for graph store authentication
      sqlite_test: # The configuration for the SQLite database used for testing
        provider: sqlite #The database provider type: `neo4j`, `postgres`, or `sqlite`
        config: # A dictionary containing provider-specific configuration
          path: sqlite_test.db. # The path for the given database

Parameter Descriptions:

Parameter	Description	Default
`provider`	The database provider type: `neo4j`, `postgres`, or `sqlite`.	Required
`config`	A dictionary containing provider-specific configuration.	Required
`config.host`	Hostname for the database (e.g., `localhost`).	Depends on provider
`config.port`	Port number for the database connection.	Depends on provider
`config.user`	Username for database authentication.	Depends on provider
`config.db_name`	Database name (for `postgres`).	Depends on provider
`config.password`	Password for database authentication.	Depends on provider
`config.uri`	The URI for the given database.	Depends on provider
`config.path`	The path for the given database.	Depends on provider
`config.username`	Username for internal graph store authentication.	Depends on provider
`my_storage_id`	The specific configuration for the system’s internal graph store.	Required
`sqlite_test`	The configuration for the SQLite database used for testing.	Required

Embedders

Defines various embedding models, which can be used to generate vector representations of text.

Parameters
With Comments

resources:
  embedders:
    openai_embedder: 
      provider: openai
      config:
        model: "text-embedding-3-small"
        api_key: <YOUR_API_KEY>
        base_url: "https://api.openai.com/v1"
        dimensions: 1536
    aws_embedder_id:
      provider: 'amazon-bedrock'
      config:
        region: "us-west-2"
        aws_access_key_id: <AWS_ACCESS_KEY_ID>
        aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
        model_id: "amazon.titan-embed-text-v2:0"
        similarity_metric: "cosine"
    ollama_embedder: # The embedder Service ID
      provider: openai
      config:
        model: "nomic-embed-text"
        api_key: "EMPTY"
        base_url: "http://host.docker.internal:11434/v1"
        dimensions: 768

  resources:
    embedders:
      openai_embedder: # The embedder ID
        provider: openai # The embedder provider type
        config: # A dictionary containing provider-specific configuration
          model: "text-embedding-3-small" # Model name
          api_key: <YOUR_API_KEY> # API key for OpenAI
          base_url: "https://api.openai.com/v1" # Base URL for OpenAI
          dimensions: 1536 # Defines the length of the vector generated for the input text
      aws_embedder_id: # The embedder ID
        provider: 'amazon-bedrock' # The embedder provider type
        config: # A dictionary containing provider-specific configuration
          region: "us-west-2" # AWS region for Bedrock
          aws_access_key_id: <AWS_ACCESS_KEY_ID> # AWS access key ID for Bedrock
          aws_secret_access_key: <AWS_SECRET_ACCESS_KEY> # AWS secret access key for Bedrock
          model_id: "amazon.titan-embed-text-v2:0" # Bedrock model ID
          similarity_metric: "cosine" # Defines the mathematical method used to compare two vectors for relevance (e.g., cosine).
      ollama_embedder: # The embedder ID
        provider: openai # The embedder provider type
        config: # A dictionary containing provider-specific configuration
          model: "nomic-embed-text" # Model name
          api_key: "EMPTY" # Always "EMPTY" for Ollama
          base_url: "http://host.docker.internal:11434/v1" # Base URL for OpenAI
          dimensions: 768 # Defines the length of the vector generated for the input text

Parameter Descriptions:

Parameter	Description	Default
`Embedder ID`	The embedder ID: `openai_embedder`, `aws_embedder_id`, `ollama_embedder`.	Required
`provider`	The embedder provider type: `openai`, `amazon-bedrock`.	Required
`config`	A dictionary containing provider-specific configuration.	Required
`config.model`	Model name (e.g., `text-embedding-3-small` for OpenAI, `nomic-embed-text` for Ollama).	Depends on provider
`config.api_key`	API key for OpenAI.	Required for OpenAI
`config.base_url`	Base URL for OpenAI.	Required for OpenAI
`config.dimensions`	Defines the length of the vector generated for the input text.	Required for OpenAI
`config.region`	AWS region for Bedrock.	Required for Bedrock
`config.aws_access_key_id`	AWS access key ID for Bedrock.	Required for Bedrock
`config.aws_secret_access_key`	AWS secret access key for Bedrock.	Required for Bedrock
`config.model_id`	Bedrock model ID.	Required for Bedrock
`similarity_metric`	Defines the mathematical method used to compare two vectors for relevance (e.g., cosine).	Required for Bedrock

Language Models

Defines various language models for tasks like summarization and generation.

Parameters
With Comments

resources:
  language_models:
    openai_model:
      provider: openai-responses
      config:
        model: "gpt-4o-mini"
        api_key: <YOUR_API_KEY>
        base_url: "https://api.openai.com/v1"
    aws_model:
      provider: "amazon-bedrock"
      config:
        region: "us-west-2"
        aws_access_key_id: <AWS_ACCESS_KEY_ID>
        aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
        model_id: "openai.gpt-oss-20b-1:0"
    ollama_model:
      provider: openai-chat-completions
      config:
        model: "llama3"
        api_key: "EMPTY"
        base_url: "http://host.docker.internal:11434/v1"

    resources:
      language_models:
        openai_model: # Language Model ID
          provider: openai-responses # The language model provider type
          config: # A dictionary containing provider-specific configuration
            model: "gpt-4o-mini" # Model name
            api_key: <YOUR_API_KEY> # API key for OpenAI.
            base_url: "https://api.openai.com/v1" # The base URL for the model
        aws_model: # Language Model ID
          provider: "amazon-bedrock" # The language model provider type
          config: # A dictionary containing provider-specific configuration
            region: "us-west-2"
            aws_access_key_id: <AWS_ACCESS_KEY_ID> # AWS access key ID for Bedrock
            aws_secret_access_key: <AWS_SECRET_ACCESS_KEY> # AWS secret access key for Bedrock
            model_id: "openai.gpt-oss-20b-1:0" # Bedrock model ID
        ollama_model: # Language Model ID
          provider: openai-chat-completions # The language model provider type
          config: # A dictionary containing provider-specific configuration
            model: "llama3" # Model name
            api_key: "EMPTY" # API key for OpenAI. for Ollama, this is always "EMPTY"
            base_url: "http://host.docker.internal:11434/v1" # The base URL for the model

Parameters for each language model ID (openai_model, aws_model, ollama_model):

Parameter	Description	Default
`provider`	The language model provider type: `openai-responses`, `openai-chat-completions`, `amazon-bedrock`.	Required
`config`	A dictionary containing provider-specific configuration.	Required
`config.model`	Model name (e.g., `gpt-4o-mini` for OpenAI).	Depends on provider
`config.api_key`	API key for OpenAI.	Required for OpenAI
`config.base_url`	The base URL for the model	Depends on provider
`config.region`	AWS region for Bedrock.	Required for Bedrock
`config.aws_access_key_id`	AWS access key ID for Bedrock.	Required for Bedrock
`config.aws_secret_access_key`	AWS secret access key for Bedrock.	Required for Bedrock
`config.model_id`	Bedrock model ID.	Required for Bedrock

Rerankers

Defines various reranking strategies used to reorder search results for improved relevance.

Parameters
With Comments

rerankers:
my_reranker_id:
  provider: "rrf-hybrid"
  config:
    reranker_ids:
      - id_ranker_id
      - bm_ranker_id
      - ce_ranker_id
id_ranker_id:
  provider: "identity"
bm_ranker_id:
  provider: "bm25"
ce_ranker_id:
  provider: "cross-encoder"
  config:
    model_name: "cross-encoder/qnli-electra-base"
aws_reranker_id:
  provider: "amazon-bedrock"
  config:
    region: "us-west-2"
    aws_access_key_id: <AWS_ACCESS_KEY_ID>
    aws_secret_access_key: <AWS_SECRET_ACCESS_KEY>
    model_id: "amazon.rerank-v1:0"

rerankers:
  my_reranker_id: # The reranker and reranker types you specify
    provider: "rrf-hybrid" # The reranker provider type
    config: # A dictionary containing provider-specific configuration
      reranker_ids: # List of reranker IDs to combine for `rrf-hybrid`
        - id_ranker_id # Identity Reranker
        - bm_ranker_id # Best Match Algorithm Reranker
        - ce_ranker_id # Cross-Encoder Reranker
  id_ranker_id:
    provider: "identity" # The reranker provider type
  bm_ranker_id:
    provider: "bm25" # The reranker provider type
  ce_ranker_id:
    provider: "cross-encoder" # The reranker provider type
    config: # A dictionary containing provider-specific configuration
      model_name: "cross-encoder/qnli-electra-base"
  aws_reranker_id:
    provider: "amazon-bedrock" # The reranker provider type
    config: # A dictionary containing provider-specific configuration
      region: "us-west-2" # AWS region for Bedrock
      aws_access_key_id: <AWS_ACCESS_KEY_ID> # AWS access key ID for Bedrock
      aws_secret_access_key: <AWS_SECRET_ACCESS_KEY> # AWS secret access key for Bedrock
      model_id: "amazon.rerank-v1:0" # Bedrock model ID

Parameter Descriptions:

Parameter	Description	Default
`my_reranker_id`	The reranker and reranker types you specify.	Required
`provider`	The reranker provider type: `bm25`, `amazon-bedrock`, `cross-encoder`, `embedder`, `identity`, `rrf-hybrid`.	Required
`config`	A dictionary containing provider-specific configuration.	Required
`config.reranker_ids`	List of reranker IDs to combine for `rrf-hybrid`.	Required for rrf-hybrid
`config.model_name`	Model name for `cross-encoder`.	Depends on provider
`config.embedder_id`	ID of an embedder for `embedder` reranker.	Required for embedder
`config.region`	AWS region for Bedrock.	Required for Bedrock
`config.aws_access_key_id`	AWS access key ID for Bedrock.	Required for Bedrock
`config.aws_secret_access_key`	AWS secret access key for Bedrock.	Required for Bedrock
`config.model_id`	Bedrock model ID.	Required for Bedrock.

Proxy Configuration

If you are deploying MemMachine behind a corporate proxy, you may need to configure it to route traffic through your proxy server and trust custom Certificate Authorities (CAs).

Docker Compose

To configure proxies in a Docker Compose setup, add the HTTP_PROXY, HTTPS_PROXY, and SSL_CERT_FILE environment variables to your service definitions. You may also need to mount a custom CA certificate if your proxy performs SSL inspection. d For an end-to-end example, see sample_configs/env.dockercompose in this repository. The file contains environment settings you can source together with your own docker-compose.yml file. Add the following to your docker-compose.yml for the memmachine service:

services:
  memmachine:
    environment:
      # ... other variables ...
      # Proxy settings
      HTTP_PROXY: ${HTTP_PROXY:-http://proxy.example.com:8080}
      HTTPS_PROXY: ${HTTPS_PROXY:-http://proxy.example.com:8080}
      SSL_CERT_FILE: /app/custom-ca-cert.pem
    volumes:
      # ... other volumes ...
      - ./custom-ca-cert.pem:/app/custom-ca-cert.pem:ro,Z

Standard Installation (Pip/Source)

If you are running MemMachine directly on your host machine (e.g., using pip or from source), simply export the standard environment variables before starting the application.

Linux or MacOS
Windows (PowerShell)

export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export SSL_CERT_FILE="/path/to/custom-ca-cert.pem"

memmachine-server

$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:SSL_CERT_FILE = "C:\path\to\custom-ca-cert.pem"

memmachine-server

Getting Started

Install Guides

Integrations

Tools

Core Concepts

Open Source

MemMachine Configuration

Configuration Sections

Databases

Embedders

Language Models

Rerankers

Proxy Configuration

Docker Compose

Standard Installation (Pip/Source)

Getting Started

Install Guides

Integrations

Tools

Core Concepts

Open Source

​MemMachine Configuration

​Configuration Sections

​Databases

​Embedders

​Language Models

​Rerankers

​Proxy Configuration

​Docker Compose

​Standard Installation (Pip/Source)

MemMachine Configuration

Configuration Sections

Databases

Embedders

Language Models

Rerankers

Proxy Configuration

Docker Compose

Standard Installation (Pip/Source)