Settings

Choose who writes your notes, what gets saved, and how much memory your agent receives. Most people can keep the defaults. Start with the note-writing service, privacy, and startup memory below; the later sections cover less common setups.

Change a setting

Open the local viewer using the private link printed by the installer, then open Settings. That link authorizes changes on your computer; keep it private. The viewer exposes the common controls, not every option in this reference.

The full settings file is ~/.memindex/settings.json, or settings.json inside your chosen data folder. Add or change entries without replacing the whole file. Values are normally strings, including "true", "false", and numbers. For example:

{
  "MEMINDEX_CONTEXT_OBSERVATIONS": "30",
  "MEMINDEX_QUOTA_FALLBACK_PROVIDER": "off"
}

If your file keeps MemIndex entries inside an env object, edit them there. Most settings accept an environment variable of the same name in preference to the saved value; exceptions are noted below. The tables show fresh-install defaults; the installer or an existing saved choice can replace them. Empty means an empty string, not the word “empty”.

Restart the local service after file or environment changes, and start a fresh agent session to check startup memory. Restarting does not reset a provider's allowance or clear a quota pause. Changing the data folder does not move existing memory: back it up and arrange the move separately before changing that setting. Local settings do not change how MemIndex hosting runs; write to [email protected] for that.

Who writes the notes

Your note-writing service is separate from the agent you work in. Sending activity to a service can use a paid allowance. If fallback is enabled, another configured service can receive that activity too. See Privacy.

Setting	Default	What it does
MEMINDEX_PROVIDER	claude	Chooses the note writer: claude, codex, gemini, openrouter, or openai-compatible.
MEMINDEX_MODEL	claude-haiku-4-5-20251001	Claude model used to write notes, subject to model routing below.
MEMINDEX_PROVIDER_BY_SOURCE	Empty	Picks the note writer for each agent. It is a JSON object, for example {"codex":"codex","claude":"claude"} to write Codex sessions with Codex and Claude Code sessions with Claude. Use the agent names MemIndex shows (claude, codex, cursor, kimi, and so on); claude-code also works for claude. An agent that is not listed uses MEMINDEX_PROVIDER. If a listed writer is not ready, notes fall back to Claude. A value that is not valid JSON is ignored, with a warning in the worker log.
MEMINDEX_OBSERVER_ENABLED	true	false pauses note writing. MemIndex makes no new model calls for notes or summaries. Existing memory, search, and the session-start panel keep working, and the status line reads “notes paused” instead of “MEMORY NOT SAVING”. Activity is not stored while this is off, so turning it back on starts fresh. Work already running when you switch it off finishes.
MEMINDEX_DISABLE_SUMMARY	false	true skips the summary written at the end of a session. This suits scripted and headless runs. Notes are still written.
MEMINDEX_CLAUDE_AUTH_METHOD	subscription	Saved installer/viewer label: subscription, api-key, gateway, or cli. Actual credentials and endpoint choose how Claude authenticates; changing this label alone does not switch accounts or note-writing transport.
CLAUDE_CODE_PATH	Empty	Location of the Claude executable; empty means find it automatically. File or environment only.
MEMINDEX_CLAUDE_CONFIG_DIR	Empty	Claude account/configuration folder for note-writing subprocesses. Empty uses the existing Claude configuration.
MEMINDEX_OBSERVER_CLAUDE_CONFIG_DIR	Empty	Separate folder for note-writer transcripts while credentials stay on the normal profile. Only applies when the preceding override is empty.
MEMINDEX_CODEX_MODEL	Empty	Codex model for note-writing; empty uses Codex's own default.
MEMINDEX_CODEX_PATH	codex	Codex executable. File or environment only.
MEMINDEX_CODEX_REASONING_EFFORT	low	How much reasoning Codex uses: none, minimal, low, medium, high, xhigh, max, ultra, or empty for its default.
MEMINDEX_GEMINI_API_KEY	Empty	Your Gemini credential.
MEMINDEX_GEMINI_API_KEYS	Empty	Extra Gemini credentials, separated by commas or newlines, for rotation when a key cannot serve a request.
MEMINDEX_GEMINI_MODEL	gemini-flash-latest	Gemini model that writes notes.
MEMINDEX_GEMINI_RATE_LIMITING_ENABLED	true	Paces Gemini requests to reduce rate-limit failures.
MEMINDEX_OPENROUTER_API_KEY	Empty	Your OpenRouter credential.
MEMINDEX_OPENROUTER_API_KEYS	Empty	Extra OpenRouter credentials for rotation, separated by commas or newlines.
MEMINDEX_OPENROUTER_MODEL	cohere/north-mini-code:free	Model identifier sent to OpenRouter. Availability and charges depend on the provider.
MEMINDEX_OPENROUTER_BASE_URL	Empty	Alternative chat-service address; empty uses OpenRouter.
MEMINDEX_OPENROUTER_TEMPERATURE	Empty	Optional randomness value sent with requests; empty leaves it to the service.
MEMINDEX_OPENROUTER_SITE_URL	Empty	Optional site attribution sent to OpenRouter.
MEMINDEX_OPENROUTER_APP_NAME	memindex	Application attribution sent to OpenRouter.
MEMINDEX_OPENROUTER_REASONING_EFFORT	Empty	Optional none, minimal, low, medium, or high; applies only to OpenRouter's own service. Empty turns reasoning off, so a reasoning model cannot use up the reply and leave no note. A service that rejects that setting is asked again without it, and MemIndex remembers this for the rest of the run.
MEMINDEX_OPENROUTER_EXTRA_BODY	Empty	JSON object of extra provider request options. File or environment only; do not put secrets in shared examples.
MEMINDEX_OPENAI_COMPAT_PRESET	Empty	Preset for an OpenAI-compatible service: nvidia-nim, deepseek, groq, together, vllm, ollama, or lmstudio. Empty means custom.
MEMINDEX_OPENAI_COMPAT_API_KEY	Empty	Credential for that service, set in the file or environment. It does not reuse the OpenRouter key.
MEMINDEX_OPENAI_COMPAT_API_KEYS	Empty	Extra credentials for that service, separated by commas or newlines.
MEMINDEX_OPENAI_COMPAT_BASE_URL	Empty	Chat-service address, overriding the preset when supplied.
MEMINDEX_OPENAI_COMPAT_MODEL	Empty	Exact model identifier; empty uses the preset's model, if it has one.

