Agent Hooks — Memorius

How hooks work

A hook script is generated per agent. When an agent fires a lifecycle event, it pipes a JSON payload to the memorius-hook engine, which auto-detects which agent sent it and runs the configured actions.

Generate the hook scripts and plugins for every supported agent:

memorius-plugin-gen init      # creates universal-manifest.yaml
# edit the manifest to pick agents + actions
memorius-plugin-gen generate  # emits per-agent plugins, hook scripts, skill cards

Then point your agent at the generated hook. The engine reads stdin, detects the agent, and executes the actions for that event — mine, diary, inject_context, and more.

Hook actions

Ten action types the engine can run on an event. The engine may also return block to pause agent execution (allow/block semantics).

Action	Description
`mine_dir`	Read transcript file(s) and mine via the vault engine.
`diary`	Write a diary entry.
`conditional_diary`	Write a diary only after N exchanges (interval-based).
`command`	Execute a shell command (sanitized via `shlex`, `shell=False`).
`log`	Log a message.
`webhook`	POST the event payload to a URL (with SSRF protection).
`inject_context`	Inject relevant memories into context.
`consolidate`	Run memory consolidation.
`factcheck`	Fact-check a statement from the event payload.
`allow/block`	Engine returns `block` to pause agent execution.

Auto-detection & priority

No --agent flag needed — the engine figures out which agent sent the event from the payload. Force one with --agent if you prefer.

Detection priority (most-specific first):

OpenClaude → Claude Code → Codex → Gemini CLI → OpenClaw → OpenCode → Pi → Generic

Agent	Marker / protocol	Events
OpenClaude	`OpenClaude` marker in payload	stop, precompact, session_start
Claude Code	`stop_hook_active` / `precompact`	stop, precompact, session_start
Codex CLI	`session_id` + `context_dir`	session_start, session_stop, stop, precompact
Gemini CLI	`conversation_id` + `extensions`	stop, session_start
OpenClaw	`openclaw` marker	stop, session_stop, precompact, session_start
OpenCode	`provider` dict + `openCodeVersion`	stop, session_stop, session_start, precompact
Pi	`event` in the Pi event set	session_start, session_shutdown, pre_compact, tool_call, turn_end
Generic	fallback for unrecognized payloads	any

The `memorius-hook` CLI

memorius-hook run              # process a hook event from stdin
memorius-hook init-config      # generate default ~/.memorius/hooks.yaml
memorius-hook status           # show hook state summary

Auto-detect the agent by piping the payload in:

cat hook-payload.json | memorius-hook mine
cat hook-payload.json | memorius-hook diary

# or force a specific agent:
memorius-hook mine --agent claude-code
memorius-hook diary --agent opencode

Plugin generator

Generates per-agent plugins: plugin.json, hooks.json, hook shell scripts, skill cards, commands, marketplace.json, and a README.

memorius-plugin-gen list              # show supported agents
memorius-plugin-gen init              # create universal-manifest.yaml
memorius-plugin-gen generate          # generate plugins for all agents
memorius-plugin-gen generate --watch  # live regeneration on config change

Conversation normalizers

The memorius-normalize CLI converts Discord, Telegram, WhatsApp, and generic chat exports into a uniform transcript that mine / extract understand.

memorius-normalize detect <files>   # auto-detect the format
memorius-normalize convert <file>   # convert one file to a transcript
memorius-normalize batch <dir>      # convert a whole directory
memorius-normalize pipe             # read stdin, write stdout

Format	Description
`discord`	Discord channel export JSON (DiscordChatExporter).
`telegram`	Telegram Desktop chat export JSON.
`whatsapp`	WhatsApp plain-text export (international + US/EU variants).
`generic-json`	Any JSON with `{role, content}`, `{author, text}`, or `{from, text}`.
`generic-messages`	List of message objects with role/author fields.
`generic-chat`	Dict with a `conversations` / `chats` key.
`generic-text`	Plain text with `speaker:` lines or `>` transcript markers.

Security hardening

Defense	Detail
Command execution	`shlex.split()` with `shell=False` — no shell injection; shell metacharacters are stripped from templates.
Webhook SSRF	Blocks localhost, private IPs, cloud metadata endpoints, and non-HTTP schemes.
Context injection	Prompt-injection protection sanitizes memory content before LLM injection (strips "ignore previous instructions", XML tags, control characters).

Repository

Memorius is MIT-licensed and fully open source. Star the repo, open an issue, or dig into the source on GitHub.

Star on GitHub Open an issue