Mnemo, the example bot

A complete bot you run yourself, built on the official TypeScript SDK, and a blueprint for your own. Its README from mnema-talk-mnemo-bot v0.1.15.

Mnemo is an AI helper bot for Mnema Talk. It is self-hosted: you run Mnemo yourself and connect it to the AI provider of your choice with your own API key. Mnema Talk has no AI features of its own; Mnemo is a separate program that uses the bot API, and it is also a blueprint to copy when you write a bot of your own.

Ask it in your community's chat:

  • @Mnemo how many degrees is it in Marbella right now? It checks the live weather.
  • /ask what is 1234 × 5678 / 3? It calculates this exactly instead of guessing.
  • @Mnemo what time is it in Tokyo, and what is 10 miles in km?
  • @Mnemo who wrote The Name of the Rose? It looks this up on Wikipedia and gives the link.
  • @Mnemo which is the best class in WoW? It gives a short, balanced take and says that this is opinion and depends on the patch.

It answers when you mention it, through the /ask command, and in the threads it starts, where it remembers the conversation. Under each answer are the buttons Regenerate (limited, see MNEMO_MAX_REGENERATIONS) and, for /ask, Follow up. How an answer was made is for admins only (/details).


Quick start (5 minutes)

Requires Mnema Talk 3.1.0 or newer: the first release that contains the bot platform (3.1 or later). Older servers have no manifests, buttons or bot SDK, and Mnemo cannot be added to them. Reading attachments needs Mnema Talk 3.3.0 or newer (the first release that lets bots download them); on an older server Mnemo says so instead.

You need a Mnema Talk server on which you are the Owner (or hold Manage bots), an API key from an AI provider (or a local model, see AI providers), and Docker or Node.js 24.

1. Add Mnemo to your server

The file mnemo.manifest.json describes Mnemo: its name, its avatar, the /ask and /details commands, and what it asks for (to see channels, send messages and add reactions, and to receive messages through the GUILD_MESSAGES intent). Build the add link for your server:

git clone https://github.com/mnema-xyz/talk-mnemo-bot.git
cd talk-mnemo-bot
npm ci
npm run add-link -- https://talk.example.org

(npm ci needs Node.js 24. Without it, use the paste option below.)

Open the printed link while you are signed in. Mnema Talk shows what Mnemo asks for. Tick the channels where Mnemo may work (none are ticked at first), then confirm. Mnema Talk shows the bot's token once: copy it.

If you would rather not run npm on that machine, open Admin area > Bots > Add from manifest and paste the contents of mnemo.manifest.json.

The link only carries the manifest, in the part after #, which the browser never sends to the server. Opening the link creates nothing until you confirm.

Headless setup (no browser). The confirm screen calls one endpoint, which you can call yourself as the Owner (or with Manage bots): POST /api/admin/bots/install creates the bot, allows its permissions in the channels you list and returns the token once. The calls need the session cookie of a signed-in admin and an Origin header equal to the server's address:

URL=https://talk.example.org
curl -sS -c jar -H "Origin: $URL" -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"..."}' $URL/api/auth/login
jq -n --slurpfile m mnemo.manifest.json --arg c "<channel id>" \
  '{manifest:$m[0], intents:$m[0].intents, permissions:$m[0].permissions, channel_ids:[$c]}' |
curl -sS -b jar -H "Origin: $URL" -H 'Content-Type: application/json' \
  --data @- $URL/api/admin/bots/install | jq -r .token.secret

Channel ids come from GET /api/channels. Pass the token to Mnemo through MNEMA_TOKEN_FILE rather than the shell history. The name you mention (@bot-...) is in the member list and in the ready line of Mnemo's log.

2. Configure

cp .env.example .env

Fill in three values:

MNEMA_URL=https://talk.example.org   # your server
MNEMA_TOKEN=mnb_...                  # the token from step 1
MNEMO_API_KEY=sk-ant-...             # your Anthropic key (default provider)

Using OpenAI, OpenRouter or a local model instead? See AI providers. No AI account yet? Set MNEMO_PROVIDER=fake and leave the key empty: Mnemo then echoes your question, which checks the connection, the permissions and the buttons without any costs.

3. Run

With Docker, which pulls the published image ghcr.io/mnema-xyz/mnemo (linux/amd64 and linux/arm64):

docker compose up -d
docker compose logs -f mnemo

To build the image from this checkout instead, add the build file: docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build.

Or with Node.js 24:

npm start        # reads .env; variables already in the environment win

The log says "msg":"ready" once Mnemo is connected, and it shows as online in the member list.

4. Ask

In a channel you ticked, write @, pick Mnemo from the list and ask, or type /ask. Nothing happens? See Troubleshooting.

Install on Unraid

