Modules
Hot-swappable capabilities that give agents awareness, memory, social intelligence, and the ability to act on the world.
What is a Module?
A module is a self-contained unit of capability. Each module owns a specific domain — memory, social relationships, scheduling, skills — and integrates with the agent through two mechanisms:
Passive influence on every pipeline run. hook_data_gathering injects context before the LLM executes; hook_after_event_execution runs post-processing in the background (entity extraction, memory writes, job evaluation).
Active capabilities the LLM can call during execution. Each module exposes tools via its own MCP server. The agent discovers available tools automatically based on which modules are active.
Modules are independent by design — they never reference or depend on each other. This makes them hot-swappable: enable, disable, or replace any module without affecting the rest of the system.
Module Types
Modules come in two types, determined by how they are activated:
Always active. These modules run on every interaction — Awareness, Chat, Social Network, Memory. The agent doesn’t decide whether to use them; they’re part of the baseline.
Created on demand. When the user asks the agent to do something that requires a specific module (schedule a job, learn a skill, message another agent), the LLM decides to create an instance. The instance lives within a Narrative and persists across sessions.
Instances & Narratives
Modules themselves are stateless templates. The state lives in instances— concrete activations of a module bound to a specific Narrative.
When you switch topics, the agent switches Narratives — and with it, the set of active module instances. A job running in one Narrative doesn't appear in another. Your chat history in one storyline is separate from another. This is how modules stay organized across topics.
During Step 2 of the runtime pipeline, the LLM evaluates which instances should be active for this interaction — keeping existing ones, adding new ones, or archiving completed ones.
Built-in Modules
Persistent agent identity — role, personality, goals. Auto-collected from conversations.
Dual-track conversation history. Thinking vs speaking paradigm. Message delivery.
Entity graph of users, agents, and groups. Relationship tracking and interaction patterns.
Cross-session recall via builtin memory and optional EverMemOS. Document RAG.
Scheduled, recurring, and ongoing background tasks with autonomous execution.
Installable capabilities from ClawHub marketplace or GitHub URLs.
Inter-agent messaging via MessageBus. @mention addressing, channels, and group discussions.
Custom Modules
You can build your own modules following the same pattern — inherit from XYZBaseModule, implement hooks and MCP tools, register in MODULE_MAP. See the full guide.