message lifecycle events: received → preprocessed → sent #14539

matskevich · 2026-02-12T08:09:50Z

matskevich
Feb 12, 2026

your agent forgets everything. here's the fix.

every time openclaw compacts context, your agent loses conversations. it can't search old messages. it can't remember what you discussed last week. you can't build memory, analytics, or automations on top — because there's no event stream to build on.

message hooks change this. three events — received, preprocessed, sent — turn openclaw from a stateless chatbot into infrastructure you can build real systems on.

what becomes possible

1. your agent never forgets again
every message → append-only log → survives compaction forever. semantic search over your entire history. "what did we discuss about X last month?" — answered in seconds, not hallucinated.

2. auto-digest & people memory
nightly skill reads the raw log → writes daily summaries, extracts facts about people, links conversations to goals. "met petya, he launched a startup" → auto-updates people/petya.md. your agent builds a knowledge graph while you sleep.

3. voice messages become searchable text
message:preprocessed fires after transcription. voice notes that were <media:audio> black boxes become full-text searchable transcripts. same for photos → descriptions, links → summaries.

4. security: catch leaked secrets
message:sent hook scans every outgoing message for API keys, tokens, credentials (regex + entropy detection). your agent reads .env files — this catches what prompt rules miss.

5. multi-bot collaboration
two bots in the same group can't see each other's messages (telegram limitation). hooks forward events to a shared hub → bots coordinate in real-time. we run this in production with 2 bots across 4 groups.

6. conversation analytics
when are you most active? what topics dominate? sentiment over time? received/sent ratio? all derived from the raw event stream, zero additional instrumentation.

7. trigger anything from any message
any skill can subscribe to message:received and fire automations: notifications, auto-responses, webhook triggers, content routing. no more polling, no more prompt-based workarounds.

none of this is possible today. openclaw has no message event system. hooks exist for commands and sessions, but messages — the core of what an AI assistant does — are invisible to the extension system.

the proposal

three lifecycle events, fired automatically:

incoming message
  → message:received        (raw input, before any processing)
  → applyMediaUnderstanding  (transcription, image description)
  → applyLinkUnderstanding   (link summaries)
  → message:preprocessed     (enriched — transcripts, descriptions, summaries)
  → agent processing
  → message:sent             (outgoing reply)

why three events, not two?

PR #6797 gives us received + sent. but received fires before media processing:

voice → <media:audio> (no transcript)
photos → <media:image> (no description)

any hook that needs actual content (search, moderation, routing) gets useless tags instead of text. preprocessed fills this gap — fires after transcription/description, before the agent sees it.

preprocessed context

type MessagePreprocessedContext = {
  rawBody?: string;           // original before processing
  processedBody?: string;     // after media + link understanding
  transcript?: string;        // audio/video transcript (groq/whisper)
  mediaOutputs?: MediaUnderstandingOutput[];  // image descriptions, etc.
  senderId?: string;
  senderName?: string;
  channel?: string;
  isGroup?: boolean;
  groupId?: string;
};

production data

we've been running all three events in a fork for 7+ days:

metric	value
events captured	550+
uptime	7 days continuous
bots	2 independent instances
groups	4 (infosec, CTF, brainstorming, content)
hooks consuming events	3 (memory, DLP, multi-bot sync)
crashes from hook system	0

real example — voice message lifecycle:

received: body = <media:audio> (useless for search/logging)
preprocessed: transcript = full text via groq/whisper + provider metadata (searchable)
sent: bot's reply (correlates with input)

implementation

~40 lines across 2 files. no new dependencies. no breaking changes:

src/hooks/message-hooks.ts — new type + trigger function
src/auto-reply/reply/get-reply.ts — one call after media processing

follows the exact pattern of existing triggerMessageReceived / triggerMessageSent.

PR feat(hooks): add message:received and message:sent hook events #6797 — message:received + message:sent (pending review, 10+ days)
PR feat(hooks): add message:sent and message:received internal hook events #6384 — independent implementation by another author (same feature, also pending)
multiple community requests for message events in Feb 2026

both PRs have been waiting 10+ days with no maintainer review. the community clearly wants this. happy to submit a clean PR combining all improvements, or help review either existing PR.

running this in production daily. if you want message hooks now, backport patch is available. but mainline support would benefit everyone.

plaindigital · 2026-02-12T15:06:05Z

plaindigital
Feb 12, 2026

already in use, system-wide, not only for openclaw case

0 replies

bravercell · 2026-02-12T15:42:01Z

bravercell
Feb 12, 2026

I'm slow - others make what I think of. We need it, go main

0 replies

Danilka · 2026-02-12T19:36:43Z

Danilka
Feb 12, 2026

Super important update! Used successfully by our community, praised by every participant.

1 reply

Solituda Feb 12, 2026

Already in use. Very important update. Worth adding to the main.

beaux-riel · 2026-02-12T20:24:20Z

beaux-riel
Feb 12, 2026

Great write-up @matskevich. The three-event lifecycle is the right design — we're building Engram (agent memory) on OpenClaw and the preprocessed gap is exactly what blocks voice message recall.

