@onlooker-community/ecosystem 0.22.0 → 0.23.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.22.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.22.0",
+  ".": "0.23.0",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
@@ -11,5 +11,5 @@
   "plugins/warden": "0.2.0",
   "plugins/librarian": "0.1.0",
   "plugins/curator": "0.1.0",
-  "plugins/historian": "0.1.0"
+  "plugins/historian": "0.2.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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)
 
 

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.22.0",
+  "version": "0.23.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",

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

@@ -1,7 +1,7 @@
 {
   "name": "historian",
-  "version": "0.1.0",
-  "description": "Episodic memory layer. At SessionEnd, chunks and sanitizes the session transcript and stores the chunks locally under ~/.onlooker/historian/<project-key>/sessions/. Future-tense retrieval (vector embeddings + UserPromptSubmit similarity surfacer) lands in a follow-up; this PR ships the indexing pipeline only. Builds on the Onlooker ecosystem plugin.",
+  "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"

package/plugins/historian/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

package/plugins/historian/README.md

@@ -2,7 +2,7 @@
 
 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, and persists the chunks under `~/.onlooker/historian/<project-key>/sessions/<session-id>.jsonl`. Future sessions can retrieve relevant past chunks when the user starts a similar problem.
+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.
 
@@ -12,8 +12,8 @@ See [`docs/design.md`](docs/design.md) and [ADR-001](docs/adr/001-local-embeddin
 
 | 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), and appends one JSONL line per chunk to the session's file. Emits `historian.indexing.*` and `historian.chunk.*` events along the way. |
-| `UserPromptSubmit` | No-op in this PR — the rate gate, query embedder, ANN lookup, and surfacer are deferred to a follow-up that ships the retrieval pipeline alongside the first embedder backend. |
+| `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
 
@@ -34,6 +34,7 @@ See [`config.json`](config.json) for the full set of tunable defaults.
 ```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
 ```
 
@@ -50,16 +51,29 @@ Each chunk line:
   "body_chars": 2103,
   "created_at": "2026-06-04T...",
   "source": "local",
-  "redaction_count": 0
+  "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 (transcript reader → chunker → sanitizer → JSONL store)**. Deferred to follow-up landings:
+This plugin ships **scaffolding + the SessionEnd indexing pipeline + the UserPromptSubmit retrieval pipeline + Ollama embedder integration**. Deferred to follow-up landings:
 
-- **Retrieval and surfacer** — `UserPromptSubmit` rate gate, query embedding, ANN lookup, and `additionalContext` injection of the top match.
-- **Embedder backends** — ollama (`nomic-embed-text`), fastembed sidecar, and remote (opt-in via the two-key egress affirmation from [ADR-001](docs/adr/001-local-embeddings-only.md)). Chunks are indexed without vectors today; the JSONL records make adding embeddings a future column-add, not a re-index.
+- **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.
 

package/plugins/historian/config.json

@@ -20,11 +20,27 @@
       "_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": "none",
-      "_note": "Embedder backends (ollama, fastembed, remote) are deferred to a follow-up. The current 'none' value indexes chunks without vectors; retrieval is also deferred."
+      "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": {
-      "_note": "UserPromptSubmit retrieval and surfacer are deferred to a follow-up commit; the hook currently no-ops."
+      "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/scripts/hooks/historian-prompt-submit.sh

@@ -1,15 +1,269 @@
 #!/usr/bin/env bash
-# Historian UserPromptSubmit hook — STUB.
+# Historian UserPromptSubmit retrieval pipeline.
 #
-# The full retrieval pipeline (rate gate → query embedder → ANN lookup →
-# additionalContext surfacer) is deferred to a follow-up landing that ships
-# the first embedder backend. Today the hook is intentionally a no-op so
-# the plugin can be installed and indexing can run without retrieval.
+# 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 produces additionalContext while the retrieval pipeline is
-#     unimplemented.
+#   - 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

package/plugins/historian/scripts/hooks/historian-session-end.sh

@@ -47,6 +47,8 @@ source "${PLUGIN_ROOT}/scripts/lib/historian-transcript.sh"
 source "${PLUGIN_ROOT}/scripts/lib/historian-chunker.sh"
 # shellcheck source=../lib/historian-sanitizer.sh
 source "${PLUGIN_ROOT}/scripts/lib/historian-sanitizer.sh"
+# shellcheck source=../lib/historian-embedder.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-embedder.sh"
 
 INPUT=$(cat 2>/dev/null || true)
 CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
@@ -135,6 +137,25 @@ SANITIZED=$(historian_sanitizer_run "$CHUNKS" "$NEVER_INDEX_PATHS" "$REDACT_SECR
 KEPT=$(printf '%s' "$SANITIZED" | jq '.kept')
 DROPPED=$(printf '%s' "$SANITIZED" | jq '.dropped')
 
+# Probe the embedder once before the chunk loop. If unavailable we
+# index without vectors. The retriever shipped today is embedding-only,
+# so chunks written without an `embedding` field are persisted but
+# invisible to retrieval until they are re-indexed against a working
+# embedder. Chunk bodies stay intact, so re-indexing is a re-embed pass
+# rather than a full re-chunk.
+EMBEDDER_READY=0
+EMBEDDER_BACKEND=$(historian_config_get '.historian.embedder.backend')
+[[ -z "$EMBEDDER_BACKEND" || "$EMBEDDER_BACKEND" == "null" ]] && EMBEDDER_BACKEND="none"
+if [[ "$EMBEDDER_BACKEND" != "none" ]]; then
+	if historian_embedder_available; then
+		EMBEDDER_READY=1
+	else
+		historian_emit "historian.embedder.unavailable" "$SESSION_ID" "$(jq -cn \
+			--arg backend "$EMBEDDER_BACKEND" \
+			'{ backend: $backend }')"
+	fi
+fi
+
 # Re-indexing replaces the existing session file rather than appending,
 # so SessionEnd is safely idempotent if re-fired against the same id.
 historian_storage_reset_session "$PROJECT_KEY" "$SESSION_ID"
@@ -149,7 +170,9 @@ for ((i = 0; i < KEPT_COUNT; i++)); do
 
 	CHUNK_ID=$(historian_ulid)
 	REDACTION_COUNT=$(printf '%s' "$CHUNK" | jq -r '.redaction_count // 0')
+	BODY=$(printf '%s' "$CHUNK" | jq -r '.body_redacted // ""')
 
+	# Build the base record. The embedding (if any) is added below.
 	RECORD=$(jq -cn \
 		--arg chunk_id "$CHUNK_ID" \
 		--arg session_id "$SESSION_ID" \
@@ -163,6 +186,14 @@ for ((i = 0; i < KEPT_COUNT; i++)); do
 			source: $source
 		}')
 
+	if (( EMBEDDER_READY == 1 )) && [[ -n "$BODY" ]]; then
+		EMBEDDING=$(historian_embedder_embed "$BODY")
+		if [[ -n "$EMBEDDING" ]]; then
+			RECORD=$(printf '%s' "$RECORD" | jq -c --argjson v "$EMBEDDING" \
+				'. + { embedding: $v }')
+		fi
+	fi
+
 	if historian_storage_append_chunk "$PROJECT_KEY" "$SESSION_ID" "$RECORD"; then
 		CHUNKS_INDEXED=$((CHUNKS_INDEXED + 1))
 		if (( REDACTION_COUNT > 0 )); then

package/plugins/historian/scripts/lib/historian-embedder.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Embedder client for Historian.
+#
+# Per ADR-001, the default backend is local ollama with the
+# `nomic-embed-text` model. The interface is intentionally a single
+# function that takes a string and returns a JSON array of floats, so
+# alternate backends (fastembed sidecar, remote API) can drop in later
+# without changing callers.
+#
+# Fail-soft: returns empty string on any failure (ollama not reachable,
+# JSON decode error, missing curl). Callers treat empty as "skip the
+# embedding and emit historian.embedder.unavailable".
+
+# Resolve config (the caller has typically run historian_config_load
+# before invoking us). We re-read the config knobs here so this lib can
+# be sourced and used outside the SessionEnd hook context.
+
+_historian_embedder_backend() {
+	local v
+	v=$(historian_config_get '.historian.embedder.backend' 2>/dev/null)
+	[[ -z "$v" ]] && v="none"
+	printf '%s' "$v"
+}
+
+_historian_embedder_ollama_host() {
+	local v
+	v=$(historian_config_get '.historian.embedder.ollama.host' 2>/dev/null)
+	[[ -z "$v" ]] && v="http://127.0.0.1:11434"
+	printf '%s' "$v"
+}
+
+_historian_embedder_ollama_model() {
+	local v
+	v=$(historian_config_get '.historian.embedder.ollama.model' 2>/dev/null)
+	[[ -z "$v" ]] && v="nomic-embed-text"
+	printf '%s' "$v"
+}
+
+_historian_embedder_ollama_timeout() {
+	local v
+	v=$(historian_config_get '.historian.embedder.ollama.request_timeout_seconds' 2>/dev/null)
+	[[ -z "$v" || "$v" == "null" ]] && v=8
+	printf '%s' "$v"
+}
+
+# Returns 0 if the currently-configured embedder is reachable and the
+# backend is something other than "none". A side-effect-free probe.
+historian_embedder_available() {
+	local backend
+	backend=$(_historian_embedder_backend)
+	case "$backend" in
+		none|"")
+			return 1
+			;;
+		ollama)
+			command -v curl >/dev/null 2>&1 || return 1
+			local host timeout
+			host=$(_historian_embedder_ollama_host)
+			timeout=$(_historian_embedder_ollama_timeout)
+			# HEAD `/api/tags` is the cheapest way to confirm the daemon
+			# is up without rendering a payload.
+			curl -fsS --max-time "$timeout" -o /dev/null "${host}/api/tags" 2>/dev/null
+			;;
+		*)
+			# fastembed / remote backends not implemented yet — treat as
+			# unavailable.
+			return 1
+			;;
+	esac
+}
+
+# Embed a single string. Prints a JSON array of floats on success
+# (e.g. `[0.123,0.456,...]`), or empty string on any error.
+# Usage: historian_embedder_embed <text>
+historian_embedder_embed() {
+	local text="${1:-}"
+	[[ -z "$text" ]] && return 0
+
+	local backend
+	backend=$(_historian_embedder_backend)
+	case "$backend" in
+		none|"")
+			return 0
+			;;
+		ollama)
+			_historian_embedder_embed_ollama "$text"
+			;;
+		*)
+			# Backend declared but not implemented — fail-soft.
+			return 0
+			;;
+	esac
+}
+
+# Internal: call ollama's /api/embeddings endpoint.
+_historian_embedder_embed_ollama() {
+	local text="$1"
+	command -v curl >/dev/null 2>&1 || return 0
+
+	local host model timeout payload response
+	host=$(_historian_embedder_ollama_host)
+	model=$(_historian_embedder_ollama_model)
+	timeout=$(_historian_embedder_ollama_timeout)
+
+	payload=$(jq -cn --arg model "$model" --arg prompt "$text" \
+		'{ model: $model, prompt: $prompt }') || return 0
+
+	response=$(curl -fsS --max-time "$timeout" \
+		-H 'Content-Type: application/json' \
+		-d "$payload" \
+		"${host}/api/embeddings" 2>/dev/null) || return 0
+	[[ -z "$response" ]] && return 0
+
+	# The ollama embeddings endpoint returns `{"embedding":[...]}`. Pull
+	# just the array and validate it parses + is non-empty.
+	local vector
+	vector=$(printf '%s' "$response" | jq -c '.embedding // empty' 2>/dev/null)
+	[[ -z "$vector" || "$vector" == "null" ]] && return 0
+
+	# Sanity: must be an array of numbers, length > 0.
+	printf '%s' "$vector" | jq -e '
+		type == "array" and length > 0 and all(.[]; type == "number")
+	' >/dev/null 2>&1 || return 0
+
+	printf '%s' "$vector"
+}