@lorekit/cli 1.28.0 → 1.29.1

package/README.md

@@ -75,12 +75,49 @@ 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.
+
+**Replacing a token.** A plain re-run reuses the token already in your config.
+An interactive `lorekit install --force` instead asks what to do with it —
+**keep**, **replace** (paste a new one), or **remove** — so a revoked token can
+be swapped without hand-editing `.mcp.json` / `~/.claude.json`. The stored token
+is only ever shown masked (`lk_rw_…ijkl`). Non-interactive runs (`--yes`, or no
+TTY) never prompt and keep reusing the stored token; pass `--token` to replace
+it in a script.
+
 > 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
@@ -98,7 +135,9 @@ Verifies the setup and prints a status report:
   gitignored
 - for `remote`: `.mcp.json` has a `lorekit` server, the endpoint is real (not
   the `<project-ref>` placeholder), the token and its permission tier
-  (`lk_rw_*` / `lk_ro_*` / `lk_wo_*`), and that the endpoint is reachable
+  (`lk_rw_*` / `lk_ro_*` / `lk_wo_*`), that the endpoint is reachable, and —
+  the `authentication` check — that the token is **still accepted by the
+  server**
 - for `off`: a note that memory is disabled
 - the git-derived read/write scopes for the current directory
 
@@ -109,6 +148,22 @@ lorekit doctor --deep     # also does a write → read → delete round-trip (ne
 
 Exit code is non-zero if any check fails, so it fits CI gates.
 
+**`connectivity` and `authentication` are different questions.** `connectivity`
+probes the public `/health` function: it proves the network path and says
+nothing about your credential. `authentication` makes one authenticated,
+side-effect-free request and reports what the server said about the token
+itself:
+
+| Result | Meaning |
+| --- | --- |
+| `PASS — token accepted` | the token is live (read access confirmed) |
+| `PASS — no read permission` | accepted, but it is a write-only `lk_wo_*` token |
+| `FAIL — token REJECTED (HTTP 401)` | revoked, deleted, or never valid — every remote read and write is broken |
+| `WARN` | rate limited, unreachable, or an inconclusive answer — never reported as "revoked" |
+
+A revoked token is a **failure**, not a warning: fix it by creating a new token
+and running `lorekit install --force`, which offers to replace the stored one.
+
 ### `lorekit list` (alias `ls`)
 
 Shows the lessons that apply to **where you are** — the scopes `deriveScope`
@@ -509,13 +564,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"],
@@ -579,6 +641,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 |
@@ -594,7 +708,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
@@ -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
@@ -575,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.28.0",
+  "version": "1.29.1",
   "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 (