Mnemo is a single container with no ports, so it installs from the Community Apps Apps tab like any other app. It needs a Mnema Talk server 3.1 or newer (3.3 or newer to read attachments) on which you are the Owner (or hold Manage bots), for example one installed from the Mnema Talk template.

  1. Create the bot in Talk. Sign in as the Owner and open Admin area > Bots > Add from manifest. Paste the contents of mnemo.manifest.json, confirm, and tick the channels where Mnemo may work (none are ticked at first). Talk shows the bot's token once: copy it now. If you lose it, regenerate it under Admin area > Bots.
  2. Install. In the Apps tab search for Mnemo and click Install.
  3. Fill in the template.
    • Talk server URL: the address your members open, with https://.
    • Bot token: the token from step 1.
    • AI provider and AI API key: anthropic (the default) with your key from the provider's console. For OpenAI choose openai. For a local model choose openai-compatible, enter the Provider base URL (for example http://192.168.1.10:11434/v1 for Ollama) and an AI model name; no key is needed. No AI account yet? Choose fake: Mnemo echoes your question, which checks the connection and permissions at no cost.
    • AI model: leave empty for claude-haiku-5-5 on Anthropic; the other providers need a model name.
    • Daily token budget and the per-minute limits are under Show more settings; the defaults (1,000,000 tokens a day, 5 questions per member and 20 per channel per minute) cost roughly ten cents a day on the default model. See Costs and limits.
  4. Apply, then check the log. The Docker tab's log shows "msg":"ready" once Mnemo is connected, and it appears online in the member list. In a channel you ticked, mention Mnemo or type /ask.

The Appdata path (/mnt/user/appdata/mnemo) holds only the day's token count, so a restart cannot reset the budget. The container runs read-only with all capabilities dropped. To update, use the Docker tab's check for updates; the template follows the 0.1 tag, which carries the patch releases (read the changelog before changing the minor line). Problems: Troubleshooting.

How Mnemo answers

YouMnemo
Mention it in a channel: @mnemo how warm is it in Oslo?Reacts with 👀 while it works, then answers in a thread under your message
Write in a thread that Mnemo started (no mention needed)Answers in the thread and remembers the conversation so far (bounded, see MNEMO_THREAD_*)
Mention it inside somebody else's threadAnswers that one message there, with no earlier context, and does not follow that thread
/ask question:… [private:true]Answers in the channel, or only to you with private
RegenerateWrites a new answer to the same question. Only the person who asked, or an admin (server administrator or MNEMO_ADMIN_USER_IDS), can use it, at most MNEMO_MAX_REGENERATIONS times per answer (default 2; 0 removes the button). Every regeneration counts against the daily budget and the rate limits. The old answer stays but loses its buttons, and the button disappears from the last answer once the limit is reached. An answer about an attachment has no Regenerate: Mnemo does not keep the file, so ask again with it
/details (admins only)Shows you privately which tools were used with which input, which model answered, the tokens used and what was sent to the provider, for the last public answer in the channel. Answers to /ask private:true are never shown
Follow up (under /ask answers)Opens a small form for a follow-up question, which is answered with the earlier question and answer as context
Mention or reply with an attachmentPrompts for consent first, then answers questions about the image or file

Details are an admin matter. /details is restricted to administrators by default (default_member_permissions). Server administrators always have access to /details and can regenerate answers. To give additional members access without granting them full server administrator privileges, set MNEMO_ADMIN_USER_IDS to their user IDs. Anyone else who runs it gets a private refusal and sees nothing. The same facts, without any message text, are in the log at info level (answer_details, details_viewed, details_refused).

Images and file attachments