I'm going to add message:preprocessed to PR #6384 and rebase. Your production data (550+ events, 3 hooks, 0 crashes) makes a strong case for the maintainers.

Happy to have you co-author or review. Let's consolidate and get this across the line.

cc @Glucksberg @NOVA-Openclaw

0 replies

kalichkin · 2026-02-12T20:46:29Z

kalichkin
Feb 12, 2026

Very much needed, hope this gets into the main soon!

0 replies

ftseitlx · 2026-02-13T03:34:42Z

ftseitlx
Feb 13, 2026

great patch,the original memory is B/S love it!

0 replies

Drickon · 2026-02-13T15:05:19Z

Drickon
Feb 13, 2026

Added message:preprocessed to PR #9859. Fires after media + link processing, right next to the existing message:transcribed hook. Transcript is available as a separate field in the context for hooks that need it independently.

0 replies

matskevich · 2026-02-15T14:31:39Z

matskevich
Feb 15, 2026
Author

security layer: what message hooks enable (production report)

we've been running message hooks as security infrastructure for 10+ days. sharing what works and what's missing.

what works today (received + sent)

outbound DLP (data loss prevention)

message:sent hook scans every outgoing message before delivery:

regex patterns for API keys, AWS credentials, private keys, JWTs
entropy detection for high-randomness strings (tokens, secrets)
known-pattern matching (OpenAI sk-, Anthropic sk-ant-, etc.)

why this matters: your agent reads .env files, config files, code with hardcoded secrets. prompt rules ("don't leak secrets") are unreliable — the agent can be convinced to ignore them. a hook catches what prompts miss, every time, deterministically.

inbound audit trail

message:received logs every incoming message with sender identity, timestamp, channel, group context. this gives you:

who said what, when (forensics)
unauthorized access attempts (messages from non-allowlisted users)
rate limiting data (detect flooding/abuse)

what preprocessed unlocks for security

message:preprocessed fires after transcription and media processing. without it:

voice message arrives → hook sees <media:audio> → can't moderate content
photo arrives → hook sees <media:image> → can't scan for policy violations

with preprocessed:

voice → full transcript available → content moderation, keyword detection, compliance scanning
photo → description available → policy filtering, content classification
links → summaries available → phishing detection, domain reputation checks

real example from production: user sends voice message containing credentials. received hook sees <media:audio> — useless. preprocessed hook sees the full transcript — catches the secret.

the gap: observation vs prevention

current hooks are fire-and-forget — they see events but can't block them. the hook runs, but message processing continues regardless.

for a real security gateway, you need hooks that can return a decision:

message:received -> PreReceive hook -> {allow: true/false, reason: "blocked: spam"}
agent processing -> PreSend hook -> {allow: true/false, sanitized: "..."}

this would enable:

inbound filtering: block messages from banned users before agent processes them
outbound prevention: catch and redact secrets before they're sent, not after
content policy enforcement: reject policy-violating responses before delivery
rate limiting with teeth: actually throttle, not just log

we'd be happy to prototype this. the pattern already exists in openclaw for PreToolUse hooks (which CAN block tool execution). extending the same pattern to messages would be consistent with existing architecture.

other fixes we found running hooks in production

1. groupId missing from MessageSentContext

when bot replies in a group, message:sent doesn't include groupId. you can't correlate sent messages to the group they were sent in. we patched this — 6 files, straightforward fix.

2. error isolation

if a hook throws, it shouldn't crash message delivery. we wrap all triggers in try/catch — hook errors are logged but don't break the bot. this should be the default behavior upstream.

both are small PRs we can submit once the base hooks land.

running all of this in production with 2 bots, 4 groups, 700+ events. zero crashes from the hook system. message hooks aren't just a memory feature — they're the foundation for security, compliance, and automation.

0 replies

matskevich · 2026-02-15T15:16:57Z

matskevich
Feb 15, 2026
Author

follow-up: opened a separate proposal for PreReceive / PreSend hooks — message-level blocking and redaction.

→ #17234

current message hooks (received/preprocessed/sent) are fire-and-forget: great for logging, memory, analytics. but for security you need prevention, not just detection. pre-hooks would close that gap — same pattern as existing PreToolUse hooks, extended to messages.

the two proposals are complementary:

this discussion (message lifecycle events: received → preprocessed → sent #14539): message lifecycle events (observation layer)
proposal: PreReceive / PreSend hooks — message-level security gateway #17234: pre-hooks (action layer — block, redact, transform)

0 replies

Uh oh!

message lifecycle events: received → preprocessed → sent #14539

Uh oh!

Uh oh!

your agent forgets everything. here's the fix.

what becomes possible

the proposal

why three events, not two?

preprocessed context

production data

implementation

related

Replies: 9 comments · 1 reply

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matskevich Feb 15, 2026 Author

security layer: what message hooks enable (production report)

what works today (received + sent)

what preprocessed unlocks for security

the gap: observation vs prevention

other fixes we found running hooks in production

Uh oh!

matskevich Feb 15, 2026 Author

Replies: 9 comments 1 reply

matskevich
Feb 15, 2026
Author

matskevich
Feb 15, 2026
Author