@onlooker-community/ecosystem 0.19.0 → 0.21.0

package/.claude-plugin/marketplace.json

@@ -124,6 +124,32 @@
       "license": "MIT",
       "keywords": ["security", "prompt-injection", "rule-of-two", "safety", "content-gate", "untrusted-content"],
       "tags": ["safety", "security"]
+    },
+    {
+      "name": "librarian",
+      "source": "./plugins/librarian",
+      "description": "Consolidation layer between archivist's per-session artifacts and the user's durable typed memory store. Reads archivist artifacts at SessionEnd, applies a durability filter, classifies survivors via Haiku into the four memory types (user, feedback, project, reference), and queues proposals for explicit confirmation via /librarian review. Auto-promotion is opt-in. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["memory", "consolidation", "promotion", "classifier", "auto-memory", "session"],
+      "tags": ["memory", "context-engineering"]
+    },
+    {
+      "name": "curator",
+      "source": "./plugins/curator",
+      "description": "Maintenance layer for the typed auto-memory store. At every SessionStart, runs four cheap heuristic checks against the memories at ~/.claude/projects/<encoded>/memory/ — date_decayed (ISO-8601 dates past the grace period), path_broken (path-shaped references that don't resolve under the repo root), broken_index (MEMORY.md pointing at missing files), and orphaned_memory (files in the dir not referenced from MEMORY.md). Surfaces findings via /curator review; never edits the memory store directly. Parallel to cartographer (which audits hand-maintained instruction files), curator audits the auto-memory substrate. Requires the ecosystem plugin.",
+      "author": {
+        "name": "Onlooker Community"
+      },
+      "homepage": "https://onlooker.dev",
+      "repository": "https://github.com/onlooker-community/ecosystem",
+      "license": "MIT",
+      "keywords": ["memory", "audit", "staleness", "findings", "auto-memory", "decay"],
+      "tags": ["memory", "context-engineering"]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ecosystem",
-  "version": "0.19.0",
+  "version": "0.21.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.19.0",
+  ".": "0.21.0",
   "plugins/archivist": "0.1.0",
   "plugins/tribunal": "1.0.1",
   "plugins/echo": "0.2.0",
@@ -8,5 +8,7 @@
   "plugins/compass": "0.2.0",
   "plugins/scribe": "0.2.0",
   "plugins/counsel": "0.2.0",
-  "plugins/warden": "0.2.0"
+  "plugins/warden": "0.2.0",
+  "plugins/librarian": "0.1.0",
+  "plugins/curator": "0.1.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.21.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.20.0...ecosystem-v0.21.0) (2026-06-04)
+
+
+### Features
+
+* **curator:** introduce plugin with cheap-tier checks :microscope: ([#57](https://github.com/onlooker-community/ecosystem/issues/57)) ([7f9fa18](https://github.com/onlooker-community/ecosystem/commit/7f9fa18bbde29c8b5bd1eaad185bd4c5595a3762))
+
+## [0.20.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.19.0...ecosystem-v0.20.0) (2026-06-04)
+
+
+### Features
+
+* **librarian:** land plugin end-to-end with memory layer designs :seedling: ([#55](https://github.com/onlooker-community/ecosystem/issues/55)) ([d4821ef](https://github.com/onlooker-community/ecosystem/commit/d4821efabfeb587e460e898d7db8f92fcc3f2c61))
+
 ## [0.19.0](https://github.com/onlooker-community/ecosystem/compare/ecosystem-v0.18.0...ecosystem-v0.19.0) (2026-06-02)
 
 

package/docs/memory-architecture.md

@@ -0,0 +1,102 @@
+# Memory Architecture
+
+This document describes how the Onlooker ecosystem manages memory across timescales — from the in-session working context, through compaction-resistant session memory, into durable cross-session knowledge, and back out as just-in-time recall.
+
+It is the companion to [`architecture.md`](architecture.md), which describes the substrate. This doc describes how the memory-flavored plugins compose on top of it.
+
+---
+
+## The four timescales
+
+| Timescale | Lifetime | Substrate | Plugin |
+|-----------|----------|-----------|--------|
+| Working | Within one model turn | Conversation context window | (the model itself) |
+| Session | One Claude Code session, across compactions | `~/.onlooker/archivist/<project-key>/` | **archivist** |
+| Durable | Across sessions, weeks–months | `~/.claude/projects/<encoded-project>/memory/` | **librarian**, **curator** |
+| Episodic | Across sessions, retrieved on similarity | `~/.onlooker/historian/<project-key>/` | **historian** |
+
+Each plugin operates on exactly one substrate. They communicate by events, not by reaching across substrates.
+
+---
+
+## The pipeline
+
+```mermaid
+flowchart LR
+    session[Active session]
+    session -->|PreCompact| archivist[(archivist artifacts<br/>per session)]
+    archivist -->|SessionEnd| librarian{librarian:<br/>worth keeping?}
+    librarian -->|propose| memstore[(typed memory store<br/>user / feedback / project / reference)]
+    memstore -->|SessionStart audit| curator{curator:<br/>still valid?}
+    curator -->|prune proposals| memstore
+
+    session -->|SessionEnd| historian[(historian vector store<br/>transcript embeddings)]
+    historian -->|UserPromptSubmit similarity| session
+    memstore -->|SessionStart inject| session
+    archivist -->|SessionStart inject| session
+```
+
+### Flow of a fact
+
+A non-obvious project fact ("the auth migration is driven by legal, not tech debt") goes through:
+
+1. **Captured during session** — surfaces in the conversation, lands in the transcript.
+2. **Extracted at compaction by archivist** — written as a `decisions/<ulid>.json` artifact when context fills.
+3. **Reinjected by archivist next session** — appears in `additionalContext` if it ranks within the recency/pinning budget. The fact survives session boundaries but lives in a per-session, recency-ranked space.
+4. **Promoted by librarian** — at session end (or on demand), librarian decides "this should be a `project` memory" and writes it to the typed memory store with provenance pointing back to the archivist artifact.
+5. **Audited by curator** — periodically, curator checks whether the **Why:** is still load-bearing (has the legal review concluded? did the migration land?). If stale, curator surfaces a prune proposal.
+6. **Recalled by historian (separately)** — if a future session encounters a similar problem ("we're being asked to rip out X middleware again"), historian retrieves the transcript chunk from the original session where this was discussed, providing fuller context than the distilled project memory can carry.
+
+---
+
+## Boundaries between memory plugins
+
+The memory plugins overlap in spirit but operate on different substrates and answer different questions. Misunderstanding these boundaries is the most likely failure mode.
+
+| Plugin | Question it answers | Storage | Trigger |
+|--------|---------------------|---------|---------|
+| archivist | "What did we decide / try / leave open in *this* session?" | `~/.onlooker/archivist/<project-key>/` | PreCompact, SessionStart |
+| librarian | "Which of those decisions deserves to live forever?" | `~/.claude/projects/<encoded-project>/memory/` (writes proposals; user confirms) | SessionEnd, scheduled |
+| curator | "Which of our durable memories are now wrong, stale, or contradictory?" | reads & proposes prunes against the typed memory store | SessionStart (cheap), scheduled (LLM) |
+| historian | "Have we seen something like this before, and if so, what happened?" | `~/.onlooker/historian/<project-key>/` (embeddings) | SessionEnd, UserPromptSubmit |
+| scribe | "What's a readable artifact of what we did?" | scribe's own output dir | session end |
+| cartographer | "Are the instruction files (CLAUDE.md, AGENTS.md, rules/) internally consistent?" | reads instruction files; emits findings | SessionStart, instruction-file writes |
+| counsel | "What does the *event log* across all plugins tell us to improve?" | reads JSONL log; produces brief | weekly |
+
+**The two easiest confusions:**
+
+1. **cartographer vs. curator.** Cartographer audits the *instruction files* the user maintains by hand (CLAUDE.md, AGENTS.md, `.claude/rules/`). Curator audits the *typed auto-memory store* the librarian writes into. Same shape of audit, different substrate. They are parallel, not redundant.
+
+2. **archivist vs. librarian.** Archivist keeps everything from a session, ranked by recency, and reinjects into the next one. Librarian promotes a small subset into the typed memory store where it will be reinjected *every* session, with classification (user/feedback/project/reference) and provenance.
+
+---
+
+## Shared invariants
+
+All three new memory plugins follow the ecosystem conventions:
+
+- **Project keying** for plugin-owned storage (`~/.onlooker/<plugin>/<project-key>/`) uses the SHA256-of-remote-URL scheme from [`architecture.md`](architecture.md#project-keying), so cross-clone consistency is preserved for plugin state. Note: the typed memory store the librarian writes into is keyed by Claude Code's per-checkout path encoding (`~/.claude/projects/<encoded-project>/memory/`), which is a different scheme — see [librarian ADR-001](../plugins/librarian/docs/adr/001-propose-dont-auto-write.md) for how this asymmetry is handled.
+- **No cross-plugin runtime dependencies.** Librarian degrades gracefully if archivist artifacts are absent (no proposals; emits `librarian.scan.skipped`). Curator degrades gracefully if the memory store is empty. Historian degrades gracefully if no past transcripts are indexed.
+- **Event emission via `onlooker-event.mjs`.** Event types: `librarian.*`, `curator.*`, `historian.*`. Registered in `@onlooker-community/schema` before first emission.
+- **Fail-soft on missing `~/.onlooker/`.** Plugins must not block a session they were not invited to.
+- **Context-budget awareness.** Reinjection at `SessionStart` competes for the same budget archivist already uses. Each plugin's design lays out its budget cap explicitly; the ecosystem does not yet enforce a global ceiling. See [Open Questions](#open-questions) below.
+
+---
+
+## Open Questions
+
+1. **Global reinjection ceiling.** Archivist, librarian (via the typed memory store it writes into), historian, counsel, and cartographer all surface things at `SessionStart`. Each respects its own cap, but there is no shared budget. A `governor.context_budget.*` event series could attribute context spend per plugin and provide a soft global cap. Currently each plugin sets its own ceiling independently.
+
+2. **Memory store path scheme divergence.** Claude Code's typed memory store uses per-checkout path encoding; the ecosystem uses SHA256-of-remote-URL for cross-clone sharing. Librarian writes to the former (so the user sees promotions in the same place as their hand-written memories), but its own operational state (proposals queue, provenance log) lives at `~/.onlooker/librarian/<project-key>/` under the ecosystem scheme. This asymmetry is handled in [librarian ADR-001](../plugins/librarian/docs/adr/001-propose-dont-auto-write.md) but remains an awkwardness worth revisiting if Claude Code adopts a remote-derived key.
+
+3. **Promotion provenance after deletion.** When the user manually deletes a promoted memory, librarian should learn from that — at minimum, don't re-propose the same content. Sketched in librarian's design as the "tombstone" mechanism but not yet decided.
+
+4. **Historian and secrets.** Embedding entire transcripts means tokens, paths, and other sensitive strings that appeared in a past conversation become recallable. Deletion semantics (purge by session_id, by date range, by pattern) need to be defined before historian goes beyond a design sketch.
+
+---
+
+## Plugin design documents
+
+- [Librarian](../plugins/librarian/docs/design.md) — consolidates archivist artifacts into the typed memory store
+- [Curator](../plugins/curator/docs/design.md) — detects stale, contradictory, and decayed memories
+- [Historian](../plugins/historian/docs/design.md) — episodic retrieval over past session transcripts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlooker-community/ecosystem",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Agents, skills, hooks, commands, rules, and MCP configurations that power [Onlooker](https://onlooker.dev)",
   "author": {
     "name": "Onlooker Community",
@@ -19,14 +19,14 @@
     "onlooker-install": "install.sh"
   },
   "dependencies": {
-    "@onlooker-community/schema": "^2.4.0"
+    "@onlooker-community/schema": "^2.5.0"
   },
   "scripts": {
     "postinstall": "echo '\\n  onlooker-ecosystem installed!\\n  Run: npx onlooker-install typescript\\n  Docs: https://github.com/onlooker-community/ecosystem\\n'",
     "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",
+    "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",
     "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/curator/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "curator",
+  "version": "0.1.0",
+  "description": "Maintenance layer for the user's typed auto-memory store. At every SessionStart, runs four cheap heuristic checks (date_decayed, path_broken, broken_index, orphaned_memory) against the memories at ~/.claude/projects/<encoded>/memory/ inside a wall-clock budget. Surfaces findings as a one-line pointer to /curator review; never edits the memory store directly. 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/curator/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.0](https://github.com/onlooker-community/ecosystem/compare/curator-v0.0.1...curator-v0.1.0) (2026-06-04)
+
+
+### Features
+
+* **curator:** introduce plugin with cheap-tier checks :microscope: ([#57](https://github.com/onlooker-community/ecosystem/issues/57)) ([7f9fa18](https://github.com/onlooker-community/ecosystem/commit/7f9fa18bbde29c8b5bd1eaad185bd4c5595a3762))
+
+## Changelog

package/plugins/curator/README.md

@@ -0,0 +1,55 @@
+# Curator
+
+Maintenance layer for the user's typed auto-memory store.
+
+At every `SessionStart`, Curator runs cheap heuristic checks against the memories at `~/.claude/projects/<encoded-project>/memory/` — stale ISO-8601 dates past the grace period, broken path references, broken `MEMORY.md` index entries, and orphaned memory files — and surfaces findings as a one-line pointer to `/curator review`. Curator never edits the memory store directly.
+
+The weekly LLM-backed contradiction sweep described in [`docs/design.md`](docs/design.md) is a future capability — see the **Status** section below for what's actually shipped today.
+
+Curator is a sibling plugin to [`ecosystem`](../../) and assumes the Onlooker observability substrate (`~/.onlooker/`) is present. It is parallel to [`cartographer`](../cartographer) (which audits hand-maintained instruction files like `CLAUDE.md`) — same audit shape, different substrate.
+
+## How it works
+
+| Hook | What Curator does |
+|------|---------------------|
+| `SessionStart` | Runs the four cheap-tier checks (date_decayed, path_broken, broken_index, orphaned_memory) against the memory store, inside a wall-clock budget (`cheap_checks.wall_clock_budget_ms`, default 500ms). Writes new findings under `~/.onlooker/curator/<project-key>/findings/` keyed by ULID, deduping repeat findings via `deduped_hash`. Injects a one-line `additionalContext` pointer when open findings exist. |
+
+## Activation
+
+Curator is **off by default**. Enable per-project in `.claude/settings.json`:
+
+```json
+{
+  "curator": {
+    "enabled": true
+  }
+}
+```
+
+Or globally in `~/.claude/settings.json`. See [`config.json`](config.json) for the full set of tunable defaults.
+
+## Storage layout
+
+```text
+~/.onlooker/curator/<project-key>/
+├── manifest.json                    # project metadata
+├── last_llm_sweep.json              # watermark for the weekly LLM pass
+├── last_cheap_scan.json             # watermark for the per-session check
+└── findings/<ulid>.json             # one finding per file
+```
+
+## Status
+
+This plugin ships **scaffolding + four cheap-tier checks (date_decayed, path_broken, broken_index, orphaned_memory) + SessionStart surfacer**. Deferred to follow-up landings:
+
+- **LLM contradiction sweep** — design and the watermark plumbing (`last_llm_sweep.json`) are in place; the Haiku pair-evaluation loop is not implemented. `llm_sweep.enabled` defaults to `false` and is a no-op until the sweep ships.
+- **`/curator review` interactive walkthrough** — accept / prune / edit / reclassify / acknowledge / defer for surfaced findings.
+- **Usage tracker** (zero-recall-window findings) — depends on a substrate-level `memory.recalled` emitter that doesn't exist yet. `usage_tracker.enabled` defaults to `false`; see [`docs/design.md`](docs/design.md) Open Question #1.
+- **Symbol reference check** — backtick-wrapped identifiers grep'd against the repo. Not yet wired.
+
+## Requirements
+
+- The `ecosystem` plugin installed (for `~/.onlooker/` substrate).
+- `jq` for JSON manipulation.
+- `python3` for date math and path resolution.
+- `git` to resolve the project key and (for the reference check) the repo root.

package/plugins/curator/config.json

@@ -0,0 +1,41 @@
+{
+  "plugin_name": "curator",
+  "storage_path": "~/.onlooker",
+  "curator": {
+    "enabled": false,
+    "memory_store_path": "${HOME}/.claude/projects/${CLAUDE_PROJECT_ENCODED}/memory",
+    "cheap_checks": {
+      "enabled": true,
+      "wall_clock_budget_ms": 500,
+      "skip_if_session_age_under_seconds": 5
+    },
+    "date_check": {
+      "enabled": true,
+      "date_grace_period_days": 14
+    },
+    "reference_check": {
+      "enabled": true,
+      "check_urls": false,
+      "url_allowlist": []
+    },
+    "usage_tracker": {
+      "enabled": false,
+      "usage_window_days": 30,
+      "_note": "Disabled until the substrate memory.recalled emitter ships. Setting to true today is a no-op."
+    },
+    "llm_sweep": {
+      "enabled": false,
+      "_note": "Disabled until the Haiku pair-evaluation loop ships. Setting to true today is a no-op.",
+      "model": "claude-haiku-4-5-20251001",
+      "temperature": 0.2,
+      "max_output_tokens": 96,
+      "interval_days": 7,
+      "max_pair_evaluations_per_sweep": 50,
+      "contradiction_similarity_threshold": 0.4
+    },
+    "surfacer": {
+      "max_pointer_chars": 200,
+      "skip_when_zero": true
+    }
+  }
+}

package/plugins/curator/docs/adr/001-staleness-tiers.md

@@ -0,0 +1,100 @@
+# ADR-001: Two-Tier Staleness Checks — Cheap Every Session, LLM Weekly
+
+- Status: Accepted
+- Date: 2026-06-02
+- Deciders: Meagan
+- Tags: curator, memory, performance, rate-limiting
+
+## Context and Problem Statement
+
+Curator audits the typed memory store for staleness, broken references, contradictions, and decayed dates. The natural place to surface findings is at `SessionStart` — that's when the user is paged in for the day's work and most receptive to a one-line "Curator: 2 findings to review" pointer.
+
+But `SessionStart` fires on every session, including every restart after compaction and every new branch checkout. Whatever curator runs at `SessionStart` runs *a lot*. Two pressures push against each other:
+
+- The checks need to be cheap enough not to delay session startup or accumulate hidden cost.
+- The most valuable check (contradiction detection between memory pairs) requires an LLM call per candidate pair, and the candidate set grows with the memory store.
+
+A single check tier — either "all checks every session" or "all checks on a manual trigger" — fails the gradient. The first is too expensive at scale; the second is too easy to forget, and findings rot quietly.
+
+## Decision Drivers
+
+- **`SessionStart` is a hot path.** Cartographer's design explicitly documents that audits run as a detached background process to avoid blocking sessions. Curator inherits the same constraint.
+- **Cheap checks are nearly free.** Date pattern matching, file-exists checks on path references, and `rg` calls for symbol references all sit in the millisecond range. They can run every session inside a wall-clock budget without observable latency.
+- **LLM contradiction checks scale poorly.** Pairwise comparison is O(N²) on the candidate set even after similarity-filtering. A 100-memory store today may have ~10 candidate pairs; a 500-memory store has more. Running this every session is paying a recurring cost that grows with the user's investment in the system — the worst kind of cost curve.
+- **The signal decays slowly.** A contradiction between two memories does not become more or less true between Monday and Tuesday. Weekly cadence captures real changes (new memories, edited memories) without burning compute on a static problem.
+- **User-pull beats system-push for big sweeps.** A manual `/curator scan` skill exists for users who want to force a full sweep — that's the right surface for "I just landed a big refactor; re-check everything."
+- **Cartographer precedent.** Cartographer runs a periodic background audit and surfaces findings as events. Curator's tiered cadence is the moral equivalent: cheap checks are the "always-on" surface, the LLM sweep is the "periodic" surface.
+
+## Considered Options
+
+1. **One tier: all checks every session.** Simple, predictable, expensive at scale. Wall-clock budget acts as a ceiling but degrades coverage as the store grows.
+2. **One tier: all checks on manual trigger only.** Cheap and predictable but loses the always-on signal users want from `SessionStart`. Findings rot.
+3. **Two tiers: cheap checks every session, LLM sweep at most once per N days.** Preserves the always-on cheap signal and amortizes the expensive sweep over time.
+4. **Three tiers: cheap every session, mid-cost (e.g., rg-based symbol re-check) daily, LLM weekly.** Finer granularity. Adds operational complexity (multiple watermarks, multiple skip-reason cases) without an obvious payoff at current memory-store sizes.
+5. **Adaptive cadence.** Run the LLM sweep when the memory store has changed by more than X% since last sweep. Conceptually elegant but introduces a change-detection layer that itself needs validation.
+
+## Decision
+
+We adopt **Option 3: two tiers with a watermark-gated LLM sweep at most once per `llm_sweep_interval_days` (default: 7)**.
+
+The cheap tier runs on every `SessionStart` inside a `wall_clock_budget_ms` budget (default: 500ms). It performs:
+
+- Date pattern parsing and grace-period checks.
+- Path reference existence checks.
+- Symbol reference `rg` checks (capped at `max_symbol_checks_per_session`).
+- Usage tracker reads from the JSONL log (when the `memory.recalled` emitter ships).
+
+If the cheap tier runs over budget, curator emits `curator.scan.skipped` with `reason: "over_budget"` and exits without partial results. The wall-clock budget exists to make budget overruns visible as events rather than as silent slowdowns.
+
+The LLM tier runs only when `now - last_llm_sweep_at >= llm_sweep_interval_days`. The watermark lives at `~/.onlooker/curator/<project-key>/last_llm_sweep.json`. When the gate opens:
+
+- Pairwise Jaccard similarity is computed across all memories.
+- Pairs above `contradiction_similarity_threshold` (default: 0.4) with opposing sentiment markers proceed to LLM evaluation.
+- Up to `max_pair_evaluations_per_sweep` (default: 50) calls are made, watermark advances regardless of whether the cap is hit.
+
+The manual `/curator scan` skill bypasses both rate gates. Useful for "I just landed N memories; re-check now."
+
+Option 4 was rejected because the user-visible benefit of a third tier is unclear at current memory-store sizes (typically tens of entries, not hundreds). It can be added later without changing the architecture if scale changes the calculus.
+
+Option 5 was rejected as a default because change-detection introduces a calibration problem (what counts as significant change?) on top of the staleness-detection problem. It is plausible as a future optimization layered on Option 3 (e.g., advance the LLM watermark when the memory store has changed by less than a threshold, to defer the next sweep).
+
+## Consequences
+
+### Positive
+
+- `SessionStart` latency stays bounded by the cheap-check wall-clock budget — typically well under 500ms.
+- The expensive LLM sweep runs at a cadence that matches the rate-of-change of the underlying signal (memories don't contradict each other on a per-minute basis).
+- A manual override (`/curator scan`) gives users the always-available "scan now" surface without making it the default.
+- Budget overruns are observable: `curator.scan.skipped` with `reason: "over_budget"` is a leading indicator that the memory store has grown enough to need tuning.
+- The watermark-gated sweep also caps cost: a user with a single high-traffic project pays at most N LLM-sweep calls per `llm_sweep_interval_days`.
+
+### Negative
+
+- A contradiction introduced today may go up to 7 days before being flagged. This is the cost of weekly cadence. Mitigation: the manual `/curator scan` exists; users who notice they just added two conflicting memories can force a check.
+- The two-tier model is slightly more complex than one tier. Two watermarks (cheap-tier last-run, LLM-tier last-sweep), two budget knobs, two skip reasons. The added complexity is small relative to the cost savings.
+- The cheap tier's wall-clock budget interacts badly with very large memory stores. At ≥200 memories, the cheap tier may itself need a per-memory cap (e.g., "scan only memories touched in the last N days"). Not yet a problem; flagged as a future open question.
+
+### Neutral
+
+- The choice of 7 days for `llm_sweep_interval_days` is a guess. Users who care can override. A future calibration could measure how often pair-similarity-with-opposing-sentiment results change verdict between consecutive sweeps; if the rate is low, the interval could grow.
+
+## Implementation Notes
+
+- The cheap-tier wall-clock budget is checked between sub-tasks, not within them. A single `rg` call that itself runs over budget is allowed to finish; the gate prevents *the next* sub-task from starting.
+- The LLM watermark is updated *before* the sweep begins, not after. This prevents a sweep that crashes midway from being retried immediately on the next `SessionStart`. The downside: a crashed sweep delays the next full check by the interval. Acceptable — better than a crash-retry loop.
+- Findings dedup uses `deduped_hash`. For `contradiction` findings the hash includes both memory bodies' content hashes, so an edit to either body re-opens the finding for re-evaluation on the next sweep.
+- Manual `/curator scan` updates the watermark like an automatic sweep — a user who runs the skill on Monday and Tuesday gets two LLM sweeps in two days, which is fine because they explicitly asked for it.
+- The cheap-tier and LLM-tier are independently configurable via `cheap_checks.enabled` and `llm_sweep.enabled`. Users can run either tier alone (e.g., LLM sweep off in a budget-sensitive project).
+
+## Validation
+
+- A memory store of ~50 entries should produce cheap-check sweeps under 200ms on a typical macOS dev laptop. If `curator.scan.skipped` with `reason: "over_budget"` fires at this size, the wall-clock budget needs tuning, not the design.
+- An LLM sweep at ~50 memories should make ≤20 pair-evaluation calls in the common case. The `max_pair_evaluations_per_sweep` cap of 50 should not be reached. If it is reached regularly, similarity threshold and sentiment-marker filtering need tuning.
+- Findings open for more than two LLM-sweep intervals without user action should produce a `curator.finding.aged_unhandled` summary event — an integration point for counsel's weekly brief.
+
+## References
+
+- Cartographer design — precedent for background audits with per-finding events (`plugins/cartographer/docs/design.md`)
+- Compass ADR-001 — precedent for explicit budget gates and skip-reason events (`plugins/compass/docs/adr/001-evaluate-prompts-in-context.md`)
+- Memory architecture overview (`docs/memory-architecture.md`)
+- Curator design (`../design.md`)