Claude credentials and other key names

For Claude API or gateway access, edit .env inside your MemIndex data folder. It uses NAME=value lines, separate from settings.json. The note writer deliberately ignores inherited shell values for the first three names. Keep this file private and restart the worker after changing it.

Credential	Default	What it does
ANTHROPIC_API_KEY	Unset	API credential for Claude note-writing. When no custom endpoint is set, this uses direct API access instead of your signed-in plan.
ANTHROPIC_BASE_URL	Unset	Custom Claude-compatible gateway address. Your normal account token is not forwarded to that gateway. Supply a gateway credential if it needs one.
ANTHROPIC_AUTH_TOKEN	Unset	Bearer credential for the configured Claude service or gateway.
CLAUDE_CODE_OAUTH_TOKEN	Unset	A long-lived token for your Claude plan, made with claude setup-token. MemIndex uses it when your stored Claude login is missing or has expired. A token set in the worker's environment wins over this file.

With no custom endpoint or explicit API credential, Claude note-writing uses your signed-in account credentials. If that login expires, you can sign in again with /login in Claude Code, or run claude setup-token and put the result in ~/.memindex/.env as CLAUDE_CODE_OAUTH_TOKEN=<token>. Sessions that paused because Claude was signed out try again soon after a different token or login appears, without waiting for new activity. MEMINDEX_CLAUDE_CONFIG_DIR selects a different account profile when needed.

