Configuration

Remind is configured via config files, environment variables, or CLI arguments. Settings resolve with this priority (highest first):

CLI arguments (--llm, --embedding)
Environment variables
Project-local config file (<project>/.remind/remind.config.json)
Global config file (~/.remind/remind.config.json)
Defaults

Config files

Global config

Create ~/.remind/remind.config.json:

json

{
  "llm_provider": "anthropic",
  "embedding_provider": "openai",
  "consolidation_threshold": 5,
  "auto_consolidate": true,

  "anthropic": {
    "api_key": "sk-ant-...",
    "model": "claude-sonnet-4-20250514",
    "ingest_model": "claude-haiku-4-20250414"
  },

  "openai": {
    "api_key": "sk-...",
    "base_url": null,
    "model": "gpt-4.1",
    "embedding_model": "text-embedding-3-small",
    "ingest_model": "gpt-4.1-mini"
  },

  "azure_openai": {
    "api_key": "...",
    "base_url": "https://your-resource.openai.azure.com",
    "deployment_name": "gpt-4",
    "embedding_deployment_name": "text-embedding-3-small",
    "embedding_size": 1536,
    "ingest_deployment_name": "gpt-4-mini"
  },

  "ollama": {
    "url": "http://localhost:11434",
    "llm_model": "llama3.2",
    "embedding_model": "nomic-embed-text",
    "ingest_model": "llama3.2:1b"
  },

  "decay": {
    "enabled": true,
    "decay_interval": 20,
    "decay_rate": 0.1
  },

  "ingest_buffer_size": 4000,

  "hybrid_keyword_weight": 0.3,

  "db_url": null,

  "logging_enabled": false,

  "cli_output_mode": "table",

  "episode_types": ["observation", "decision", "question", "meta", "preference",
                     "outcome", "fact"]
}

You only need to include settings you want to change from defaults. A minimal config:

json

{
  "llm_provider": "anthropic",
  "embedding_provider": "openai",
  "anthropic": { "api_key": "sk-ant-..." },
  "openai": { "api_key": "sk-..." }
}

Project-local config

You can place a remind.config.json inside a project's .remind/ directory to override global settings for that project:

myproject/
├── .remind/
│   ├── remind.config.json   ← project-local config
│   └── remind.db            ← project-local database
└── ...

Project-local config uses the same format as the global config. Settings in the project-local file override the global file, but are themselves overridden by environment variables and CLI arguments.

A typical use case is selecting a different provider or model for a specific project:

json

{
  "llm_provider": "ollama",
  "ollama": { "llm_model": "deepseek-coder-v2" }
}

The CLI automatically reads <cwd>/.remind/remind.config.json. When using the Python API, pass project_dir to create_memory() to enable project-local config loading.

Do not commit secrets

If your project-local config contains API keys or other secrets, make sure .remind/ is in your .gitignore. Better yet, keep secrets in the global config (~/.remind/remind.config.json) or in environment variables, and use the project-local file only for non-sensitive settings like provider choice and model selection.

CLI output mode

cli_output_mode sets the default for browse/list commands (inspect, topics, entities, status, and others): table (human-readable, default), json (full structured stdout), or compact-json (minimal id / title / summary objects, command-specific extras such as mention_count on entities list). In JSON config you can also use the alias cliOutputMode, or set compactJson to a string such as "compact-json" (same normalization as cli_output_mode).

Per command: --json, --compact-json, or --table — at most one (they override the default mode).
Environment: REMIND_CLI_OUTPUT_MODE=table, json, or compact-json.

Environment variables

Every config-file setting has a corresponding environment variable. Environment variables take precedence over both config files.

Complete reference

General

