Slack Bot Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• packages/mom/src/agent.ts
• packages/mom/src/slack.ts
• packages/mom/src/store.ts
• packages/mom/README.md
• packages/mom/src/sandbox.ts
• AGENTS.md
• packages/mom/CHANGELOG.md

The mom (Master Of Mischief) package implements a powerful, self-managing Slack bot. It integrates with the Slack API using Socket Mode, delegating tasks to an AI agent powered by the pi-agent-core library. The architecture is designed to be minimal and extensible, allowing the bot to manage its own tools, memory, and workspace autonomously. Each @mention triggers a fresh, ephemeral agent run, which derives its context from a persistent file-based workspace, ensuring both stateless execution and long-term memory.

The core design philosophy revolves around a persistent data directory that the bot uses as its workspace. This directory contains conversation logs, user-uploaded attachments, working memory files, and custom-built CLI tools known as "skills". This approach gives the agent a form of "infinite context" by enabling it to query its own history and knowledge base from the file system, while keeping the immediate prompt to the LLM concise.

Sources: packages/mom/README.md, packages/mom/src/agent.ts

Core Components

The bot's architecture is composed of several key classes and modules that work together to handle Slack events, manage agent execution, and persist data.

This diagram shows the main components and their relationships.

MomBot

The MomBot class is the main entry point for the Slack integration. It initializes the Slack clients, sets up event handlers, and manages user/channel information.

• Responsibilities:
  • Connect to Slack via SocketModeClient and WebClient.
  • Handle incoming events like app_mention and message.
  • Fetch and cache workspace users and channels on startup.
  • Backfill missed messages from channels upon restart.
  • Create a SlackContext for each incoming message.
  • Invoke the MomHandler to process the message.
• Key File: packages/mom/src/slack.ts

AgentRunner

The AgentRunner is responsible for a single, complete execution cycle of the AI agent in response to a user message. It is created by the main application and passed to the MomHandler.

• Responsibilities:
  • Prepare the agent's context by gathering recent messages, memory files, and building the system prompt.
  • Create an ephemeral Agent instance from @mariozechner/pi-agent-core.
  • Subscribe to agent events (tool_execution_start, message_end, etc.) to provide real-time feedback to Slack.
  • Manage a message queue to send responses and tool status updates to Slack in the correct order.
  • Invoke the agent with the user's prompt.
  • Handle the final response and usage tracking.
• Key File: packages/mom/src/agent.ts

ChannelStore

The ChannelStore class manages all file system interactions for a given channel, ensuring data is persisted correctly within the workspace.

• Responsibilities:
  • Log all user messages, bot responses, and tool activities to a log.jsonl file in the respective channel's directory.
  • Download and save attachments from user messages.
  • Provide the last known timestamp for a channel to support message backfilling.
• Key File: packages/mom/src/store.ts

Sandbox Executor

The sandbox executor provides a secure environment for the agent to run bash commands. It supports two modes: Docker (recommended) and host.

• Responsibilities:
  • Provide an exec method to run shell commands.
  • Abstract the execution environment (Docker container or local host).
  • Translate file paths between the container and the host system when necessary.
• Key File: packages/mom/src/sandbox.ts

Message Processing Flow

When a user mentions the bot in a Slack channel, a sequence of events is triggered to process the request and generate a response.

The sequence diagram below illustrates the end-to-end flow.

Agent Context and Prompting

A crucial part of the architecture is how the agent's context is constructed for each run. This is handled by the AgentRunner and is designed to be both comprehensive and token-efficient.

System Prompt Construction

The buildSystemPrompt function assembles a detailed prompt that provides the agent with all necessary context about its environment, capabilities, and the current conversation.

This diagram shows the data sources for the system prompt.

The system prompt includes:

• Current Date/Time: For time-aware operations.
• Slack Formatting Rules: Instructions on using mrkdwn.
• Slack ID Mappings: Tables mapping channel and user IDs to their names.
• Environment Details: Information about the execution environment (Docker or host).
• Workspace Layout: A tree-view of the data directory structure.
• Skills & Memory: Instructions on how to create and use custom tools ("skills") and how to use MEMORY.md files.
• Current Memory: The concatenated content of global and channel-specific MEMORY.md files.
• Log Query Patterns: Critical instructions and jq examples for efficiently searching the log.jsonl history without overflowing the context window.
• Tool Definitions: A list of available built-in tools.

Sources: packages/mom/src/agent.ts:258-361

Conversation History

To provide conversational context, the getRecentMessages function retrieves the last 50 "turns" from the channel's log.jsonl. A "turn" is defined as a single user message or a sequence of consecutive bot messages, which prevents tool-heavy interactions from pushing out valuable conversation history. This history is passed in the user prompt, not the system prompt, to improve LLM prompt caching.

Sources: packages/mom/src/agent.ts:77-156, packages/mom/CHANGELOG.md:38-42

Workspace and Data Persistence

The bot's entire state is stored in a single data directory, making it portable and transparent.

Directory Structure

The workspace is organized by channel, with shared resources at the root.

./data/                         # Host directory
  ├── MEMORY.md                 # Global memory (all channels)
  ├── skills/                   # Global custom CLI tools
  ├── SYSTEM.md                 # Log of all environment modifications
  └── C123ABC/                  # Directory for a specific Slack channel
      ├── MEMORY.md             # Channel-specific memory
      ├── log.jsonl             # Full conversation history for the channel
      ├── attachments/          # Files shared by users in the channel
      ├── scratch/              # Agent's working directory for tasks
      └── skills/               # Channel-specific CLI tools

Sources: packages/mom/README.md, packages/mom/src/agent.ts:293-303

Logging (log.jsonl)

All interactions are logged to log.jsonl in the relevant channel directory. This includes user messages, bot text responses, tool calls, and tool results. Each line is a JSON object.

Field	Type	Description
date	string	ISO 8601 timestamp (e.g., "2025-11-26T10:44:00.123Z").
ts	string	Slack timestamp (e.g., "1732619040.123456"). Used for sorting.
user	string	User ID or "bot".
userName	string	User's handle (e.g., "mario").
text	string	The message content. For tools, this is a structured string like [Tool] bash: {...}.
attachments	Array	List of attachments with original and local paths.
isBot	boolean	true if the message is from the bot, false otherwise.

Sources: packages/mom/README.md, packages/mom/src/store.ts:46-59

Tooling and Extensibility

The agent is equipped with a set of built-in tools and can be extended with custom "skills".

Built-in Tools

The agent has a core set of tools for interacting with its environment.

Tool	Description
bash	Execute shell commands in the sandboxed environment. This is the primary tool.
read	Read the contents of a file.
write	Create or overwrite a file.
edit	Perform surgical find-and-replace edits on a file.
attach	Upload a file from the workspace back to the Slack channel.

Sources: packages/mom/README.md, packages/mom/src/agent.ts:355-360

Custom Skills

A key feature is the ability for the agent to create its own reusable CLI tools, referred to as "skills".

• Purpose: To automate recurring tasks, interact with external APIs (e.g., Gmail, JIRA), or perform complex data processing.
• Storage: Skills can be stored globally in data/skills/ or on a per-channel basis in data/<channel>/skills/.
• Documentation: Each skill is expected to have a SKILL.md file explaining its usage, which the agent is instructed to read before using the tool.
• Discovery: The agent is prompted to list created skills in the global MEMORY.md file to remember them across sessions.

Sources: packages/mom/README.md, packages/mom/src/agent.ts:305-312, AGENTS.md

Conclusion

The mom Slack bot architecture is a robust system that leverages ephemeral, context-aware agents to perform tasks. Its reliance on a persistent file-based workspace for logs, memory, and skills provides a powerful mechanism for long-term learning and self-management. By offloading conversational history and detailed knowledge to the file system, the agent can maintain a concise and effective prompt for the LLM, enabling it to handle complex, multi-step tasks within the Slack environment. The sandboxed execution and clear separation of concerns between Slack communication, agent logic, and data persistence make for a secure and maintainable system.