Other services also accept credential names without the MEMINDEX_ prefix: GEMINI_API_KEY, GEMINI_API_KEYS, OPENROUTER_API_KEY, OPENROUTER_API_KEYS, OPENAI_COMPAT_API_KEY, and OPENAI_COMPAT_API_KEYS. The local worker reads these names from the credential file when the corresponding main key settings are empty. For a process-environment override, use the full MEMINDEX_ setting name instead. Singular names hold one key; plural names hold extra keys for rotation.

Allowance, fallback, and model routing

Quota thresholds are fractions: 0.93 means 93% used. They reserve allowance for your own work. A provider can still refuse work earlier. Queued work waits during a pause unless an eligible fallback can handle it.

Setting	Default	What it does
MEMINDEX_QUOTA_FALLBACK_PROVIDER	claude	Alternative note writer when the selected service cannot serve requests. Choices: claude, gemini, openrouter, openai-compatible, or off. Empty also means Claude. Claude fallback needs a usable account or key.
MEMINDEX_QUOTA_FALLBACK_MODEL	Empty	Claude model for Claude fallback; empty follows the normal Claude model and routing. Other fallback services ignore this setting.
MEMINDEX_QUOTA_THRESHOLD_FIVE_HOUR	0.95	Pause subscription note-writing at this share of the five-hour allowance.
MEMINDEX_QUOTA_THRESHOLD_SEVEN_DAY	0.93	Pause at this share of the overall weekly allowance.
MEMINDEX_QUOTA_THRESHOLD_SEVEN_DAY_OPUS	0.93	Weekly threshold for the Opus allowance.
MEMINDEX_QUOTA_THRESHOLD_SEVEN_DAY_SONNET	0.92	Weekly threshold for the Sonnet allowance.
MEMINDEX_QUOTA_THRESHOLD_OVERAGE	0.95	Threshold for the reported extra-usage allowance.
MEMINDEX_TIER_ROUTING_ENABLED	true	Lets Claude note-writing choose different models for simpler work and summaries.
MEMINDEX_TIER_SIMPLE_MODEL	haiku	Claude model for simpler work when routing is enabled.
MEMINDEX_TIER_SUMMARY_MODEL	Empty	Claude model for session summaries; empty uses the main model.
MEMINDEX_TIER_FAST_MODEL	haiku	Model used by the $TIER:fast model alias.
MEMINDEX_TIER_SMART_MODEL	sonnet	Model used by the $TIER:smart model alias.
MEMINDEX_MAX_CONCURRENT_AGENTS	2	Maximum simultaneous Claude note-writing subprocesses.
MEMINDEX_CODEX_MAX_CONCURRENT_AGENTS	2	Maximum simultaneous Codex note-writing sessions.
MEMINDEX_CODEX_OBSERVATION_BATCH_SIZE	8	Maximum queued tool events bundled into one Codex request.
MEMINDEX_CODEX_OBSERVATION_BATCH_MAX_CHARS	32000	Character budget for a Codex event batch.
MEMINDEX_OBSERVER_MAX_CONVERSATION_CHARS	400000	Starts a fresh note-writing conversation after this character budget is reached.
MEMINDEX_OBSERVER_CONTEXT_WINDOW	Empty	Model capacity in tokens; empty detects it automatically. Helps keep requests within the model's input limit.
MEMINDEX_OBSERVER_MAX_OUTPUT_TOKENS	4096	Maximum reply size for HTTP note-writing requests.
MEMINDEX_OBSERVE_BARE_PROMPTS	false	When enabled, sends a prompt alone for note-writing. Normally it travels with the next tool event, reducing requests.
MEMINDEX_LLM_TIMEOUT_MS	180000	Per-attempt wait in milliseconds for non-streaming note-writing requests.
MEMINDEX_LLM_STREAM_IDLE_TIMEOUT_MS	90000	Maximum silence during a streamed reply; accepts 1000–300000 milliseconds. Streaming also has an overall five-minute cap.
MEMINDEX_FIELD_OPTIMIZE_TIMEOUT_MS	180000	Wait in milliseconds for shortening oversized note fields.

What gets recorded

These controls affect supported capture paths. They do not erase earlier notes or the agent's own history.

