@lorekit/cli 1.26.0 → 1.27.0

package/README.md

@@ -53,7 +53,8 @@ without needing a marketplace:
 3. **Hooks** — the *deterministic* layer: lessons injected on every
    `SessionStart`, and on a tool failure (`PostToolUseFailure`) any lessons that
    look **relevant to that failure** ("you've hit this before") plus a nudge to
-   record the fix, and a retrospective nudge on `Stop`. These fire the shared
+   record the fix, and a retrospective nudge on `Stop` — by default only when the
+   session actually hit friction (`hooks.stop`). These fire the shared
    `lorekit hook` engine and are merged into `settings.json` (existing hooks
    preserved).
 
@@ -519,6 +520,18 @@ Both files share this schema — all fields optional:
                            // suppress specific hook events; union across layers
                            // values: "SessionStart" | "PostToolUseFailure" | "Stop"
 
+  "hooks.stop": "friction",
+                           // gate the end-of-turn retrospective nudge:
+                           //   "friction" (default) — only nudge once/session when the
+                           //     session hit friction (a failed tool call or a stuck
+                           //     retry loop, read from the transcript); silent otherwise
+                           //   "always"             — nudge once per session regardless
+                           //   "off"                — never (same effect as disabling Stop)
+                           // repo wins over user
+                           // (friction is detectable only on Claude Code, which exposes a
+                           //  transcript; on Cursor/Codex there is none, so "friction"
+                           //  falls back to firing so no lesson is silently lost)
+
   "hooks.adapter": "claude",
                            // explicit adapter when auto-detection is ambiguous
                            // values: "claude" | "cursor" | "codex"

package/bin/lorekit.mjs

@@ -288,7 +288,8 @@ ${c.bold('Options')}
       --tags <a,b,c>       Comma-separated tags (default: none)
       --source-agent <n>   Source agent name to record (default: none)
       --trigger <slug>     Trigger context slug (default: none)
-      --ttl-days <n>       Days until auto-expiry 1–365 (remote only)
+      --ttl-days <n>       Days until auto-expiry 1–365 (local or remote)
+      --clear-ttl          Remove any existing expiry (make it permanent)
       --org <slug>         Write to this org's scope (remote only)
       --origin-repo <o/n>  Override the derived provenance repository
       --origin-branch <b>  Override the derived provenance branch
@@ -574,7 +575,7 @@ const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
   'from', 'to', 'apply', 'yes', 'no-hooks', 'force', 'deep', 'adapter',
   'event', 'json', 'scope', 'threshold', 'help', 'version',
-  'value', 'tags', 'source-agent', 'trigger', 'ttl-days', 'org', 'remote', 'local',
+  'value', 'tags', 'source-agent', 'trigger', 'ttl-days', 'clear-ttl', 'org', 'remote', 'local',
   'link', 'base', 'q', 'owner', 'range', 'view', 'archived',
   'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',
 ];
@@ -601,7 +602,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
-    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'no-origin', 'json', 'remote', 'local', 'link', 'archived'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

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

package/src/adapters/claude.mjs

@@ -42,6 +42,9 @@ export const claude = {
       toolInput: input.tool_input || null,
       toolResponse: input.tool_response || null,
       event: input.hook_event_name || null,
+      // Path to the session JSONL (present on Stop/SubagentStop) — read by the
+      // friction-gated retrospective to decide whether the session is worth a nudge.
+      transcriptPath: input.transcript_path || null,
     };
   },
 

package/src/control.mjs

@@ -5,6 +5,7 @@
 //   scope.defaults  — map of scope-prefix → { tags } applied to every matching write
 //   tags.default    — array of tags appended to every write (both layers merged)
 //   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")
 //
 // Two layers of config, two kinds of statement:
@@ -39,6 +40,19 @@ export function normalizeMode(v) {
   return null;
 }
 
