Configuration reference

Use mama init to create a configuration, then change non-secret settings in ~/.mama/config.yaml and ~/.mama/connectors.json. Rotate credentials with mama secret set <NAME> in a terminal. Restart the daemon to apply config edits. The owner can change timezone live in chat with owner.timezone.set; development-memory settings are separate.

config.yaml

The runtime requires version, agent, database and logging. Unknown keys are logged as ignored in W1; they do not configure features. A telegram.token key is an error, even if empty. Move that value using mama secret set MAMA_TELEGRAM_TOKEN, then remove the YAML key. telegram.owner_user_ids is also rejected: remove it and run mama register-owner <telegram id> for each owner with the daemon stopped.

telegram.owner_chat_id must be a negative group or supergroup ID, also listed in telegram.allowed_chats. A solo owner creates a group with the bot for common changes. Positive private chat IDs are rejected because every private chat enters its person’s intake and cannot reach the common session.

Key	Meaning and default
version	Required; must be 1.
timezone	IANA time zone for reports, schedules and displayed times; defaults to the machine’s time zone. Owner changes through owner.timezone.set apply without restart.
member_root	Optional absolute directory for team members’ homes: each member’s workspace, downloads and backend homes. It must not overlap HOME, the MAMA home or owner data paths. Required before registering owner people or serving members; active members are admitted in their own Telegram DMs.
tools_root	Absolute directory outside HOME for the document toolkit every session uses; it must not overlap member_root in either direction. On macOS mama tools install defaults it to the Shared folder beside the home folders and adds this key.
agent.backend	Required; claude or codex.
agent.model	Required, nonblank backend model identifier.
agent.effort	low, medium, high, max, or xhigh; default medium. Backend support determines the useful values.
agent.max_turns	Required positive integer. init writes 100.
agent.timeout	Required. How long a turn may go without progress, in milliseconds. Any output from the runtime restarts it (a tool call, its result, a message), so only a single step longer than this stops a working turn. init writes 600000.
agent.max_turn_ms	The longest one turn may run in all, in milliseconds; default 3600000. It always applies, and it is the only stop for a turn that keeps working while agent.run_token_budget is 0.
agent.run_token_budget	Nonnegative integer; default 0 (no budget limit).
agent.codex_home	Optional managed Codex home override; normally ~/.mama/.codex.
agent.codex_cwd	Optional owner workspace override used by the daemon for both backends; normally ~/.mama/workspace. Keep the workspace inside the MAMA data home, outside downloads and connectors; boot refuses an overlap.
agent.codex_sandbox	The parser accepts read-only, workspace-write, and danger-full-access; the owner Codex session requires workspace-write and rejects the other values.
agent.autonomous_web_fetch	Hosts that turns with no person in them (source changes, record orders, reports, notices, personal jobs) may open with web fetch; a host covers its subdomains, and "*" allows every host. Default: none. Web search stays available in every turn, and turns where a person speaks keep web fetch. Claude backend only; Codex has web search only.
agent.tools.mcp_config	Optional path to the Claude owner action MCP configuration; normally ~/.mama/runtime/mama-mcp-config.json. The daemon generates its MAMA entry.
database.path	Required database path. init writes ~/.mama/memory.db.
logging.level	Required; debug, info, warn, or error.
logging.file	Required log path. init writes ~/.mama/logs/daemon.log.
telegram.enabled	Boolean; default false.
telegram.owner_chat_id	Negative group or supergroup ID for the common session; required when Telegram is enabled and must also be in allowed_chats. Private chat IDs are rejected.
telegram.allowed_chats	Array of common group chat IDs; default empty. Active owner-role members are admitted there; personal DMs use the registry.
telegram.polling	Boolean; default true. false disables inbound polling by this instance.
discord.enabled / slack.enabled	Start the Discord or Slack owner gateway. Each enabled gateway requires an owner channel listed in allowed_channels and at least one owner_user_ids entry.
discord.owner_channel_id / slack.owner_channel_id	Channel used for reports, notifications, security alerts, and file delivery when that messenger is selected. It must be allowlisted.
discord.allowed_channels / slack.allowed_channels	Channel IDs from which owner-authored messages may enter the owner session and to which configured delivery may go.
discord.owner_user_ids / slack.owner_user_ids	User IDs accepted as the owner in allowed channels. Other senders are dropped and logged with hashed IDs.
delivery.reports	Messenger for scheduled reports; one of telegram, discord, or slack. Default telegram. The selected gateway must be enabled and configured.
delivery.notifications	Messenger for [notify] results; one of telegram, discord, or slack. Default telegram.
delivery.security_alerts	Messenger for viewer security alerts; one of telegram, discord, or slack. Default telegram.
delivery.interrupted_notice	What the owner is told when a turn on their message was cut off (a timeout or a restart). The turn is not run again; the owner can resend the request. Default: an English notice.
jev.enabled	Lets the owner agent call judge (Jev) to narrow many candidates; default false. Owner text in a judge call goes to the Jev service. Everything works without it.
jev.keyFile	Jev key file for replay and, when enabled, judge; default ~/.mama/jev-key.
jev.vocabFile	Replay vocabulary file; default ~/.mama/backfill/vocab.json.
wiki.enabled	Boolean; default false when the wiki block is present.
wiki.vaultPath	Required when wiki is enabled; vault root.
wiki.wikiDir	Required when wiki is enabled; wiki directory within the vault, or an absolute path.
reports.full_report_hours	Array of hours 0–23 in the configured owner time zone; default [8, 13, 18]. An empty array schedules no full reports.
reports.reminder_start_hour	Hour 0–23 in the configured owner time zone; default 9.
reports.reminder_end_hour	Hour 0–23 in the configured owner time zone; default 21; must be at least the start hour.
reports.daily_hour	Hour 0–23 in the configured owner time zone; default 23. With the wiki enabled, the agent writes that day’s page daily/YYYY-MM-DD.md at this hour; messages later that day are not in it. 0 writes the day that just ended. A report due in the same hour goes first, and a day missed while the daemon was down is written after midnight.