Env variable	Config field	Type	Default
`LLM_PROVIDER`	`llm_provider`	string	`anthropic`
`EMBEDDING_PROVIDER`	`embedding_provider`	string	`openai`
`CONSOLIDATION_THRESHOLD`	`consolidation_threshold`	int	`5`
`CONCEPTS_PER_PASS`	`concepts_per_pass`	int	`64`
`AUTO_CONSOLIDATE`	`auto_consolidate`	bool	`true`
`EXTRACTION_BATCH_SIZE`	`extraction_batch_size`	int	`50`
`EXTRACTION_LLM_BATCH_SIZE`	`extraction_llm_batch_size`	int	`10`
`CONSOLIDATION_BATCH_SIZE`	`consolidation_batch_size`	int	`25`
`LLM_CONCURRENCY`	`llm_concurrency`	int	`3`
`INGEST_BUFFER_SIZE`	`ingest_buffer_size`	int	`4000`
`REMIND_HYBRID_KEYWORD_WEIGHT`	`hybrid_keyword_weight`	float	`0.3`
`REMIND_RECALL_INITIAL_CANDIDATES`	`recall_initial_candidates`	int	`10`
`REMIND_RERANKING_ENABLED`	`reranking_enabled`	bool	`false`
`REMIND_RERANKING_MODEL`	`reranking_model`	string	`cross-encoder/ms-marco-MiniLM-L-6-v2`
`REMIND_DB_URL`	`db_url`	string	`null` (SQLite default)
`REMIND_LOGGING_ENABLED`	`logging_enabled`	bool	`false`
`REMIND_CLI_OUTPUT_MODE`	`cli_output_mode`	string	`table` (`table`, `json`, or `compact-json`; default CLI output for browse/list commands)
`REMIND_EPISODE_TYPES`	`episode_types`	comma-separated list	all built-in types

Anthropic (Claude)

Env variable	Config field	Type	Default
`ANTHROPIC_API_KEY`	`anthropic.api_key`	string	—
`ANTHROPIC_MODEL`	`anthropic.model`	string	`claude-sonnet-4-20250514`
`ANTHROPIC_INGEST_MODEL`	`anthropic.ingest_model`	string	—

OpenAI

Env variable	Config field	Type	Default
`OPENAI_API_KEY`	`openai.api_key`	string	—
`OPENAI_BASE_URL`	`openai.base_url`	string	—
`OPENAI_MODEL`	`openai.model`	string	`gpt-4.1`
`OPENAI_EMBEDDING_MODEL`	`openai.embedding_model`	string	`text-embedding-3-small`
`OPENAI_INGEST_MODEL`	`openai.ingest_model`	string	—

Azure OpenAI

Env variable	Config field	Type	Default
`AZURE_OPENAI_API_KEY`	`azure_openai.api_key`	string	—
`AZURE_OPENAI_API_BASE_URL`	`azure_openai.base_url`	string	—
`AZURE_OPENAI_DEPLOYMENT_NAME`	`azure_openai.deployment_name`	string	—
`AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME`	`azure_openai.embedding_deployment_name`	string	—
`AZURE_OPENAI_EMBEDDING_SIZE`	`azure_openai.embedding_size`	int	`1536`
`AZURE_OPENAI_INGEST_DEPLOYMENT_NAME`	`azure_openai.ingest_deployment_name`	string	—

Ollama (local)

Env variable	Config field	Type	Default
`OLLAMA_URL`	`ollama.url`	string	`http://localhost:11434`
`OLLAMA_LLM_MODEL`	`ollama.llm_model`	string	`llama3.2`
`OLLAMA_EMBEDDING_MODEL`	`ollama.embedding_model`	string	`nomic-embed-text`
`OLLAMA_INGEST_MODEL`	`ollama.ingest_model`	string	—

No API keys needed. Install Ollama and pull models:

bash

ollama pull llama3.2           # LLM
ollama pull nomic-embed-text   # Embeddings

Memory decay

Env variable	Config field	Type	Default
`REMIND_DECAY_ENABLED`	`decay.enabled`	bool	`true`
`REMIND_DECAY_INTERVAL`	`decay.decay_interval`	int	`20`
`REMIND_DECAY_RATE`	`decay.decay_rate`	float	`0.1`