Setting	Default	What it does
MEMINDEX_EXCLUDED_PROJECTS	Empty	Comma-separated folder-name or path patterns to leave out of capture.
MEMINDEX_PROJECT_NAME_SOURCE	path	path names a project from its folder/Git root; git-remote uses the origin's organization/repository name. Changing it can change which project you see.
MEMINDEX_PROJECT_ENVIRONMENTS	[]	JSON list of { "name": "shared-name", "patterns": ["folder-pattern"] } groups. Matching folders share that project name.
MEMINDEX_SKIP_TOOLS	ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion	Comma-separated tool names to leave out of tool observations.
MEMINDEX_SKIP_BASH_PATTERNS	Empty	Regular expression for shell commands to skip. Empty adds no command filter.
MEMINDEX_SKIP_SUBAGENT_OBSERVATIONS	false	Skips observations identified as subagent work when enabled.
MEMINDEX_SKIP_AGENT_TYPES	Empty	Comma-separated subagent types to skip.
MEMINDEX_CAPTURE_ADVISOR_CALLS	false	Saves Claude Code advisor replies from the transcript at turn end, locally.
MEMINDEX_TRANSCRIPTS_ENABLED	true	Enables configured conversation-file watchers. Does not itself add a watcher.
MEMINDEX_TRANSCRIPTS_CONFIG_PATH	~/.memindex/transcript-watch.json	Watcher configuration file. The default is under the home folder; set it explicitly when using a different location.
MEMINDEX_CODEX_TRANSCRIPT_INGESTION	false	Opts into full capture from configured native Codex conversation-file watches. Usually unnecessary because native hooks capture main sessions.
MEMINDEX_CODEX_SUBAGENT_INGESTION	false	Opts into capture from Codex subagent conversation files when a matching watch exists. Can increase note-writing usage. The skip-subagents setting still applies.
MEMINDEX_MEMORY_WATCH_ROOTS	Empty	Opt-in JSON list of up to eight memory folders to import as notes. Each entry needs path and project; platformSource is optional. No folders are watched by default.
MEMINDEX_REDACT_ENABLED	false	Replaces recognized secrets before supported processing paths. It cannot catch every secret.
MEMINDEX_REDACT_DISABLED_BUILTINS	Empty	Comma-separated built-in secret-pattern names to turn off.
MEMINDEX_REDACT_CUSTOM_PATTERNS	[]	JSON list of { "name": "label", "regex": "pattern" } extra secret filters.
MEMINDEX_REDACT_LOG_MATCHES	false	Logs filter names and match counts, without the matched text.
MEMINDEX_TOOL_USES_RETENTION_DAYS	0	0 keeps stored tool events. A positive number removes older events already linked to saved notes at worker startup. It does not remove the notes.

Modes and languages

A mode decides what MemIndex writes down and in which language. Set it with MEMINDEX_MODE in settings.json, then restart the local service (npx memindex restart). New notes use the new mode; notes you already have stay as they were.

{
  "MEMINDEX_MODE": "code--ko"
}

Mode	What it does
code	The default. Notes in English about software work.
code--chill	Fewer notes. Keeps only what would be painful to rediscover: shipped features, fixed bugs, decisions and their reasons, and gotchas.
personal	For everyday conversations rather than code: people, rules, preferences, commitments and decisions.
code--<language>	The same as code, with notes and summaries written in another language.

Every built-in language mode:

Language	Mode
Arabic	code--ar
Bengali	code--bn
Brazilian Portuguese	code--pt-br
Chinese	code--zh
Czech	code--cs
Danish	code--da
Dutch	code--nl
Finnish	code--fi
French	code--fr
German	code--de
Greek	code--el
Hebrew	code--he
Hindi	code--hi
Hungarian	code--hu
Indonesian	code--id
Italian	code--it
Japanese	code--ja
Korean	code--ko
Norwegian	code--no
Polish	code--pl
Romanian	code--ro
Russian	code--ru
Spanish	code--es
Swedish	code--sv
Thai	code--th
Turkish	code--tr
Ukrainian	code--uk
Urdu	code--ur
Vietnamese	code--vi

