MemMachine Configuration
MemMachine’s configuration is managed through acfg.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
Logging
Manages the path, format, and level of application logging.Parameters:
- 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
| 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
Episode Store
Configuration for the database storing raw episode data.Parameters:
- 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
| 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
Episodic Memory
Configuration for the episodic memory service, which handles event-based memories.Parameter Descriptions:
- Parameters
- With Comments
episodic_memory:
session_key: user-session-id
metrics_factory_id: prometheus
long_term_memory:
backend: event
session_id: user-session-id
vector_store: my-vector-store
segment_store: profile_storage
embedder: my-openai-embedder
reranker: my-rrf-reranker
properties_schema:
source_role: str
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
backend: event # Use VectorStore + SegmentStore. Use declarative for VectorGraphStore.
session_id: user-session-id # Reuses parent session_key
vector_store: my-vector-store # ID of the VectorStore from 'resources.databases'
segment_store: profile_storage # ID of the SQL database used by SegmentStore
embedder: my-openai-embedder # ID of the Embedder from 'resources.embedders'
reranker: my-rrf-reranker # ID of the Reranker from 'resources.rerankers'
properties_schema: # Optional filterable event-memory properties
source_role: str
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 | 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.backend | Long-term memory backend. Use event for VectorStore + SegmentStore, or declarative for VectorGraphStore. | declarative when omitted |
long_term_memory.vector_store | Event backend only: ID of a VectorStore defined in resources.databases. | Required for event backend |
long_term_memory.segment_store | Event backend only: ID of a SQL database defined in resources.databases. | Required for event backend |
long_term_memory.vector_graph_store | Declarative backend only: ID of a VectorGraphStore defined in resources.databases. | Required for declarative backend |
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. Event backend can omit it to use embedding scores directly. | Depends on backend |
long_term_memory.session_id | The same session_key used for long-term memory operations. | Inherited from session_key |
long_term_memory.properties_schema | Event backend only: user-defined filterable properties and their type names. | {} |
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
Retrieval Agent
Configuration for optional top-level retrieval-agent orchestration used by
episodic search when Parameter Descriptions:
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 | 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
Semantic Memory
Configuration for the semantic memory service, which handles declarative, knowledge-based memories.Parameters:
- 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
| 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
Session Manager
Configuration for the session management database.Parameters:
- Parameter
- With Comment
session_manager:
database: profile_storage
session_manager:
database: profile_storage # ID of the database from 'resources.databases'
| Parameter | Description | Default |
|---|---|---|
database | The ID of a database defined in resources.databases for session data storage. | Required |
Server
Server
API server host and port configuration.Parameters:
- 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
| Parameter | Description | Default |
|---|---|---|
host | API server interface host. | localhost |
port | API server port. | 8080 |
Prompt
Prompt
Manages the default prompts used by semantic memory for organization and summarization.Parameter Description:
- 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 | 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
Resources
This section centralizes the definitions of various external resources, which can then be referenced by ID in other parts of the configuration.Parameter Descriptions:
Parameter Descriptions:
Parameters for each language model ID (
Parameter Descriptions:
Databases
Defines connections to various database backends. Relational and graph databases store structured memory data; VectorStore providers such as Qdrant, Milvus, SQLiteVectorStore, and SQLiteVec back event-memory and vector-backed semantic-memory indexes.- 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
milvus_vector_store:
provider: milvus
config:
uri: ./memmachine_milvus.db
# uri: https://example.api.gcp-us-west1.zillizcloud.com
# token: $MILVUS_TOKEN
# db_name: default
consistency_level: Session
resources:
databases:
profile_storage:
provider: postgres # Relational database provider
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: # The specific configuration for the internal graph store
provider: neo4j # Graph database provider
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 # Local relational database provider
config: # A dictionary containing provider-specific configuration
path: sqlite_test.db. # The path for the given database
milvus_vector_store: # VectorStore for event or vector-backed semantic memory
provider: milvus # Milvus Lite by default, or Milvus server / Zilliz Cloud
config:
uri: ./memmachine_milvus.db # Local Milvus Lite file path
# token: $MILVUS_TOKEN # Required for Zilliz Cloud or auth-enabled Milvus
# db_name: default # Optional Milvus database name
consistency_level: Session # Strong, Session, Bounded, or Eventually
| Parameter | Description | Default |
|---|---|---|
provider | The database provider type: neo4j, postgres, sqlite, nebula_graph, qdrant, milvus, sqlite_vector_store, or sqlite_vec_vector_store. | 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.token | Milvus auth token for Zilliz Cloud or auth-enabled Milvus server. | "" |
config.consistency_level | Milvus collection consistency level: Strong, Session, Bounded, or Eventually. | Session |
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 | 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
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 | 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 theHTTP_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., usingpip 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