+// Stop-hook behaviour: `friction` (default — only nudge on detected friction),
+// `always` (nudge once per session regardless), or `off` (never). Accepts a few
+// friendly spellings so config stays forgiving.
+export const STOP_MODES = ['friction', 'always', 'off'];
+export function normalizeStopMode(v) {
+  if (typeof v !== 'string') return null;
+  const s = v.trim().toLowerCase();
+  if (['off', 'none', 'false', 'disabled', 'never'].includes(s)) return 'off';
+  if (['always', 'all', 'on', 'true', 'every'].includes(s)) return 'always';
+  if (['friction', 'smart', 'auto'].includes(s)) return 'friction';
+  return null;
+}
+
 function asList(v) {
   if (Array.isArray(v)) return v;
   if (typeof v === 'string') return v.split(',').map((s) => s.trim()).filter(Boolean);
@@ -131,6 +145,13 @@ export function resolveControl({
     ...asList(userConfig['hooks.disabled']),
   ]);
 
+  // `hooks.stop` — repo layer wins over user layer, default `friction`. Gates the
+  // end-of-turn retrospective: friction-only (default), always, or off.
+  const hooksStop =
+    normalizeStopMode(repoConfig['hooks.stop']) ||
+    normalizeStopMode(userConfig['hooks.stop']) ||
+    'friction';
+
   // `hooks.adapter` — repo layer wins over user layer (explicit project override).
   const hooksAdapter =
     (typeof repoConfig['hooks.adapter'] === 'string' && repoConfig['hooks.adapter'].trim()) ||
@@ -167,6 +188,7 @@ export function resolveControl({
     tagsDefault,
     scopeDefaults,
     hooksDisabled,
+    hooksStop,
     hooksAdapter,
     hooksInstructions,
   };

package/src/core/friction.mjs

@@ -0,0 +1,105 @@
+// Friction detection for the Stop (retrospective) hook.
+//
+// The retrospective nudge has no side effect of its own — it exists only to
+// prompt an end-of-turn reflection. Firing it on *every* session is noise: a
+// clean "regenerate four icons" turn had nothing worth remembering. So when
+// `hooks.stop` is `friction` (the default) we read the session transcript and
+// only surface the nudge when the session actually hit friction.
+//
+// Signals are deliberately conservative (a false positive nudges needlessly):
+//   - `failure`    — a tool call reported an error this session (is_error).
+//   - `stuck-loop` — the same tool+input ran >= STUCK_LOOP_THRESHOLD times
+//                    (a retry loop / repeated dead end).
+//
+// The pure `detectFriction` works on the raw transcript text so it is unit
+// testable with fixture strings; `readSessionFriction` is the thin IO wrapper.
+// Both are best-effort: anything unreadable degrades to `friction: null`
+// ("unknown"), never a throw — a memory hook must never break the host.
+import fs from 'node:fs';
+
+export const STUCK_LOOP_THRESHOLD = 3;
+
+// Reason codes, surfaced in the nudge so the reflection is grounded ("this
+// session hit a failed tool call") rather than a generic prompt.
+export const FRICTION_FAILURE = 'failure';
+export const FRICTION_STUCK_LOOP = 'stuck-loop';
+
+// Pure: scan a Claude Code JSONL transcript for friction signals. (Only Claude
+// Code surfaces a transcript path to the hook; the Cursor/Codex adapters don't,
+// so friction there is always `null` — see readSessionFriction / shouldRetrospect.)
+// Returns { friction: boolean, reasons: string[] }. Never throws.
+export function detectFriction(transcriptText, { stuckLoopThreshold = STUCK_LOOP_THRESHOLD } = {}) {
+  const reasons = new Set();
+  if (typeof transcriptText !== 'string' || transcriptText.length === 0) {
+    return { friction: false, reasons: [] };
+  }
+
+  const callCounts = new Map(); // "name input" -> count
+  for (const line of transcriptText.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry;
+    try {
+      entry = JSON.parse(trimmed);
+    } catch {
+      continue; // tolerate non-JSON / partial lines
+    }
+    const content = entry && entry.message && Array.isArray(entry.message.content)
+      ? entry.message.content
+      : null;
+    if (!content) continue;
+
+    for (const item of content) {
+      if (!item || typeof item !== 'object') continue;
+      if (item.type === 'tool_result' && item.is_error === true) {
+        reasons.add(FRICTION_FAILURE);
+      } else if (item.type === 'tool_use' && typeof item.name === 'string') {
+        // Serialize the input so identical retries collide; JSON.stringify is
+        // enough for the loop signal (key order is stable within one session).
+        let inputKey = '';
+        try {
+          inputKey = JSON.stringify(item.input ?? null);
+        } catch {
+          inputKey = '';
+        }
+        const key = `${item.name} ${inputKey}`;
+        const next = (callCounts.get(key) || 0) + 1;
+        callCounts.set(key, next);
+        if (next >= stuckLoopThreshold) reasons.add(FRICTION_STUCK_LOOP);
+      }
+    }
+  }
+
+  return { friction: reasons.size > 0, reasons: [...reasons] };
+}
+
+// IO wrapper: read the transcript at `transcriptPath` and detect friction.
+// Returns { friction: null, reasons: [] } when the path is absent or unreadable
+// — "unknown", which the caller treats conservatively (does not swallow the
+// nudge on platforms/turns where we cannot measure).
+export function readSessionFriction(transcriptPath, opts = {}) {
+  if (!transcriptPath || typeof transcriptPath !== 'string') {
+    return { friction: null, reasons: [] };
+  }
+  let text;
+  try {
+    text = fs.readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return { friction: null, reasons: [] };
+  }
+  return detectFriction(text, opts);
+}
+
+// Pure gating decision for the retrospective hook, given the resolved
+// `hooks.stop` mode and the detected friction (true | false | null=unknown):
+//   - off      → never
+//   - always   → always
+//   - friction → only on positively-detected friction; `null` (undetectable,
+//                e.g. no transcript on Cursor/Codex) falls back to firing so no
+//                lesson is silently lost where we cannot measure.
+export function shouldRetrospect(mode, friction) {
+  if (mode === 'off') return false;
+  if (mode === 'always') return true;
+  // friction mode
+  return friction !== false;
+}

package/src/core/lessons.mjs

@@ -13,6 +13,7 @@ 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';
+import { FRICTION_FAILURE, FRICTION_STUCK_LOOP } from './friction.mjs';
 
 const MAX_LESSONS = 15;
 // Cap on lessons injected on a failure — a small, focused "you've seen this
@@ -161,7 +162,8 @@ export function formatRelevantLessons(lessons) {
 
 // Build a tags hint string from config-resolved tags and scope defaults. Returns
 // "" when there are no configured tags (no hint appended to the nudge).
-function tagsHint(writeScope, { tagsDefault = [], scopeDefaults = null } = {}) {
+function tagsHint(writeScope, control) {
+  const { tagsDefault = [], scopeDefaults = null } = control || {};
   const tags = [...tagsDefault];
   if (scopeDefaults) {
     for (const [prefix, cfg] of Object.entries(scopeDefaults)) {
@@ -179,30 +181,41 @@ function tagsHint(writeScope, { tagsDefault = [], scopeDefaults = null } = {}) {
   return ` Include tags: [${tags.map((t) => JSON.stringify(t)).join(', ')}].`;
 }
 
-// The LoreKit web app URL for the Lore Explorer, pre-filtered to the given scope.
-// Exported so tests can assert the URL shape without re-deriving the encoding.
-// Delegates to the shared `loreScopeUrl` so the scope param is JSON-encoded the
-// way the dashboard reads it — the previous raw `?scope=${scope}` fell through
-// `useUrlState`'s `JSON.parse` and silently filtered to ALL scopes.
-export function loreUrl(writeScope) {
-  return loreScopeUrl(writeScope);
+// 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 = {
+  [FRICTION_FAILURE]: 'a failed tool call',
+  [FRICTION_STUCK_LOOP]: 'a repeated retry',
+};
+
+// Join detected reason codes into a readable clause ("a failed tool call and a
+// repeated retry"). Empty/unknown reasons → "" (caller uses the generic prompt).
+function describeReasons(reasons) {
+  const phrases = (Array.isArray(reasons) ? reasons : [])
+    .map((r) => REASON_PHRASES[r])
+    .filter(Boolean);
+  if (phrases.length === 0) return '';
+  if (phrases.length === 1) return phrases[0];
+  return `${phrases.slice(0, -1).join(', ')} and ${phrases[phrases.length - 1]}`;
 }
 
 // The retrospective nudge emitted at end-of-turn (one-shot per session).
 // `control` is the resolved control object (optional) — carries tagsDefault and
-// scopeDefaults when the repo/user config defines them.
-export function retrospectiveNudge(scope, control) {
+// scopeDefaults when the repo/user config defines them. `opts.reasons` is the
+// detected friction reason codes (from core/friction.mjs) when `hooks.stop` is
+// `friction`; when present the nudge names them so the reflection is grounded.
+// Kept to a single line — the lore deep-link lives on the write CONFIRMATION,
+// 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 instruction = control && control.hooksInstructions && control.hooksInstructions.Stop
     ? `\n\nProject instruction: ${control.hooksInstructions.Stop}` : '';
-  const url = loreUrl(writeScope);
-  return (
-    `LoreKit: hit any friction worth remembering — a stuck loop, a repeated ` +
-    `failure, a gotcha, a wrong assumption? If so, memory.write to ${writeScope} ` +
-    `as an observation; else skip.${hint}${instruction}\n` +
-    `View lore: ${url}`
-  );
+  const detected = describeReasons(reasons);
+  const lead = detected
+    ? `LoreKit: this session hit ${detected} — a lesson worth saving?`
+    : `LoreKit: any friction worth remembering (stuck loop, repeat failure, gotcha, wrong assumption)?`;
+  return `${lead} memory.write to ${writeScope}; else skip.${hint}${instruction}`;
 }
 
 // Terse confirmation emitted via PostToolUse when a memory.write succeeded.

package/src/core/state.mjs

@@ -11,17 +11,33 @@ function stateDir() {
   return base;
 }
 
+function markerPath(sessionId, tag) {
+  const hash = crypto.createHash('sha256').update(`${sessionId}:${tag}`).digest('hex').slice(0, 16);
+  return path.join(stateDir(), `${hash}.seen`);
+}
+
 // Returns true the FIRST time called for a given (sessionId, tag), false after.
 // Missing sessionId → always true (cannot throttle without a key).
 export function firstTimeThisSession(sessionId, tag) {
   if (!sessionId) return true;
-  const hash = crypto.createHash('sha256').update(`${sessionId}:${tag}`).digest('hex').slice(0, 16);
-  const marker = path.join(stateDir(), `${hash}.seen`);
   try {
     // wx fails if the file already exists → not the first time.
-    fs.writeFileSync(marker, '', { flag: 'wx' });
+    fs.writeFileSync(markerPath(sessionId, tag), '', { flag: 'wx' });
     return true;
   } catch {
     return false;
   }
 }
+
+// Read-only peek: has a (sessionId, tag) marker already been written this
+// session? Unlike `firstTimeThisSession` this NEVER creates the marker, so a
+// caller can ask "did the failure hook already fire?" without consuming a
+// throttle it does not own. Missing sessionId (or any IO error) → false.
+export function sessionMarkerExists(sessionId, tag) {
+  if (!sessionId) return false;
+  try {
+    return fs.existsSync(markerPath(sessionId, tag));
+  } catch {
+    return false;
+  }
+}

package/src/hook.mjs

@@ -18,7 +18,8 @@ import {
   writeConfirmation,
 } from './core/lessons.mjs';
 import { isFailure } from './core/failure.mjs';
-import { firstTimeThisSession } from './core/state.mjs';
+import { readSessionFriction, shouldRetrospect, FRICTION_FAILURE } from './core/friction.mjs';
+import { firstTimeThisSession, sessionMarkerExists } from './core/state.mjs';
 import { recordFixture } from './core/record.mjs';
 import { claude } from './adapters/claude.mjs';
 import { cursor } from './adapters/cursor.mjs';
@@ -160,8 +161,34 @@ async function run(args) {
   }
 
   if (intent === 'retrospective') {
+    // `hooks.stop` gates the retrospective: `friction` (default) reads the
+    // session transcript and only nudges when it hit real friction; `always`
+    // keeps the once-per-session nudge; `off` is silent. The friction read is
+    // side-effect-free and happens BEFORE the once-per-session throttle is
+    // consumed, so a clean early turn stays silent without burning the marker —
+    // a later turn that does hit friction can still fire (once).
+    const stopMode = control.hooksStop || 'friction';
+    let reasons = [];
+    let friction = null;
+    if (stopMode === 'friction') {
+      ({ friction, reasons } = readSessionFriction(parsed.transcriptPath));
+      // The transcript is written ASYNCHRONOUSLY and may lag the current turn
+      // (Claude Code hooks reference, `transcript_path`), so a Stop fired right
+      // after a failing tool call can read a positively-clean `false`. The
+      // PostToolUseFailure hook already left a session-keyed marker when it
+      // fired, which is a transcript-independent witness of the exact same
+      // predicate `detectFriction` calls FRICTION_FAILURE (any errored tool
+      // result anywhere this session). Peek at it (read-only — never consume
+      // the marker) and upgrade. This covers the `failure` signal ONLY;
+      // `stuck-loop` remains transcript-only and is still exposed to the lag.
+      if (friction === false && sessionMarkerExists(parsed.sessionId, 'failure')) {
+        friction = true;
+        reasons = [FRICTION_FAILURE];
+      }
+    }
+    if (!shouldRetrospect(stopMode, friction)) return 0;
     if (!firstTimeThisSession(parsed.sessionId, 'retro')) return 0;
-    emit(retrospectiveNudge(scope, control));
+    emit(retrospectiveNudge(scope, control, { reasons }));
     return 0;
   }
 

package/src/mcp-server.mjs

@@ -56,6 +56,18 @@ export const MEMORY_TOOL_DEFS = [
           description:
             'Optional ISO 8601 creation date for migrating a pre-existing memory. Rejected if invalid or in the future. Applies only when the memory is first created.',
         },
+        ttl_days: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 365,
+          description:
+            'Optional time-to-live in days (1–365). The memory auto-expires that many days after this write and is then hidden from reads.',
+        },
+        clear_ttl: {
+          type: 'boolean',
+          description:
+            'Remove any existing expiry, making the memory permanent again. Takes precedence over ttl_days when both are supplied.',
+        },
         origin_repo: {
           type: 'string',
           description:

package/src/store/format.mjs

@@ -24,6 +24,10 @@ export const FIELDS = [
   'origin_branch',
   'origin_commit',
   'origin_pr',
+  // Expiry — the absolute ISO instant this lesson auto-expires (see src/store/
+  // ttl.mjs). Null / absent means it never expires. Appended like the origin
+  // columns: a file written before this existed simply decodes it as absent.
+  'expires_at',
 ];
 
 // Serialize an entry ({ ...columns, value }) into file text.

package/src/store/local.mjs

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { serializeEntry, parseEntry, slugify, scopeToDir } from './format.mjs';
 import { normalizeCreatedAt } from './created-at.mjs';
+import { isLive, resolveExpiresAt } from './ttl.mjs';
 
 export function createLocalStore(baseDir) {
   return new LocalStore(baseDir);
@@ -61,11 +62,12 @@ class LocalStore {
   }
 
   // list({ scope, tags, limit }) → { ok, entries } — newest-first, tag-filtered,
-  // archived hidden.
+  // archived hidden, expired hidden (lazily, mirroring the remote read paths).
   async list({ scope, tags, limit } = {}) {
+    const now = new Date();
     let rows = this._readAll(scope)
       .map((r) => r.entry)
-      .filter((e) => !e.archived_at);
+      .filter((e) => isLive(e, now));
     if (Array.isArray(tags) && tags.length) {
       rows = rows.filter((e) => tags.every((t) => (e.tags || []).includes(t)));
     }
@@ -74,11 +76,10 @@ class LocalStore {
     return { ok: true, entries: rows };
   }
 
-  // read({ scope, key }) → { ok, entry } — null when absent or archived.
+  // read({ scope, key }) → { ok, entry } — null when absent, archived, or expired.
   async read({ scope, key } = {}) {
     const found = this._findByKey(scope, key);
-    const entry = found && !found.entry.archived_at ? found.entry : null;
-    return { ok: true, entry };
+    return { ok: true, entry: found && isLive(found.entry) ? found.entry : null };
   }
 
   // write(...) → { ok, entry } — upsert by scope+key. Preserves `created` and
@@ -92,19 +93,22 @@ class LocalStore {
   // an invalid or future-dated value rather than throwing, matching the store
   // contract's error surfacing.
   async write({
-    scope, key, value, tags, source_agent, trigger, created_at,
+    scope, key, value, tags, source_agent, trigger, created_at, ttl_days, clear_ttl,
     origin_repo, origin_branch, origin_commit, origin_pr,
   } = {}) {
-    let override;
+    const now = new Date().toISOString();
+    const existing = this._findByKey(scope, key);
+    let override, expires_at;
     try {
       override = normalizeCreatedAt(created_at);
+      expires_at = resolveExpiresAt({
+        clearTtl: clear_ttl, ttlDays: ttl_days, now, current: existing?.entry.expires_at,
+      });
     } catch (e) {
       return { ok: false, error: e.message };
     }
     const dir = this._dir(scope);
     fs.mkdirSync(dir, { recursive: true });
-    const now = new Date().toISOString();
-    const existing = this._findByKey(scope, key);
     const created = existing ? existing.entry.created || now : override || now;
     const entry = {
       scope,
@@ -122,6 +126,7 @@ class LocalStore {
       created,
       updated: existing ? now : override || now,
       archived_at: null,
+      expires_at,
       value: value == null ? '' : String(value),
     };
     const file = existing ? existing.file : this._freshPath(dir, key);
@@ -152,6 +157,7 @@ class LocalStore {
       created: entry.created ?? now,
       updated: entry.updated ?? now,
       archived_at: entry.archived_at ?? null,
+      expires_at: entry.expires_at ?? null,
       value: entry.value == null ? '' : String(entry.value),
     };
     const file = existing ? existing.file : this._freshPath(dir, entry.key);
@@ -258,9 +264,10 @@ class LocalStore {
   // lossy for `project::{name}` (stored by basename only). Returns
   // `[{ scope, count }]`, unsorted.
   async listScopes() {
+    const now = new Date();
     const counts = new Map();
     for (const { entry } of this._walkEntries()) {
-      if (entry.archived_at || !entry.scope) continue;
+      if (!entry.scope || !isLive(entry, now)) continue;
       counts.set(entry.scope, (counts.get(entry.scope) || 0) + 1);
     }
     return [...counts.entries()].map(([scope, count]) => ({ scope, count }));
@@ -392,12 +399,13 @@ class TwoTierStore {
   // a lesson present in both tiers is counted once — project shadows home, the
   // same first-wins merge `list()` uses. Returns `[{ scope, count }]`, unsorted.
   async listScopes() {
+    const now = new Date();
     const seen = new Set(); // `${scope}\x00${key}` — dedup across tiers
     const counts = new Map();
     const tiers = this.projectActive() ? [this.project, this.home] : [this.home];
     for (const tier of tiers) {
       for (const { entry } of tier._walkEntries()) {
-        if (entry.archived_at || !entry.scope) continue;
+        if (!entry.scope || !isLive(entry, now)) continue;
         const id = `${entry.scope}\x00${entry.key ?? ''}`;
         if (seen.has(id)) continue;
         seen.add(id);

package/src/store/ttl.mjs

@@ -0,0 +1,69 @@
+// Zero-dependency mirror of the TTL (time-to-live) contract used by the hosted
+// MCP server (packages/mcp-core/src/ttl.ts) and the `memory_write` RPC
+// (migrations 00030/00031). Keeps the local file store's expiry semantics
+// identical to the remote one, so a memory written offline expires the same way
+// it would have online — and a local↔remote migration is lossless.
+//
+//   - `ttl_days` (1–365) sets `expires_at = <write instant> + N days`, mirroring
+//     the RPC's `now() + interval` — NOT `created + N`, so a backdated migration
+//     (created_at override) still expires relative to when it was written.
+//   - `clear_ttl` removes the expiry, making the row permanent again; it beats
+//     `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.
+
+export const TTL_MIN_DAYS = 1;
+export const TTL_MAX_DAYS = 365;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+// Validate and normalise an optional `ttl_days` write parameter.
+// Returns the integer number of days, or null when no TTL was supplied.
+// Throws Error on a present-but-invalid value (fractional, out of range, NaN).
+export function parseTtlDays(input) {
+  if (input === undefined || input === null) return null;
+  const n = typeof input === 'number' ? input : Number(input);
+  if (!Number.isFinite(n)) throw new Error('ttl_days must be a finite number');
+  if (!Number.isInteger(n)) throw new Error('ttl_days must be an integer');
+  if (n < TTL_MIN_DAYS) throw new Error(`ttl_days must be >= ${TTL_MIN_DAYS}`);
+  if (n > TTL_MAX_DAYS) throw new Error(`ttl_days must be <= ${TTL_MAX_DAYS}`);
+  return n;
+}
+
+// The absolute ISO expiry instant for a memory: `from` (ISO string or Date)
+// advanced by `ttlDays` whole days.
+export function expiresAtFrom(ttlDays, from) {
+  const base = from instanceof Date ? from.getTime() : Date.parse(from);
+  return new Date(base + ttlDays * DAY_MS).toISOString();
+}
+
+// Whether a stored `expires_at` has elapsed at `now`. Absent → never expires.
+// An unparseable value fails SAFE (treated as never-expiring) so a corrupt or
+// hand-edited frontmatter field can never hide a lesson from every read.
+export function isExpired(expiresAt, now = new Date()) {
+  if (!expiresAt) return false;
+  const ms = Date.parse(expiresAt);
+  if (Number.isNaN(ms)) return false;
+  return ms <= now.getTime();
+}
+
+// Whether a stored entry is currently visible to reads: not archived and not
+// expired. The SINGLE definition of "live", shared by every read path (list /
+// read / listScopes) so a future hidden dimension is added once, never
+// re-spelled per call site. The raw primitives (getEntry / _findByKey for
+// delete / archive) deliberately bypass this so they can still act on hidden rows.
+export function isLive(entry, now = new Date()) {
+  return !entry.archived_at && !isExpired(entry.expires_at, now);
+}
+
+// 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
+// the row keeps whatever `current` expiry it already had. Throws (via
+// parseTtlDays) on an invalid `ttlDays` only when NOT clearing, so the caller
+// can surface `{ ok:false }`.
+export function resolveExpiresAt({ clearTtl, ttlDays, now, current } = {}) {
+  if (clearTtl) return null;
+  const days = parseTtlDays(ttlDays);
+  if (days != null) return expiresAtFrom(days, now);
+  return current ?? null;
+}

package/src/write.mjs

@@ -14,6 +14,7 @@
 //   --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)
+//   --clear-ttl            Remove any existing expiry (make the memory permanent)
 //   --org <slug>           Write to this org (remote only)
 //
 // Provenance — where the lesson is being recorded FROM. Derived automatically
@@ -43,6 +44,7 @@ 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';
 
 // Read all of stdin to a string. Resolves to '' when stdin IS a TTY (no pipe).
 function readStdin() {
@@ -108,7 +110,28 @@ export async function write(args) {
   const tags = args.tags ? String(args.tags).split(',').map((t) => t.trim()).filter(Boolean) : [];
   const sourceAgent = typeof args['source-agent'] === 'string' ? args['source-agent'] : undefined;
   const trigger = typeof args.trigger === 'string' ? args.trigger : undefined;
-  const ttlDays = args['ttl-days'] ? Number(args['ttl-days']) : undefined;
+  // `--ttl-days` is validated HERE, at the flag seam, rather than being left to the
+  // store: a truthiness test silently swallowed `--ttl-days 0` (falsy) and
+  // `--ttl-days abc` (NaN, dropped again by the `ttl_days` spread further down), so
+  // both exited 0 having written no expiry while `--ttl-days 999` correctly errored.
+  // The seam matters as much as the check — `store/remote.mjs` forwards `ttl_days`
+  // verbatim and `JSON.stringify(NaN)` would reach the server as `null`, so a
+  // store-side fix would leave the remote path silently broken. Mirrors how
+  // `--origin-pr` is handled below: an explicitly supplied value is a caller
+  // assertion, so a malformed one is a usage error.
+  let ttlDays;
+  if (args['ttl-days'] !== undefined) {
+    // A bare `--ttl-days` with no value parses as boolean `true` (see parseArgs);
+    // feed NaN so the shared validator rejects it instead of silently meaning 1 day.
+    const rawTtlDays = args['ttl-days'] === true ? NaN : args['ttl-days'];
+    try {
+      ttlDays = parseTtlDays(rawTtlDays);
+    } catch (e) {
+      err(`${c.red('Error:')} --ttl-days is invalid — ${(e && e.message) || String(e)}`);
+      return 1;
+    }
+  }
+  const clearTtl = Boolean(args['clear-ttl']);
   const orgSlug = typeof args.org === 'string' ? args.org : undefined;
 
   // ── Provenance ────────────────────────────────────────────────────────────
@@ -198,6 +221,7 @@ export async function write(args) {
     ...(sourceAgent ? { source_agent: sourceAgent } : {}),
     ...(trigger ? { trigger } : {}),
     ...(ttlDays ? { ttl_days: ttlDays } : {}),
+    ...(clearTtl ? { clear_ttl: true } : {}),
     ...(orgSlug ? { org: orgSlug } : {}),
     ...origin,
   };
@@ -249,5 +273,6 @@ export async function write(args) {
     'lorekit.cli.write.inserted': inserted,
     'lorekit.cli.write.has_tags': tags.length > 0,
     'lorekit.cli.write.has_ttl': Boolean(ttlDays),
+    'lorekit.cli.write.clear_ttl': clearTtl,
   };
 }