@onlooker-community/ecosystem 0.21.0 → 0.23.0

package/.claude-plugin/marketplace.json

@@ -150,6 +150,19 @@
       "license": "MIT",
       "keywords": ["memory", "audit", "staleness", "findings", "auto-memory", "decay"],
       "tags": ["memory", "context-engineering"]
+    },
+    {
+      "name": "historian",
+      "source": "./plugins/historian",
+      "description": "Episodic memory layer for past Claude Code sessions. At SessionEnd, reads the session transcript, drops tool calls and tool results, chunks the remaining user + assistant turns at turn boundaries with overlap, redacts secret-shaped substrings (AWS keys, GitHub PATs, Anthropic API keys, KEY=value env assignments), and appends one JSONL line per surviving chunk to ~/.onlooker/historian/<project-key>/sessions/<session-id>.jsonl. Future-tense retrieval (vector embeddings + UserPromptSubmit similarity surfacer) lands in a follow-up; this version ships the indexing pipeline only. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["memory", "episodic", "transcript", "indexing", "session", "retrieval"],
+      "tags": ["memory", "context-engineering"]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Observability substrate for Claude Code. Provides the shared ~/.onlooker/ storage root, canonical schema-validated event emission, session and tool tracking hooks, and prompt rules. Required by all other Onlooker plugins.",
   "author": {
     "name": "Onlooker Community",

package/.release-please-manifest.json

@@ -1,5 +1,5 @@
 {
-  ".": "0.21.0",
+  ".": "0.23.0",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
@@ -10,5 +10,6 @@
   "plugins/counsel": "0.2.0",
   "plugins/warden": "0.2.0",
   "plugins/librarian": "0.1.0",
-  "plugins/curator": "0.1.0"
+  "plugins/curator": "0.1.0",
+  "plugins/historian": "0.2.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.23.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.22.0...ecosystem-v0.23.0) (2026-06-04)
+
+
+### Features
+
+* **ecosystem:** emit memory.recalled at SessionStart :link: ([#62](https://github.com/onlooker-community/ecosystem/issues/62)) ([d5876f9](https://github.com/onlooker-community/ecosystem/commit/d5876f9f819165cc07d691d733662b549863b7f5))
+* **historian:** retrieval pipeline + ollama embedder :telescope: ([#61](https://github.com/onlooker-community/ecosystem/issues/61)) ([7eae752](https://github.com/onlooker-community/ecosystem/commit/7eae752a288c4678ab093042469f2e65d428f0d9))
+
+## [0.22.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.21.0...ecosystem-v0.22.0) (2026-06-04)
+
+
+### Features
+
+* **historian:** introduce SessionEnd indexing :spiral_notepad: ([#59](https://github.com/onlooker-community/ecosystem/issues/59)) ([dd6c7f6](https://github.com/onlooker-community/ecosystem/commit/dd6c7f6ea872437cab6b16de50838dfc72750c7b))
+
 ## [0.21.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.20.0...ecosystem-v0.21.0) (2026-06-04)
 
 

package/hooks/hooks.json

@@ -87,6 +87,10 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/session-start-tracker.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/memory-recall-tracker.sh"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -26,7 +26,7 @@
     "test": "npm run test:bats && npm run test:schema",
     "test:bats": "bats test/bats",
     "test:schema": "node --test test/node/*.test.mjs",
-    "test:shellcheck": "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh plugins/archivist/scripts/hooks/*.sh plugins/archivist/scripts/lib/*.sh plugins/tribunal/scripts/hooks/*.sh plugins/tribunal/scripts/lib/*.sh plugins/echo/scripts/hooks/*.sh plugins/echo/scripts/lib/*.sh plugins/governor/scripts/hooks/*.sh plugins/governor/scripts/lib/*.sh plugins/compass/scripts/hooks/*.sh plugins/compass/scripts/lib/*.sh plugins/scribe/scripts/hooks/*.sh plugins/scribe/scripts/lib/*.sh plugins/counsel/scripts/hooks/*.sh plugins/counsel/scripts/lib/*.sh plugins/warden/scripts/hooks/*.sh plugins/warden/scripts/lib/*.sh plugins/librarian/scripts/hooks/*.sh plugins/librarian/scripts/lib/*.sh plugins/curator/scripts/hooks/*.sh plugins/curator/scripts/lib/*.sh",
+    "test:shellcheck": "shellcheck -S error -x install.sh scripts/common.sh scripts/hooks/*.sh scripts/lib/*.sh plugins/archivist/scripts/hooks/*.sh plugins/archivist/scripts/lib/*.sh plugins/tribunal/scripts/hooks/*.sh plugins/tribunal/scripts/lib/*.sh plugins/echo/scripts/hooks/*.sh plugins/echo/scripts/lib/*.sh plugins/governor/scripts/hooks/*.sh plugins/governor/scripts/lib/*.sh plugins/compass/scripts/hooks/*.sh plugins/compass/scripts/lib/*.sh plugins/scribe/scripts/hooks/*.sh plugins/scribe/scripts/lib/*.sh plugins/counsel/scripts/hooks/*.sh plugins/counsel/scripts/lib/*.sh plugins/warden/scripts/hooks/*.sh plugins/warden/scripts/lib/*.sh plugins/librarian/scripts/hooks/*.sh plugins/librarian/scripts/lib/*.sh plugins/curator/scripts/hooks/*.sh plugins/curator/scripts/lib/*.sh plugins/historian/scripts/hooks/*.sh plugins/historian/scripts/lib/*.sh",
     "lint:references": "node scripts/lint/check-references.mjs",
     "lint:manifests": "node scripts/lint/check-manifests.mjs",
     "coverage:node": "node scripts/coverage/run-coverage.mjs",

package/plugins/historian/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "historian",
+  "version": "0.2.0",
+  "description": "Episodic memory layer. At SessionEnd, chunks and sanitizes the session transcript and stores chunks under $ONLOOKER_DIR/historian/<project-key>/sessions/ (default $HOME/.onlooker). On UserPromptSubmit, embeds the prompt and performs similarity retrieval over stored chunks to surface relevant past context. Builds on the Onlooker ecosystem plugin.",
+  "author": {
+    "name": "Onlooker Community",
+    "url": "https://onlooker.dev"
+  },
+  "homepage": "https://onlooker.dev",
+  "repository": "https://github.com/onlooker-community/ecosystem",
+  "license": "MIT",
+  "skills": [],
+  "agents": []
+}

package/plugins/historian/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.2.0](https://github.com/onlooker-community/ecosystem/compare/historian-v0.1.0...historian-v0.2.0) (2026-06-04)
+
+
+### Features
+
+* **historian:** retrieval pipeline + ollama embedder :telescope: ([#61](https://github.com/onlooker-community/ecosystem/issues/61)) ([7eae752](https://github.com/onlooker-community/ecosystem/commit/7eae752a288c4678ab093042469f2e65d428f0d9))
+
+## [0.1.0](https://github.com/onlooker-community/ecosystem/compare/historian-v0.0.1...historian-v0.1.0) (2026-06-04)
+
+
+### Features
+
+* **historian:** introduce SessionEnd indexing :spiral_notepad: ([#59](https://github.com/onlooker-community/ecosystem/issues/59)) ([dd6c7f6](https://github.com/onlooker-community/ecosystem/commit/dd6c7f6ea872437cab6b16de50838dfc72750c7b))
+
+## Changelog

package/plugins/historian/README.md

@@ -0,0 +1,84 @@
+# Historian
+
+Episodic memory layer for past Claude Code sessions.
+
+At every `SessionEnd`, Historian reads the session transcript, splits it into overlapping chunks at turn boundaries, redacts secret-shaped substrings, embeds each chunk via a local Ollama daemon, and persists the chunks under `~/.onlooker/historian/<project-key>/sessions/<session-id>.jsonl`. At every `UserPromptSubmit`, Historian embeds the prompt and retrieves the most similar past chunk (within a similarity floor and freshness window), then injects an `additionalContext` block whose first line is a "looks similar" pointer and whose body is a multi-line excerpt of the matched chunk.
+
+Historian is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present. It is parallel to [`librarian`](../librarian) (which consolidates session decisions into the typed memory store) — both turn session-scoped material into something queryable across sessions, but at different levels of distillation. Librarian distills; historian preserves verbatim.
+
+See [`docs/design.md`](docs/design.md) and [ADR-001](docs/adr/001-local-embeddings-only.md) for the full design, including the local-embeddings-by-default decision.
+
+## How it works
+
+| Hook | What Historian does |
+|------|---------------------|
+| `SessionEnd` | Reads the transcript at `transcript_path`, drops tool calls and tool results (keeps user + assistant messages), chunks at turn boundaries inside the configured character target with overlap, runs the sanitizer (secret redaction + `[historian:skip]` markers + path-deny list), embeds each surviving chunk via the configured backend, and appends one JSONL line per chunk to the session's file. Emits `historian.indexing.*`, `historian.chunk.*`, and `historian.embedder.unavailable` events along the way. |
+| `UserPromptSubmit` | Rate-gated retrieval: short prompts, cooldown windows, and per-session caps short-circuit before the embedder runs. Otherwise embeds the prompt, streams every JSONL chunk for the project, and injects an `additionalContext` block — a header pointer line plus a multi-line excerpt — for the top cosine-similarity match above the floor. Excludes chunks from the current session id (a session retrieving its own chunks is the degenerate case). Emits `historian.retrieval.started` when the rate gate clears, `historian.retrieval.surfaced` on the surfaced outcome, and `historian.retrieval.complete` with `outcome: surfaced\|empty\|skipped` and a `skip_reason` enum for skipped runs. |
+
+## Activation
+
+Historian is **off by default**. Enable per-project in `.claude/settings.json`:
+
+```json
+{
+  "historian": {
+    "enabled": true
+  }
+}
+```
+
+See [`config.json`](config.json) for the full set of tunable defaults.
+
+## Storage layout
+
+```text
+~/.onlooker/historian/<project-key>/
+├── manifest.json                          # project metadata
+├── retrieval-state/<session-id>.json      # rate-gate state: count + last_ms
+└── sessions/<session-id>.jsonl            # one chunk per line, append-only
+```
+
+Each chunk line:
+
+```json
+{
+  "chunk_id": "01J...",
+  "session_id": "...",
+  "chunk_index": 0,
+  "start_turn_index": 0,
+  "end_turn_index": 3,
+  "body_redacted": "...",
+  "body_chars": 2103,
+  "created_at": "2026-06-04T...",
+  "source": "local",
+  "redaction_count": 0,
+  "embedding": [0.123, 0.456, ...]
+}
+```
+
+The `embedding` field is present iff the embedder was available at indexing time. Chunks indexed without an embedder are still readable but invisible to similarity retrieval until they are re-indexed.
+
+## Embedder
+
+Default backend is local **Ollama** with the `nomic-embed-text` model. Set up:
+
+```bash
+ollama pull nomic-embed-text
+ollama serve   # run as a background service; the historian client expects 127.0.0.1:11434
+```
+
+Override the host or model in `.claude/settings.json` under `historian.embedder.ollama.{host,model,request_timeout_seconds}`. Set `historian.embedder.backend: "none"` to disable embedding entirely — chunks index without vectors and retrieval no-ops.
+
+## Status
+
+This plugin ships **scaffolding + the SessionEnd indexing pipeline + the UserPromptSubmit retrieval pipeline + Ollama embedder integration**. Deferred to follow-up landings:
+
+- **fastembed sidecar and remote embedder backends** — opt-in via the two-key egress affirmation from [ADR-001](docs/adr/001-local-embeddings-only.md).
+- **Prune (retention sweep) and purge (manual)** skills.
+- **`/historian recall`, `/historian setup`, `/historian stats`, `/historian purge`** slash commands.
+
+## Requirements
+
+- The `ecosystem` plugin installed (for `~/.onlooker/` substrate).
+- `jq` for JSON manipulation.
+- `python3` for chunking and sanitization (no extra packages — stdlib only).

package/plugins/historian/config.json

@@ -0,0 +1,46 @@
+{
+  "plugin_name": "historian",
+  "storage_path": "~/.onlooker",
+  "historian": {
+    "enabled": false,
+    "indexing": {
+      "trigger": "SessionEnd",
+      "min_transcript_chars_to_index": 1200,
+      "chunk_target_chars": 2400,
+      "chunk_overlap_chars": 400,
+      "retention_days": 365
+    },
+    "sanitization": {
+      "redact_secret_patterns": true,
+      "drop_skip_marker": true,
+      "never_index_paths": []
+    },
+    "session_archive": {
+      "enabled": false,
+      "_note": "When true, the full transcript at SessionEnd is copied alongside the chunks so retrieval can link to the source. When false, only chunk bodies are retained."
+    },
+    "embedder": {
+      "backend": "ollama",
+      "_note": "Backend selector. `ollama` (default) talks to a local Ollama daemon. `none` skips embedding entirely; retrieval no-ops without vectors. `fastembed` and `remote` are reserved for a future landing.",
+      "ollama": {
+        "host": "http://127.0.0.1:11434",
+        "model": "nomic-embed-text",
+        "request_timeout_seconds": 8
+      }
+    },
+    "retrieval": {
+      "enabled": true,
+      "cooldown_seconds": 60,
+      "max_retrievals_per_session": 5,
+      "min_prompt_chars": 60,
+      "retrieval_top_k": 5,
+      "min_similarity": 0.55,
+      "max_age_days": 180
+    },
+    "surfacer": {
+      "excerpt_chars_max": 400,
+      "include_age_hint": true,
+      "_note": "Retrieval always surfaces top-1 (per the design's deliberate top-1 inject). Multi-result surfacing is reserved for a future `/historian recall` skill rather than the UserPromptSubmit inject path."
+    }
+  }
+}

package/plugins/historian/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/historian-session-end.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PLUGIN_ROOT\"/scripts/hooks/historian-prompt-submit.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/historian/scripts/hooks/historian-prompt-submit.sh

@@ -0,0 +1,269 @@
+#!/usr/bin/env bash
+# Historian UserPromptSubmit retrieval pipeline.
+#
+# Flow:
+#   1. Rate gate (cooldown_seconds, max_retrievals_per_session,
+#      min_prompt_chars). Each ungated invocation costs one ollama
+#      embedding round-trip; the gates keep the cost bounded.
+#   2. Embed the prompt via the configured backend.
+#   3. Stream every chunk record for the project from disk one line at
+#      a time, cosine-search against the query vector, filter by
+#      min_similarity and max_age_days.
+#   4. Emit one historian.retrieval.surfaced event for the top match
+#      and inject an `additionalContext` block whose first line is a
+#      "looks similar" pointer and whose body is a multi-line excerpt
+#      of the matched chunk.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks the prompt.
+#   - Emits valid hookSpecificOutput JSON even when nothing to inject.
+#   - No-ops when historian.enabled is not true OR retrieval is disabled.
+#   - Lifecycle events: historian.retrieval.started fires when the rate
+#     gate clears and we are about to embed. All outcomes flow through
+#     historian.retrieval.complete with `outcome: surfaced | empty |
+#     skipped` and (on skipped) a `skip_reason` enum (short_prompt,
+#     cooldown, budget, embedder_unavailable). The surfaced case also
+#     emits historian.retrieval.surfaced with the matched chunk's
+#     chunk_id, similarity, age_days, and source_session_id.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	_candidate="$(cd "${PLUGIN_ROOT}/../.." 2>/dev/null && pwd)"
+	if [[ -f "${_candidate}/scripts/lib/validate-path.sh" ]]; then
+		_ECOSYSTEM_ROOT="$_candidate"
+	fi
+fi
+if [[ -n "$_ECOSYSTEM_ROOT" && -f "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh" ]]; then
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh"
+fi
+
+# shellcheck source=../lib/historian-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-config.sh"
+# shellcheck source=../lib/historian-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-project-key.sh"
+# shellcheck source=../lib/historian-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-storage.sh"
+# shellcheck source=../lib/historian-emit.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-emit.sh"
+# shellcheck source=../lib/historian-embedder.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-embedder.sh"
+# shellcheck source=../lib/historian-retriever.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-retriever.sh"
+
+_emit_context() {
+	local context="${1:-}"
+	jq -cn --arg ctx "$context" '{
+		hookSpecificOutput: {
+			hookEventName: "UserPromptSubmit",
+			additionalContext: $ctx
+		}
+	}'
+}
+
+_now_ms() {
+	python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null \
+		|| echo "$(( $(date +%s) * 1000 ))"
+}
+
+INPUT=$(cat 2>/dev/null || true)
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.prompt // .user_message // .message // ""' 2>/dev/null) || PROMPT=""
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+[[ -z "$SESSION_ID" ]] && SESSION_ID="unknown"
+
+REPO_ROOT=$(historian_project_repo_root "$CWD")
+historian_config_load "$REPO_ROOT"
+
+if ! historian_config_enabled; then
+	_emit_context ""
+	exit 0
+fi
+
+RETRIEVAL_ENABLED=$(historian_config_get '.historian.retrieval.enabled')
+if [[ "$RETRIEVAL_ENABLED" == "false" ]]; then
+	_emit_context ""
+	exit 0
+fi
+
+PROJECT_KEY=$(historian_project_key "$CWD")
+if [[ -z "$PROJECT_KEY" ]]; then
+	_emit_context ""
+	exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Rate gate.
+#
+# Skipped paths emit historian.retrieval.complete with outcome:"skipped"
+# and a skip_reason, matching the schema's lifecycle-event shape. There
+# is no separate retrieval.skipped event in the schema; the outcome
+# field carries that signal.
+# ----------------------------------------------------------------------------
+
+RETRIEVAL_STARTED_MS=$(_now_ms)
+
+_emit_complete_skipped() {
+	local reason="$1"
+	local now duration
+	now=$(_now_ms)
+	duration=$((now - RETRIEVAL_STARTED_MS))
+	historian_emit "historian.retrieval.complete" "$SESSION_ID" "$(jq -cn \
+		--arg outcome "skipped" \
+		--arg skip_reason "$reason" \
+		--argjson duration_ms "$duration" \
+		'{ outcome: $outcome, skip_reason: $skip_reason, duration_ms: $duration_ms }')"
+}
+
+MIN_PROMPT_CHARS=$(historian_config_get '.historian.retrieval.min_prompt_chars')
+[[ -z "$MIN_PROMPT_CHARS" || "$MIN_PROMPT_CHARS" == "null" ]] && MIN_PROMPT_CHARS=60
+
+PROMPT_LEN=${#PROMPT}
+if (( PROMPT_LEN < MIN_PROMPT_CHARS )); then
+	_emit_complete_skipped "short_prompt"
+	_emit_context ""
+	exit 0
+fi
+
+COOLDOWN_SECONDS=$(historian_config_get '.historian.retrieval.cooldown_seconds')
+[[ -z "$COOLDOWN_SECONDS" || "$COOLDOWN_SECONDS" == "null" ]] && COOLDOWN_SECONDS=60
+MAX_RETRIEVALS=$(historian_config_get '.historian.retrieval.max_retrievals_per_session')
+[[ -z "$MAX_RETRIEVALS" || "$MAX_RETRIEVALS" == "null" ]] && MAX_RETRIEVALS=5
+
+STATE=$(historian_retrieval_state_read "$PROJECT_KEY" "$SESSION_ID")
+PREV_COUNT=$(printf '%s' "$STATE" | jq -r '.count // 0')
+PREV_LAST_MS=$(printf '%s' "$STATE" | jq -r '.last_ms // 0')
+
+NOW_MS=$(_now_ms)
+ELAPSED_MS=$((NOW_MS - PREV_LAST_MS))
+COOLDOWN_MS=$((COOLDOWN_SECONDS * 1000))
+
+if (( PREV_LAST_MS > 0 && ELAPSED_MS < COOLDOWN_MS )); then
+	_emit_complete_skipped "cooldown"
+	_emit_context ""
+	exit 0
+fi
+
+if (( PREV_COUNT >= MAX_RETRIEVALS )); then
+	_emit_complete_skipped "budget"
+	_emit_context ""
+	exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Embed the prompt + search.
+# ----------------------------------------------------------------------------
+
+historian_emit "historian.retrieval.started" "$SESSION_ID" "$(jq -cn \
+	--argjson prompt_chars "$PROMPT_LEN" \
+	'{ prompt_chars: $prompt_chars }')"
+
+if ! historian_embedder_available; then
+	BACKEND=$(historian_config_get '.historian.embedder.backend')
+	[[ -z "$BACKEND" || "$BACKEND" == "null" ]] && BACKEND="none"
+	historian_emit "historian.embedder.unavailable" "$SESSION_ID" "$(jq -cn \
+		--arg backend "$BACKEND" '{ backend: $backend }')"
+	_emit_complete_skipped "embedder_unavailable"
+	_emit_context ""
+	exit 0
+fi
+
+QUERY_EMBEDDING=$(historian_embedder_embed "$PROMPT")
+if [[ -z "$QUERY_EMBEDDING" ]]; then
+	_emit_complete_skipped "embedder_unavailable"
+	_emit_context ""
+	exit 0
+fi
+
+TOP_K=$(historian_config_get '.historian.retrieval.retrieval_top_k')
+[[ -z "$TOP_K" || "$TOP_K" == "null" ]] && TOP_K=5
+MIN_SIMILARITY=$(historian_config_get '.historian.retrieval.min_similarity')
+[[ -z "$MIN_SIMILARITY" || "$MIN_SIMILARITY" == "null" ]] && MIN_SIMILARITY="0.55"
+MAX_AGE=$(historian_config_get '.historian.retrieval.max_age_days')
+[[ -z "$MAX_AGE" || "$MAX_AGE" == "null" ]] && MAX_AGE=180
+
+SESSIONS_DIR=$(historian_sessions_dir "$PROJECT_KEY")
+RESULTS=$(historian_retriever_search "$SESSIONS_DIR" "$QUERY_EMBEDDING" "$TOP_K" \
+	"$MIN_SIMILARITY" "$MAX_AGE" "$SESSION_ID")
+RESULT_COUNT=$(printf '%s' "$RESULTS" | jq 'length' 2>/dev/null) || RESULT_COUNT=0
+
+# Bump the rate-gate state for any non-skipped run (we paid for the
+# embedding regardless of whether anything matched).
+historian_retrieval_state_write "$PROJECT_KEY" "$SESSION_ID" \
+	"$((PREV_COUNT + 1))" "$NOW_MS" || true
+
+if [[ "$RESULT_COUNT" == "0" ]]; then
+	NOW=$(_now_ms)
+	DURATION_MS=$((NOW - RETRIEVAL_STARTED_MS))
+	historian_emit "historian.retrieval.complete" "$SESSION_ID" "$(jq -cn \
+		--arg outcome "empty" \
+		--argjson duration_ms "$DURATION_MS" \
+		'{ outcome: $outcome, duration_ms: $duration_ms }')"
+	_emit_context ""
+	exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Surfacer.
+# ----------------------------------------------------------------------------
+
+EXCERPT_MAX=$(historian_config_get '.historian.surfacer.excerpt_chars_max')
+[[ -z "$EXCERPT_MAX" || "$EXCERPT_MAX" == "null" ]] && EXCERPT_MAX=400
+INCLUDE_AGE=$(historian_config_get '.historian.surfacer.include_age_hint')
+[[ -z "$INCLUDE_AGE" || "$INCLUDE_AGE" == "null" ]] && INCLUDE_AGE="true"
+
+TOP=$(printf '%s' "$RESULTS" | jq -c '.[0]')
+TOP_CHUNK_ID=$(printf '%s' "$TOP" | jq -r '.chunk_id // ""')
+TOP_SIM=$(printf '%s' "$TOP" | jq -r '.similarity // 0')
+TOP_AGE=$(printf '%s' "$TOP" | jq -r '.age_days // 0')
+TOP_SESSION=$(printf '%s' "$TOP" | jq -r '.session_id // ""')
+TOP_BODY=$(printf '%s' "$TOP" | jq -r '.body_redacted // ""')
+
+EXCERPT="$TOP_BODY"
+if (( ${#EXCERPT} > EXCERPT_MAX )); then
+	EXCERPT="${EXCERPT:0:EXCERPT_MAX}…"
+fi
+
+if [[ "$INCLUDE_AGE" == "true" ]]; then
+	AGE_HINT=" (${TOP_AGE}d ago, session ${TOP_SESSION})"
+else
+	AGE_HINT=""
+fi
+
+CONTEXT=$(printf 'Historian: a past chunk looks similar%s. Excerpt:\n\n> %s\n' \
+	"$AGE_HINT" "$EXCERPT")
+
+historian_emit "historian.retrieval.surfaced" "$SESSION_ID" "$(jq -cn \
+	--arg chunk_id "$TOP_CHUNK_ID" \
+	--argjson similarity "$TOP_SIM" \
+	--argjson age_days "$TOP_AGE" \
+	--arg source_session_id "$TOP_SESSION" \
+	'{
+		chunk_id: $chunk_id,
+		similarity: $similarity,
+		age_days: $age_days,
+		source_session_id: $source_session_id
+	}')"
+
+NOW=$(_now_ms)
+DURATION_MS=$((NOW - RETRIEVAL_STARTED_MS))
+historian_emit "historian.retrieval.complete" "$SESSION_ID" "$(jq -cn \
+	--arg outcome "surfaced" \
+	--argjson top_similarity "$TOP_SIM" \
+	--argjson candidates_above_floor "$RESULT_COUNT" \
+	--argjson duration_ms "$DURATION_MS" \
+	'{
+		outcome: $outcome,
+		top_similarity: $top_similarity,
+		candidates_above_floor: $candidates_above_floor,
+		duration_ms: $duration_ms
+	}')"
+
+_emit_context "$CONTEXT"
+exit 0