Session-start context shows which mode is active as Mode: <name> (<id>). To write your own, use the mode-creator skill, or put a mode file in a modes folder inside your data folder.

Memory at the start of a session

More context uses more of your agent's input budget. These settings shape supported startup-context paths, not the number of notes kept in your database.

Setting	Default	What it does
MEMINDEX_CONTEXT_OBSERVATIONS	50	Number of recent notes offered as startup context. The viewer accepts 1–200.
MEMINDEX_CONTEXT_SESSION_COUNT	10	Number of recent sessions considered for startup context.
MEMINDEX_CONTEXT_FULL_COUNT	0	Number of notes expanded in full rather than shown as short index rows.
MEMINDEX_CONTEXT_FULL_FIELD	narrative	Expanded detail: narrative for the explanation or facts for individual facts.
MEMINDEX_CONTEXT_OBSERVATION_TYPES	Empty	Comma-separated note types to include. Empty uses every type in the active mode.
MEMINDEX_CONTEXT_OBSERVATION_CONCEPTS	Empty	Comma-separated concept tags to include. Empty uses the active mode's tags.
MEMINDEX_CONTEXT_MAIN_AGENT_ONLY	true	Leaves subagent observations out of startup memory; it does not disable their capture.
MEMINDEX_BRANCH_MEMORY_ENABLED	true	Tags each note with the git branch it was written on, ranks the current branch first in startup memory and search, and shows pins in the startup panel. false stops all three.
MEMINDEX_SEND_BRANCH_TO_HOSTING	true	Sends the git branch name to MemIndex hosting with each event, search and startup request so the server can rank by branch. false keeps branch names on your machine: local ranking and pins still work, and hosting receives none.
MEMINDEX_SESSION_START_INCLUDE_ALL_SOURCES	false	When enabled, includes notes from other agent platforms in the same project.
MEMINDEX_CONTEXT_SHOW_READ_TOKENS	false	Shows the estimated cost of reading each note.
MEMINDEX_CONTEXT_SHOW_WORK_TOKENS	false	Shows the work-token counts associated with notes.
MEMINDEX_CONTEXT_SHOW_SAVINGS_AMOUNT	false	Shows an estimated token-saving amount.
MEMINDEX_CONTEXT_SHOW_SAVINGS_PERCENT	true	Shows an estimated token-saving percentage.
MEMINDEX_CONTEXT_SHOW_LAST_SUMMARY	true	Includes the latest session summary.
MEMINDEX_CONTEXT_SHOW_LAST_MESSAGE	false	Includes the latest assistant message where supported.
MEMINDEX_CONTEXT_SHOW_TERMINAL_OUTPUT	true	Prints startup context in the Claude Code terminal as well as supplying it to the agent.
MEMINDEX_REINFORCE_ALPHA	0	0 keeps recency ranking. A positive weight lets repeatedly confirmed older notes rise in startup results.
MEMINDEX_WELCOME_HINT_ENABLED	true	Includes the short getting-started hint in supported context output.
MEMINDEX_MEMORY_INSTRUCTIONS_ENABLED	true	Includes instructions telling the agent how to use MemIndex memory tools.
MEMINDEX_WORK_STATE_ENABLED	true	Enables persistent work lists and their memory tools, and includes open work at startup.
MEMINDEX_ENDLESS_MODE_ENABLED	true	After Claude Code compaction, offers a rendered session record to continue from. Local worker only.
MEMINDEX_MODE	code	Note-writing profile: defines note types, concept tags, and writing instructions. Requires an installed mode.

Recall and project files

