Crate nexus_memory_hooks 

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
• Droid (Factory CLI): settings-based (~/.factory/settings.json) — SessionStart, SessionEnd, PostToolUse, PreCompact, Stop
• pi-mono: Extension-based (TypeScript) — session start, end, checkpoint, error, 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, 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 retrieval::RetrievalEngine;

pub use retrieval::RetrievalResult;

pub use retrieval::SubconsciousMode;

pub use retry_buffer::RetryArtifact;

pub use retry_buffer::RetryBuffer;

pub use session::SessionContext;

pub use sync_state::SyncState;

pub use transcript::read_transcript;

pub use transcript::read_transcript_from;

pub use transcript::TranscriptEntry;

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::DroidHook;

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

injection

Reference injection system for agent configuration files.

monitor

Session and process monitoring

persistence

Persistence adapter for enriched hook memories

rescorer

Mid-session relevance re-scorer for active agent sessions.

retrieval

Subconscious retrieval engine — surfaces relevant memories for injection.

retry_buffer

Retry buffer for failed LLM enrichment

session

Session context for extracted data

signal

Signal handling for graceful shutdown

sync_state

Sync state tracking for incremental subconscious retrieval.

transcript

Transcript streamer — reads Claude Code JSONL transcripts and formats them for Nexus ingest.

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