Galeed

The cross-project trace/log spine — "heap of witness" (Genesis 31:48).

Galeed is the family's shared logging capability: a structured event stream that separates process telemetry (what the system did, step by step) from the final output (the answer). It is intentionally dependency-free (pure stdlib) so any project can adopt it.

In Genesis 31, Laban and Jacob raise one memorial heap and give it two names — Galeed ("heap of witness", the record itself) and Mizpah ("watchtower", the one who watches over it). The family keeps the pair: Galeed records; Mizpah views.

What it provides

• events — a structured event vocabulary (EventType, TraceEvent, stable ids). Self-contained and extensible.
• recorder — Tracer: created once per request/operation; emits events, persists them, and exposes query helpers.
• bus — a process-wide in-process pub/sub (TraceBus) for live streaming (e.g. SSE to a process panel or a dev-log window).
• feedback — lightweight feedback events tied to a trace.
• cairn — emit_cairn_observation(...), a tiny bridge for events that Huldah can analyse as human-load and agent-effectiveness evidence. The module and cairn_kind key keep the Cairn name: it is the observation format, not the analyser (which was renamed in the Deborah/Huldah split).
• llm_calls — the LLM debugging layer: one document per model call with the COMPLETE input (prompt or messages list) and COMPLETE output, a human step_name, and parent_call_id chains for recursive flows. Spine events stay lean; the heavy payloads live here. Wrap direct calls with capture_llm_call(...); Hoglah records every job automatically.

from galeed import Tracer, EventType, get_bus, record_llm_call, capture_llm_call
from galeed import emit_cairn_observation

Viewers

• galeed trace (CLI, pip install galeed[cli]) — the clean In→Out call tree for every source: chains nested, --verbose for the technical layer, filters (--session/--trace/--source/--step/--call/--status/--since), --follow live tail, --json export (works without the extra).
• galeed sessions / galeed events — spine summaries and raw events.
• galeed serve (pip install galeed[web], default port 8785) — the HTTP trace API browser viewers read: Tirzah-compatible /api/trace/* shapes, /api/llm-calls, and an SSE tail. Mizpah points here by default.

Connection: --mongo-uri/--mongo-db or GALEED_MONGO_URI / GALEED_MONGO_DB (default mongodb://localhost:27017 / mnemosyne_dev).

Who emits into it

Any family project — Tirzah, Mahalath, Hoglah, Deborah, Huldah, Milcah — emits its process telemetry through Galeed. Mizpah is the viewer over what Galeed records.

When a product wants Huldah to read an event as human-facing observation evidence, emit it through the Cairn-format bridge:

emit_cairn_observation(
    tracer,
    kind="agent_output",
    message="Generated recommendation without authority citation.",
    tags=["missing_evidence"],
    human_systems=["trust calibration", "uncertainty management"],
    duration_ms=4200,
)

This stores a normal Galeed trace event with metadata.cairn_kind, tags, human_systems, duration_ms, and the standard correlation ids already carried by the tracer.

Schema discipline

Events carry a schema_version (galeed.SCHEMA_VERSION); bump it only on a backwards-incompatible change to the event shape (new event types are additive and need no bump). For cross-repo joins, populate the standard CORRELATION_KEYS (request_id, session_id, trace_id, plan_id, job_id) — galeed.correlation_ids(event) reads them back from fields + metadata so a trace can be stitched across projects.

Review

A point-in-time functional + code review of 0.3.x is in docs/review-2026-08-08.md; findings actioned in 0.4.0 (unpriced models → None cost, instrumentation coverage in galeed sessions, faster hook Mongo probe, bus drop counter, canonical usage).

Note (F2): Tirzah still writes many llm_calls without usage/duration — that fix belongs in Tirzah. galeed sessions now makes the gap visible.

Develop

Works the same on native Linux and WSL — stdlib-only, no platform-specific steps.

pip install -e ".[dev]"   # pytest lives in the dev extra
pytest

Hook bridges for coding agents

Galeed includes bridges so external coding agents (Codex CLI, Claude Code, Cursor) can stream their lifecycle into the family trace spine.

Install the hook command (requires the cli extra for Mongo):

pip install "galeed[cli]"

Example Codex config (~/.codex/config.toml):

[hooks]
SessionStart = ["galeed-codex-hook", "SessionStart"]
PreToolUse   = ["galeed-codex-hook", "PreToolUse"]
PostToolUse  = ["galeed-codex-hook", "PostToolUse"]
Stop         = ["galeed-codex-hook", "Stop"]

The handler reads JSON from stdin (Codex hook payload) and emits events with source="codex" (types like codex.sessionstart, codex.posttooluse, codex.tool.started, etc.). Use the same GALEED_MONGO_* env vars.

See the integration plan in the Noa docs for full context and phased rollout (Phase 0 is a minimal trace spike using a single PostToolUse hook).