Skip to main content

Hooks System

Register callbacks on any memory or knowledge graph operation. Hooks fire before and after operations, with support for cancellation, payload transformation, and error handling.

Available Events​

Memory Lifecycle​

  • before:store / after:store
  • before:update / after:update
  • before:delete / after:delete
  • before:recall / after:recall

Knowledge Graph​

  • before:kg:addEntity / after:kg:addEntity
  • before:kg:addTriple / after:kg:addTriple
  • before:kg:invalidate / after:kg:invalidate

Graph Traversal​

  • before:graph:traverse / after:graph:traverse
  • before:graph:bridges / after:graph:bridges

Agent Diary​

  • before:diary:write / after:diary:write

Ingestion and Dedup​

  • before:ingest / after:ingest
  • before:dedup / after:dedup
  • before:nest:list / after:nest:list

Special​

  • before:* / after:* — catch-all wildcards
  • error — fired when a hook listener throws

MCP Tools​

ToolWhat it does
localnest_hooks_statsCheck enabled state, listener counts, active events
localnest_hooks_list_eventsGet all valid event names

Programmatic Usage​

// Register a hook
hooks.on('after:store', async (entry, ctx) => {
  console.log('Stored memory', entry.id);
});

// Cancel an operation
hooks.on('before:store', async (entry) => {
  if (entry.content.includes('SECRET')) {
    return { cancel: true, reason: 'blocked sensitive content' };
  }
});

// One-time hook
hooks.once('after:kg:addTriple', async (triple) => {
  console.log('First triple added:', triple);
});

Hook Behavior​

  • before: hooks can cancel operations by returning { cancel: true }
  • before: hooks can transform payloads by returning { payload: newPayload }
  • after: hooks are informational — they cannot cancel or transform
  • error: hooks fire when any listener throws, preventing cascading failures
  • Hooks are disabled by default and can be toggled via hooks.setEnabled(bool)