Boolean env vars accept true, 1, yes (case-insensitive) as truthy values; anything else is falsy.

Quick-start examples

Anthropic + OpenAI embeddings (most common):

bash

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

OpenAI for everything:

bash

export OPENAI_API_KEY=sk-...
export LLM_PROVIDER=openai
export EMBEDDING_PROVIDER=openai

Azure OpenAI:

bash

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_API_BASE_URL=https://your-resource.openai.azure.com
export AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4
export AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME=text-embedding-3-small
export LLM_PROVIDER=azure_openai
export EMBEDDING_PROVIDER=azure_openai

Ollama (fully local):

bash

export LLM_PROVIDER=ollama
export EMBEDDING_PROVIDER=ollama

Database

Remind uses SQLite by default but supports any database backend via SQLAlchemy (PostgreSQL, MySQL, etc.).

Database location (SQLite)

Context	Default path
CLI (no `--db` flag)	`<cwd>/.remind/remind.db` (project-local)
CLI with `--db name`	`~/.remind/name.db`
MCP Server / Python API	`~/.remind/{name}.db`

Using PostgreSQL or MySQL

Set db_url in config, the REMIND_DB_URL environment variable, or use the --db CLI flag with a full URL:

bash

# Via environment variable
export REMIND_DB_URL="postgresql+psycopg://user:pass@localhost:5432/remind"

# Via CLI flag
remind --db "postgresql+psycopg://user:pass@localhost:5432/remind" remember "hello"

# Via config file
{
  "db_url": "postgresql+psycopg://user:pass@localhost:5432/remind"
}

Install the appropriate driver extra:

bash

pip install "remind-mcp[postgres]"   # PostgreSQL (psycopg + pgvector)
pip install "remind-mcp[mysql]"      # MySQL (PyMySQL)

Vector search

Remind uses native vector indexes for embedding search when available:

SQLite: sqlite-vec is pulled in as a dependency. When your Python build can load SQLite extensions, Remind loads sqlite-vec and stores embeddings in vec0 virtual tables with cosine-distance KNN.
PostgreSQL: The Python driver is included with remind-mcp[postgres]. Embeddings are stored in vector(N) columns with HNSW indexes. The vector extension is created automatically — but the PostgreSQL server must have pgvector installed (e.g. use the pgvector/pgvector Docker image instead of vanilla postgres).
Fallback: If sqlite-vec cannot be loaded (see below) or pgvector is unavailable, Remind uses brute-force NumPy cosine similarity. Results are the same; large databases may be slower on recall.

Vector tables are created lazily when the first embedding is written. No manual schema setup is needed.

SQLite: when sqlite-vec is not used

sqlite-vec is a loadable extension. Python’s sqlite3 module only exposes enable_load_extension when the interpreter was built against a SQLite library that supports loadable extensions. Many macOS Python builds (including some pyenv installs linked against the system SQLite) omit this, so Remind cannot load sqlite-vec even though the sqlite-vec package is installed. In that case Remind logs an informational message and uses the brute-force path instead of crashing.

Check your interpreter:

bash

python -c "import sqlite3; c=sqlite3.connect(':memory:'); print('load_extension:', hasattr(c, 'enable_load_extension'))"

If this prints load_extension: False, native SQLite vector indexes are unavailable until you use a Python build that supports extension loading.

Typical fix with Homebrew + pyenv (Apple Silicon and Intel; paths come from brew --prefix):

bash

brew install sqlite openssl xz

export PYTHON_CONFIGURE_OPTS="--enable-loadable-sqlite-extensions --with-openssl=$(brew --prefix openssl)"
export LDFLAGS="-L$(brew --prefix sqlite)/lib"
export CPPFLAGS="-I$(brew --prefix sqlite)/include"

pyenv install 3.12.11   # or your target version

Then reinstall Remind into that Python. Alternatively, Homebrew’s python@3.x often works out of the box; create a venv from $(brew --prefix python@3.12)/bin/python3.12 and install Remind there.

