Enum HookEvent 

pub enum HookEvent {
    PreStore,
    PostStore,
    PreRecall,
    PostRecall,
    PreSearch,
    PostSearch,
    PreDelete,
    PostDelete,
    PrePromote,
    PostPromote,
    PreLink,
    PostLink,
    PreConsolidate,
    PostConsolidate,
    PreGovernanceDecision,
    PostGovernanceDecision,
    OnIndexEviction,
    PreArchive,
    PreTranscriptStore,
    PostTranscriptStore,
    PreRecallExpand,
    PreReflect,
    PostReflect,
    PreCompaction,
    OnCompactionRollback,
}

The 21 lifecycle events the hook pipeline supports.

HookEvent is the tag an operator names in hooks.toml (event = "post_store") and the discriminator the executor uses when routing a payload to its subscribed hook chain.

Payload types are defined in this module — see the per-variant payload table in the module-level documentation and the individual variant doc-comments.

Serde uses snake_case so the on-disk and on-wire spelling matches the table in docs/v0.7/V0.7-EPIC.md § Track G2.

NSA CSI MCP Security mapping

Primary defense against NSA concern (c) Poor approval workflows and implementation of NSA recommendation (d) Constrain and sandbox tool execution + (f) Filter and monitor output pipelines and chained execution per U/OO/6030316-26 (May 2026 v1.0). 25 lifecycle events (20 baseline + 5 v0.7.0 additions: PreRecallExpand, PreReflect, PostReflect, PreCompaction, OnCompactionRollback) give operators a substrate-side hook for every memory operation, with the four-way decision contract (Allow / Modify / Deny / AskUser) and chain ordering (priority-desc, first-Deny short-circuits). Default-off — a v0.7 install with no ~/.config/ai-memory/hooks.toml behaves identically to v0.6.4. Capability inventory anchor: track_g_hook_pipeline. Mapping narrative in docs/compliance/nsa-csi-mcp.html §3.3 (concern c), §4.4 (recommendation d), and §4.6 (recommendation f).

Variants

PreStore

Fires before a memory is persisted. Payload: MemoryDelta (writable).

TODO(G3-G11): wire here at crate::storage::insert.

PostStore

Fires after a memory has been persisted. Payload: Memory (read-only).

TODO(G3-G11): wire here at crate::storage::insert (post-INSERT).

PreRecall

Fires before a recall query executes. Payload: RecallQuery (writable).

TODO(G3-G11): wire here at crate::storage::recall.

PostRecall

Fires after a recall query returns. Payload: RecallResult (read-only).

TODO(G3-G11): wire here at crate::storage::recall (post-return).

PreSearch

Fires before a full-text search executes. Payload: SearchQuery (writable).

TODO(G3-G11): wire here at crate::storage::search.

PostSearch

Fires after a full-text search returns. Payload: SearchResult (read-only).

TODO(G3-G11): wire here at crate::storage::search (post-return).

PreDelete

Fires before a memory is deleted. Payload: MemoryRef (writable target id).

TODO(G3-G11): wire here at crate::storage::delete.

PostDelete

Fires after a memory has been deleted. Payload: MemoryRef (read-only).

TODO(G3-G11): wire here at crate::storage::delete (post-DELETE).

PrePromote

Fires before a tier promotion. Payload: PromoteDelta (writable target tier).

TODO(G3-G11): wire here at crate::storage::promote_to_namespace.

PostPromote

Fires after a tier promotion. Payload: PromoteResult (read-only).

TODO(G3-G11): wire here at crate::storage::promote_to_namespace (post-UPDATE).

PreLink

Fires before a link is created. Payload: LinkDelta (writable).

TODO(G3-G11): wire here at crate::storage::create_link.

PostLink

Fires after a link has been created. Payload: Link (read-only).

TODO(G3-G11): wire here at crate::storage::create_link (post-INSERT).

PreConsolidate

Fires before a consolidation pass runs. Payload: ConsolidationDelta (writable).

TODO(G3-G11): wire here at crate::storage::consolidate.

PostConsolidate

Fires after a consolidation pass completes. Payload: ConsolidationResult (read-only).

