Summary

Add a new hook event message:received that fires before the agent processes an incoming message. This enables pre-turn automations like memory curation, context injection, and audit logging.

Use Cases

1. Memory curation (memfas) — Score and curate relevant memories before the turn, reducing token usage by 80%+
2. Context injection — Auto-inject relevant context based on message content
3. Audit logging — Log all incoming messages for compliance
4. Rate limiting — Check/enforce per-user limits before processing

Proposed Event Shape

type MessageReceivedHookEvent = {
  type: "message";
  action: "received";
  context: {
    message: string;
    senderId?: string;
    channel: string;
    isGroup: boolean;
    sessionKey: string;
    
    // Mutable: hooks can inject context
    injectedContext?: string;
    
    // Mutable: hooks can skip processing
    skipProcessing?: boolean;
  };
};

Example Hook

const handler: HookHandler = async (event) => {
  if (event.type !== "message" || event.action !== "received") return;
  
  // Run memfas curation
  const curated = await runMemfasCurate(event.context.message);
  event.context.injectedContext = curated.context;
};

Design Doc

See docs/proposals/message-received-hook.md for full proposal.

Related

• Hooks system: https://docs.clawd.bot/hooks
• memfas (memory curation): https://github.com/wangtian24/agent-memfas