@onlooker-community/ecosystem 0.21.0 → 0.22.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.22.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.22.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.1.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.21.0",
+  "version": "0.22.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.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.",
+  "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,10 @@
+# Changelog
+
+## [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,70 @@
+# 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, 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.
+
+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), 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. |
+
+## 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
+└── 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
+}
+```
+
+## Status
+
+This plugin ships **scaffolding + the SessionEnd indexing pipeline (transcript reader → chunker → sanitizer → JSONL store)**. 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.
+- **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,30 @@
+{
+  "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": "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."
+    },
+    "retrieval": {
+      "_note": "UserPromptSubmit retrieval and surfacer are deferred to a follow-up commit; the hook currently no-ops."
+    }
+  }
+}

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,15 @@
+#!/usr/bin/env bash
+# Historian UserPromptSubmit hook — STUB.
+#
+# 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.
+#
+# Hook contract:
+#   - Always exits 0.
+#   - Never produces additionalContext while the retrieval pipeline is
+#     unimplemented.
+
+set -uo pipefail
+exit 0

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

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# Historian SessionEnd indexing pipeline.
+#
+# Reads the session transcript, drops tool calls / tool results, chunks
+# the remaining user + assistant turns at turn boundaries, redacts
+# secret-shaped substrings, and appends one JSONL line per surviving
+# chunk to ~/.onlooker/historian/<project-key>/sessions/<session-id>.jsonl.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session shutdown.
+#   - No-ops when historian.enabled is not true.
+#   - No-ops when there is no project key, no transcript path, or the
+#     transcript is shorter than min_transcript_chars_to_index.
+#   - Indexing failures are fail-soft: an emitted historian.indexing.complete
+#     with outcome "skipped" + a skip_reason is the worst case.
+
+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-ulid.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-ulid.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-transcript.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-transcript.sh"
+# shellcheck source=../lib/historian-chunker.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-chunker.sh"
+# shellcheck source=../lib/historian-sanitizer.sh
+source "${PLUGIN_ROOT}/scripts/lib/historian-sanitizer.sh"
+
+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=""
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null) || TRANSCRIPT_PATH=""
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+[[ -z "$SESSION_ID" ]] && SESSION_ID="unknown"
+
+REPO_ROOT=$(historian_project_repo_root "$CWD")
+historian_config_load "$REPO_ROOT"
+historian_config_enabled || exit 0
+
+PROJECT_KEY=$(historian_project_key "$CWD")
+[[ -z "$PROJECT_KEY" ]] && exit 0
+
+historian_storage_init "$PROJECT_KEY" || exit 0
+REMOTE_URL=$(historian_project_remote_url "$CWD")
+historian_storage_write_manifest "$PROJECT_KEY" "$REMOTE_URL" "$REPO_ROOT" || true
+
+# ----------------------------------------------------------------------------
+# Transcript-availability check first — emit no started/complete for the
+# transcript_unavailable path, just a complete-with-skip so the timeline
+# reads cleanly. Once we have a real char count, emit started with that
+# count (the schema requires transcript_chars on started, so emitting
+# zero before the read produced misleading telemetry).
+# ----------------------------------------------------------------------------
+
+SCAN_START_MS=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+	|| SCAN_START_MS=$(($(date +%s) * 1000))
+
+_emit_skip() {
+	local reason="$1"
+	local now_ms duration_ms
+	now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+		|| now_ms=$(($(date +%s) * 1000))
+	duration_ms=$((now_ms - SCAN_START_MS))
+	historian_emit "historian.indexing.complete" "$SESSION_ID" "$(jq -cn \
+		--arg outcome "skipped" \
+		--arg skip_reason "$reason" \
+		--argjson duration_ms "$duration_ms" \
+		'{ outcome: $outcome, skip_reason: $skip_reason, duration_ms: $duration_ms }')"
+}
+
+if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
+	_emit_skip "transcript_unavailable"
+	exit 0
+fi
+
+MIN_CHARS=$(historian_config_get '.historian.indexing.min_transcript_chars_to_index')
+[[ -z "$MIN_CHARS" || "$MIN_CHARS" == "null" ]] && MIN_CHARS=1200
+
+TURNS=$(historian_transcript_load "$TRANSCRIPT_PATH")
+TRANSCRIPT_CHARS=$(historian_transcript_char_count "$TURNS")
+[[ -z "$TRANSCRIPT_CHARS" || "$TRANSCRIPT_CHARS" == "null" ]] && TRANSCRIPT_CHARS=0
+
+historian_emit "historian.indexing.started" "$SESSION_ID" "$(jq -cn \
+	--arg session_id "$SESSION_ID" \
+	--argjson transcript_chars "$TRANSCRIPT_CHARS" \
+	'{ session_id: $session_id, transcript_chars: $transcript_chars }')"
+
+if (( TRANSCRIPT_CHARS < MIN_CHARS )); then
+	_emit_skip "too_short"
+	exit 0
+fi
+
+# ----------------------------------------------------------------------------
+# Chunker → sanitizer → JSONL store.
+# ----------------------------------------------------------------------------
+
+TARGET_CHARS=$(historian_config_get '.historian.indexing.chunk_target_chars')
+[[ -z "$TARGET_CHARS" || "$TARGET_CHARS" == "null" ]] && TARGET_CHARS=2400
+OVERLAP_CHARS=$(historian_config_get '.historian.indexing.chunk_overlap_chars')
+[[ -z "$OVERLAP_CHARS" || "$OVERLAP_CHARS" == "null" ]] && OVERLAP_CHARS=400
+
+CHUNKS=$(historian_chunker_split "$TURNS" "$TARGET_CHARS" "$OVERLAP_CHARS")
+NEVER_INDEX_PATHS=$(historian_config_get '.historian.sanitization.never_index_paths | tojson')
+[[ -z "$NEVER_INDEX_PATHS" || "$NEVER_INDEX_PATHS" == "null" ]] && NEVER_INDEX_PATHS='[]'
+
+# Honor the two on/off knobs from the config block.
+REDACT_SECRETS=$(historian_config_get '.historian.sanitization.redact_secret_patterns')
+[[ -z "$REDACT_SECRETS" || "$REDACT_SECRETS" == "null" ]] && REDACT_SECRETS="true"
+DROP_SKIP=$(historian_config_get '.historian.sanitization.drop_skip_marker')
+[[ -z "$DROP_SKIP" || "$DROP_SKIP" == "null" ]] && DROP_SKIP="true"
+
+SANITIZED=$(historian_sanitizer_run "$CHUNKS" "$NEVER_INDEX_PATHS" "$REDACT_SECRETS" "$DROP_SKIP")
+KEPT=$(printf '%s' "$SANITIZED" | jq '.kept')
+DROPPED=$(printf '%s' "$SANITIZED" | jq '.dropped')
+
+# 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"
+
+NOW_TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+CHUNKS_INDEXED=0
+KEPT_COUNT=$(printf '%s' "$KEPT" | jq 'length' 2>/dev/null) || KEPT_COUNT=0
+
+for ((i = 0; i < KEPT_COUNT; i++)); do
+	CHUNK=$(printf '%s' "$KEPT" | jq -c ".[$i]")
+	[[ -z "$CHUNK" || "$CHUNK" == "null" ]] && continue
+
+	CHUNK_ID=$(historian_ulid)
+	REDACTION_COUNT=$(printf '%s' "$CHUNK" | jq -r '.redaction_count // 0')
+
+	RECORD=$(jq -cn \
+		--arg chunk_id "$CHUNK_ID" \
+		--arg session_id "$SESSION_ID" \
+		--argjson chunk_input "$CHUNK" \
+		--arg created_at "$NOW_TS" \
+		--arg source "local" \
+		'$chunk_input + {
+			chunk_id: $chunk_id,
+			session_id: $session_id,
+			created_at: $created_at,
+			source: $source
+		}')
+
+	if historian_storage_append_chunk "$PROJECT_KEY" "$SESSION_ID" "$RECORD"; then
+		CHUNKS_INDEXED=$((CHUNKS_INDEXED + 1))
+		if (( REDACTION_COUNT > 0 )); then
+			historian_emit "historian.chunk.sanitized" "$SESSION_ID" "$(jq -cn \
+				--arg chunk_id "$CHUNK_ID" \
+				--argjson redaction_count "$REDACTION_COUNT" \
+				'{ chunk_id: $chunk_id, redaction_count: $redaction_count }')"
+		fi
+	fi
+done
+
+# Emit one chunk.dropped event per skip reason summary (caps at the
+# number of unique reasons; per-chunk emission would spam the log).
+DROPPED_COUNT=$(printf '%s' "$DROPPED" | jq 'length' 2>/dev/null) || DROPPED_COUNT=0
+if (( DROPPED_COUNT > 0 )); then
+	for reason in $(printf '%s' "$DROPPED" | jq -r '.[].reason' | sort -u); do
+		historian_emit "historian.chunk.dropped" "$SESSION_ID" "$(jq -cn \
+			--arg reason "$reason" \
+			'{ reason: $reason }')"
+	done
+fi
+
+NOW_MS=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+	|| NOW_MS=$(($(date +%s) * 1000))
+DURATION_MS=$((NOW_MS - SCAN_START_MS))
+
+historian_emit "historian.indexing.complete" "$SESSION_ID" "$(jq -cn \
+	--arg outcome "ok" \
+	--argjson chunks_indexed "$CHUNKS_INDEXED" \
+	--argjson chunks_dropped "$DROPPED_COUNT" \
+	--argjson duration_ms "$DURATION_MS" \
+	'{
+		outcome: $outcome,
+		chunks_indexed: $chunks_indexed,
+		chunks_dropped: $chunks_dropped,
+		duration_ms: $duration_ms
+	}')"
+
+exit 0

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

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Chunker for Historian.
+#
+# Given a JSON array of normalized turns (from historian-transcript.sh),
+# produces a JSON array of chunk records. Each chunk:
+#   - Respects turn boundaries (no mid-turn splits)
+#   - Targets `target_chars` characters with `overlap_chars` overlap
+#     (carrying the last N chars of one chunk's content as the start of
+#     the next)
+#   - Records start_turn_index, end_turn_index, body_chars
+#
+# Character-based chunking instead of token-based: tokenizers vary by
+# embedder, and the chunker shouldn't have to know which embedder will
+# run downstream. Char counts approximate token counts at ~4 chars / token
+# for English-ish prose; configs are tunable.
+
+# Usage: historian_chunker_split <turns_json> <target_chars> <overlap_chars>
+# Output: JSON array of chunks.
+historian_chunker_split() {
+	local turns="${1:-[]}"
+	local target_chars="${2:-2400}"
+	local overlap_chars="${3:-400}"
+
+	python3 - "$target_chars" "$overlap_chars" "$turns" <<'PY'
+import json, sys
+
+target = int(sys.argv[1])
+overlap = max(0, int(sys.argv[2]))
+turns = json.loads(sys.argv[3] or "[]")
+
+chunks = []
+chunk_index = 0
+buf_parts = []
+buf_chars = 0
+buf_start = None
+buf_end = None
+
+# Pending overlap text carried from the previous chunk. It seeds the next
+# chunk's body but doesn't get attributed a turn (the overlap is purely
+# textual continuity for the embedder).
+pending_overlap = ""
+
+
+def flush(force_text=None):
+    """Emit the current buffer as a chunk. force_text overrides the
+    accumulated body and is used when a single turn exceeds the target."""
+    global chunk_index, buf_parts, buf_chars, buf_start, buf_end
+    if force_text is None:
+        if not buf_parts:
+            return
+        body = "\n\n".join(buf_parts)
+    else:
+        body = force_text
+    if not body.strip():
+        # Reset and skip empty bodies (can happen with overlap-only carry).
+        buf_parts = []
+        buf_chars = 0
+        buf_start = None
+        buf_end = None
+        return
+    chunks.append({
+        "chunk_index": chunk_index,
+        "start_turn_index": buf_start,
+        "end_turn_index": buf_end,
+        "body": body,
+        "body_chars": len(body),
+    })
+    chunk_index += 1
+    buf_parts = []
+    buf_chars = 0
+    buf_start = None
+    buf_end = None
+
+
+for turn in turns:
+    role = turn.get("role", "")
+    content = turn.get("content", "")
+    if not content:
+        continue
+    rendered = f"{role}: {content}"
+    rendered_len = len(rendered)
+
+    # If this single turn exceeds the target, flush whatever's pending and
+    # emit the oversized turn as its own chunk. The next chunk's overlap
+    # carries the last `overlap` chars of this turn's body.
+    if rendered_len > target:
+        # Flush pending buffer first.
+        if buf_parts:
+            flush()
+        # Seed an oversized chunk on its own.
+        body_for_chunk = (pending_overlap + ("\n\n" if pending_overlap else "")) + rendered
+        # Set start/end markers for the standalone chunk.
+        buf_start = turn["turn_index"]
+        buf_end = turn["turn_index"]
+        flush(force_text=body_for_chunk)
+        pending_overlap = body_for_chunk[-overlap:] if overlap > 0 else ""
+        continue
+
+    candidate_len = buf_chars + rendered_len + (2 if buf_parts else 0)  # 2 for "\n\n"
+    if buf_parts and candidate_len > target:
+        # Flush the buffer; start a new chunk seeded with overlap from the
+        # body we just emitted.
+        last_body = ""
+        if chunks:
+            last_body = chunks[-1]["body"]
+        flush()
+        if overlap > 0 and last_body:
+            pending_overlap = last_body[-overlap:]
+        else:
+            pending_overlap = ""
+
+    if not buf_parts and pending_overlap:
+        buf_parts.append(pending_overlap)
+        buf_chars += len(pending_overlap)
+        pending_overlap = ""
+
+    buf_parts.append(rendered)
+    buf_chars += rendered_len + (2 if len(buf_parts) > 1 else 0)
+    if buf_start is None:
+        buf_start = turn["turn_index"]
+    buf_end = turn["turn_index"]
+
+# Final flush.
+if buf_parts:
+    flush()
+
+print(json.dumps(chunks))
+PY
+}

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Config resolution for Historian.
+#
+# Reads three layers, latest wins:
+#   1. plugins/historian/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   historian_config_load <repo_root>    # populates _HISTORIAN_CONFIG (JSON)
+#   historian_config_get <jq-path>       # echoes string value (empty if unset)
+#   historian_config_enabled             # 0 if historian.enabled is true
+#
+# Settings overlay only touches the `historian.*` subtree of settings.json.
+
+_HISTORIAN_CONFIG="{}"
+
+historian_config_load() {
+	local repo_root="${1:-}"
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local home_dir="${HOME:-}"
+
+	local merged="{}"
+	local file
+
+	file="${plugin_root}/config.json"
+	if [[ -f "$file" ]]; then
+		local defaults
+		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
+		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
+			|| merged="$defaults"
+	fi
+
+	for file in "${home_dir}/.claude/settings.json" "${repo_root}/.claude/settings.json"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ historian: (.historian // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		merged=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
+			def deepmerge($a; $b):
+				if ($a|type) == "object" and ($b|type) == "object" then
+					reduce (($a|keys) + ($b|keys) | unique)[] as $k
+						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+				elif $b == null then $a
+				else $b end;
+			deepmerge($a; $b)
+		' 2>/dev/null) || true
+	done
+
+	_HISTORIAN_CONFIG="$merged"
+}
+
+# Read a value from the loaded config. The explicit null check (instead of
+# `// empty`) preserves boolean `false` — `// empty` would treat it the same
+# as null and silently drop "explicitly disabled" settings.
+historian_config_get() {
+	local path="$1"
+	printf '%s' "$_HISTORIAN_CONFIG" \
+		| jq -r "${path} | if . == null then empty else . end" 2>/dev/null
+}
+
+historian_config_enabled() {
+	local v
+	v=$(historian_config_get '.historian.enabled')
+	[[ "$v" == "true" ]]
+}