Setting	Default	What it does
MEMINDEX_MEMORY_SEARCH_HOOK_ENABLED	true	Adds MemIndex results to supported native memory lookups. Native results remain available.
MEMINDEX_SEMANTIC_INJECT	auto	Adds related past notes when a session starts from a prompt, in supported hook paths. auto turns it on only when MEMINDEX_MODE is personal; true and false always win.
MEMINDEX_SEMANTIC_INJECT_LIMIT	5	Maximum related notes requested per prompt.
MEMINDEX_SEMANTIC_INJECT_FORMAT	narrative	narrative includes explanation text; index provides short rows to expand with memory tools.
MEMINDEX_FOLDER_CLAUDEMD_ENABLED	false	Writes supported project-folder memory summaries to Claude instruction files.
MEMINDEX_FOLDER_USE_LOCAL_MD	false	Uses CLAUDE.local.md instead of CLAUDE.md for those generated summaries.
MEMINDEX_FOLDER_MD_EXCLUDE	[]	JSON list of folder paths to exclude from generated summaries.
MEMINDEX_FOLDER_MD_SKELETON_DENYLIST	[]	JSON list of folder patterns where empty generated summaries should be omitted.
MEMINDEX_FILE_READ_GATE_ENABLED	true (retained key)	Ignored. File reads pass through with their original range; this key cannot make MemIndex block a read. Supplementary history is bounded separately.

Search by meaning

Chroma is the optional search index. Turning it off keeps the saved database and uses database-only search. Remote or API-backed indexing can send memory text to another service.

Setting	Default	What it does
MEMINDEX_CHROMA_ENABLED	true	Enables the index used for search by meaning.
MEMINDEX_CHROMA_MODE	local	local runs the index on this computer; remote connects to an existing Chroma server.
MEMINDEX_CHROMA_HOST	127.0.0.1	Remote index host.
MEMINDEX_CHROMA_PORT	8000	Remote index port.
MEMINDEX_CHROMA_SSL	false	Uses HTTPS for the remote index when enabled.
MEMINDEX_CHROMA_API_KEY	Empty	Credential for the remote index, set in the file or environment.
MEMINDEX_CHROMA_TENANT	default_tenant	Tenant containing the remote collection.
MEMINDEX_CHROMA_DATABASE	default_database	Database containing the remote collection.
MEMINDEX_CHROMA_EMBEDDING_FUNCTION	default	How new collections turn text into search vectors. The default runs locally; openai, cohere, jina, voyageai, and roboflow need vendor credentials and send text to that vendor. Changing it requires re-indexing.
MEMINDEX_CHROMA_UVX_PATH	Empty	Location of uvx, or its folder; empty searches installed uv locations and PATH. File or environment only.
MEMINDEX_CHROMA_PREWARM_TIMEOUT_MS	120000	Startup wait in milliseconds for the index service.
MEMINDEX_CHROMA_MUTATION_TIMEOUT_MS	600000	Maximum wait in milliseconds for index writes.
MEMINDEX_CHROMA_MAX_PENDING_MUTATIONS	5000	Maximum queued index changes; excess writes are deferred to a later backfill.
MEMINDEX_CHROMA_MEMORY_LIMIT_MB	2048	Restarts the local index process tree above this memory limit in MB. 0 disables the cap.
MEMINDEX_SEARCH_RECENCY_DAYS	90	Age window for searches by meaning without explicit dates. 0 searches all ages; explicit date filters take priority.

Duplicate notes

Optional duplicate detection merges notes with the same normalized title and records approximate matches for review. Approximate matches are not automatically merged. These settings tune candidate selection.

Setting	Default	What it does
MEMINDEX_DEDUP_ENABLED	false	Enables normalized-title merging and approximate-match candidates for new observations.
MEMINDEX_DEDUP_COSINE_THRESHOLD	0.80	Similarity needed to flag a possible duplicate for review; higher means stricter matching.
MEMINDEX_DEDUP_IDF_VETO_DF	10	A distinguishing word found in at most this many project notes can rule out an approximate match.
MEMINDEX_DEDUP_MIN_SHARED_TOKENS	2	Minimum shared words before comparing notes.
MEMINDEX_DEDUP_MIN_PROJECT_DOCS	10	Minimum project note count before approximate matching begins.
MEMINDEX_DEDUP_MAX_SCAN	2000	Maximum candidate notes inspected for one insertion.
MEMINDEX_DEDUP_MAX_BACKFILL_ROWS	50000	Maximum project size the duplicate-scan command processes.

