@lorekit/cli 1.27.0 → 1.29.0

package/README.md

@@ -75,12 +75,41 @@ lorekit install --global      # set it up for every project
 ```
 
 In a TTY it prompts for the scope (and for `--endpoint` / `--token` if missing).
-Flags: `--project` / `--global` pick the scope non-interactively; `--no-hooks`
-installs the skills + MCP only (memory stays model-invoked); `--yes` runs
+Flags: `--project` / `--global` pick the scope non-interactively; `--yes` runs
 non-interactively (endpoint required via flag/env; scope defaults to project);
 `--force` overwrites an existing skill copy. Re-running is idempotent — the hook
 entries are updated in place, never duplicated.
 
+#### Choosing the hooks
+
+The hooks are a separate, explicit choice — they add a `lorekit hook` subprocess
+to three Claude Code lifecycle events and write into `settings.json`, so install
+asks rather than assuming. **None of them writes memory:** they inject context,
+and the write is still the model calling `memory.write`.
+
+| Mode | Wires | What you get |
+|------|-------|--------------|
+| `all` | `SessionStart`, `PostToolUseFailure`, `Stop` | Lessons injected at session start, plus a nudge on a tool failure and a friction-gated one at end of turn |
+| `read-only` | `SessionStart` | Lessons injected; nothing ever nudges |
+| `none` | — | Skills + MCP only; memory stays model-invoked |
+
+```bash
+lorekit install --hooks read-only   # inject lessons, never nudge
+lorekit install --hooks none        # remove any wired hooks
+lorekit install --no-hooks --yes    # don't wire new ones; leave existing alone
+```
+
+In a TTY the prompt preselects whatever is **already wired**, so re-running
+install never resurrects hooks you declined; a genuinely fresh install
+preselects `all`. `--yes` / a non-TTY takes that same preselected value without
+asking — `all` on a fresh install, otherwise whatever is already wired (`none`
+if you previously removed them), and a hand-wired set that matches no preset
+keeps exactly that set — no event is added or removed, though a stale hook
+command is still refreshed. Pass `--hooks <mode>` to choose explicitly.
+`--hooks none` removes hooks that are already there; `--no-hooks` only skips
+wiring new ones. `lorekit doctor` reports which events are wired, and in which
+scope.
+
 > The hook command uses a global `lorekit` when one is on your `PATH` (fast),
 > otherwise `npx -y @lorekit/cli`. Installing the CLI globally
 > (`npm i -g @lorekit/cli`) is recommended so hooks fire without an npx
@@ -321,6 +350,7 @@ lorekit link global                       # the Explorer filtered to global scop
 lorekit link repo::owner/repo prefer-guards   # open one lesson's detail sheet
 lorekit link global::prefer-guards --json     # { url, surface, base, params }
 lorekit url --q "flaky test" --owner personal # search + ownership filter
+lorekit link global --tags "perf,ci"          # Explorer filtered to labels
 ```
 
 With no arguments it links to the cwd's **most-specific scope** ("share what I'm
@@ -331,8 +361,9 @@ that lesson's detail sheet. It sets **both** the `lesson` param (which opens the
 sheet) and `scope` — not because scope is needed to find the lesson (the sidebar
 reads one unfiltered recent set), but so the Explorer list *behind* the sheet is
 filtered to the lesson's own scope. Filter flags mirror the Explorer: `--q`
-(search), `--owner <all|personal|orgId>`, `--range`/`--from`/`--to`, `--archived`,
-`--view <scope|time>`.
+(search), `--owner <all|personal|orgId>`, `--tags <a,b,c>` (label filter, AND
+across labels; comma-separated or a JSON array), `--range`/`--from`/`--to`,
+`--archived`, `--view <scope|time>`.
 
 Every param is `encodeURIComponent(JSON.stringify(value))` — the exact inverse of
 how the dashboard's `useUrlState` reads it back (`JSON.parse`, falling back to the
@@ -507,13 +538,20 @@ Both files share this schema — all fields optional:
                            // tags appended to every memory.write from this repo/user
                            // both layers merged: repo tags first, then user tags
 
+  "ttl.default": 90,
+                           // days until a write that named no TTL expires
+                           // repo wins over user (a scalar policy cannot merge)
+                           // omit for the historical behaviour: memories are permanent
+
   "scope.defaults": {
     "repo::owner/name":     { "tags": ["team"] },
-    "branch::owner/name::": { "tags": ["ephemeral"] }
+    "branch::owner/name::": { "tags": ["ephemeral"], "ttl_days": 14 },
+    "global":               { "ttl_days": null }
   },
-                           // per-scope tag defaults applied to writes whose scope
+                           // per-scope tag and TTL defaults applied to writes whose scope
                            // starts with the key; matched by prefix (no wildcards needed)
                            // repo config only — this is a team-level write policy
+                           // ttl_days: null means "permanent", overriding ttl.default
 
   // ── Hook behaviour ─────────────────────────────────────────────────────────
   "hooks.disabled": ["Stop"],
@@ -577,6 +615,58 @@ cannot override**:
 `lorekit doctor` to see the resolved mode, **which source decided it**, and any
 active deny constraints.
 
+### Default TTL
+
+A memory with no TTL never expires. That is still the out-of-the-box behaviour,
+and it is the right default for a lesson someone deliberately curated — but it is
+the wrong one for the steady drip of observations a hook nudges an agent into
+writing at the end of every run. `ttl.default` and
+`scope.defaults.<prefix>.ttl_days` let a repo say how long its lore stays fresh.
+
+**Precedence, most specific first:**
+
+| # | Source | Wins because |
+| - | ------ | ------------ |
+| 1 | `--ttl-days` / `--clear-ttl` | An explicit flag is the caller's assertion about this one memory. `--clear-ttl` is how you keep something forever in a repo that defaults to expiring. |
+| 2 | The longest matching `scope.defaults` prefix with a `ttl_days` key | The most specific scope is the one the config author meant. `null` there means permanent. |
+| 3 | `ttl.default` | The repo-wide (or user-wide) fallback. |
+| 4 | No expiry | Nothing configured. |
+
+Prefix matching is `::`-delimited, so `branch::` covers every branch scope while
+`repo::owner` does **not** cover `repo::owner/name` — `owner/name` is a single
+segment. Tags from `scope.defaults` union across every matching prefix; a TTL
+cannot, so exactly one entry wins.
+
+A configured TTL that is out of range (or not a number) is **ignored** — the
+write succeeds with no expiry rather than failing. Config is ambient state that
+must never break an unrelated write; `--ttl-days 999`, by contrast, is a usage
+error, because you typed it. `lorekit write` names the source in its output:
+
+```
+  expires in 90 days (from config)
+```
+
+**Two limits worth knowing.** First, this is a **client-side** default: the
+hosted `memory.write` contract is unchanged, so omitting `ttl_*` there still
+means permanent. An agent talking straight to the MCP endpoint never sees your
+config file. Second, a **hook cannot apply it** — hooks only read lore and emit
+text; the write happens afterwards, in the agent's context. So the nudges instead
+*advise* the resolved number:
+
+```
+LoreKit: hit any friction worth remembering … Set ttl_days: 90 (this scope's
+configured default) unless the lesson is durable enough to keep forever.
+```
+
+That is advice, not enforcement. An agent that ignores it writes a permanent
+memory, exactly as before.
+
+**Refresh on update is free.** `memory_write` refreshes `expires_at` only when a
+`ttl_*` is supplied, so re-writing the same `scope`+`key` with the default
+applied slides the window forward — a lesson that keeps recurring keeps living,
+and one nobody has seen in 90 days decays. Expired rows are swept nightly, which
+also returns their headroom against the plan's memory cap.
+
 ## Options
 
 | Flag | Meaning |
@@ -592,7 +682,8 @@ active deny constraints.
 | `--to <tier>` | Migration destination tier: `home` / `project` (`migrate`; default routes by scope) |
 | `--apply` | Apply the migration — alias of `--yes` (`migrate`) |
 | `-y, --yes` | Non-interactive / apply; never prompt |
