Skip to main content

Crate nexus_memory_hooks

Crate nexus_memory_hooks 

Source
Expand description

Nexus Hooks - Agent hooks system for automated memory extraction

This crate provides a four-layer extraction system for capturing agent session context with 95-100% reliability:

  1. Native Hooks (98-100%): Claude Skills, pi-mono, oh-my-pi, pi-skills
  2. Session Monitor (95%): Process monitoring via sysinfo
  3. Inactivity Detector (90%): Configurable timeout detection
  4. Persistent Buffer (99%): Crash recovery from buffer

§Supported Agents

§Native Lifecycle (dedicated hook implementation + skill installation)

  • Claude Code: Skills-based (SKILL.md format) — session start, end, checkpoint, error, compact
  • pi-mono: Skills-based (TypeScript/Bun) — session end, checkpoint, compact
  • oh-my-pi: Skills-based (TypeScript/Bun + Rust N-API) — session end, checkpoint, error, compact
  • pi-skills: Cross-compatible skills — session end, checkpoint, compact

§Monitor Only (process detection, no native hooks)

  • Gemini: Process monitoring only (function calling not yet wired)
  • Qwen: Process monitoring only (hooks subagent not yet wired)

§Wrapper Lifecycle (generic CLI wrapper, atexit + process detection)

  • CLI Agents: Amp, Droid, OpenCode, Codex, Hermes (shared CLIHook implementation)

§Example

use nexus_memory_hooks::{HookFactory, AgentHook, MultiLayerExtractor};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create hook for specific agent
    let factory = HookFactory::new();
    let mut hook = factory.create_hook("claude-code")?;

    // Check if session is active
    let activity = hook.detect_session_activity().await?;
    println!("Session active: {}", activity.is_active);

    // Extract session context
    if activity.is_active {
        let context = hook.extract_session_context().await?;
        println!("Extracted context: {:?}", context);
    }

    Ok(())
}

Re-exports§

pub use base::AgentHook;
pub use base::HookResult;
pub use base::LifecycleCapabilities;
pub use buffer::PersistentBuffer;
pub use candidate::derive_candidates;
pub use candidate::MemoryCandidate;
pub use claude_payload::flatten_text_value;
pub use claude_payload::normalize_claude_payload;
pub use claude_payload::normalize_generic_payload;
pub use claude_payload::normalize_payload;
pub use claude_payload::NormalizedHookEvent;
pub use detector::InactivityDetector;
pub use enrichment::EnrichedMemory;
pub use enrichment::EnrichmentBatchResult;
pub use enrichment::EnrichmentService;
pub use error::HookError;
pub use error::Result;
pub use extractor::MultiLayerExtractor;
pub use factory::HookFactory;
pub use monitor::ProcessMonitor;
pub use monitor::SessionMonitor;
pub use persistence::persist_enriched_memories;
pub use persistence::PersistResult;
pub use retry_buffer::RetryArtifact;
pub use retry_buffer::RetryBuffer;
pub use session::SessionContext;
pub use types::AgentType;
pub use types::DetectionLayer;
pub use types::ExtractionSource;
pub use types::SessionActivity;
pub use types::SupportTier;
pub use agents::CLIHook;
pub use agents::ClaudeCodeHook;
pub use agents::GeminiHook;
pub use agents::OhMyPiHook;
pub use agents::PiMonoHook;
pub use agents::PiSkillsHook;
pub use agents::QwenHook;

Modules§

agents
Agent hook implementations
base
AgentHook trait definition
buffer
Persistent buffer for crash recovery
candidate
High-signal memory candidate derivation from normalized hook events
claude_payload
Hook payload normalization
detector
Inactivity detector for session timeout detection
enrichment
LLM enrichment for hook-derived memory candidates
error
Error types for the hooks system
extractor
Multi-layer extractor combining all detection methods
factory
Hook factory for creating agent-specific hooks
monitor
Session and process monitoring
persistence
Persistence adapter for enriched hook memories
retry_buffer
Retry buffer for failed LLM enrichment
session
Session context for extracted data
signal
Signal handling for graceful shutdown
types
Common types for the hooks system

Constants§

DEFAULT_BUFFER_FLUSH_INTERVAL_SECS
Default buffer flush interval in seconds
DEFAULT_INACTIVITY_TIMEOUT_SECS
Default inactivity timeout in seconds (5 minutes)
DEFAULT_POLLING_INTERVAL_SECS
Default process polling interval in seconds
VERSION
Hook version