# How ai-memory Captures Agent Lifecycle Hooks: Hook Installation, Sanitization, and Storage

> Discover how ai-memory captures agent lifecycle hooks. Learn about hook installation, sanitization, and storage for seamless AI agent behavior tracking.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-09-09

---

**ai-memory captures AI agent behavior by installing shell scripts that execute automatically at key lifecycle points—session start, tool usage, and shutdown—then sanitizes and stores these events via an MCP router to SQLite and searchable wiki storage.**

The **ai-memory** system provides complete observability into AI coding agents without requiring explicit logging calls from the agent itself. By intercepting **agent lifecycle hooks** at the operating system level, the system records bounded, privacy-preserving telemetry that feeds a cross-session knowledge base. This article examines the hook installation process, payload sanitization pipeline, and server-side storage architecture implemented in the `akitaonrails/ai-memory` repository.

## Hook Installation and the MCP Runtime

The **Multi-Client Protocol (MCP) runtime** sources hook scripts from a dedicated pool directory, enabling automatic execution whenever an agent process starts or interacts with system tools.

### Running the Installer Script

Hook registration begins with [`scripts/install-hooks.sh`](https://github.com/akitaonrails/ai-memory/blob/main/scripts/install-hooks.sh), which copies shell and PowerShell scripts into `hooks/pool/`. This installation binds the hooks to the MCP runtime environment, ensuring they are available for every subsequently launched agent process.

```bash

# From the repository root

./scripts/install-hooks.sh

```

### Pool Directory Structure

After installation, the `hooks/pool/` directory contains platform-specific variants for Unix (`.sh`) and Windows PowerShell (`.ps1`). The MCP runtime automatically sources these scripts when spawning agent processes, creating a consistent capture layer across operating systems.

## The Four Core Lifecycle Hook Entry Points

The system captures **agent lifecycle hooks** through four specific entry points that fire at distinct phases of execution.

### Session Start Hook

The `session-start.{sh,ps1}` script fires immediately when an agent session begins. It transmits a bounded JSON payload containing the **session-id**, **agent-kind**, and timestamp to the server’s `/hook` endpoint.

```json
{
  "session_id": "7f3c9e4b-a1d2-4f5e-b8c9-d3e4f5a6b7c8",
  "agent_kind": "OpenCode",
  "timestamp": "2026-09-09T12:34:56Z",
  "event": "session_start"
}

```

### Pre-Tool-Use and Post-Tool-Use Hooks

**`pre-tool-use.{sh,ps1}`** executes immediately before the agent invokes any external tool (e.g., `git`, `curl`, `cargo`). It records the tool name, arguments, and current session context. Conversely, **`post-tool-use.{sh,ps1}`** captures exit status, duration, and stdout/stderr snippets after the tool completes.

```bash
#!/usr/bin/env bash
session_id="${AI_MEMORY_SESSION_ID}"
tool="$1"
shift
args="$@"

curl -s -X POST -H "Content-Type: application/json" \
  -d "{\"session_id\":\"$session_id\",\"event\":\"pre_tool\",\"tool\":\"$tool\",\"args\":\"$args\"}" \
  http://127.0.0.1:49374/hook

```

### Session Stop Hook

The `stop.{sh,ps1}` script signals session termination when the agent process exits, ensuring the system records the exact end time and final state of the interaction.

## Payload Sanitization and Security Boundaries

All hook payloads pass through the **ai-memory-hooks** crate before reaching permanent storage. Located in [`crates/ai-memory-hooks/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-hooks/src/lib.rs), this library enforces the **only trust boundary** for untrusted data entering the system.

The `sanitize()` function strips user-provided secrets, normalizes timestamps, and produces a `Sanitized<NewObservation>` struct. This guarantees that sensitive information never reaches the storage layer, even if agents accidentally include credentials in command arguments.

```rust
use ai_memory_hooks::{sanitize, NewObservation};

let raw = NewObservation::new(json_payload);
let sanitized = sanitize(raw).expect("sanitisation failed");
store::write_observation(sanitized);

```

## Server-Side Ingestion and Storage

Once sanitized, lifecycle events flow through the MCP router into persistent storage with full-text search capabilities.

### MCP Router and Authentication

The MCP router at [`crates/ai-memory-mcp/src/router.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/router.rs) receives POST requests at the `/hook` endpoint. It validates the `AuthLevel` of the submitting agent before forwarding the sanitized observation to the storage actor. This authentication step ensures that only authorized agents can write to the observation log.

### SQLite Storage with FTS5 Indexing

The **ai-memory-store** actor writes observations into an SQLite database’s `observations` table. Simultaneously, the system updates an **FTS5** full-text-search index, enabling immediate querying of captured tool outputs and session metadata.

### Atomic Wiki Updates

Certain hooks—particularly `user-prompt-submit`—trigger writes to the Wiki layer in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs). This component performs an atomic **tmp + rename + fsync** operation, ensuring that captured prompts appear as permanent markdown pages that are instantly searchable without risking data corruption during concurrent writes.

## Summary

- **Hook installation** via [`scripts/install-hooks.sh`](https://github.com/akitaonrails/ai-memory/blob/main/scripts/install-hooks.sh) registers shell scripts that the MCP runtime sources automatically for every agent session.
- **Four core entry points**—`session-start`, `pre-tool-use`, `post-tool-use`, and `stop`—capture the complete agent lifecycle without explicit logging code.
- **Sanitization boundary** at [`crates/ai-memory-hooks/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-hooks/src/lib.rs) removes secrets via the `sanitize()` function before storage.
- **Server-side pipeline** validates `AuthLevel` in the MCP router, then persists to SQLite with FTS5 indexing and atomic wiki updates.

## Frequently Asked Questions

### What are agent lifecycle hooks in ai-memory?

**Agent lifecycle hooks** are automated shell scripts that execute at specific points during an AI agent's execution—specifically when sessions start, before and after tool usage, and when processes stop. These hooks capture telemetry without requiring the agent to perform explicit logging calls.

### How does ai-memory prevent secrets from leaking through hooks?

The **ai-memory-hooks** crate in [`crates/ai-memory-hooks/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-hooks/src/lib.rs) implements a mandatory `sanitize()` function that processes all payloads before storage. This function strips user-provided secrets and normalizes data into a `Sanitized<NewObservation>` struct, ensuring the capture layer serves as the sole trust boundary for untrusted data.

### Which hook runs before a tool is executed?

The **`pre-tool-use.{sh,ps1}`** hook executes immediately before the agent invokes any external tool. According to the source in [`hooks/pool/pre-tool-use.sh`](https://github.com/akitaonrails/ai-memory/blob/main/hooks/pool/pre-tool-use.sh), this script captures the tool name, arguments, and session context, then POSTs this data to the local MCP router at `http://127.0.0.1:49374/hook`.

### Where are the captured lifecycle events stored?

Sanitized observations are stored in an SQLite database by the **ai-memory-store** actor, with concurrent updates to an FTS5 full-text-search index. Additionally, certain events trigger atomic writes to the Wiki layer at [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), which uses tmp-file creation followed by rename and fsync operations to guarantee durable, searchable markdown records.