Modules

A module is a small middleware that participates in one or more lifecycle hooks. Modules ship as npm packages that implement a tiny interface — six fields, four of them optional.

The interface

import type { Module } from '@prxy/module-sdk';
 
export const myModule: Module = {
  name: 'my-module',
  version: '1.0.0',
 
  async init(storage) {
    // optional: one-shot setup at server boot
  },
 
  async pre(ctx) {
    // optional: pre-request hook (mutate or short-circuit)
    return { continue: true };
  },
 
  async stream(chunk, ctx) {
    // optional: per-chunk hook for streaming responses
    return chunk;
  },
 
  async post(ctx) {
    // optional: post-response hook (side effects)
  },
};

Full SDK reference at /sdk/interface.

Module categories

Each built-in module fits one of seven categories. Knowing the category tells you roughly where it should sit in the pipeline:

Category	Purpose	Where in pipeline	Examples
`cache`	Skip the provider call	First	`exact-cache`, `semantic-cache`, `tool-cache`
`safety`	Block bad requests early	Early	`cost-guard`, `guardrails`, `airgap`
`optimization`	Reduce tokens sent	Mid	`mcp-optimizer`, `prompt-optimizer`
`context`	Manage messages array	Mid	`ipc`, `rehydrator`, `compaction-bridge`
`injection`	Add to prompt	Late	`patterns`
`routing`	Choose model/provider	Last pre hook	`router`
`tracking`	Log + bill + learn	Post hooks	`usage-tracker`

Built-in modules

mcp-optimizer — embed tool descriptions, drop the irrelevant ones.
exact-cache — hash the canonical request, return identical responses.
semantic-cache — embed and search; return when similar enough.
patterns — inject learned patterns; forge new ones from outcomes.
cost-guard — per-request, per-day, per-month USD caps.
ipc — infinite context — compress old turns instead of dropping them.
router — smart model selection.
rehydrator — pull archived context back when relevant.
compaction-bridge — survive Claude Code auto-compaction.
prompt-optimizer — restructure prompts for max provider cache.
tool-cache — observe MCP tool result cache hits today; response rewriting is planned.
guardrails — PII redaction, profanity blocks, custom regex.

Availability matrix

Status values are production, preview, planned, or deprecated.

Module	Status	Cloud	Local	Streaming	Requires storage	Requires provider key	Docs	Last updated
`mcp-optimizer`	production	yes	yes	pre-hooks	yes	no	/modules/mcp-optimizer	2026-05-03
`exact-cache`	production	yes	yes	yes	yes	no	/modules/exact-cache	2026-05-03
`semantic-cache`	production	yes	yes	yes	yes	no	/modules/semantic-cache	2026-05-03
`patterns`	production	yes	yes	partial: injection works, streaming post-forge is skipped	yes	no	/modules/patterns	2026-05-03
`cost-guard`	production	yes	partial: local has no hosted billing ledger	yes	yes	no	/modules/cost-guard	2026-05-03
`ipc`	production	yes	yes	yes	yes	no	/modules/ipc	2026-05-03
`router`	production	yes	yes	pre-hooks	optional	no	/modules/router	2026-05-03
`rehydrator`	production	yes	yes	pre-hooks	yes	no	/modules/rehydrator	2026-05-03
`compaction-bridge`	production	yes	yes	pre-hooks	yes	no	/modules/compaction-bridge	2026-05-03
`prompt-optimizer`	production	yes	yes	pre-hooks	no	no	/modules/prompt-optimizer	2026-05-03
`tool-cache`	preview	yes	yes	partial: observes/records, does not inject cached tool results yet	yes	no	/modules/tool-cache	2026-05-03
`guardrails`	production for regex backend; external backends planned	yes	yes	pre-hooks	no	no	/modules/guardrails	2026-05-03
`mpp-gate`	preview	yes	no	no	yes	no	/api/agent-payments	2026-05-03

Requires provider key means the module itself requires a provider credential to run. A non-cached LLM request still needs provider access unless it uses the managed MPP route.

Cloud-only / local-only

Most production modules work in both environments. A few have asymmetric capabilities: