Skip to main content

​
Modes & Languages

Claude-Mem uses a flexible Mode System to adapt its behavior, observation types, and output language. This allows you to switch between different workflows (like coding vs. email investigation) or languages without reinstalling the plugin.

​
What is a Mode?

A “mode” is a configuration profile that defines:
  1. Observer Role: How Claude should analyze your work (e.g., “Software Engineer” vs. “Forensic Analyst”).
  2. Observation Types: Valid categories for memory (e.g., “Bug Fix”, “Feature” vs. “Person”, “Organization”).
  3. Concepts: Semantic tags for indexing (e.g., “Pattern”, “Trade-off”).
  4. Language: The language used for generating observations and summaries.

​
Configuration

Set the active mode using the CLAUDE_MEM_MODE setting in ~/.claude-mem/settings.json:
Or via environment variable:
The active mode is shown in the startup context injected into each new session, for example:

​
Creating a Custom Mode

Run /mode-creator to design a domain-specific note system through an interactive interview. It helps choose observation types and concept tags, writes and validates the mode, installs it under ~/.claude-mem/modes/, activates it, optionally configures Telegram alerts, restarts the worker, and verifies the active mode in startup context. Custom modes in the data directory are durable across plugin upgrades. A same-named user file cannot shadow a bundled mode ID: for example, ~/.claude-mem/modes/code.json is ignored and logged as an error. To customize bundled code, use a code--<name> override, which inherits the bundled parent:
Custom IDs that do not collide with bundled modes load from the user modes directory. CLAUDE_MEM_MODES_DIR remains an explicit override for development and tests and may supply any ID. All loaded modes must have complete prompts and valid observation types and concepts after inheritance is applied. Invalid mode content is logged and rejected with its file paths and missing or invalid keys. A missing mode file is logged before falling back to validated bundled code; an invalid bundled fallback also throws. Avoid editing files inside the plugin cache because a plugin update can replace them.

​
Telegram alerts and session wrap-ups

Telegram has two separate delivery paths. A session wrap-up sends the latest stored session summary once the Claude Code session ends. Per-observation alerts are real-time notifications for matching observation types or concepts; they are now disabled by default, even when Telegram itself is enabled. Configure the new settings as strings in ~/.claude-mem/settings.json:
  • CLAUDE_MEM_TELEGRAM_WRAPUPS_ENABLED defaults to "true", but no wrap-up can be sent until a route is configured.
  • CLAUDE_MEM_TELEGRAM_OBSERVATION_ALERTS_ENABLED defaults to "false"; set it to "true" only when you want the existing CLAUDE_MEM_TELEGRAM_TRIGGER_TYPES or CLAUDE_MEM_TELEGRAM_TRIGGER_CONCEPTS alerts to resume.
  • CLAUDE_MEM_TELEGRAM_WRAPUP_ROUTES defaults to "{}" and contains a JSON object keyed by project name.
For example, use this route object as the value of CLAUDE_MEM_TELEGRAM_WRAPUP_ROUTES:
A route needs a chat_id; its bot_token can override CLAUDE_MEM_TELEGRAM_BOT_TOKEN, and key is an optional route label. CLAUDE_MEM_TELEGRAM_ENABLED remains the master switch for both paths. Route lookup first matches the project name exactly, then the parent name before the first / for worktrees. If neither route exists, claude-mem logs No wrap-up route for project and does not send anything—there is never a fallback to CLAUDE_MEM_TELEGRAM_CHAT_ID for a wrap-up.

​
Available Modes

​
Code Mode (Default)

The standard mode for software development. Captures bug fixes, features, refactors, and architectural decisions. ID: code

​
Code Mode Variants

Behavioral variants that change how the code mode operates:

​
Multilingual Code Modes

Inherits all behavior from Code Mode but instructs Claude to generate all memory artifacts (titles, narratives, facts, summaries) in the target language. To use Chill in another language, chain both IDs: code--chill--ko records only what Chill keeps and writes it in Korean. See Mode Inheritance.

​
Email Investigation Mode

A specialized mode for analyzing email dumps (e.g., FOIA releases, corporate archives). Focuses on identifying entities, relationships, timeline events, and key topics. ID: email-investigation Observation Types:
  • entity: Person, organization, or email address
  • relationship: Connection between entities
  • timeline-event: Time-stamped event in communication sequence
  • evidence: Supporting documentation or proof
  • anomaly: Suspicious pattern or irregularity
  • conclusion: Investigative finding or determination

​
Mode Inheritance

The system supports inheritance using the -- separator. For example, code--es means:
  1. Load code (Parent) configuration.
  2. Load code--es (Child) configuration.
  3. Merge Child into Parent (Child overrides).
This allows for lightweight “remix” modes that only change specific aspects (like the language prompt) while keeping the core definitions intact. A mode ID can chain several overrides. Each segment after the parent names one parent--segment file, merged in order from left to right. For example, code--chill--ko means:
  1. Load code (Parent) configuration.
  2. Merge code--chill into it.
  3. Merge code--ko into the result.
When two overrides set the same key, the one further right wins. Chill and the language modes change different prompts, so code--chill--ko and code--ko--chill behave the same. Your own overrides chain the same way, for example code--chill--architecture-practice. If any file in the chain is missing, Claude-Mem logs it and falls back to code.