Report hours use the timezone setting. File paths accept ~ and ${HOME}. Most relative paths resolve against the user’s home; a relative wiki.wikiDir stays relative to its vault. See backends and reports for behavior.

connectors.json

The file is an object keyed by connector name: chatwork, slack, trello, kagemusha, calendar, gmail, drive, sheets, notion, obsidian, discord, telegram, imessage, or claude-code. Names are normalized to lowercase; case collisions fail validation. Unknown connector names and unknown fields are logged as ignored. A missing file means no configured connectors.

Field within each connector	Required content
enabled	Boolean.
pollIntervalMinutes	Finite number greater than zero. init writes 5.
channels	Object keyed by source ID. Each entry needs role; supported additional fields are listed below.
channels.<id>.role	truth, hub, deliverable, spoke, reference, or ignore.
channels.<id>.name	Optional display name. Claude Code requires a unique display alias for each selected project directory.
channels.<id>.boardId	Trello board ID.
channels.<id>.folderId	Drive folder ID.
channels.<id>.driveId	Drive shared-drive ID.
channels.<id>.spreadsheetId	Google Sheets spreadsheet ID.
channels.<id>.sheetRange	Google Sheets range including the header row, unless dataRange is set.
channels.<id>.dataRange	Optional Google Sheets data range when headers and rows use separate ranges.
channels.<id>.vaultPath	Obsidian vault path. Each configured channel maps one vault to a channel ID.
auth.type	token, cli, or none.
auth.tokenName	Environment variable name, never its token value; required for Notion, Discord and Telegram source.
auth.cli, auth.cliAuthCommand	Optional CLI authentication metadata; Google connectors use gws and gws auth login.

init uses MAMA_CHATWORK_TOKEN, MAMA_SLACK_TOKEN, MAMA_TRELLO_KEY, MAMA_TRELLO_TOKEN, MAMA_NOTION_TOKEN, MAMA_DISCORD_TOKEN, and MAMA_TELEGRAM_SOURCE_TOKEN as connector secret names. The owner Telegram messenger uses the separate MAMA_TELEGRAM_TOKEN. Gmail, Drive, Sheets, and Calendar use a logged-in gws CLI; Kagemusha uses the read-only local bridge. Claude Code channel keys are selected project directory names and their name values are display aliases. See connectors for per-source setup and channel roles.

Environment and credentials

The generated start.sh exports auth.env for the daemon. That file has mode 0600; the owner agent cannot read it. The daemon removes secret-shaped environment names before launching either owner backend. Pass non-secret service settings through the startup environment.

Variable	Purpose
MAMA_TELEGRAM_TOKEN	Telegram bot credential.
MAMA_TELEGRAM_SOURCE_TOKEN	Separate bot credential used by the Telegram source connector.
MAMA_CHATWORK_TOKEN, MAMA_SLACK_TOKEN	Connector credentials used by generated connector configuration.
MAMA_DISCORD_TOKEN, MAMA_NOTION_TOKEN	Discord and Notion connector credentials.
MAMA_TRELLO_KEY, MAMA_TRELLO_TOKEN	Separate Trello API key and token.
MAMA_AUTH_TOKEN	Viewer API bearer credential.
MAMA_CF_ACCESS_ISSUER, MAMA_CF_ACCESS_AUD	Expected Cloudflare Access issuer and audience for JWT verification. Both must be configured.
MAMA_VIEWER_HOSTNAMES	Comma-separated extra allowed Host names; loopback hosts are already allowed.
MAMA_VIEWER_OWNER_EMAILS	Comma-separated verified emails expected in access monitoring. This flags unfamiliar identities; it does not grant or deny access.
MAMA_API_HOST	Viewer bind address; default 127.0.0.1.
MAMA_API_PORT	Viewer port; default 3847, accepted range 1024–65535.
MAMA_VIEWER_DIR	Optional viewer static-asset directory.
MAMA_PID_FILE	Optional daemon PID-record location.

Sources: runtime parser, daemon wiring, connector parser, initial setup, backend boundary, viewer API.