Configuration engram.toml config file and environment variables
Engram looks for configuration in the following order:
./engram.toml — current directory~/.engram/engram.toml — home directoryDefault values — if no config file found
Environment variables always override file values.
[ database ] path = "~/.engram/memories.db" [ embedding ] provider = "voyage" # voyage | deterministic model = "voyage-code-3" # api_key = "..." # or via ENGRAM_VOYAGE_API_KEY [ llm ] provider = "openai" # openai | local model = "gpt-4o-mini" # api_key = "..." # or via ENGRAM_OPENAI_API_KEY [ server ] socket_path = "~/.engram/engram.sock" reindex_interval_secs = 3600 [ hnsw ] max_connections = 16 ef_construction = 200 ef_search = 40 dimension = 1024 [ consolidation ] stale_days = 90 min_score = 0.3 [ trainer ] trainer_binary = "engram-trainer" trainer_timeout_secs = 300 models_path = "~/.engram/models" Parameter Default Description path~/.engram/memories.dbPath to SQLite database
Parameter Default Description providervoyageEmbedding provider: voyage or deterministic modelvoyage-code-3Embedding model api_key— API key (prefer environment variable) dimension1024Embedding vector dimension
The deterministic provider requires no API key and generates deterministic embeddings from text. Suitable for testing.
Parameter Default Description provideropenaiLLM provider: openai or local modelgpt-4o-miniText generation model api_key— API key (prefer environment variable)
The local provider uses an ONNX model from trainer.models_path for local generation without API calls.
Parameter Default Description socket_path~/.engram/engram.sockUnix socket path reindex_interval_secs3600Reindex interval (seconds, 0 = disabled)
Parameter Default Description max_connections16Maximum connections in HNSW graph ef_construction200Accuracy during index construction ef_search40Accuracy during search dimension1024Vector dimension (must match embedding.dimension)
Parameter Default Description stale_days90Stale record threshold (days) min_score0.3Minimum score for consolidation candidates
Parameter Default Description trainer_binaryengram-trainerTrainer binary path or name trainer_timeout_secs300Trainer execution timeout (seconds) models_path~/.engram/modelsDirectory for ONNX models
Variable Overrides ENGRAM_VOYAGE_API_KEYembedding.api_key (when provider=voyage)ENGRAM_OPENAI_API_KEYllm.api_key (when provider=openai)ENGRAM_DB_PATHdatabase.pathENGRAM_SOCKET_PATHserver.socket_pathENGRAM_EMBEDDING_MODELembedding.modelENGRAM_LLM_MODELllm.modelENGRAM_TRAINER_BINARYtrainer.trainer_binaryENGRAM_TRAINER_TIMEOUTtrainer.trainer_timeout_secsENGRAM_MODELS_PATHtrainer.models_path
~/.engram/ engram.toml # configuration memories.db # SQLite database engram.sock # Unix socket server models/ # ONNX models from trainer *.hnsw # serialized HNSW indexes The engram init command creates the ~/.engram/ directory with default configuration and an empty database. If the directory already exists, init skips creating existing files.