# Memory-Bridge Hook in Claude-Code-Harness: Event Logging and Session Context Integration

> Discover the memory-bridge hook in Claude-Code-Harness. This Go handler ensures fail-safe event logging and session context integration for persistent context across sessions.

- Repository: [Chachamaru/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness)
- Tags: deep-dive
- Published: 2026-05-28

---

**The memory-bridge hook is a fail-safe Go handler that validates session events, persists them to local JSONL storage, and forwards them to an optional `harness-mem` daemon, enabling persistent context across Claude Code sessions without ever blocking execution.**

The **memory-bridge hook** serves as the central integration point between the claude-code-harness and external long-term memory services. Implemented in the `Chachamaru127/claude-code-harness` repository, this component captures lifecycle events across multiple hook phases and ensures that session history remains available for context enrichment, even when the optional memory daemon is temporarily offline.

## Core Implementation and Architecture

### Go Handler Location and Entry Point

The memory-bridge hook is implemented as a Go handler in [`go/internal/hookhandler/memory_bridge.go`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/internal/hookhandler/memory_bridge.go). The harness binary invokes this handler via the subcommand `harness hook memory-bridge`, making it available as a callable entry point within the hook lifecycle.

### Event Validation and Local Persistence

The hook validates incoming JSON payloads containing `session_id`, `cwd`, and `hook_event_name` fields. Upon successful validation, it immediately appends a structured log entry to `.claude/state/memory-bridge-events.jsonl`, creating a durable audit trail that persists independently of the optional daemon's availability.

### HTTP Forwarding to harness-mem

When a `harness-mem` daemon is available on `http://127.0.0.1:37888`, the hook forwards events to the appropriate HTTP endpoint:

- **Standard events** post to `/v1/events/record`
- **Session termination** (`stop` events) post to `/v1/sessions/finalize`

All network operations enforce a **2-second timeout** and execute silently to prevent session interruption.

## Integration with Session Context Lifecycle

### Hook Phase Wiring

The memory-bridge hook integrates into four critical lifecycle phases defined in [`.claude-plugin/hooks.json`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.claude-plugin/hooks.json):

- **SessionStart** (with `once: true` flag to ensure single invocation)
- **UserPromptSubmit**
- **PostToolUse**
- **Stop**

This wiring ensures comprehensive event coverage across the entire session lifecycle.

### Context Enrichment and Resume Packs

While the hook itself returns only an approve decision, its side effects enable downstream context injection. The [`memory-session-start.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/memory-session-start.sh) script—executed subsequent to the bridge during session initialization—queries the daemon's `/v1/resume-pack` endpoint and writes the response to [`.claude/state/memory-resume-context.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.claude/state/memory-resume-context.md). Subsequent hooks read this file to inject **additionalContext** into the current session's prompt, effectively resuming context from previous sessions.

### Fail-Open Safety Guarantees

The hook implements **fail-open semantics**: if JSON parsing fails, the daemon is unreachable, or the target endpoint is unknown, it always returns `{"decision":"approve","reason":"memory-bridge: … dispatched"}`. This ensures the Claude Code session never blocks due to memory service unavailability.

## Supported Event Types and Payload Structure

The hook processes five distinct event types corresponding to harness lifecycle stages:

- **session-start**: Marks session initialization
- **user-prompt**: Captures user input submission
- **post-tool-use**: Logs tool execution completion
- **stop**: Handles session termination (forwarded to `/v1/sessions/finalize`)
- **codex-notify**: Captures Codex-specific notifications

## Configuration and Script Architecture

The hook deployment relies on a layered script architecture orchestrated through [`.claude-plugin/hooks.json`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.claude-plugin/hooks.json). The configuration entry typically specifies:

```json
{
  "command": "/bin/bash -c … exec \"$root/bin/harness\" \"$@\"' _ hook memory-bridge",
  "once": true
}

```

This delegates to [`scripts/hook-handlers/memory-bridge.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/hook-handlers/memory-bridge.sh), which utilizes [`scripts/lib/harness-mem-bridge.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/lib/harness-mem-bridge.sh) to locate the external `harness-mem` repository and coordinate execution with specialized handlers like [`memory-session-start.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/memory-session-start.sh).

## Practical Usage and Debugging

You can manually test the hook by piping JSON directly to the harness binary:

```bash
cat <<EOF | harness hook memory-bridge
{
  "session_id": "1234-abcd",
  "cwd": "/path/to/project",
  "hook_event_name": "user-prompt"
}
EOF

```

This appends a line to `.claude/state/memory-bridge-events.jsonl`:

```json
{"event":"user-prompt","session_id":"1234-abcd","cwd":"/path/to/project","timestamp":"2026-05-28T14:12:00Z"}

```

When the daemon is active, this payload simultaneously posts to `http://127.0.0.1:37888/v1/events/record`, enabling real-time session tracking while maintaining the local backup.

## Summary

- The **memory-bridge hook** operates from [`go/internal/hookhandler/memory_bridge.go`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/internal/hookhandler/memory_bridge.go) as the primary conduit between the harness and long-term memory services.
- It **validates and logs** all session events to `.claude/state/memory-bridge-events.jsonl` before attempting HTTP forwarding to the daemon.
- **Fail-open design** guarantees that session execution continues uninterrupted regardless of daemon availability, JSON parsing errors, or network failures.
- Integration with **SessionStart**, **UserPromptSubmit**, **PostToolUse**, and **Stop** phases enables persistent context through resume packs fetched by [`memory-session-start.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/memory-session-start.sh).
- The **2-second timeout** and silent failure modes ensure production-safe operation in `Chachamaru127/claude-code-harness`.

## Frequently Asked Questions

### What happens if the harness-mem daemon is offline?

The hook returns an approve decision immediately after local logging. Because the HTTP call includes a 2-second timeout and fails silently, session workflow continues without interruption. The event remains available in `.claude/state/memory-bridge-events.jsonl` for later synchronization when the daemon reconnects.

### How does the memory-bridge hook differ from the memory-session-start.sh script?

The **memory-bridge hook** handles event validation, logging, and forwarding for all lifecycle phases, while **memory-session-start.sh** specifically executes during the SessionStart phase to fetch persisted resume data from the daemon's `/v1/resume-pack` endpoint. The bridge establishes the logging infrastructure; the session-start script consumes that infrastructure to inject context into the current session.

### Where is the hook configuration declared?

Hook wiring is declaratively specified in [`.claude-plugin/hooks.json`](https://github.com/Chachamaru127/claude-code-harness/blob/main/.claude-plugin/hooks.json), where the memory-bridge command is registered under the `SessionStart`, `UserPromptSubmit`, `PostToolUse`, and `Stop` arrays with appropriate flags like `once: true` for session initialization.

### What file path stores the local event log?

The hook writes to `.claude/state/memory-bridge-events.jsonl` in the project root, creating a JSONL-formatted audit trail that downstream components can parse for session history and debugging purposes.