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

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. 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:

• 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 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. 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. The configuration entry typically specifies:

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

This delegates to scripts/hook-handlers/memory-bridge.sh, which utilizes scripts/lib/harness-mem-bridge.sh to locate the external harness-mem repository and coordinate execution with specialized handlers like memory-session-start.sh.

Practical Usage and Debugging

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

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:

{"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 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.
• 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}