See also Retrieval — Vector indexes and the SQLite example.

Memory decay

Concepts that are rarely recalled gradually lose retrieval priority, mimicking how human memory fades.

Option	Default	Description
`decay.enabled`	`true`	Set `false` to disable
`decay.decay_interval`	`20`	Recalls between decay passes
`decay.decay_rate`	`0.1`	How much `decay_factor` drops per interval (0.0-1.0)

When a concept is recalled, it gets rejuvenated — its decay factor gets a boost proportional to match strength. Recently recalled concepts are protected by a 60-second grace window.

View decay stats with remind stats.

Consolidation

Option	Default	Description
`consolidation_threshold`	`5`	Episodes before auto-consolidation triggers
`concepts_per_pass`	`64`	Max concepts included per consolidation LLM pass
`auto_consolidate`	`true`	Whether to auto-consolidate after `remember`
`extraction_batch_size`	`50`	Episodes fetched per extraction loop pass (independent of consolidation batch size)
`extraction_llm_batch_size`	`10`	Episodes grouped into each extraction LLM call
`consolidation_batch_size`	`25`	Episodes fetched and generalized per consolidation loop pass
`llm_concurrency`	`3`	Max concurrent LLM calls across extraction + consolidation; also bounds topic-group parallelism
`fact_cluster_jaccard_threshold`	`0.5`	Min Jaccard similarity between entity sets to cluster facts together. Lower values create larger clusters; higher values create more focused clusters.

Env variable	Config field	Type	Default
`REMIND_FACT_CLUSTER_JACCARD_THRESHOLD`	`fact_cluster_jaccard_threshold`	float	`0.5`

Legacy aliases remain supported: consolidation_concepts_per_pass, entity_extraction_batch_size, and consolidation_llm_concurrency.

Retrieval tuning

Option	Default	Description
`hybrid_keyword_weight`	`0.3`	Blend between embedding similarity and keyword overlap. `0.0` = pure embedding, `1.0` = pure keyword.
`recall_initial_candidates`	`10`	How many initial embedding candidates to fetch before spreading activation and reranking. Increase to 15-20 when using reranking.

The default 0.3 keyword weight means 70% embedding similarity + 30% keyword overlap. This helps surface results with exact term matches that embeddings alone might miss. See Retrieval for details.

Env variable	Config field	Type	Default
`REMIND_HYBRID_KEYWORD_WEIGHT`	`hybrid_keyword_weight`	float	`0.3`
`REMIND_RECALL_INITIAL_CANDIDATES`	`recall_initial_candidates`	int	`10`

Reranking

Cross-encoder reranking rescores retrieval candidates using a model that reads the query and each document together, producing more accurate relevance judgments than embedding similarity alone. Disabled by default — requires installing the rerank extra.

bash

pip install "remind-mcp[rerank]"

Option	Default	Description
`reranking_enabled`	`false`	Enable cross-encoder reranking during recall
`reranking_model`	`cross-encoder/ms-marco-MiniLM-L-6-v2`	Which cross-encoder model to use
`cli_recall_worker_enabled`	`true`	Use a persistent CLI recall worker when reranking is enabled
`cli_recall_worker_idle_seconds`	`600`	Idle timeout before the CLI recall worker exits

Env variable	Config field	Type	Default
`REMIND_RERANKING_ENABLED`	`reranking_enabled`	bool	`false`
`REMIND_RERANKING_MODEL`	`reranking_model`	string	`cross-encoder/ms-marco-MiniLM-L-6-v2`
`REMIND_CLI_RECALL_WORKER_ENABLED`	`cli_recall_worker_enabled`	bool	`true`
`REMIND_CLI_RECALL_WORKER_IDLE_SECONDS`	`cli_recall_worker_idle_seconds`	int	`600`

Enable via config file:

json

{
  "reranking_enabled": true,
  "recall_initial_candidates": 15
}