Local service and connections

Binding beyond this computer makes read access reachable on the network. Keep the default unless you have arranged the intended access controls. Reading and writing both need the installation's private worker secret; the viewer link supplies it. See Privacy.

Setting	Default	What it does
MEMINDEX_DATA_DIR	~/.memindex	Memory folder. Does not copy or move existing files.
MEMINDEX_WORKER_HOST	127.0.0.1	Address on which the local service listens. localhost is normalized to 127.0.0.1.
MEMINDEX_WORKER_PORT	Per-user port	38700 plus your numeric user ID modulo 100; 38777 when no user-ID function exists. Use the installer or doctor output to find yours.
MEMINDEX_WORKER_AUTOSTART	true	Lets hooks and memory tools start the worker. When false, use an externally managed worker; the CLI start command will not launch it either.
MEMINDEX_IDLE_EXIT_SEC	0	0 keeps the worker running. A positive value (minimum 60 seconds) allows an idle shutdown only when work and requests have settled; inactive while transcript watches run or autostart is disabled.
MEMINDEX_ALLOWED_ORIGINS	Empty	Comma-separated browser origins allowed to reach the worker beyond the viewer page it serves itself. A page on any other local port, such as a development server, needs its origin listed here. Does not replace the install secret.
MEMINDEX_PUBLIC_URL	Empty	Browser-reachable base address for generated viewer links behind a proxy or port forward. Empty uses a local address.
MEMINDEX_API_TIMEOUT_MS	30000; Windows 45000	Hook HTTP request deadline in milliseconds.
MEMINDEX_SESSION_INIT_TIMEOUT_MS	10000; Windows 7000	Session-initialization request budget in milliseconds, bounded by the host hook's deadline.
MEMINDEX_HOOK_FAIL_LOUD_THRESHOLD	3	Consecutive unreachable-worker hook calls before a one-time session notice. Does not block your agent.
MEMINDEX_LOG_LEVEL	INFO	Detail in logs: DEBUG, INFO, WARN, ERROR, or SILENT. Read from the settings file only; restart to apply.
MEMINDEX_PYTHON_VERSION	3.13	Python version requested for local search tooling.
MEMINDEX_HOSTING_OFFER	true	Shows the hosting offer during installation. Does not enable hosting.
MEMINDEX_TV_TOKEN	Empty	Optional secret for remote read-only observation viewing. Empty disables that special access path. A remote Observation TV that sends this token can still watch without the install secret. Set in file or environment alongside the intended network binding.
MEMINDEX_RUNTIME	worker	worker uses this computer; server sends supported integration requests to MemIndex hosting.
MEMINDEX_SERVER_URL	Per-user local server address	http://127.0.0.1: plus MEMINDEX_SERVER_PORT if set, otherwise 38877 plus your user ID modulo 100 (38954 without a user-ID function). For hosting, set https://memindex.ai.
MEMINDEX_SERVER_API_KEY	Empty	Private server credential.
MEMINDEX_SERVER_PROJECT_ID	Empty	Server project receiving and serving memory.
MEMINDEX_SERVER_BETA_URL	Same per-user address as above	Older address key used only when MEMINDEX_SERVER_URL is empty. Use the current key for new setups.
MEMINDEX_SERVER_BETA_API_KEY	Empty	Older credential key used when the current server-key setting is empty.
MEMINDEX_SERVER_BETA_PROJECT_ID	Empty	Older project key used when the current project setting is empty.
MEMINDEX_AUTH_MODE	api-key	How the server checks keys. Leave it as api-key.
MEMINDEX_CLOUD_SYNC_TOKEN	Empty	Hosting key this computer syncs with. Set by npx memindex sync connect; empty means sync is off.
MEMINDEX_CLOUD_SYNC_USER_ID	Empty	Account the sync key belongs to. Set by npx memindex sync connect.
MEMINDEX_CLOUD_SYNC_HUB_URL	Empty	Address this computer syncs with. Set by npx memindex sync connect.
MEMINDEX_CLOUD_SYNC_DEVICE_ID	Empty	This computer's sync id. Created on first sync.
MEMINDEX_CLOUD_SYNC_DEVICE_NAME	This computer's name	Name shown for this computer in sync status.
MEMINDEX_CLOUD_SYNC_WS	true	true receives other computers' changes as they happen; false checks for them now and then instead.
MEMINDEX_CLOUD_SYNC_CONTENT_BATCH_SIZE	40	Notes sent in each sync request.
MEMINDEX_CLOUD_SYNC_REQUEST_TIMEOUT_MS	90000	How long one sync request may take, in milliseconds.