Mnemo can read images and files attached to the message that mentions it, or to the message it replies to:

  • Consent first: Before downloading or sending anything to an AI provider, Mnemo asks in the channel with Yes, check it and No buttons. The prompt names the file and whose it is (the asker's own, or the author of the message the question replies to). Mnemo reads one file per question, the first attachment of that message, and the prompt says so when there are more. Only the member who asked can answer. After 10 minutes the question expires: the buttons go and the prompt says it expired, so the asker knows to ask again. If using a local model (attachments.local: true / MNEMO_ATTACHMENTS_LOCAL=true), the prompt states that the file stays on this server and will be processed by the local model. Consent can be disabled with MNEMO_ATTACHMENTS_ASK_CONSENT=false.
  • Limits apply: The consent prompt and the accepted answer each count as a question against the member and channel rate limits, and so does a refusal (a file type Mnemo cannot read, a file too large, attachments switched off). Nothing is offered or downloaded once the daily budget is used up. A Yes over the limit is refused privately and the prompt stays, so the asker can try again later.
  • Size limit: Attachments up to MNEMO_ATTACHMENTS_MAX_BYTES are read (10 MB by default, and at most). The size is checked from metadata before downloading; larger files are refused without downloading, and the refusal names the configured limit.
  • Supported types:
    • Images (png, jpeg, webp, gif first frame) are sent to vision-capable models, downscaled automatically to fit provider limits (e.g. Anthropic's 5 MB and 8000 px limit). Images of more than 40 megapixels are not read.
    • PDFs have text extracted (or sent as document blocks to Anthropic). The extraction reads plain text from the PDF's content streams, skips a stream that would inflate to more than 4 MB, and stops once the streams of one file add up to 32 MB (a skipped stream counts with the 4 MB).
    • Text files (txt, md, csv, json, log, and source code) are read as text.
    • Text from a file (a text file or a PDF's extracted text) is cut to 40,000 characters, and the cut is marked.
    • Unsupported files (archives, audio, video) are refused before downloading.
  • Privacy: Attachment data is never written to disk or kept in thread memory. The file goes to the provider only with the question it was accepted for; the thread memory and the answer's record keep the bare question and Mnemo's text answer. Later questions in the thread do not send the file again (asking about it again needs a new consent), and an answer about a file has no Regenerate.

Mnemo ignores other bots and its own messages, never reads a channel's history, and only answers in the channels it was given (narrow them further with MNEMO_ALLOWED_CHANNELS). Long answers are split at Mnema Talk's 4000-character limit, at paragraph boundaries, with code blocks kept intact.

Mnemo only answers. It cannot moderate, change settings, send direct messages or act anywhere else. A bot account on Mnema Talk cannot do these things anyway, and Mnemo asks for no permissions beyond reading and writing in the channels you tick.

Configuration

Settings come from environment variables. Optionally, settings can also come from a JSON file named by MNEMO_CONFIG; environment variables override it. Mnemo checks everything at start and stops with a list of every problem, naming the variable:

Mnemo's configuration has 2 problems:
  - MNEMO_MAX_TOOL_CALLS: Too big: expected number to be <=20
  - MNEMA_TOKEN (or MNEMA_TOKEN_FILE) is required: the bot token from Admin area > Bots

Secrets (MNEMA_TOKEN, MNEMO_API_KEY, MNEMO_SEARCH_API_KEY) come only from the environment, or from a file when you add _FILE to the name (MNEMA_TOKEN_FILE=/run/secrets/mnema_token, for Docker secrets). The config file refuses them. Mnemo never logs them.

Connection and provider

VariableDefaultMeaning
MNEMA_URL(required)Your Mnema Talk server, e.g. https://talk.example.org
MNEMA_TOKEN / _FILE(required)The bot token from Admin area > Bots
MNEMO_PROVIDERanthropicanthropic, openai, openai-compatible or fake
MNEMO_API_KEY / _FILEThe provider's API key; not needed for a local server
MNEMO_MODELclaude-haiku-5-5 for AnthropicRequired for the other providers
MNEMO_BASE_URLThe provider's address; required for openai-compatible
MNEMO_ANTHROPIC_EFFORTlowlow, medium or high: how much the model thinks before answering (Anthropic only)
MNEMO_MAX_OUTPUT_TOKENS4096Upper limit of one model reply
MNEMO_PROVIDER_TIMEOUT_MS60000Limit for one provider call
MNEMO_VISIONtruetrue or false: whether the model supports image input

Tools

VariableDefaultMeaning
MNEMO_TOOLSallComma-separated: weather, calculator, datetime, convert_units, wikipedia, web_search
MNEMO_SEARCH_PROVIDERbrave or tavily; turns on web_search together with the key
MNEMO_SEARCH_API_KEY / _FILEThe search provider's key
MNEMO_MAX_TOOL_CALLS6Tool calls per question; more are refused, and the model answers with what it has
MNEMO_TOOL_TIMEOUT_MS10000Limit for one tool call

Where and how Mnemo answers

VariableDefaultMeaning
MNEMO_ALLOWED_CHANNELS(all it can see)Comma-separated channel IDs
MNEMO_REPLY_IN_THREADtrueAnswer a mention in a thread (false: as a reply in the channel, without thread memory)
MNEMO_SEND_DISPLAY_NAMEfalseTell the provider the asker's display name
MNEMO_ADMIN_USER_IDSnoneComma-separated user IDs that may run /details and regenerate answers (optional; server administrators always have access)
MNEMO_MAX_REGENERATIONS2How often one answer may be regenerated (0 to 10); 0 removes the Regenerate button
MNEMO_THREAD_MAX_TURNS12Messages of a thread that Mnemo remembers (a question and an answer are two)
MNEMO_THREAD_MAX_CHARS12000Characters of a thread that Mnemo remembers; the oldest are dropped first
MNEMO_THREAD_TTL_HOURS24Mnemo forgets a thread that has been quiet for this long
MNEMO_SYSTEM_PROMPTbuilt inThe persona, see Changing the persona
MNEMO_SYSTEM_PROMPT_FILEThe persona from a file

Attachments

VariableDefaultMeaning
MNEMO_ATTACHMENTS_ENABLEDtrueWhether Mnemo can read images and file attachments
MNEMO_ATTACHMENTSAll attachment settings at once, as a JSON object ({"enabled":false}); the single variables in this table override its keys
MNEMO_ATTACHMENTS_MAX_BYTES10485760 (10 MB)Maximum attachment size in bytes (upper bound 10 MB)
MNEMO_ATTACHMENTS_ASK_CONSENTtrueAsk for consent before downloading or forwarding attachments
MNEMO_ATTACHMENTS_PROVIDER_NAME(provider name)Provider name displayed in the consent prompt
MNEMO_ATTACHMENTS_LOCALfalseWhen true, consent prompt indicates the file stays on this server and is processed locally

Limits and budget

VariableDefaultMeaning
MNEMO_MEMBER_LIMIT_PER_MINUTE5Questions per member per minute (0 = no limit)
MNEMO_CHANNEL_LIMIT_PER_MINUTE20Questions per channel per minute (0 = no limit)
MNEMO_DAILY_TOKEN_BUDGET1000000Tokens (input + output) per UTC day (0 = no limit)
MNEMO_DAILY_COST_BUDGET_USD0US dollars per UTC day (0 = no limit)
MNEMO_PRICE_INPUT_PER_MTOKknown for Claude modelsPrice per million input tokens, for the cost budget and the Details note
MNEMO_PRICE_OUTPUT_PER_MTOKknown for Claude modelsPrice per million output tokens

Running

VariableDefaultMeaning
MNEMO_HEALTH_PORT8080Port of the health endpoint (0 = off)
MNEMO_HEALTH_HOST127.0.0.1Address of the health endpoint; 0.0.0.0 to reach it from outside the container
MNEMO_DATA_DIRdata (/data in Docker)Where the day's budget survives a restart
MNEMO_LOG_LEVELinfodebug, info, warn or error
MNEMO_CONFIGA JSON config file

The config file

mnemo.config.example.json shows the format: the same settings in camelCase (maxToolCalls, allowedChannels, ...). Lists are JSON arrays. mnemo.config.schema.json lets your editor check and complete it.

MNEMO_CONFIG=./mnemo.config.json node src/main.ts

AI providers

All providers use the same interface (src/providers/types.ts), and all support tools. Pick one with MNEMO_PROVIDER.

Anthropic (default)

MNEMO_PROVIDER=anthropic
MNEMO_API_KEY=sk-ant-...                 # console.anthropic.com
# MNEMO_MODEL=claude-haiku-5-5           # the default: fast and the cheapest
# MNEMO_MODEL=claude-sonnet-5-5          # better answers, about 20 times the price

Mnemo uses the Messages API with tool use, through Anthropic's official SDK. MNEMO_ANTHROPIC_EFFORT=low (the default) keeps answers quick and cheap; use medium for harder questions.

OpenAI

MNEMO_PROVIDER=openai
MNEMO_API_KEY=sk-...
MNEMO_MODEL=<a current model from your account's model list>

Mnemo uses OpenAI's Responses API with function tools, so every OpenAI model that can call functions works, also those that cannot call tools through Chat Completions (OpenAI's docs name GPT-6 Astra and GPT-6.1 Sol). Nothing is stored at OpenAI between calls (store: false). Pick a small, current model: Mnemo's questions are short, and tools do the exact parts.

Any OpenAI-compatible server

Ollama, LM Studio, vLLM, OpenRouter, LiteLLM and others speak OpenAI's Chat Completions API, which Mnemo uses for them. Set the base URL (the part before /chat/completions) and the model name that the server knows. The model must support tool calling through Chat Completions: GPT-6 Astra and GPT-6.1 Sol do not (OpenAI's docs), so reach those with MNEMO_PROVIDER=openai, not through a proxy.

# Ollama on the same machine (ollama pull <model> first)
MNEMO_PROVIDER=openai-compatible
MNEMO_BASE_URL=http://localhost:11434/v1
MNEMO_MODEL=<model name, e.g. one listed by `ollama list`>

# OpenRouter
MNEMO_PROVIDER=openai-compatible
MNEMO_BASE_URL=https://openrouter.ai/api/v1
MNEMO_API_KEY=sk-or-...
MNEMO_MODEL=<provider/model id from openrouter.ai/models>

# LM Studio: http://localhost:1234/v1, vLLM: http://<host>:8000/v1

Inside Docker, localhost is the container itself. Use http://host.docker.internal:11434/v1 (Docker Desktop, OrbStack) or the host's address to reach a model server on the host.

Fake

MNEMO_PROVIDER=fake answers You asked: … without any AI. Use it to check a new installation, and in the tests.

Tools

The model decides when to use a tool. Every tool's input is validated before it runs. A tool's result is cut to 6000 characters and given to the model as data, never as instructions.

ToolWhat it doesServiceKey
weatherCurrent weather and up to 7 days of forecast for a place ("Marbella", "Springfield, Illinois"), metric or imperialOpen-Meteo forecast and geocodingnone
calculatorExact arithmetic: + - * / ^ mod ! %, parentheses, sqrt, log, trigonometry, round, min, max, pi, e. A small parser written for Mnemo (src/tools/math.ts); it never runs codenonenone
datetimeThe date and time in a place or IANA time zone, and conversion between zones, including daylight saving timeNode's time zone data; Open-Meteo to find a place's zonenone
convert_unitsLength, mass, volume (US and imperial), area, speed, time, data (kB and KiB), pressure, energy, temperature. Not currenciesnonenone
wikipediaThe summary and link of the best matching article, in any language editionWikimedia REST APInone
web_searchTop web results (title, link, snippet), for recent eventsBrave Search API or Tavilyyes; off without one

Questions of taste ("the best class in WoW", "the best phone") are answered from the model's own knowledge, with a short note that the answer is opinion and depends on the version or patch. The default persona asks for this.

Turn tools off with MNEMO_TOOLS, for example MNEMO_TOOLS=calculator,datetime,convert_units for a Mnemo that never contacts outside services.

Privacy: what is sent where

To your AI provider, for each question:

  • the question, without the @mnemo mention;
  • in a thread: the earlier questions and answers of that thread, at most MNEMO_THREAD_MAX_TURNS messages and MNEMO_THREAD_MAX_CHARS characters;
  • after Follow up: the earlier question and answer;
  • the asker's display name, only with MNEMO_SEND_DISPLAY_NAME=true (off by default);
  • the system prompt, the current date and time (UTC), the tool descriptions and the tools' results;
  • when asking about an attachment (with consent granted): the processed image, document, or extracted text for that question only. Attachment bytes are never stored on disk or kept in thread history: later questions in the thread carry only the earlier question text and answers.

When an admin regenerates an answer in a thread, the model sees the admin's display name instead of the asker's (only with MNEMO_SEND_DISPLAY_NAME on).

Mnemo never sends the provider a channel's history, other members' messages outside its threads, user IDs, usernames, avatars, the server's address or your Mnema Talk token. /details shows admins what was sent.

To the tools' services, only the tool's input: the place name for Open-Meteo, the search words for Wikipedia and web search. Mnemo identifies itself with the User-Agent Mnemo/<version> (+<this repository>) and sends nothing else.

Kept by Mnemo, in memory only: the bounded thread conversations (for MNEMO_THREAD_TTL_HOURS, at most 1000 threads; beyond that the quietest thread is forgotten and Mnemo stops answering there without a mention) and what the buttons need (for 24 hours, at most 2000 answers). A restart forgets them. On disk there is only the day's token count (budget.json in MNEMO_DATA_DIR), without any content.

Logs hold events, counts, model and tool names, and attachment sizes and MIME types. They contain no message text, attachment content or secrets.

Your provider's own terms decide what happens to the data it receives (for example, whether it is used for training or how long it is kept). Read them, or use a local model through openai-compatible, so that nothing leaves your network except the tools' lookups.

Costs and limits

You pay your AI provider for tokens. Each question costs one model call, plus one more for each round of tool use. A typical question with one tool round uses roughly 3,000 to 6,000 input tokens (the system prompt and tool descriptions are sent each time) and a few hundred output tokens. On Anthropic, that repeated part is cached and billed at a tenth of the input price after the first call within 5 minutes (see Prompt caching), so busy bots cost less than the figures below; they assume no caching.

With the default claude-haiku-5-5 ($0.10 per million input tokens, $0.50 per million output tokens, list price at the time of writing), that is well under a tenth of a cent per question, roughly a thousand questions or more per US dollar. Larger models cost many times more. Check your provider's current prices.

Prompt caching (Anthropic)

Why. Every model call repeats the same large block: the tool descriptions and the system prompt, thousands of tokens. Anthropic can keep that block cached for 5 minutes. A cached token costs a tenth of the normal input price, and writing it to the cache costs a quarter more once. So the first call of a burst pays slightly more and every call after it, including each round of tool use within one question, is much cheaper. Each read renews the 5 minutes, so a bot that gets a question at least every 5 minutes stays warm. On the default claude-haiku-5-5 this takes most of the input cost out of busy periods.

What you need to do. Nothing: caching is on for the anthropic provider and has no setting. It does not apply to the OpenAI providers. Two things keep it working:

  • Mnemo keeps the system prompt identical for every request. The current time and, with MNEMO_SEND_DISPLAY_NAME=true, the asker's name are sent as a short note in front of the question instead. Answers are unchanged.
  • If you set your own persona (MNEMO_SYSTEM_PROMPT or MNEMO_SYSTEM_PROMPT_FILE), keep it free of anything that changes per request, such as a date or an ID: a changing prompt can never be cached. Prompts shorter than the model's minimum for caching (512 tokens on the Claude 5.5 models, tools included) are not cached and cost the normal price; the default persona with the built-in tools is above it.

How the budgets count it.

SettingCached tokens
MNEMO_DAILY_COST_BUDGET_USDReads at 0.1 times and writes at 1.25 times MNEMO_PRICE_INPUT_PER_MTOK. Models with cheaper reads (Sonnet 5.5 and Opus 5.5 read at 0.05 times) are counted a little too high, never too low.
MNEMO_DAILY_TOKEN_BUDGETCounted in full. A cached token still went through the model, so this budget measures volume; the cost budget measures money.
/detailsShows the full prompt size; the dollar figure uses the cache prices.

How to check that it works. Set MNEMO_LOG_LEVEL=debug. Every Anthropic call then logs one anthropic_cache line:

{"time":"2026-11-13T12:00:00.000Z","level":"debug","msg":"anthropic_cache","model":"claude-haiku-5-5","input_tokens":42,"cache_read_input_tokens":3900,"cache_creation_input_tokens":0,"output_tokens":120}

The first call after a pause of more than 5 minutes writes the cache (cache_creation_input_tokens is large). Calls within the next 5 minutes read it (cache_read_input_tokens is large, cache_creation_input_tokens small). If cache_read_input_tokens stays at 0 across calls, the start of the prompt changes between requests: check a custom persona for dates or IDs.

Guards keep a busy channel or a curious member from running up a bill:

  • Rate limits: 5 questions per member and 20 per channel per minute by default. Over the limit, Mnemo says how long to wait: privately for /ask and the buttons, and once per member and minute for mentions (further mentions in that minute are dropped quietly). Attachment questions count twice: once for the consent prompt and once for the accepted answer.
  • Daily budget: 1,000,000 tokens per UTC day by default (about $0.10 to $0.15 a day on Haiku if it is used up). Set MNEMO_DAILY_COST_BUDGET_USD for a limit in dollars. When it is used up, Mnemo says so and answers again after midnight UTC. Before each model call Mnemo reserves that call's worst case and settles it with the usage the provider reports, so questions asked at the same time do not overshoot it together. The worst case is an estimate: the input at about 3 characters per token for Latin text and one token per character for other scripts (CJK, Cyrillic, ...), plus MNEMO_MAX_OUTPUT_TOKENS. A call that fails or times out is counted at that worst case, because the provider may still bill it. The estimate is generous but not exact, so treat the budget as a firm guard rather than an accounting: the last few thousand tokens of a day can stay unused, and an unusual input could still exceed its estimate. The count survives restarts (budget.json in MNEMO_DATA_DIR).
  • Tool calls: at most MNEMO_MAX_TOOL_CALLS per question, and at most 8 model calls per question in any case.
  • Timeouts: one provider call (MNEMO_PROVIDER_TIMEOUT_MS) and one tool call (MNEMO_TOOL_TIMEOUT_MS).

Set a spending limit in your provider's console as well. Mnemo's budget counts what it is told; the provider's limit is the one that holds even if something goes wrong.

Running in production

  • Docker (Dockerfile): node:24-alpine pinned by digest, production dependencies only, runs as the unprivileged node user, no build step (Node 24 runs the TypeScript sources directly). The docker-compose.yml adds a read-only root file system, drops all capabilities and keeps /data in a volume.

  • Health: GET /healthz on MNEMO_HEALTH_HOST:MNEMO_HEALTH_PORT answers 200 while connected to Mnema Talk and 503 otherwise, with the version, model and the day's token count. The Docker image's HEALTHCHECK uses it.

  • Logs: one JSON object per line on stdout (time, level, msg and fields), ready for Loki, journald or docker compose logs.

  • Shutdown: on SIGTERM or SIGINT Mnemo closes the gateway connection and exits within 10 seconds. Questions in flight at that moment are not answered.

  • Reconnects: the SDK keeps the connection with heartbeats, resumes after short drops and reconnects with backoff.

  • Updates: docker compose pull && docker compose up -d. The image tags are latest, X.Y (follows patch releases) and X.Y.Z (fixed); to pin one set MNEMO_VERSION in .env, for example MNEMO_VERSION=0.1.2. Read the changelog before a new minor version. Your data lives in the mnemo-data volume and survives updates. If you build from a checkout: git pull && docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build. Dependabot keeps the dependencies, the base image and the CI actions current in this repository.

  • Verifying the image: images from 0.1.3 on are signed with cosign, keyless, by this repository's release workflow (earlier images are not signed). Verify with a current cosign:

    cosign verify ghcr.io/mnema-xyz/mnemo:0.1 \
      --certificate-oidc-issuer https://token.actions.githubusercontent.com \
      --certificate-identity-regexp '^https://github\.com/mnema-xyz/(talk-mnemo-bot|mnema-talk-mnemo-bot)/\.github/workflows/release\.yml@refs/(heads/main|tags/v.+)$'
    

    The repository was called mnema-talk-mnemo-bot until 0.1.6; images up to that version are signed under that name, later ones as talk-mnemo-bot. The pattern accepts both.

    The signature belongs to the image digest, not to the tag: cosign verify resolves the tag, and the output shows the digest it checked. For an unattended update, verify the tag and then deploy that digest (ghcr.io/mnema-xyz/mnemo@sha256:...), so nothing can change between the check and the pull.

  • One instance per bot token. Two instances would both answer.

Troubleshooting

SymptomCause and fix
Mnemo exits at once with configuration has N problemsRead the list: each line names the variable to fix
Mnemo exits at start with connect_refused or gateway_closed_for_goodThe log's hint says why. connect_refused: the token was refused (wrong, revoked, the bot disabled or banned: regenerate it in Admin area > Bots). gateway_closed_for_good: the gateway refused the connection, for example code 4014 when the bot may not use GUILD_MESSAGES (allow it in Admin area > Bots). Waiting fixes neither, so Mnemo does not retry
Log repeats connect_failedMnema Talk is not reachable at MNEMA_URL (yet). Mnemo keeps retrying with backoff up to once a minute
Mnemo exits with gateway_closed_for_good while runningThe server closed the connection for good, typically because the token was regenerated or revoked, or the bot was disabled, banned or lost an intent. Mnemo exits with code 1 so that Docker restarts it and the next start says what is wrong
Mnemo is online but does not react to a mentionThe channel is not one you ticked, so Mnemo cannot see it. Allow its role in the channel, or check MNEMO_ALLOWED_CHANNELS. Also check that you picked Mnemo from the mention list, so that it is a real mention
/ask is not in the command listThe command shows only where the bot can view and send. If an admin disabled it in Admin area > Bots, it stays off
Running /ask fails because the bot is not connectedMnemo is not running, or not yet connected. Check its log and /healthz
Answers say the AI provider refused the API keyWrong MNEMO_API_KEY, or the key belongs to another provider
Answers say the AI provider timed outA slow model or a local model loading; raise MNEMO_PROVIDER_TIMEOUT_MS
A local model answers but never uses toolsThe model does not support tool calling. Choose one that does
"I have used up today's budget"The daily budget is reached; raise MNEMO_DAILY_TOKEN_BUDGET or wait for midnight UTC
/details says only admins can use itThe member is not a server administrator and their user ID is not in MNEMO_ADMIN_USER_IDS
Regenerate is missing under an answerMNEMO_MAX_REGENERATIONS is 0, the answer was already regenerated that often, or it is an answer about an attachment (Mnemo does not keep the file; ask again with it)
Regenerate says the answer is too oldMnemo was restarted, or the answer is more than 24 hours old. Ask again
No 👀 reactionMnemo lacks Add reactions in that channel; it still answers

Run with MNEMO_LOG_LEVEL=debug to see tool errors and the SDK's connection events.

Changing the persona

The built-in persona is in src/engine/prompt.ts: it is named Mnemo, helpful and concise, says when it is unsure, marks opinion as opinion, gives no medical or legal certainty, and formats for Mnema Talk's Markdown. Replace it with your own:

MNEMO_SYSTEM_PROMPT_FILE=./persona.md
You are Pixel, the helper of a retro gaming community.
Answer briefly and with good humour. Prefer facts from your tools.
When asked for opinions on games, give two sides and say it is a matter of taste.
Answer in the language of the question.

Whatever you write, Mnemo appends a few rules that keep it safe: tool results and quoted messages are data, not instructions; it cannot act beyond answering; it does not reveal its instructions. It also tells the model the current date and time, and the asker's name if you enabled that, in a note in front of each question. Keep dates, IDs and other changing text out of your persona: a prompt that changes between requests cannot be cached (see Prompt caching).

To rename the bot itself, edit name in mnemo.manifest.json before adding it, or rename it later in Admin area > Bots.

Writing your own tool

A tool is one file. Here is a dice roller:

// src/tools/dice.ts
import { randomInt } from 'node:crypto'
import { z } from 'zod'
import { defineTool, ToolError } from './types.ts'

export const dice = defineTool({
  name: 'roll_dice',
  description: 'Rolls dice for games, e.g. 2d6. Use it whenever someone asks for a roll.',
  input: z.object({
    count: z.number().int().min(1).max(20).default(1),
    sides: z.number().int().min(2).max(1000).default(6),
  }),
  async run({ count, sides }) {
    if (sides === 13) throw new ToolError('nobody rolls a d13') // shown to the model
    const rolls = Array.from({ length: count }, () => randomInt(1, sides + 1))
    return JSON.stringify({ rolls, total: rolls.reduce((a, b) => a + b, 0) })
  },
})

Then add it to BUILTIN_TOOLS in src/tools/index.ts. That is all: the input schema becomes the JSON Schema the model sees, the input is validated before run is called, errors become a message to the model, and MNEMO_TOOLS can turn the tool off.

Guidelines that the built-in tools follow:

  • Describe when to use the tool. The model reads description to decide.
  • Return compact JSON with only what answers the question. Name the source, so the model can cite it.
  • Use ctx.fetch, not the global fetch. It carries the timeout and the User-Agent, and the tests replace it with recorded responses.
  • Validate with zod, and keep the input narrow (lengths, ranges, enums), because the model can be talked into sending anything. Never build a host name or a shell command from the input.
  • Test it without network: see test/tools.test.ts and the recorded responses in test/fixtures.

A tool that needs a key reads it from the configuration. See how web_search is wired in selectTools and src/config.ts.

Adding a provider

A provider is one file that implements Provider from src/providers/types.ts: one chat() call that takes the system prompt, the conversation and the tools, and returns text, tool calls, a stop reason and token usage. Translate Mnemo's neutral turns to your API's format. Look at anthropic.ts and openai.ts, which are under 200 lines each. Then add a case to src/providers/index.ts and the name to provider in src/config.ts.

How the code is organised

src/
  main.ts            start: configuration, engine, Mnema Talk client, health, shutdown
  config.ts          settings, environment variables, validation
  bot/               everything about Mnema Talk (SDK): mentions, threads, /ask, buttons
  engine/            the answering loop, limits, budget, memory, message splitting, persona
  providers/         one file per AI provider, behind one interface
  tools/             one file per tool, behind one interface
  health.ts, log.ts  health endpoint, JSON logs
test/                unit tests (no network) and the integration test
scripts/             manifest, add link, config schema, integration test runner

The engine knows nothing about Mnema Talk, and the bot code knows nothing about AI. To put Mnemo into another chat, keep engine/, providers/ and tools/, and replace bot/.

Dependencies

Five runtime dependencies, each for a reason:

PackageWhy
@mnema-xyz/bot-sdkThe official SDK: REST, gateway with heartbeats, resume and backoff, interactions, components. It has no dependencies of its own
@anthropic-ai/sdkAnthropic's official client: request types, retries, typed errors
openaiOpenAI's official client, which also serves every OpenAI-compatible server
sharpImage processing: downscales large images and extracts frames from animated GIFs to satisfy AI provider limits
zodValidates the configuration and each tool's input, and produces the JSON Schemas the model sees from the same definitions

There are no other runtime dependencies. HTTP uses Node's fetch, time zones use Intl, and the math parser is Mnemo's own. The development tools are TypeScript (type checking only, nothing is compiled), ESLint with typescript-eslint, and Node's built-in test runner.

The SDK dependency

The SDK comes from the npm registry, pinned to an exact version like every dependency here:

"@mnema-xyz/bot-sdk": "3.4.0"

Each SDK version is published from mnema-xyz/bot-sdk-js by its CI with npm provenance, and package-lock.json pins its SHA-512 integrity, so npm ci refuses anything else. npm audit signatures checks the registry signatures and the provenance attestation.

Development

npm ci
npm run check            # lint, typecheck, unit tests
npm test                 # unit tests only: no network, no AI, fake provider and recorded responses
npm run dev              # run with .env, restart on changes
npm run manifest         # rebuild mnemo.manifest.json after changing the avatar or commands
npm run config-schema    # rebuild mnemo.config.schema.json after changing settings

The integration test starts a throwaway Mnema Talk with Docker, built from a checkout of the server, adds Mnemo from its manifest, and checks mentions, threads, /ask, Regenerate, the health endpoint and shutdown, with the fake provider:

MNEMA_SRC=../talk scripts/integration.sh

The avatar is assets/mnemo.svg, in Mnema Talk's colours. scripts/render-avatar.sh turns it into the PNG for the manifest (with headless Chrome).

See CONTRIBUTING.md for the rules, and SECURITY.md to report a vulnerability.

License

MIT License. Mnema Talk itself is AGPL-3.0-only; Mnemo is a separate program that talks to it over its bot API, so it is not bound by that license. Releases up to and including 0.1.3 were published under AGPL-3.0-only.

Something wrong on this page? Tell us.