-| `--no-hooks` | Skip wiring the lifecycle hooks; skills + MCP only (`install`) |
+| `--hooks <mode>` | Lifecycle hooks to wire: `all` / `read-only` / `none` (`install`; `none` removes any already wired) |
+| `--no-hooks` | Skip wiring the lifecycle hooks; skills + MCP only. Leaves already-wired hooks alone (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
 | `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `link`) |

package/bin/lorekit.mjs

@@ -40,8 +40,10 @@ ${c.bold('Commands')}
               LoreKit MCP server, and install the deterministic hooks (memories
               on SessionStart, a nudge on tool failure + at Stop). Prompts to
               install for this project (.claude) or globally for every project
-              (~/.claude); --project / --global choose non-interactively,
-              --no-hooks skips the hooks (skills stay model-invoked only).
+              (~/.claude); --project / --global choose non-interactively.
+              Also prompts whether to wire the hooks (all / read-only /
+              none); --hooks <mode> chooses non-interactively and --no-hooks
+              skips them (skills stay model-invoked only).
   uninstall   Reverse install: remove the lorekit-memory + lorekit-setup skills,
               the MCP server entry, and the lifecycle hooks for the chosen scope. Surgical —
               other servers, hooks, and settings are left untouched. Prompts
@@ -85,8 +87,8 @@ ${c.bold('Commands')}
   link (url)  Print a shareable dashboard deep-link URL for the current context,
               a scope, or a specific lesson (opens its detail sheet). No args
               links to the cwd's most-specific scope. Filter flags mirror the
-              Explorer (--q / --owner / --range / --archived / --view); --base or
-              LOREKIT_APP_URL override the dashboard host. --json. Pipe it:
+              Explorer (--q / --owner / --tags / --range / --archived / --view);
+              --base or LOREKIT_APP_URL override the dashboard host. --json. Pipe it:
               lorekit link | pbcopy.
   bootstrap   Apply the BYOD schema to a user-supplied Supabase database.
               Only needed when using LOREKIT_STORAGE_URL / LOREKIT_STORAGE_ANON_KEY.
@@ -119,6 +121,7 @@ ${c.bold('Options')}
                           default routes each entry by scope)
       --apply             Apply the migration (alias of --yes) (migrate)
   -y, --yes               Non-interactive / apply; never prompt
+      --hooks <mode>      Lifecycle hooks to wire: all | read-only | none (install)
       --no-hooks          Skip wiring the lifecycle hooks (install)
       --force             Overwrite existing skill files (install)
       --deep              Do a write→read→delete round-trip (doctor)
@@ -162,8 +165,19 @@ ${c.bold('Usage')}
   npx @lorekit/cli install [options]
 
 Scaffolds the lorekit-memory (runtime read/write) and lorekit-setup (loop
-authoring) skills, adds the LoreKit MCP server, and wires the deterministic
-hooks (memories on SessionStart, a nudge on tool failure + at Stop).
+authoring) skills, adds the LoreKit MCP server, and asks whether to wire the
+deterministic hooks. The hooks inject context — they never write memory
+themselves; the write is still the model calling memory.write.
+
+${c.bold('Hook modes')}
+  all         SessionStart (inject lessons) + PostToolUseFailure and Stop
+              (nudge you to record one). Preselected on a fresh install.
+  read-only   SessionStart only — lessons are injected, nothing ever nudges.
+  none        No hooks; the skills stay model-invoked only.
+
+An interactive run preselects whatever is already wired, so re-running install
+never resurrects hooks you declined. Answering "No hooks" (or --hooks none)
+REMOVES hooks that are already there; --no-hooks only skips wiring new ones.
 
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
@@ -171,13 +185,16 @@ ${c.bold('Options')}
       --global            Install for every project: ~/.claude/skills + ~/.claude.json
   -e, --endpoint <url>    LoreKit MCP endpoint (else LOREKIT_MCP_URL)
   -t, --token <token>     LoreKit token: lk_rw_* read+write, lk_ro_* read-only, lk_wo_* write-only
-      --no-hooks          Skip wiring the lifecycle hooks (skill stays model-invoked only)
+      --hooks <mode>      Wire the lifecycle hooks: all | read-only | none
+      --no-hooks          Skip wiring the lifecycle hooks (leaves existing ones alone)
       --force             Overwrite existing skill files
-  -y, --yes               Non-interactive; never prompt (defaults to --project)
+  -y, --yes               Non-interactive; never prompt (defaults to --project, and to the
+                          already-wired hooks — all on a fresh install)
 
 ${c.bold('Examples')}
   npx @lorekit/cli install --endpoint https://ref.supabase.co/functions/v1/mcp --token lk_rw_xxx
   npx @lorekit/cli install --global
+  npx @lorekit/cli install --hooks read-only --yes
   npx @lorekit/cli install --no-hooks --yes
 `,
   uninstall: `${c.bold('lorekit uninstall')} — reverse install for the chosen scope
@@ -506,6 +523,7 @@ ${c.bold('Options')}
       --scope <scope>     Scope to link to (when no positional scope is given)
       --q <text>          Pre-fill the Explorer search box
       --owner <o>         Ownership filter: all | personal | <orgId>
+      --tags <a,b,c>      Label filter (AND across labels); comma-separated or a JSON array
       --range <json>      Date range as {"from":"YYYY-MM-DD","to":"YYYY-MM-DD"}
       --from <date>       Range start (shorthand for --range)
       --to <date>         Range end (shorthand for --range)
@@ -521,6 +539,7 @@ ${c.bold('Examples')}
   npx @lorekit/cli link repo::owner/repo prefer-guards   # open one lesson's detail sheet
   npx @lorekit/cli link global::prefer-guards --json     # { url, surface, base, params }
   npx @lorekit/cli url --q "flaky test" --owner personal # search + ownership filter
+  npx @lorekit/cli link global --tags "perf,ci"          # Explorer filtered to labels
 `,
   migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store into the current layout
 
@@ -573,7 +592,7 @@ ${c.bold('Options')}
 // typo like `--gloabl` should fail loudly, not quietly fall back to --project.
 const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
-  'from', 'to', 'apply', 'yes', 'no-hooks', 'force', 'deep', 'adapter',
+  'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'force', 'deep', 'adapter',
   'event', 'json', 'scope', 'threshold', 'help', 'version',
   'value', 'tags', 'source-agent', 'trigger', 'ttl-days', 'clear-ttl', 'org', 'remote', 'local',
   'link', 'base', 'q', 'owner', 'range', 'view', 'archived',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.27.0",
+  "version": "1.29.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/config.mjs

@@ -144,20 +144,94 @@ function readServerFromFile(file) {
   return { server, url: url || null };
 }
 
+// The hook wiring presets `install` offers. They are presets over
+// CLAUDE_HOOK_EVENTS, NOT a per-event checkbox list — the meaningful decision a
+// user makes is "read my lessons / also nudge me / neither", and `hooks.disabled`
+// already exists for surgical per-event suppression after the fact.
+//   all       — every lifecycle event (the recommended default)
+//   read-only — SessionStart only: lessons are injected, nothing ever nudges
+//   none      — no hooks; the skills stay model-invoked only
+export const HOOK_MODES = ['all', 'read-only', 'none'];
+
+// Pure: the events a mode wires. An unknown mode yields the full set, so a
+// mis-typed value can never silently disable the hooks — `install` validates the
+// flag up front and refuses instead.
+export function hookEventsForMode(mode) {
+  if (mode === 'none') return [];
+  if (mode === 'read-only') return ['SessionStart'];
+  return [...CLAUDE_HOOK_EVENTS];
+}
+
+// Pure inverse of `hookEventsForMode`: which mode does this set of wired events
+// correspond to? `custom` for anything that matches no preset (e.g. someone hand-
+// wired only `Stop`) — the caller must not silently rewrite such a setup.
+export function hookModeFromEvents(events) {
+  const set = new Set(events || []);
+  for (const mode of HOOK_MODES) {
+    const want = hookEventsForMode(mode);
+    if (want.length === set.size && want.every((e) => set.has(e))) return mode;
+  }
+  return 'custom';
+}
+
+// Extract the flat list of hook command strings for one event out of the nested
+// group shape Claude Code uses: { [event]: [ { hooks: [ { type, command } ] } ] }.
+export function hookCommandsForEvent(hooksObj, event) {
+  const groups = hooksObj && Array.isArray(hooksObj[event]) ? hooksObj[event] : [];
+  const commands = [];
+  for (const group of groups) {
+    const inner = group && Array.isArray(group.hooks) ? group.hooks : [];
+    for (const h of inner) {
+      if (h && typeof h.command === 'string') commands.push(h.command);
+    }
+  }
+  return commands;
+}
+
+// Which CLAUDE_HOOK_EVENTS currently have a lorekit hook wired in this scope's
+// settings file. Best-effort: an absent or unparseable file reads as none — this
+// is a detection helper (it decides a prompt default and a doctor line), never a
+// write path, so it must not throw. The single reader shared by `install` and
+// `doctor` so the two can never disagree about what is wired.
+export function installedHookEvents(root, scope = 'project') {
+  let hooks = {};
+  try {
+    const cfg = JSON.parse(fs.readFileSync(settingsPath(root, scope), 'utf8'));
+    if (cfg && typeof cfg.hooks === 'object' && cfg.hooks) hooks = cfg.hooks;
+  } catch {
+    return [];
+  }
+  return CLAUDE_HOOK_EVENTS.filter((event) =>
+    hookCommandsForEvent(hooks, event).some((cmd) => LOREKIT_HOOK_RE.test(cmd)),
+  );
+}
+
 // Wire the lorekit hook engine into Claude Code settings for the scope,
 // preserving all other settings and any non-lorekit hooks. Idempotent: an
 // existing lorekit hook entry per event is updated in place, never duplicated.
 // `runner` is the command prefix (e.g. 'lorekit' or 'npx -y @lorekit/cli').
-export function upsertClaudeHooks(root, scope, runner) {
+//
+// `events` selects WHICH of CLAUDE_HOOK_EVENTS to wire (default: all of them).
+// Any lorekit entry for a CLAUDE_HOOK_EVENT *not* in the list is REMOVED — that
+// pruning is what makes a downgrade (all → read-only) an actual downgrade rather
+// than an additive no-op that leaves the nudges firing. Only lorekit's own
+// entries are touched; a co-located third-party hook on the same event survives.
+export function upsertClaudeHooks(root, scope, runner, events = CLAUDE_HOOK_EVENTS) {
   const file = settingsPath(root, scope);
   const config = readJsonIfExists(file) || {};
   if (!config.hooks || typeof config.hooks !== 'object') config.hooks = {};
 
+  const wanted = new Set(events);
   let added = 0;
   let updated = 0;
   let unchanged = 0;
+  let removed = 0;
 
   for (const event of CLAUDE_HOOK_EVENTS) {
+    if (!wanted.has(event)) {
+      removed += pruneLorekitHooks(config.hooks, event);
+      continue;
+    }
     const command = `${runner} hook --adapter claude --event ${event} --dir "\${CLAUDE_PROJECT_DIR}"`;
     if (!Array.isArray(config.hooks[event])) config.hooks[event] = [];
     const groups = config.hooks[event];
@@ -183,8 +257,31 @@ export function upsertClaudeHooks(root, scope, runner) {
     }
   }
 
+  if (Object.keys(config.hooks).length === 0) delete config.hooks;
+
   writeFileAtomic(file, JSON.stringify(config, null, 2) + '\n');
-  return { file, added, updated, unchanged };
+  return { file, added, updated, unchanged, removed };
+}
+
+// Drop every lorekit hook entry for one event from a hooks object, tidying up
+// the groups and the event key it empties. Returns how many entries went. Shared
+// by `upsertClaudeHooks`'s pruning and `removeClaudeHooks`'s full teardown.
+function pruneLorekitHooks(hooksObj, event) {
+  const groups = hooksObj[event];
+  if (!Array.isArray(groups)) return 0;
+
+  let removed = 0;
+  for (const group of groups) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    const before = group.hooks.length;
+    group.hooks = group.hooks.filter(
+      (h) => !(h && typeof h.command === 'string' && LOREKIT_HOOK_RE.test(h.command)),
+    );
+    removed += before - group.hooks.length;
+  }
+  hooksObj[event] = groups.filter((g) => g && Array.isArray(g.hooks) && g.hooks.length > 0);
+  if (hooksObj[event].length === 0) delete hooksObj[event];
+  return removed;
 }
 
 // Throwing read — used by `install` so a corrupt .mcp.json aborts the write
@@ -279,20 +376,9 @@ export function removeClaudeHooks(root, scope = 'project') {
   }
 
   let removed = 0;
+  // Snapshot the keys: pruneLorekitHooks deletes the ones it empties.
   for (const event of Object.keys(config.hooks)) {
-    const groups = config.hooks[event];
-    if (!Array.isArray(groups)) continue;
-    for (const group of groups) {
-      if (!group || !Array.isArray(group.hooks)) continue;
-      const before = group.hooks.length;
-      group.hooks = group.hooks.filter(
-        (h) => !(h && typeof h.command === 'string' && LOREKIT_HOOK_RE.test(h.command)),
-      );
-      removed += before - group.hooks.length;
-    }
-    // Drop groups we emptied, then the event key if it has no groups left.
-    config.hooks[event] = groups.filter((g) => g && Array.isArray(g.hooks) && g.hooks.length > 0);
-    if (config.hooks[event].length === 0) delete config.hooks[event];
+    removed += pruneLorekitHooks(config.hooks, event);
   }
   if (Object.keys(config.hooks).length === 0) delete config.hooks;
 

package/src/control.mjs

@@ -2,8 +2,10 @@
 // target, who decided, and which deny constraints are active. Also resolves
 // write-behaviour properties from the config layers:
 //
-//   scope.defaults  — map of scope-prefix → { tags } applied to every matching write
+//   scope.defaults  — map of scope-prefix → { tags, ttl_days } applied to every
+//                     matching write
 //   tags.default    — array of tags appended to every write (both layers merged)
+//   ttl.default     — days until a write with no explicit TTL expires
 //   hooks.disabled  — array of hook event names to suppress (e.g. ["Stop"])
 //   hooks.stop      — Stop-hook gating ("friction" default | "always" | "off")
 //   hooks.adapter   — explicit adapter override ("claude" | "cursor" | "codex")
@@ -53,6 +55,31 @@ export function normalizeStopMode(v) {
   return null;
 }
 
+// A config value that is meant to be a number, or null when it is absent or is
+// something else entirely. Numeric strings are accepted because JSON configs get
+// hand-edited; the RANGE check happens later, at the point of use.
+function firstNumber(v) {
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+  if (typeof v === 'string' && v.trim() !== '') {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+// Whether a config layer DECLARED a scalar policy value — the layer-selection
+// predicate for keys that cannot merge. Same shape as the `hooks.adapter` guard
+// below: a layer that put something usable-looking there owns the decision, even
+// when the something turns out to be unparseable. Selecting the layer on the
+// PARSED value instead is the bug: `firstNumber(repo) ?? firstNumber(user)` makes
+// a garbage repo value (`"ttl.default": "90 days"`) indistinguishable from an
+// absent one, so the user layer silently takes over and the retention a write
+// gets depends on state outside the repository — two developers on the same
+// commit would disagree, and neither could tell from the checkout.
+function declaresScalar(v) {
+  return typeof v === 'number' || (typeof v === 'string' && v.trim() !== '');
+}
+
 function asList(v) {
   if (Array.isArray(v)) return v;
   if (typeof v === 'string') return v.split(',').map((s) => s.trim()).filter(Boolean);
@@ -131,9 +158,34 @@ export function resolveControl({
     ...asList(userConfig['tags.default']),
   ].filter((t) => typeof t === 'string' && t.length > 0);
 
+  // `ttl.default` — days until a write that named no TTL expires. A SCALAR
+  //    policy, so it cannot merge the way `tags.default` does: repo wins over
+  //    user, matching `hooks.adapter`. Read as "the project decided how long its
+  //    lore stays fresh"; a user who disagrees can still pass --ttl-days or
+  //    --clear-ttl per write, which always outranks config.
+  //
+  //    Deliberately NOT validated here. `resolveControl` is the pure resolver
+  //    every command calls, including read-only ones — a `"ttl.default": 900`
+  //    typo must not make `lorekit list` throw. The value is bounds-checked at
+  //    the point of use (resolveDefaultTtlDays), where an invalid one degrades
+  //    to "no default".
+  //
+  //    Which is exactly why the LAYER is chosen before the value is parsed (see
+  //    declaresScalar): "repo wins" has to hold for a repo value that is wrong,
+  //    or a typo'd project policy silently becomes a per-machine one instead of
+  //    degrading to "no default". An absent key and an explicit `null` still
+  //    fall through to the user layer — only a declared, usable-looking value
+  //    claims the decision.
+  const ttlDefaultRaw = declaresScalar(repoConfig['ttl.default'])
+    ? repoConfig['ttl.default']
+    : userConfig['ttl.default'];
+  const ttlDefault = firstNumber(ttlDefaultRaw);
+
   // `scope.defaults` — repo layer only (team-scoped write policy).
-  //    Schema: { "<scope-prefix>": { "tags": [...] } }
+  //    Schema: { "<scope-prefix>": { "tags": [...], "ttl_days": <n> | null } }
   //    Matched against a write's resolved scope using startsWith — no glob dep.
+  //    `ttl_days: null` is meaningful (permanent), so a per-scope entry can opt
+  //    out of `ttl.default` — see resolveDefaultTtlDays.
   const scopeDefaults =
     repoConfig['scope.defaults'] && typeof repoConfig['scope.defaults'] === 'object'
       ? repoConfig['scope.defaults']
@@ -186,6 +238,7 @@ export function resolveControl({
     denies,
     connection,
     tagsDefault,
+    ttlDefault,
     scopeDefaults,
     hooksDisabled,
     hooksStop,

package/src/core/lessons.mjs

@@ -13,6 +13,12 @@ import { resolvePrecedence, matchesQuery } from '../lessons-pure.mjs';
 // correctly (a raw `?scope=global` silently means "all scopes") and can't drift
 // from the command-line links.
 import { loreScopeUrl, buildLessonUrl } from '../deeplink-pure.mjs';
+// The SAME resolver `lorekit write` applies, so the TTL the nudge advises an
+// agent to send is byte-for-byte the one the CLI would have applied itself. A
+// hook cannot set a TTL — it only reads and emits text; the write happens later,
+// over MCP, in the agent's context. Advising the number is the only lever the
+// hook has, which is exactly why it must not be a second, hand-kept copy.
+import { resolveDefaultTtlDays, matchesScopePrefix } from '../store/ttl.mjs';
 import { FRICTION_FAILURE, FRICTION_STUCK_LOOP } from './friction.mjs';
 
 const MAX_LESSONS = 15;
@@ -167,10 +173,10 @@ function tagsHint(writeScope, control) {
   const tags = [...tagsDefault];
   if (scopeDefaults) {
     for (const [prefix, cfg] of Object.entries(scopeDefaults)) {
-      if (
-        writeScope === prefix ||
-        writeScope.startsWith(prefix.endsWith('::') ? prefix : prefix + '::')
-      ) {
+      // Tags UNION across every matching prefix — they accumulate, so a broad
+      // and a narrow entry both contribute. The TTL hint below deliberately does
+      // NOT: a memory has one expiry, so the most specific prefix wins outright.
+      if (matchesScopePrefix(writeScope, prefix)) {
         for (const t of Array.isArray(cfg.tags) ? cfg.tags : []) {
           if (typeof t === 'string' && t.length > 0 && !tags.includes(t)) tags.push(t);
         }
@@ -181,6 +187,19 @@ function tagsHint(writeScope, control) {
   return ` Include tags: [${tags.map((t) => JSON.stringify(t)).join(', ')}].`;
 }
 
+// Build the TTL hint appended to a nudge. Empty string when the scope has no
+// configured default, so an unconfigured repo's nudge is unchanged.
+//
+// Phrased as an instruction to pass `ttl_days` rather than as a statement about
+// what will happen, because nothing enforces it: the agent is about to call
+// `memory.write` over MCP, where omitting `ttl_days` still means permanent. The
+// hint is advice with a number attached — the same posture as the tags hint.
+function ttlHint(writeScope, control) {
+  const days = resolveDefaultTtlDays(writeScope, control || {});
+  if (days == null) return '';
+  return ` Set ttl_days: ${days} (this scope's configured default) unless the lesson is durable enough to keep forever.`;
+}
+
 // One-line phrases for the detected friction reason codes (see core/friction.mjs),
 // so the nudge names what happened instead of a generic prompt.
 const REASON_PHRASES = {
@@ -208,7 +227,7 @@ function describeReasons(reasons) {
 // which is where a link is actually actionable.
 export function retrospectiveNudge(scope, control, { reasons = [] } = {}) {
   const writeScope = scope.repoScope || 'global';
-  const hint = tagsHint(writeScope, control);
+  const hint = `${tagsHint(writeScope, control)}${ttlHint(writeScope, control)}`;
   const instruction = control && control.hooksInstructions && control.hooksInstructions.Stop
     ? `\n\nProject instruction: ${control.hooksInstructions.Stop}` : '';
   const detected = describeReasons(reasons);
@@ -240,7 +259,7 @@ export function writeConfirmation(scope, key, writtenScope) {
 // scopeDefaults when the repo/user config defines them.
 export function failureNudge(toolName, scope, control) {
   const writeScope = scope.repoScope || 'global';
-  const hint = tagsHint(writeScope, control);
+  const hint = `${tagsHint(writeScope, control)}${ttlHint(writeScope, control)}`;
   const instruction = control && control.hooksInstructions && control.hooksInstructions.PostToolUseFailure
     ? `\n\nProject instruction: ${control.hooksInstructions.PostToolUseFailure}` : '';
   return (

package/src/deeplink-pure.mjs

@@ -29,14 +29,17 @@ export const LORE_PARAM_DEFAULTS = {
   q: '', // string search query
   range: null, // { from, to } | null (DateRange, "YYYY-MM-DD")
   owner: 'all', // 'all' | 'personal' | { orgId }
+  tags: [], // string[] — label filter (AND across labels); [] means "no filter"
   view: 'scope', // 'scope' | 'time'
   archived: false, // boolean
   lesson: null, // { scope, key } | null — opens the detail sheet
 };
 
 // A stable, readable param order (also makes URLs deterministic for tests).
-// `scope` precedes `lesson` so a lesson link reads `?scope=…&lesson=…`.
-const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'view', 'archived', 'lesson'];
+// Mirrors the `useUrlState` call order in `LoreExplorer.tsx` (+ the `lesson`
+// param last), so `tags` sits between `owner` and `view`. `scope` precedes
+// `lesson` so a lesson link reads `?scope=…&lesson=…`.
+const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'tags', 'view', 'archived', 'lesson'];
 
 // Strip trailing slashes from a base URL, falling back to the default when the
 // input is empty/absent. Pure.
@@ -154,6 +157,44 @@ export function parseViewArg(view) {
   return view === 'time' ? 'time' : 'scope';
 }
 
+// Coerce the `--tags` flag to a normalized `string[]` label filter, mirroring the
+// web app's `normalizeTags` (`packages/web/src/lib/tag-filter.ts`): trim each
+// entry, drop empties, de-duplicate, preserve first-seen order. Accepts either a
+// JSON array string (`'["perf","ci"]'`) or the friendlier comma-separated form
+// (`'perf, ci'`); a malformed JSON array falls back to comma-splitting rather
+// than throwing. Returns `[]` for absent/empty input (the default → omitted from
+// the URL). Pure.
+export function parseTagsArg(tags) {
+  if (Array.isArray(tags)) return normalizeTagList(tags);
+  if (typeof tags !== 'string' || !tags.trim()) return [];
+  const s = tags.trim();
+  if (s.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(s);
+      if (Array.isArray(parsed)) return normalizeTagList(parsed);
+    } catch {
+      /* malformed JSON array → fall through to comma-splitting */
+    }
+  }
+  return normalizeTagList(s.split(','));
+}
+
+// Trim, drop non-string/empty entries, and de-duplicate preserving order. The
+// CLI-side twin of the web's `normalizeTags`; kept inline to keep this module
+// zero-import. Pure.
+function normalizeTagList(list) {
+  const seen = new Set();
+  const out = [];
+  for (const item of list) {
+    if (typeof item !== 'string') continue;
+    const t = item.trim();
+    if (!t || seen.has(t)) continue;
+    seen.add(t);
+    out.push(t);
+  }
+  return out;
+}
+
 // Coerce the date-range flags to a `{ from, to }` DateRange or null. `--range`
 // (a JSON object string) wins; else `--from`/`--to` shorthand builds one (both
 // keys always present so the shape matches the app's DateRange). A malformed

package/src/doctor.mjs

@@ -8,9 +8,9 @@ import {
   SKILLS,
   resolveProjectRoot,
   skillInstallDir,
-  settingsPath,
   CLAUDE_HOOK_EVENTS,
-  LOREKIT_HOOK_RE,
+  installedHookEvents,
+  hookModeFromEvents,
   readLorekitServer,
   readMcpConfig,
   tokenKind,
@@ -66,6 +66,28 @@ export async function doctor(args) {
     }
   }
 
+  // 2.4. Which hooks are actually wired, and where. Hooks are an install-time
+  // CHOICE (`--hooks all|read-only|none`, or the prompt), so "why does nothing
+  // get remembered?" is answered HERE — without a positive report the only way
+  // to tell a deliberate `none` from a broken install is to read settings.json.
+  {
+    const perScope = ['project', 'global']
+      .map((s) => ({ scope: s, events: installedHookEvents(root, s) }))
+      .filter((entry) => entry.events.length > 0);
+    if (perScope.length === 0) {
+      record(
+        'info',
+        'hooks',
+        'none wired — the skills work, but memory is model-invoked only. ' +
+          'Run `lorekit install --hooks all` to wire them.',
+      );
+    } else {
+      for (const { scope, events } of perScope) {
+        record('pass', `hooks ${scope}`, `${hookModeFromEvents(events)} — ${events.join(', ')}`);
+      }
+    }
+  }
+
   // 2.5. Duplicate-hook detection — warn when the same lorekit hook event is
   // wired in both the project settings and the global settings. This causes
   // Claude Code to fire the hook twice per event, producing doubled terminal
@@ -349,43 +371,14 @@ async function deepCheckLocal(store, scope, record) {
 // Returns the list of CLAUDE_HOOK_EVENTS whose lorekit hook command appears in
 // BOTH the project settings file (.claude/settings.json) and the global one
 // (~/.claude/settings.json). An empty array means no duplicates — healthy.
+//
+// Both sides read through `installedHookEvents`, the SAME detection `install`
+// uses to preselect its hook prompt, so the two surfaces can never disagree
+// about what is wired.
 function detectDuplicateHooks(root) {
-  const dupes = [];
-  const projectFile = settingsPath(root, 'project');
-  const globalFile = settingsPath(root, 'global');
-
-  let projectHooks = {};
-  let globalHooks = {};
-  try {
-    const cfg = JSON.parse(fs.readFileSync(projectFile, 'utf8'));
-    if (cfg && typeof cfg.hooks === 'object') projectHooks = cfg.hooks;
-  } catch { /* absent or unparseable — treat as empty */ }
-  try {
-    const cfg = JSON.parse(fs.readFileSync(globalFile, 'utf8'));
-    if (cfg && typeof cfg.hooks === 'object') globalHooks = cfg.hooks;
-  } catch { /* absent or unparseable — treat as empty */ }
-
-  for (const event of CLAUDE_HOOK_EVENTS) {
-    const hasInProject = hooksForEvent(projectHooks, event).some((cmd) => LOREKIT_HOOK_RE.test(cmd));
-    const hasInGlobal = hooksForEvent(globalHooks, event).some((cmd) => LOREKIT_HOOK_RE.test(cmd));
-    if (hasInProject && hasInGlobal) dupes.push(event);
-  }
-  return dupes;
-}
-
-// Extract the flat list of hook command strings for one event from a hooks
-// object. Handles the nested-group shape Claude Code uses:
-// { [event]: [ { hooks: [ { type, command } ] } ] }
-function hooksForEvent(hooksObj, event) {
-  const groups = Array.isArray(hooksObj[event]) ? hooksObj[event] : [];
-  const commands = [];
-  for (const group of groups) {
-    const inner = group && Array.isArray(group.hooks) ? group.hooks : [];
-    for (const h of inner) {
-      if (h && typeof h.command === 'string') commands.push(h.command);
-    }
-  }
-  return commands;
+  const inProject = new Set(installedHookEvents(root, 'project'));
+  const inGlobal = new Set(installedHookEvents(root, 'global'));
+  return CLAUDE_HOOK_EVENTS.filter((event) => inProject.has(event) && inGlobal.has(event));
 }
 
 async function checkBYODStorage(record) {

package/src/install.mjs

@@ -11,7 +11,10 @@ import {
   upsertMcpServer,
   upsertClaudeHooks,
   resolveHookRunner,
-  CLAUDE_HOOK_EVENTS,
+  HOOK_MODES,
+  hookEventsForMode,
+  hookModeFromEvents,
+  installedHookEvents,
   resolveConnection,
   tokenKind,
   homeDir,
@@ -20,7 +23,7 @@ import {
 } from './config.mjs';
 import { buildRemoteUrl, splitEndpoint } from './mcp.mjs';
 import { deriveScope } from './scope.mjs';
-import { log, heading, status, select, c } from './util.mjs';
+import { log, heading, status, select, err, c } from './util.mjs';
 
 // The MCP server URL is fixed — there is only one hosted LoreKit endpoint.
 const LOREKIT_MCP_ENDPOINT = 'https://pqokxlhvnosogizsjztg.supabase.co/functions/v1/mcp';
@@ -60,11 +63,97 @@ function detectInstalled(root, scope) {
   };
 }
 
+// The interactive hook choice, as data so it can be asserted on without a pty.
+//
+// Deliberately THREE options, not a yes/no: `SessionStart` is a pure read that
+// injects existing lessons, while the other two only nudge. A single yes/no
+// bundles them, so a user who declines because they don't want to be nudged
+// also loses lesson injection — the thing LoreKit is for. Each hint says what
+// the hooks DO (inject context, nudge); none of them writes memory, and copy
+// that implied otherwise would ask for consent to something that never happens.
+export const HOOK_PROMPT_OPTIONS = [
+  {
+    label: 'Yes, all of them',
+    value: 'all',
+    hint: 'inject lessons at session start; nudge on a tool failure and at end of turn',
+  },
+  {
+    label: 'Read-only',
+    value: 'read-only',
+    hint: 'inject lessons at session start; never nudge',
+  },
+  {
+    label: 'No hooks',
+    value: 'none',
+    hint: 'skills + MCP only; memory stays model-invoked',
+  },
+];
+
+// Pure: which hook mode should the interactive prompt preselect?
+//
+// The default is the DETECTED state, not a constant — `install` is explicitly
+// re-runnable (token refresh, `--force`, completing a partial install), so a
+// constant "all" would silently resurrect hooks a user previously declined.
+// A genuinely fresh install has nothing to detect, so it preselects `all`: that
+// is the "opt in by default" the prompt is there to promote. A hand-wired subset
+// that matches no preset (`custom`) preselects `all` too — there is no preset to
+// re-offer, and the user still sees and chooses from the three options.
+//
+// That last clause is load-bearing and INTERACTIVE-ONLY: it is safe precisely
+// because the user is then shown the list and picks. A `--yes` / non-TTY run has
+// no such moment, so it must NOT take this value for a `custom` set — see
+// `install`, which leaves a hand-wired wiring untouched instead.
+export function defaultHookMode({ freshInstall, wiredEvents }) {
+  if (freshInstall) return 'all';
+  const detected = hookModeFromEvents(wiredEvents);
+  return detected === 'custom' ? 'all' : detected;
+}
+
+// Resolve the requested hook mode from the flags, or null when nothing was
+// specified (the caller then prompts / falls back). `--hooks <mode>` is the
+// explicit selector; `--no-hooks` is the pre-existing boolean and keeps its
+// documented SKIP semantics — it never removes hooks that are already wired,
+// which is why it maps to `none` here but is tracked separately below.
+//
+// A VALUELESS `--hooks` is a usage error, not an absent flag. `hooks` is not in
+// `parseArgs`' `booleans` list, so `--hooks --yes` and a trailing `--hooks`
+// both yield `true` and `--hooks=` yields `''`. Returning null for those would
+// resolve to the DETECTED mode — the exact silent fallback the validation below
+// exists to prevent — so they are surfaced as the sentinel `INVALID_HOOK_MODE`
+// and rejected alongside `--hooks bogus`. Mirrors `write.mjs`'s bare
+// `--ttl-days`, which feeds NaN to its validator for the same reason: an
+// explicitly supplied flag is a caller assertion, so a malformed one must fail.
+export const INVALID_HOOK_MODE = '(missing value)';
+
+function requestedHookMode(args) {
+  const raw = args.hooks;
+  if (typeof raw === 'string' && raw.trim()) return raw.trim().toLowerCase();
+  if (raw !== undefined && raw !== false) return INVALID_HOOK_MODE;
+  if (args['no-hooks']) return 'none';
+  return null;
+}
+
 export async function install(args) {
   const root = resolveProjectRoot(args.dir);
   const nonInteractive = Boolean(args.yes) || !process.stdin.isTTY;
   const force = Boolean(args.force);
 
+  // Validate `--hooks` before touching anything on disk: a mistyped mode must
+  // fail loudly, never silently fall back to a different wiring than asked for.
+  const requestedMode = requestedHookMode(args);
+  if (requestedMode === INVALID_HOOK_MODE) {
+    err(`\n  --hooks needs a mode. Valid modes: ${HOOK_MODES.join(' | ')}.`);
+    return 1;
+  }
+  if (requestedMode !== null && !HOOK_MODES.includes(requestedMode)) {
+    err(`\n  Unknown --hooks mode "${requestedMode}". Valid modes: ${HOOK_MODES.join(' | ')}.`);
+    return 1;
+  }
+  // An explicit `--hooks` IS the intent to change the wiring, so it must reach
+  // the hook step even on an otherwise complete install (which normally short-
+  // circuits). `--no-hooks` is skip-only and never justifies that bypass.
+  const hooksFlagExplicit = typeof args.hooks === 'string' && args.hooks.trim() !== '';
+
   heading('LoreKit install');
   log(`  project: ${c.dim(root)}`);
 
@@ -88,7 +177,9 @@ export async function install(args) {
   const globalState = detectInstalled(root, 'global');
   const currentState = scope === 'global' ? globalState : projectState;
 
-  if (currentState.isFullyInstalled && !force) {
+  const wiredEvents = installedHookEvents(root, scope);
+
+  if (currentState.isFullyInstalled && !force && !hooksFlagExplicit) {
     // Surface a clear, useful already-installed summary.
     log('');
     log(
@@ -124,10 +215,20 @@ export async function install(args) {
       log(`  ${c.yellow('Token: none configured — reads/writes will fail until a token is set')}`);
     }
 
+    // Hooks are a user choice now, so an already-installed run must SAY which
+    // one is in effect — otherwise "why does nothing get remembered?" has no
+    // answer here and the user has to go read settings.json.
+    log(
+      wiredEvents.length > 0
+        ? `  ${c.dim(`Hooks: ${wiredEvents.join(', ')}`)}`
+        : `  ${c.dim('Hooks: none wired — the skills work, but only when the model invokes them')}`,
+    );
+
     log('');
     log(`  Run ${c.cyan('npx @lorekit/cli doctor')} to verify the connection.`);
+    log(`  Change the hooks with ${c.cyan(`--hooks ${HOOK_MODES.join('|')}`)}.`);
     log(`  Pass ${c.cyan('--force')} to reinstall and overwrite existing files.`);
-    return 0;
+    return { exitCode: 0, 'lorekit.cli.hooks_mode': hookModeFromEvents(wiredEvents) };
   }
 
   // Partial install — note what's already there vs what will be added.
@@ -179,14 +280,67 @@ export async function install(args) {
   const remoteUrl = buildRemoteUrl(endpoint, token);
   const { file, existed } = upsertMcpServer(root, remoteUrl, scope);
 
-  // 5b. Wire the deterministic hooks (unless --no-hooks). This is the layer the
-  //     Claude plugin adds on top of the skill: lessons injected on every
-  //     SessionStart, a nudge on tool failure, a retrospective nudge on Stop —
-  //     firing the shared `lorekit hook` engine, which reads the same config.
-  const wireHooks = !args['no-hooks'];
+  // 5b. Hooks — the deterministic layer the Claude plugin adds on top of the
+  //     skill, firing the shared `lorekit hook` engine (which reads the same
+  //     config). NONE of them write memory: SessionStart injects existing
+  //     lessons, PostToolUseFailure surfaces relevant ones plus a write nudge,
+  //     Stop fires the friction-gated retrospective nudge. All three only emit
+  //     context — the write is still the model calling `memory.write`. The
+  //     prompt copy below says exactly that, because a user who declines
+  //     "automatic memory writing" would be declining something that never
+  //     happens and losing lesson injection, which is the product.
+  let hookMode = requestedMode;
+  // A hand-wired set matching no preset (`custom`) is the one state the three
+  // options cannot express. Interactively that is fine — `defaultHookMode`
+  // preselects `all` and the user still chooses. A `--yes` / non-TTY run never
+  // gets that moment, so taking the preselection there would WIRE `all` and
+  // silently re-add the events the user hand-removed — exactly what
+  // `hookModeFromEvents` tells callers not to do, and the opposite of the
+  // documented "otherwise whatever is already wired". So keep exactly that set
+  // — no event added or removed, though the command string is still refreshed
+  // below; `--hooks <mode>` remains the way to change it on purpose.
+  let preserveCustomHooks = false;
+  if (hookMode === null) {
+    const preselect = defaultHookMode({
+      freshInstall: !currentState.hasSkills && !currentState.hasMcp && wiredEvents.length === 0,
+      wiredEvents,
+    });
+    if (nonInteractive) {
+      preserveCustomHooks = hookModeFromEvents(wiredEvents) === 'custom';
+      hookMode = preserveCustomHooks ? 'custom' : preselect;
+    } else {
+      log('');
+      hookMode = await select('Install the LoreKit lifecycle hooks?', HOOK_PROMPT_OPTIONS, {
+        defaultIndex: Math.max(0, HOOK_PROMPT_OPTIONS.findIndex((o) => o.value === preselect)),
+      });
+    }
+  }
+
+  // `hookEventsForMode` maps any unknown mode to the full set, so `custom` must
+  // never reach it — the preserved wiring IS the event list here.
+  const hookEvents = preserveCustomHooks ? [...wiredEvents] : hookEventsForMode(hookMode);
+  // `--no-hooks` is skip-only by contract: it has always meant "don't wire
+  // them", never "take away the ones already there". An interactive `No hooks`
+  // (or an explicit `--hooks none`) is an unambiguous request to remove.
+  const skipHooksOnly = hookMode === 'none' && Boolean(args['no-hooks']) && !hooksFlagExplicit;
+  // Nothing to wire and nothing to remove ⇒ don't create a settings.json at all.
+  // `wiredEvents` reads as empty for an unparseable settings.json, so a `none`
+  // run against one is a silent no-op — correct, not a gap: Claude Code cannot
+  // parse that file either, so no lorekit hook is firing from it. Any mode that
+  // WIRES still goes through `upsertClaudeHooks`, whose throwing read surfaces
+  // the parse error rather than clobbering the file.
+  //
+  // Preserving a `custom` set does NOT mean skipping the write. Passing
+  // `hookEvents` (== `wiredEvents` here) keeps exactly that set — nothing is
+  // added, and the prune loop finds no lorekit entry on the events outside it,
+  // so `removed` is always 0 — while still REFRESHING a stale command string.
+  // Skipping the call instead left a `--force` re-install unable to repair a
+  // hook command pointing at an old runner, which is the one thing a re-install
+  // is for.
+  const touchHooks = !skipHooksOnly && (hookEvents.length > 0 || wiredEvents.length > 0);
   let hooks = null;
-  if (wireHooks) {
-    hooks = upsertClaudeHooks(root, scope, resolveHookRunner());
+  if (touchHooks) {
+    hooks = upsertClaudeHooks(root, scope, resolveHookRunner(), hookEvents);
   }
 
   // Show global paths relative to ~ (a repo-relative path would be a mess of
@@ -207,16 +361,34 @@ export async function install(args) {
   }
   status('pass', mcpLabel, `${existed ? 'updated' : 'created'} lorekit server → ${display(file)}`);
 
-  if (!wireHooks) {
-    status('info', 'hooks', 'skipped (--no-hooks) — the skill still works, but memories are model-invoked only');
+  if (!touchHooks) {
+    status(
+      'info',
+      'hooks',
+      skipHooksOnly
+        ? 'skipped (--no-hooks) — the skills still work, but memory stays model-invoked'
+        : 'none — the skills still work, but memory stays model-invoked',
+    );
   } else {
-    const n = hooks.added + hooks.updated;
+    const n = hooks.added + hooks.updated + hooks.removed;
     const hookParts = [
       hooks.added ? `${hooks.added} added` : '',
       hooks.updated ? `${hooks.updated} updated` : '',
+      hooks.removed ? `${hooks.removed} removed` : '',
     ].filter(Boolean);
     const hookState = n === 0 ? 'already wired' : hookParts.join(', ');
-    status(n === 0 ? 'info' : 'pass', 'hooks', `${hookState} → ${display(hooks.file)} (${CLAUDE_HOOK_EVENTS.join(', ')})`);
+    const wired = hookEvents.length > 0 ? ` (${hookEvents.join(', ')})` : '';
+    // The preserved-`custom` run DOES write, so it lands here rather than in the
+    // "left as-is" branch — but it is still the one state the three modes cannot
+    // express, so it keeps its own explanation of how to leave it.
+    const kept = preserveCustomHooks
+      ? `; a hand-wired set matching no preset, pass --hooks ${HOOK_MODES.join('|')} to change it`
+      : '';
+    status(
+      n === 0 ? 'info' : 'pass',
+      `hooks ${hookMode}`,
+      `${hookState} → ${display(hooks.file)}${wired}${kept}`,
+    );
   }
 
   const kind = tokenKind(token);
@@ -249,5 +421,8 @@ export async function install(args) {
       )}`,
     );
   }
-  return 0;
+  // Bounded, non-PII: which of the three presets this run landed on. Counting
+  // the `--no-hooks` FLAG (as telemetry already did) says nothing about what a
+  // user picks when actually asked, which is the whole point of the prompt.
+  return { exitCode: 0, 'lorekit.cli.hooks_mode': hookMode };
 }

package/src/link.mjs

@@ -25,6 +25,7 @@ import {
   parseOwnerArg,
   parseViewArg,
   parseRangeArg,
+  parseTagsArg,
   resolveScopeArg,
   surfaceFor,
 } from './deeplink-pure.mjs';
@@ -66,6 +67,7 @@ export async function link(args) {
   const owner = parseOwnerArg(args.owner);
   const view = parseViewArg(args.view);
   const range = parseRangeArg(args);
+  const tags = parseTagsArg(args.tags);
   const archived = Boolean(args.archived);
 
   const gaveAnyInput =
@@ -75,6 +77,7 @@ export async function link(args) {
     owner !== 'all' ||
     view !== 'scope' ||
     range !== null ||
+    tags.length > 0 ||
     archived;
 
   // Bare `lorekit link` (no scope, no lesson, no filters) → the cwd's
@@ -90,6 +93,7 @@ export async function link(args) {
   if (key) params.lesson = { scope, key };
   if (q) params.q = q;
   if (owner !== 'all') params.owner = owner;
+  if (tags.length) params.tags = tags;
   if (view !== 'scope') params.view = view;
   if (range !== null) params.range = range;
   if (archived) params.archived = true;

package/src/store/ttl.mjs

@@ -11,6 +11,14 @@
 //     `ttl_days` when both are supplied (the RPC's tri-state precedence).
 //   - a read filters an expired row out lazily (there is no purge daemon
 //     offline), exactly as the remote read paths do.
+//
+// `resolveDefaultTtlDays` is the one piece here with NO server counterpart, by
+// design. It answers "what TTL did the user configure for a write that named
+// none?" — a client-side policy question. The server contract is untouched:
+// omitting `ttl_*` on `memory.write` still means the row is permanent, so an
+// agent talking straight to the MCP endpoint is unaffected by a config file it
+// cannot see. That asymmetry is deliberate; moving the default server-side would
+// silently change what "omitted" means for every existing caller.
 
 export const TTL_MIN_DAYS = 1;
 export const TTL_MAX_DAYS = 365;
@@ -55,6 +63,76 @@ export function isLive(entry, now = new Date()) {
   return !entry.archived_at && !isExpired(entry.expires_at, now);
 }
 
+// The DEFAULT TTL for a write that named none, resolved from the config layers
+// (`ttl.default` and `scope.defaults.<prefix>.ttl_days` — see control.mjs).
+//
+// Returns the number of days, or null for "no default; the memory is permanent".
+//
+// Two rules that matter more than they look:
+//
+//   1. LONGEST MATCHING PREFIX WINS, not first-declared. `scope.defaults` is a
+//      plain object, so declaration order is whatever the author's editor left
+//      behind; a `branch::` entry and a `branch::owner/repo::` entry must resolve
+//      deterministically, and the more specific one is the one the author meant.
+//      (`tagsHint` UNIONS every match instead — correct there, because tags
+//      accumulate and a TTL cannot.)
+//   2. AN EXPLICIT `null` MEANS PERMANENT and outranks `ttl.default`. Without it
+//      a repo-wide default could not be switched off for the one scope that
+//      holds durable lore, and `"ttl_days": null` is the only honest spelling of
+//      "keep this forever" — omitting the key has to keep meaning "inherit".
+//
+// Total by contract: a malformed config (fractional days, a string, out of
+// range, a non-object entry) yields null rather than throwing. A config file is
+// not a caller assertion the way `--ttl-days` is — it is ambient state that must
+// never be able to break an unrelated write, the same posture the hook engine
+// takes toward the host agent.
+export function resolveDefaultTtlDays(scope, { ttlDefault = null, scopeDefaults = null } = {}) {
+  if (typeof scope === 'string' && scope && scopeDefaults && typeof scopeDefaults === 'object') {
+    let bestPrefix = null;
+    let bestValue;
+    for (const [prefix, cfg] of Object.entries(scopeDefaults)) {
+      if (!cfg || typeof cfg !== 'object' || !('ttl_days' in cfg)) continue;
+      if (!matchesScopePrefix(scope, prefix)) continue;
+      if (bestPrefix !== null && prefix.length <= bestPrefix.length) continue;
+      bestPrefix = prefix;
+      bestValue = cfg.ttl_days;
+    }
+    if (bestPrefix !== null) {
+      if (bestValue === null) return null; // explicit "permanent" for this scope
+      return safeTtlDays(bestValue);
+    }
+  }
+  return safeTtlDays(ttlDefault);
+}
+
+// Whether a write's resolved scope falls under a `scope.defaults` key. An exact
+// match, or a `::`-delimited descendant — so `repo::owner` never captures
+// `repo::owner-other/x`. Shared with the nudge's tags hint so the two cannot
+// disagree about what "this scope is configured" means.
+export function matchesScopePrefix(scope, prefix) {
+  if (typeof scope !== 'string' || typeof prefix !== 'string' || !prefix) return false;
+  if (scope === prefix) return true;
+  return scope.startsWith(prefix.endsWith('::') ? prefix : prefix + '::');
+}
+
+// parseTtlDays, but a rejected value degrades to null instead of throwing.
+//
+// The type guard is not redundant with parseTtlDays: that one coerces with
+// Number(), which maps `true` to 1 and `[]` to 0 — fine for a flag the user
+// typed (a CLI flag is always a string), a footgun for a JSON value where `true`
+// is a plausible typo for "yes, expire these" and would silently mean ONE DAY.
+// Only a number or a numeric string is a TTL here.
+function safeTtlDays(value) {
+  if (typeof value !== 'number' && !(typeof value === 'string' && value.trim() !== '')) {
+    return null;
+  }
+  try {
+    return parseTtlDays(value);
+  } catch {
+    return null;
+  }
+}
+
 // Resolve a write's `expires_at` from the tri-state TTL inputs, mirroring
 // memory_write (00030/00031): `clearTtl` wins (→ permanent, and `ttlDays` is
 // never even validated); else a supplied `ttlDays` sets expiry from `now`; else

package/src/write.mjs

@@ -13,7 +13,8 @@
 //   --tags <a,b,c>         Comma-separated tag list (default: no tags)
 //   --source-agent <name>  Which agent recorded this lesson (default: none)
 //   --trigger <slug>       What prompted the write (default: none)
-//   --ttl-days <n>         Days until the memory auto-expires (1–365)
+//   --ttl-days <n>         Days until the memory auto-expires (1–365). When
+//                          omitted, a configured default may apply — see below.
 //   --clear-ttl            Remove any existing expiry (make the memory permanent)
 //   --org <slug>           Write to this org (remote only)
 //
@@ -27,6 +28,15 @@
 //   --origin-pr <n>             The pull request this lesson came out of
 //   --no-origin                 Record no provenance at all
 //
+// Default TTL. A write that passes neither --ttl-days nor --clear-ttl picks up
+// whatever the config layers configured for its scope (`ttl.default` and
+// `scope.defaults.<prefix>.ttl_days`; see control.mjs). Precedence is explicit
+// flag > config > permanent, so a flag is always the last word and --clear-ttl
+// is how you say "permanent" against a repo that defaults to expiring. The
+// resolved source is reported in the confirmation line and on the telemetry
+// span, because a TTL nobody typed is exactly the kind of thing that should
+// never be silent.
+//
 // Store targeting (default: remote if configured, else local):
 //   --remote               Force write to the remote store
 //   --local                Force write to the local offline store
@@ -39,12 +49,12 @@
 // false = updated) when the remote reports it.
 import process from 'node:process';
 import { resolveProjectRoot } from './config.mjs';
-import { resolveDenies } from './control.mjs';
+import { loadControl, resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
 import { log, err, heading, status, c } from './util.mjs';
 import { parseScopeKey } from './lessons-view.mjs';
 import { deriveOrigin, mergeOrigin } from './origin.mjs';
-import { parseTtlDays } from './store/ttl.mjs';
+import { parseTtlDays, resolveDefaultTtlDays } from './store/ttl.mjs';
 
 // Read all of stdin to a string. Resolves to '' when stdin IS a TTY (no pipe).
 function readStdin() {
@@ -132,6 +142,34 @@ export async function write(args) {
     }
   }
   const clearTtl = Boolean(args['clear-ttl']);
+
+  // Neither flag given → fall back to the scope's configured default, if any.
+  // `--clear-ttl` deliberately suppresses it: "make this permanent" has to mean
+  // permanent, not "permanent unless the repo config disagrees". Config is read
+  // through the same loadControl the hooks use, so the default the nudge advises
+  // and the default this command applies can never diverge.
+  let ttlSource = ttlDays ? 'flag' : 'none';
+  if (ttlDays === undefined && !clearTtl) {
+    const configured = resolveDefaultTtlDays(scope, loadControl(root, { env }));
+    if (configured != null) {
+      ttlDays = configured;
+      ttlSource = 'config';
+    }
+  }
+
+  // What gets REPORTED is the outcome, not the input. `--clear-ttl` beats
+  // `--ttl-days` inside resolveExpiresAt (and in memory_write, migrations
+  // 00030/00031), so `--ttl-days 7 --clear-ttl` persists a permanent row —
+  // yet ttlDays/ttlSource still described the flag the user typed, so the
+  // human output claimed "expires in 7 days" and --json reported
+  // ttl_days 7 / ttl_source "flag" for a row whose expires_at is null.
+  // Kept separate from ttlDays on purpose: writeArgs below spreads
+  // `...(ttlDays ? { ttl_days } : {})`, and nulling ttlDays itself would
+  // silently stop sending ttl_days to the remote RPC — a wire change nobody
+  // asked for. The precedence lives in one place; this only mirrors it.
+  const reportedTtlDays = clearTtl ? null : (ttlDays ?? null);
+  const reportedTtlSource = clearTtl ? 'none' : ttlSource;
+
   const orgSlug = typeof args.org === 'string' ? args.org : undefined;
 
   // ── Provenance ────────────────────────────────────────────────────────────
@@ -254,6 +292,8 @@ export async function write(args) {
       tags,
       source_agent: sourceAgent || null,
       trigger: trigger || null,
+      ttl_days: reportedTtlDays,
+      ttl_source: reportedTtlSource,
       origin,
     }, null, 2));
   } else {
@@ -263,6 +303,13 @@ export async function write(args) {
     log(`  ${c.dim('scope')}  ${scope}`);
     log(`  ${c.dim('key')}    ${key}`);
     if (tags.length) log(`  ${c.dim('tags')}   ${tags.join(', ')}`);
+    // Name the source. A TTL the caller typed needs no explanation; one that came
+    // from a config file two directories up does, or the first surprise is a
+    // memory that quietly vanished.
+    if (reportedTtlDays) {
+      const suffix = reportedTtlSource === 'config' ? c.dim(' (from config)') : '';
+      log(`  ${c.dim('expires')} in ${reportedTtlDays} day${reportedTtlDays === 1 ? '' : 's'}${suffix}`);
+    }
     status('pass', verb, `${scope}::${key}`);
     log('');
   }
@@ -272,7 +319,8 @@ export async function write(args) {
     'lorekit.cli.write.store': storeName,
     'lorekit.cli.write.inserted': inserted,
     'lorekit.cli.write.has_tags': tags.length > 0,
-    'lorekit.cli.write.has_ttl': Boolean(ttlDays),
+    'lorekit.cli.write.has_ttl': Boolean(reportedTtlDays),
+    'lorekit.cli.write.ttl_source': reportedTtlSource,
     'lorekit.cli.write.clear_ttl': clearTtl,
   };
 }