External notification integrations
External notification integrations carry selected claude-mem results to systems outside the worker. Telegram delivers alerts and session summaries to people. Grok Bot receives a small live index and selected awareness facts so its agents can use recent captured memory without changing the main capture and search flow. This page is part of Distribution integrations; see also Grok Bot integration, Plugin hooks and agent modes, Cursor integration, Cowork integration, and Installation and NPX CLI.
Integration boundaries
These integrations sit after session capture and observation creation. They use different output boundaries: Telegram uses an HTTPS API, while Grok Bot uses files in its local agent data area. Neither path is the source of truth for captured memory.
External delivery paths
Telegram sends a human-readable message when a configured observation or completed session matches its rules. Grok Bot reads generated memory files during agent work and can use the observation IDs in those files to fetch full records through its normal memory path.
The main relationship between capture, storage, and delivery is:
flowchart LR
A[Captured session] --> B[Stored observations]
A --> C[Stored session summary]
B --> D[Telegram observation alert]
C --> E[Telegram session wrap-up]
B --> F[Grok Bot live index]
B --> G[Grok Bot awareness fact]
F --> H[Grok Bot agent memory]
G --> H
References: src/…/ResponseProcessor.ts• L620-652 src/…/SessionManager.ts• L216-242
Telegram delivery
Telegram provides two delivery modes with different audiences and timing. Observation alerts are narrow signals sent as observations are stored. Session wrap-ups are short summaries sent after a user explicitly ends a session and the summary is available.
Observation alerts
An observation alert is an optional notification for an observation that matches a configured type or concept. The worker passes the labeled observations and their stored IDs to the notifier, which checks the match rules before it sends anything.
The message gives the recipient enough context to decide whether to inspect the observation further. It includes the observation type, title, subtitle, project, and observation ID. Type-specific emoji make security and sensitive items easy to spot. Telegram MarkdownV2 escaping protects values that come from observation content.
Observation alerts require all of the following:
- Telegram is enabled.
- Observation alerts are enabled.
- A bot token and chat ID are present.
- At least one trigger type or concept matches the observation.
An alert failure is logged and does not stop the observation flow. This keeps an external chat service from blocking memory capture.
References: src/…/TelegramNotifier.ts• L8-13 src/…/TelegramNotifier.ts• L29-87 src/…/SettingsDefaultsManager.ts• L265-272
Session wrap-ups
A session wrap-up turns the stored session summary into a brief Telegram message. The delivery starts only after the session-end path requests it. A short grace period allows the summary write to finish before the notifier reads it.
The notifier joins the stored summary parts and gives them to a summary formatter. It accepts a short result as a bullet list. If the result is too long, it keeps complete bullets that fit the Telegram limit rather than cutting a bullet in the middle. It then escapes the result for MarkdownV2 before sending it.
Project routes select the destination chat. An exact project route has priority. A route for the part before / can serve projects below that name. A route may use its own bot token or the shared token. No route means no delivery.
Each wrap-up has a delivery record keyed by platform source, content session, project, and route. The record prevents duplicate sends. A failed send releases an unfinished claim so a later attempt can retry. A long-held claim can be reclaimed, while a sent record remains a permanent duplicate guard.
References: src/…/SessionManager.ts• L187-242 src/…/SessionManager.ts• L390-417 src/…/TelegramWrapupNotifier.ts• L7-29 src/…/TelegramWrapupNotifier.ts• L118-186 src/…/TelegramWrapupNotifier.ts• L188-283 src/…/SessionStore.ts• L2700-2808
Telegram transport
The Telegram transport is the single boundary for sending both message types. It posts JSON to Telegram's sendMessage endpoint with a chat ID, escaped MarkdownV2 text, and the MarkdownV2 parse mode. A non-success HTTP response becomes a delivery error for the caller to handle.
This boundary keeps Telegram-specific wire details out of observation and session logic. It also makes the two message modes share the same escaping and error behavior.
References: src/…/telegram-transport.ts• L1-27
Grok Bot live index
The Grok Bot live index is a compact, generated view of recent observations for each live Grok Bot agent, also called a seat. It helps an agent see that relevant memory exists without loading the full observation set into its working context. The index is a convenience view; MCP and the stored observation database remain the path for complete detail.
Seat and project mapping
The index writer discovers live Grok Bot agents from the agent data area and maps each agent to one or more claude-mem projects. It uses the shared transcript-watch project when one exists. If no watch mapping exists, it derives the project from the agent name.
The worker refreshes the index when it starts and after new observations arrive. Refreshes are delayed and combined during a burst of activity. A missing agent or missing project causes that seat to be skipped instead of affecting other seats.
References: src/…/GrokBotIndexWriter.ts• L133-179 src/…/GrokBotIndexWriter.ts• L274-339 src/…/worker-service.ts• L722-726 src/…/ResponseProcessor.ts• L639-641
Index payload
The index is a Markdown memory log owned by the integration. It contains a dated header and compact fact rows. Each row carries the observation ID, time, type icon, and title. The ID is the key link back to the full observation, so the host can use get_observations when a row needs more detail.
The writer normally selects recent observations for the seat's projects. A house fallback can fill the remaining window with recent observations from other projects when a seat has a thin diary. The result is bounded by a configurable row window and line length. The writer replaces only its generated fact block and avoids a rewrite when that block has not changed.
The file is written under the agent's memory log. The path is checked so the writer does not use the protected profile file or a file outside the integration's owned location. This makes the index a safe cache rather than an editable source of truth.
References: src/…/grok-bot-index-format.ts• L6-12 src/…/grok-bot-index-format.ts• L31-49 src/…/grok-bot-index-format.ts• L83-143 src/…/grok-bot-index-format.ts• L146-195 src/…/GrokBotIndexWriter.ts• L217-271
Awareness facts
Awareness facts are a separate, narrower Grok Bot path for selected agents. A matching observation becomes one dated line in the agent's memory log. The path uses trigger types or concepts and an explicit agent allowlist, so a normal observation does not become a write to every Grok Bot seat.
The pusher deduplicates facts and writes them atomically. It truncates a line to a safe size and logs write failures without failing the main observation flow. Awareness gives an agent a timely hint; it does not replace the live index or full memory lookup.
References: src/…/GrokBotAwarenessPusher.ts• L18-33 src/…/GrokBotAwarenessPusher.ts• L74-131 src/…/GrokBotAwarenessPusher.ts• L134-197 src/…/SettingsDefaultsManager.ts• L273-288
Observation and session relationships
The two external systems consume different results from the same captured work. This distinction prevents a notification from being mistaken for a complete record.
Observation lifecycle
After the worker labels and stores observations, it starts Telegram alerts and Grok Bot awareness as non-blocking work. It also schedules a live-index refresh. The observation IDs passed to these services are aligned with the labeled observations, which lets each external payload point back to stored memory.
The live index reads recent observations from the local database through a read-only view. Telegram alerts and awareness use the observation payload already produced by the worker. All three paths can therefore fail or be disabled without removing the stored observation.
References: src/…/ResponseProcessor.ts• L620-652 src/…/GrokBotIndexWriter.ts• L181-214
Session-end lifecycle
The session-end path marks a wrap-up request before the active session is removed. The notifier then reads the stored session and summary, formats the message, and records the send result. A stop or teardown path without the session-end marker stays silent, so a partial or abandoned session does not create a false completed-session message.
This creates a clear split: observations can produce immediate signals, while a wrap-up represents the final state of a deliberately ended session. The Telegram ledger preserves that distinction across retries and worker races.
References: src/…/SessionManager.ts• L207-242 src/…/SessionManager.ts• L390-417 src/…/TelegramWrapupNotifier.ts• L204-276
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the order of
observationsandobservationIdsaligned at every caller. A mismatch can attach the wrong ID to a Telegram or Grok Bot fact. - Keep Telegram MarkdownV2 escaping and the wrap-up size rule aligned with both message formatters and the shared transport.
- Keep the session identity and route key used by the wrap-up ledger stable across claiming, sending, retrying, and marking a message sent.
- Keep the Grok Bot index row grammar aligned with the host reader and the
get_observationslookup by observation ID. - Keep agent-to-project mapping aligned with transcript-watch configuration so captured sessions appear in the intended seat index.
- Keep the generated-file ownership boundary separate from Grok Bot profile and user-authored memory files.
- Keep the default settings and the documented enablement rules aligned for Telegram alerts, Telegram wrap-ups, awareness facts, and live indexes.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Telegram observation alerts are disabled or have no token, chat, or matching trigger | Matching observations produce no chat message | The notifier checks the feature flags, credentials, and type or concept rules before sending |
| Telegram content contains unescaped MarkdownV2 characters | Telegram can reject or misread the message | Both message modes escape content before the shared transport posts it |
| A session has no stored summary or no project route | No session wrap-up is sent | The wrap-up requires a summary and a resolved project route |
| A wrap-up send fails after a claim is created | A later attempt could be blocked by a stale claim | Failed sends release the claim, and old claims can be reclaimed while sent rows remain deduplicated |
| A Grok Bot seat has no mapped project | That seat's live index is skipped | Mapping uses transcript-watch projects and then the stable seat-name project fallback |
| The observation database cannot be opened for a live refresh | Grok Bot's index stays at its last usable state | Index queries use a read-only connection and return no rows without blocking capture |
| The index path resolves to profile.md or outside the agent memory log | Grok Bot data or user-authored files could be overwritten | The writer validates the agent ID and owned path before writing |
Key files
| File | Why to read it |
|---|---|
| src/…/ResponseProcessor.ts | Shows where stored observations fan out to Telegram, awareness, and live-index refresh work. |
| src/…/SessionManager.ts | Shows when a deliberate session end requests a wrap-up and when delivery runs. |
| src/…/telegram-transport.ts | Defines the Telegram HTTPS payload and shared MarkdownV2 transport boundary. |
| src/…/TelegramNotifier.ts | Defines observation alert matching and message content. |
| src/…/TelegramWrapupNotifier.ts | Defines summary formatting, project routing, size limits, and delivery outcomes. |
| src/…/SessionStore.ts | Defines the wrap-up claim and duplicate-delivery record. |
| src/…/GrokBotIndexWriter.ts | Connects live agents and projects to recent stored observations and generated index files. |
| src/…/grok-bot-index-format.ts | Defines the compact index row format and the owned-file boundary. |
| src/…/GrokBotAwarenessPusher.ts | Defines the selected-agent awareness path and its fact format. |
| src/…/SettingsDefaultsManager.ts | Defines the enablement, routing, trigger, and index defaults for these integrations. |