Turn sync on or off with npx memindex sync connect and npx memindex sync disconnect; npx memindex sync status shows what it is doing. A server connection needs all three current connection values. Missing connection settings can cause a local fallback in supported paths; check the intended server project to confirm memory arrived. See Hosting and plans.

Importing Jira tickets

npx memindex import jira --project KEY turns each ticket into a note in the area jira-<key>. These three settings tell it which Jira site and login to use. The environment variables JIRA_BASE_URL, JIRA_EMAIL and JIRA_API_TOKEN take priority over them. Run it with --dry-run first to see what would be written.

Setting	Default	What it does
MEMINDEX_JIRA_BASE_URL	Empty	Your Jira Cloud site, such as https://yourteam.atlassian.net. It must start with https://.
MEMINDEX_JIRA_EMAIL	Empty	The email of the Atlassian account that owns the API token.
MEMINDEX_JIRA_API_TOKEN	Empty	An Atlassian API token. Hidden in the settings view, never printed, and never saved in a note.

Automatic backups

MemIndex copies your memory database into the snapshots folder inside your memory folder on a schedule.

Setting	Default	What it does
MEMINDEX_SNAPSHOT_ENABLED	true	false stops the automatic copies.
MEMINDEX_SNAPSHOT_INTERVAL_HOURS	24	Hours between copies.
MEMINDEX_SNAPSHOT_KEEP	7	Copies kept; older ones are removed.

Other user controls

These environment switches are outside the main settings file's default list. Set them in the environment of the process that needs them.

Control	Default	What it does
MEMINDEX_DISABLE_TOOL_HOOKS=1	Unset	Disables tool observation and file-context hooks; session and turn-end hooks remain.
MEMINDEX_DISABLE_OBSERVATION=1	Unset	Disables only tool observation hooks.
MEMINDEX_DISABLE_FILE_CONTEXT=1	Unset	Disables supplementary file history and native-memory lookup additions from these hooks. Direct memory search tools remain available.
MEMINDEX_WEDGED_WORKER_UPTIME_S	300	Minimum process age before a launcher may reclaim a nonresponsive worker's port; accepts 60–86400 seconds.
MEMINDEX_ENV_FILE	.env in the data folder	Overrides the local worker credential-file path.
MEMINDEX_SERVER_PORT	Per-user port	Server listen port; defaults to 38877 plus your user ID modulo 100, or 38954 without a user-ID function.
MEMINDEX_HOST_OBSERVER_PORT	Auto-detect	Port of an OpenAI-compatible note writer you already run when using the installer's host-provider choice. Does not start one.
MEMINDEX_TELEMETRY	Off	1, true, or on opts into usage reporting; 0, false, or off disables it. A personal analytics key is also required.
MEMINDEX_TELEMETRY_KEY	Unset	Analytics project key. The package supplies none.
MEMINDEX_TELEMETRY_ERRORS	Enabled only with reporting consent	0, false, or off disables exception reports while leaving other consented usage reports unchanged.
DO_NOT_TRACK	Unset	A nonempty value other than 0 or false disables reporting regardless of other choices.

The viewer also remembers display choices such as theme, selected project, and sidebar visibility. These affect browsing, not capture or model access. Use npx memindex telemetry status, enable, or disable to manage the separate saved reporting preference. Agent-specific configuration belongs with its integration guide.