TODO(G3-G11): wire here at crate::storage::consolidate (post-return).

PreGovernanceDecision

Fires before a governance gate decision. Payload: GovernanceContext (writable).

TODO(G3-G11): wire here at crate::storage::enforce_governance.

PostGovernanceDecision

Fires after a governance gate decision. Payload: GovernanceDecision (read-only).

TODO(G3-G11): wire here at crate::storage::enforce_governance (post-return).

OnIndexEviction

Fires when the ANN index evicts an entry. Payload: EvictionEvent (read-only).

TODO(G3-G11): wire here at crate::hnsw (hnsw.eviction log site).

PreArchive

Fires before a memory is archived. Payload: MemoryRef (writable target id).

TODO(G3-G11): wire here at crate::storage::archive_memory.

PreTranscriptStore

Fires before a transcript is stored. Payload: TranscriptDelta (writable).

TODO(G3-G11): wire here at crate::transcripts::store.

PostTranscriptStore

Fires after a transcript has been stored. Payload: Transcript (read-only).

TODO(G3-G11): wire here at crate::transcripts::store (post-INSERT).

PreRecallExpand

G10: fires synchronously on the recall hot path before the embedder / DB call to allow query expansion (synonyms, spelling correction, harness-specific normalization). Payload: RecallExpandQuery (writable). Distinct from PreRecall because the budget is the recall p95 (50ms) — operators MUST configure this hook in mode = "daemon" to amortize spawn cost. Classified as crate::hooks::EventClass::HotPath.

Wires here at crate::mcp::handle_recall (top of fn).

PreReflect

v0.7.0 recursive-learning Task 6/8 — fires BEFORE the depth-cap check inside db::reflect. Decision-class hook: handlers may VETO the reflection by returning Deny, which propagates an error up to the caller distinct from a cap refusal (caller-policy refusals like “this agent is rate-limited” vs the substrate cap refusal Task 5 audits). Payload: ReflectDelta (writable — handlers may rewrite the proposed reflection’s tier / tags / priority / metadata before the cap check evaluates). Classified as crate::hooks::EventClass::Write.

Wires here at crate::storage::reflect step 4 (after source-load / depth computation, BEFORE step 5 cap check).

PostReflect

v0.7.0 recursive-learning Task 6/8 — fires AFTER the reflection transaction commits. Notify-class hook: handlers cannot veto; their return value is ignored beyond logging. Payload: ReflectResult (read-only — the post-commit envelope mirrors the memory_reflect MCP response). Classified as crate::hooks::EventClass::Write.

Wires here at crate::storage::reflect step 7 (after COMMIT succeeds, before returning ReflectOutcome to the caller). Layers on top of the existing memory_store webhook event the MCP handler dispatches — both fire on a successful reflect.

PreCompaction

v0.7.0 L1-7 compaction pipeline — fires BEFORE a compaction pass (consolidation, reflection, …) processes a cluster. Decision-class hook: handlers may Allow (default), Modify (rewrite the cluster’s candidate id list), Deny (abort the cluster — no summarise, no persist, no verify), or AskUser. Payload: CompactionDelta (writable — the candidate id list and the pass name). Classified as crate::hooks::EventClass::Write.

Wires here at src/curator/compaction.rs (before ConsolidationPass::summarize is called for each cluster).

OnCompactionRollback

v0.7.0 L1-7 compaction pipeline — fires when the verify step of a compaction pass fails. Notify-class hook: handlers cannot veto; their return value is ignored beyond logging. Payload: CompactionRollbackEvent (read-only — names the summary id and pass that failed).

NOTE: actual rollback (re-inserting source rows, invalidating the summary) is deferred to v0.8.0 Pillar 2.5 (issue #664). This hook fires NOW so integrations can detect and report verify failures; the rollback mechanics ship later.

Classified as crate::hooks::EventClass::Write.

Trait Implementations

impl Clone for HookEvent

fn clone(&self) -> HookEvent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for HookEvent

impl Debug for HookEvent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for HookEvent

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for HookEvent

impl Hash for HookEvent

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for HookEvent

fn eq(&self, other: &HookEvent) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for HookEvent

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for HookEvent