Or environment variables:

bash

REMIND_RERANKING_ENABLED=true
REMIND_RECALL_INITIAL_CANDIDATES=15

When reranking is enabled, the CLI (remind recall) starts/reuses a local background recall worker automatically so the reranker stays warm between calls. The worker exits after cli_recall_worker_idle_seconds of inactivity.

If worker startup or IPC fails, CLI recall falls back to one-shot in-process recall and still returns results.

The model is loaded lazily on the first recall request that actually runs reranking. See Retrieval — Reranking for details on how reranking interacts with spreading activation.

Auto-ingest

Settings for the ingest() pipeline, which buffers raw text and extracts memory-worthy episodes automatically. The LLM decides directly what's worth remembering -- no numeric density threshold is needed.

Option	Default	Description
`ingest_buffer_size`	`4000`	Character threshold before buffer flushes and triggers triage

Each provider config has an optional ingest_model field (or ingest_deployment_name for Azure) to use a cheaper/faster model for triage without affecting consolidation quality. When unset, triage uses the same model as consolidation.

Provider	Config field	Env var	Example
Anthropic	`anthropic.ingest_model`	`ANTHROPIC_INGEST_MODEL`	`claude-haiku-4-20250414`
OpenAI	`openai.ingest_model`	`OPENAI_INGEST_MODEL`	`gpt-4.1-mini`
Azure OpenAI	`azure_openai.ingest_deployment_name`	`AZURE_OPENAI_INGEST_DEPLOYMENT_NAME`	`gpt-4-mini`
Ollama	`ollama.ingest_model`	`OLLAMA_INGEST_MODEL`	`llama3.2:1b`

Logging

When enabled, Remind writes detailed debug logs to remind.log in the same directory as the database. This includes full LLM prompts and responses for triage, extraction, and consolidation — useful for debugging why episodes were scored a certain way or how concepts were derived.

Option	Default	Description
`logging_enabled`	`false`	Write debug logs to `remind.log` next to the database

The log file location follows the database:

Database path	Log path
`~/.remind/myproject.db`	`~/.remind/remind.log`
`<project>/.remind/remind.db`	`<project>/.remind/remind.log`

Enable via config file:

json

{
  "logging_enabled": true
}

Or environment variable:

bash

REMIND_LOGGING_ENABLED=true

Episode types

Control which episode types are valid for ingestion and storage.

Option	Default	Description
`episode_types`	all built-in types	List of enabled episode types

Built-in types: observation, decision, question, meta, preference, outcome, fact.

By default all types are enabled. To restrict to a subset:

json

{
  "episode_types": ["observation", "decision", "question", "outcome", "fact"]
}

Or via environment variable (comma-separated):

bash

REMIND_EPISODE_TYPES=observation,decision,question,outcome,fact

Custom type names are also accepted — they will be used in LLM prompts for triage and extraction with generic descriptions.

Configuration ​

Config files ​

Global config ​

Project-local config ​

CLI output mode ​

Environment variables ​

Complete reference ​

General ​

Anthropic (Claude) ​

OpenAI ​

Azure OpenAI ​

Ollama (local) ​

Memory decay ​

Quick-start examples ​

Database ​

Database location (SQLite) ​

Using PostgreSQL or MySQL ​

Vector search ​

SQLite: when sqlite-vec is not used ​

Memory decay ​

Consolidation ​

Retrieval tuning ​

Reranking ​

Auto-ingest ​

Logging ​

Episode types ​

Configuration

Config files

Global config

Project-local config

CLI output mode

Environment variables

Complete reference

General

Anthropic (Claude)

OpenAI

Azure OpenAI

Ollama (local)

Memory decay

Quick-start examples

Database

Database location (SQLite)

Using PostgreSQL or MySQL

Vector search

SQLite: when sqlite-vec is not used

Memory decay

Consolidation

Retrieval tuning

Reranking

Auto-ingest

Logging

Episode types