@lorekit/cli 1.25.1 → 1.26.1

package/bin/lorekit.mjs

@@ -288,8 +288,14 @@ ${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
+      --origin-commit <s>  Override the derived provenance commit SHA
+      --origin-pr <n>      The pull request this lesson came out of
+      --no-origin          Record no provenance at all
       --remote             Force write to the remote store
       --local              Force write to the local offline store
       --json               Machine-readable output
@@ -569,8 +575,9 @@ 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',
 ];
 
 // Commands that write to disk / talk to the network on a human's behalf. These
@@ -595,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', '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.25.1",
+  "version": "1.26.1",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/mcp-server.mjs

@@ -28,6 +28,7 @@ import { resolveProjectRoot } from './config.mjs';
 import { loadControl } from './control.mjs';
 import { createStore } from './store/index.mjs';
 import { createRemoteStore } from './store/remote.mjs';
+import { deriveOrigin, mergeOrigin } from './origin.mjs';
 
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_INFO = { name: 'lorekit-local', version: '1.0.0' };
@@ -55,6 +56,39 @@ 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:
+            'Provenance: the owner/name of the repository this memory was recorded from. Derived from the working directory when omitted.',
+        },
+        origin_branch: {
+          type: 'string',
+          description:
+            'Provenance: the git branch this memory was recorded from. Derived from the working directory when omitted.',
+        },
+        origin_commit: {
+          type: 'string',
+          description:
+            'Provenance: the commit SHA checked out when this memory was recorded. Derived from the working directory when omitted.',
+        },
+        origin_pr: {
+          type: 'integer',
+          minimum: 1,
+          description:
+            'Provenance: the pull request number this memory came out of. Pass it when you know it — the server can only infer it from CI environment variables.',
+        },
       },
     },
   },
@@ -148,10 +182,15 @@ export const ORG_TOOL_DEFS = [
 // Legacy alias kept so existing code that imports TOOL_DEFS still compiles.
 export const TOOL_DEFS = [...MEMORY_TOOL_DEFS, ...ORG_TOOL_DEFS];
 
-// tool name → (store, args) → store result. The store destructures the args it
-// needs, so the raw `arguments` object is passed straight through.
+// tool name → (store, args, ctx) → store result. The store destructures the
+// args it needs, so the raw `arguments` object is passed straight through.
+// `ctx.root` is the resolved project root (`--dir`), NOT the process cwd — an
+// MCP client launched from elsewhere would otherwise stamp the wrong origin.
 const MEMORY_DISPATCH = {
-  'memory.write': (store, a) => store.write(a),
+  // An agent calling memory.write knows the lesson, not the working directory
+  // it is running in. Fill in whatever provenance the environment can supply,
+  // with anything the caller DID pass taking precedence.
+  'memory.write': (store, a, ctx) => store.write({ ...a, ...withDerivedOrigin(a, ctx) }),
   'memory.read': (store, a) => store.read(a),
   'memory.list': (store, a) => store.list(a),
   'memory.search': (store, a) => store.search(a),
@@ -159,6 +198,22 @@ const MEMORY_DISPATCH = {
   'memory.archive': (store, a) => store.archive(a),
 };
 
+// Provenance for a tool call: the caller's explicit values win, the working
+// directory and CI environment fill the rest. Best-effort — a failure to shell
+// out to git must never fail the write, so it degrades to no origin at all.
+function withDerivedOrigin(args = {}, { root } = {}) {
+  try {
+    return mergeOrigin(deriveOrigin({ cwd: root }), {
+      origin_repo: args.origin_repo ?? null,
+      origin_branch: args.origin_branch ?? null,
+      origin_commit: args.origin_commit ?? null,
+      origin_pr: args.origin_pr ?? null,
+    });
+  } catch {
+    return {};
+  }
+}
+
 // org.* dispatch — always routed to the remote store.
 const ORG_DISPATCH = {
   'org.create': (remote, a) => remote.orgCreate(a),
@@ -188,7 +243,7 @@ function toolResult(id, payload) {
 
 // Build the per-message handler over a resolved control model. `store` is null
 // when mode is `off`. Org tools are always advertised regardless of mode.
-export function createHandler(control) {
+export function createHandler(control, { root = process.cwd() } = {}) {
   const store = createStore(control);
   const memoryTools = store ? MEMORY_TOOL_DEFS : [];
 
@@ -257,7 +312,7 @@ export function createHandler(control) {
       const fn = MEMORY_DISPATCH[name];
       if (!fn) return errorReply(id, -32601, `Unknown tool: ${name}`);
 
-      const result = await fn(store, args);
+      const result = await fn(store, args, { root });
       return toolResult(id, result);
     }
 
@@ -359,7 +414,7 @@ export async function mcpServer(
 ) {
   const root = resolveProjectRoot(args.dir);
   const control = loadControl(root, { env: withOverrides(args, env) });
-  const handle = createHandler(control);
+  const handle = createHandler(control, { root });
   // A human who runs `lorekit mcp` in a terminal would otherwise see a silent
   // hang with no sign it is alive. Reassure them on stderr — but only when
   // stdin is a TTY, so a piped MCP client never sees the banner on either channel.

package/src/origin.mjs

@@ -0,0 +1,186 @@
+// Derive a memory's ORIGIN — where a lesson is being recorded FROM — from the
+// git working directory and the ambient CI environment.
+//
+// This is the counterpart to `scope.mjs`'s `deriveScope()`. A scope says where
+// a lesson APPLIES; an origin says where it was written: the repository, the
+// branch, the checked-out commit, and the pull request the work belonged to.
+// The dashboard renders it as a "recorded from" block with links straight back
+// to the PR, branch, and commit (migration 00048).
+//
+// Nothing here is required: every field independently degrades to `null` when
+// it cannot be determined (no git, detached HEAD, no PR context), and a write
+// with no origin at all behaves exactly as it did before this existed.
+//
+// Zero-dependency, and deliberately injectable (`{ cwd, env, run }`) so the
+// whole derivation is testable without a real repository or a real CI runner.
+import { execFileSync } from 'node:child_process';
+import { ownerRepoFromRemote } from './scope.mjs';
+
+function gitRunner(args, cwd) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract a pull request number from the ambient environment.
+ *
+ * Precedence, first match wins:
+ *   1. LOREKIT_PR              — the explicit escape hatch, any CI or none.
+ *   2. GITHUB_REF              — `refs/pull/<n>/merge` on a GitHub Actions
+ *                                `pull_request` run.
+ *   3. GITHUB_PR_NUMBER        — set by several popular actions.
+ *
+ * Returns a positive integer, or `null` when no PR context is present.
+ */
+export function prNumberFromEnv(env = process.env) {
+  const explicit = toPositiveInt(env.LOREKIT_PR);
+  if (explicit !== null) return explicit;
+
+  const ref = typeof env.GITHUB_REF === 'string' ? env.GITHUB_REF : '';
+  const m = /^refs\/pull\/(\d+)\//.exec(ref);
+  if (m) {
+    const n = toPositiveInt(m[1]);
+    if (n !== null) return n;
+  }
+
+  return toPositiveInt(env.GITHUB_PR_NUMBER);
+}
+
+function toPositiveInt(raw) {
+  if (raw === undefined || raw === null || raw === '') return null;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) return null;
+  return n;
+}
+
+/**
+ * Whether a string is a usable git ref name, per git-check-ref-format.
+ *
+ * A deny list, deliberately: a branch is whatever a contributor named it, and
+ * `feat/add+x` / `fix/issue#123` / `feat/café` are all legal. The canonical
+ * rule lives in `packages/mcp-core/src/origin.ts` (`parseOriginBranch`); this
+ * is the zero-dependency CLI copy, kept behaviourally identical so a branch the
+ * CLI derives is never one the server would reject.
+ */
+export function isValidRef(value) {
+  if (typeof value !== 'string' || value === '') return false;
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f ~^:?*[\\]/.test(value)) return false;
+  if (value.startsWith('/') || value.endsWith('/')) return false;
+  if (value.startsWith('.') || value.endsWith('.')) return false;
+  if (value.endsWith('.lock')) return false;
+  if (value.includes('..') || value.includes('//') || value.includes('@{')) return false;
+  return value.length <= 255;
+}
+
+function firstNonEmpty(...values) {
+  for (const v of values) {
+    if (typeof v === 'string' && v.trim() !== '') return v.trim();
+  }
+  return null;
+}
+
+/**
+ * Derive `{ origin_repo, origin_branch, origin_commit, origin_pr }` for the
+ * current working directory.
+ *
+ * Branch resolution prefers `GITHUB_HEAD_REF` over `git rev-parse`: on a
+ * GitHub Actions `pull_request` run the checkout is a detached merge commit,
+ * so git reports `HEAD` while `GITHUB_HEAD_REF` holds the real source branch.
+ *
+ * The branch is NOT lowercased (unlike a `branch::` scope) so the GitHub
+ * `/tree/` link the dashboard builds from it resolves for a mixed-case branch.
+ *
+ * @returns an object whose four fields are each a value or `null`.
+ */
+export function deriveOrigin({ cwd = process.cwd(), env = process.env, run = gitRunner } = {}) {
+  const remote = run(['config', '--get', 'remote.origin.url'], cwd);
+  const gitBranch = run(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+
+  // On a GitHub Actions `pull_request` run the checkout is a DETACHED MERGE
+  // COMMIT of the head branch into the base, so `HEAD` (and `GITHUB_SHA`) name
+  // a commit that exists on neither branch. Since the branch below deliberately
+  // reports `GITHUB_HEAD_REF` — the real source branch — taking the merge SHA
+  // here would have the two fields describe different refs.
+  //
+  // The head commit is the merge commit's SECOND parent. A shallow checkout
+  // (actions/checkout's default `fetch-depth: 1`) does not have it, in which
+  // case we record NO commit: an absent field is honest, a mismatched one is
+  // worse than nothing.
+  const onMergeCheckout = Boolean(firstNonEmpty(env.GITHUB_HEAD_REF));
+  const gitCommit = onMergeCheckout
+    ? run(['rev-parse', 'HEAD^2'], cwd)
+    : run(['rev-parse', 'HEAD'], cwd);
+
+  // Precedence matches every other field: the explicit `LOREKIT_*` override
+  // first, then what the environment can work out. `LOREKIT_REPO` losing to the
+  // git remote would make it the one override that does not override.
+  //
+  // Each candidate goes through `isValidRepo` individually rather than only the
+  // winner, so an odd remote FALLS THROUGH to `GITHUB_REPOSITORY` instead of
+  // shadowing it with a value the server's strict `parseOriginRepo` rejects —
+  // which would 400 the write this provenance only decorates.
+  const repo =
+    isValidRepo(env.LOREKIT_REPO) ??
+    isValidRepo(ownerRepoFromRemote(remote)) ??
+    isValidRepo(env.GITHUB_REPOSITORY);
+  const branchRaw = firstNonEmpty(env.LOREKIT_BRANCH, env.GITHUB_HEAD_REF, gitBranch);
+  // A derived branch that the server would reject is dropped here rather than
+  // sent: provenance is decoration, and it must never fail the write it is
+  // decorating.
+  const branch = branchRaw && branchRaw !== 'HEAD' && isValidRef(branchRaw) ? branchRaw : null;
+  // GITHUB_SHA is only a safe fallback OFF a merge checkout — on one it is the
+  // merge commit, the very value the branch above exists to avoid.
+  const commitRaw = onMergeCheckout
+    ? firstNonEmpty(env.LOREKIT_COMMIT, gitCommit)
+    : firstNonEmpty(env.LOREKIT_COMMIT, gitCommit, env.GITHUB_SHA);
+  const commit = commitRaw && /^[0-9a-fA-F]{7,40}$/.test(commitRaw) ? commitRaw.toLowerCase() : null;
+
+  return {
+    origin_repo: repo,
+    origin_branch: branch,
+    origin_commit: commit,
+    origin_pr: prNumberFromEnv(env),
+  };
+}
+
+/**
+ * Normalise a candidate `owner/name`, or null when it is not one.
+ *
+ * The single repo rule for every derivation path, matching the server's
+ * `parseOriginRepo` (`packages/mcp-core/src/origin.ts`) — including its
+ * rejection of a dots-only segment, which `[\\w.-]+` alone admits and which
+ * would render as a link to a different repository.
+ */
+export function isValidRepo(value) {
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === '' || normalized.length > 140) return null;
+  if (!/^[\w.-]+\/[\w.-]+$/.test(normalized)) return null;
+  if (normalized.split('/').some((segment) => /^\.+$/.test(segment))) return null;
+  return normalized;
+}
+
+/**
+ * Merge a derived origin under caller-supplied overrides, dropping null fields.
+ *
+ * An explicitly supplied value always wins; a field neither supplied nor
+ * derivable is omitted entirely rather than sent as `null`, so the server's
+ * "keep the last KNOWN origin" upsert rule never erases a previously recorded
+ * value.
+ */
+export function mergeOrigin(derived = {}, overrides = {}) {
+  const out = {};
+  for (const field of ['origin_repo', 'origin_branch', 'origin_commit', 'origin_pr']) {
+    const value = overrides[field] ?? derived[field] ?? null;
+    if (value !== null && value !== undefined && value !== '') out[field] = value;
+  }
+  return out;
+}

package/src/store/format.mjs

@@ -17,6 +17,17 @@ export const FIELDS = [
   'created',
   'updated',
   'archived_at',
+  // Provenance — where the lesson was recorded FROM (see src/origin.mjs).
+  // Appended, never reordered: parseEntry is tolerant, so a file written before
+  // these existed simply decodes them as absent.
+  'origin_repo',
+  '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
@@ -91,17 +92,23 @@ class LocalStore {
   // existing key (a creation date never moves). Returns { ok:false, error } on
   // 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 } = {}) {
-    let override;
+  async write({
+    scope, key, value, tags, source_agent, trigger, created_at, ttl_days, clear_ttl,
+    origin_repo, origin_branch, origin_commit, origin_pr,
+  } = {}) {
+    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,
@@ -109,9 +116,17 @@ class LocalStore {
       tags: Array.isArray(tags) ? tags : [],
       source_agent: source_agent || null,
       trigger: trigger || null,
+      // Provenance keeps the last KNOWN value per field, mirroring the hosted
+      // memory_write upsert: a write that does not know a field must not erase
+      // what a previous write recorded.
+      origin_repo: origin_repo ?? existing?.entry.origin_repo ?? null,
+      origin_branch: origin_branch ?? existing?.entry.origin_branch ?? null,
+      origin_commit: origin_commit ?? existing?.entry.origin_commit ?? null,
+      origin_pr: origin_pr ?? existing?.entry.origin_pr ?? null,
       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);
@@ -135,9 +150,14 @@ class LocalStore {
       tags: Array.isArray(entry.tags) ? entry.tags : [],
       source_agent: entry.source_agent ?? null,
       trigger: entry.trigger ?? null,
+      origin_repo: entry.origin_repo ?? null,
+      origin_branch: entry.origin_branch ?? null,
+      origin_commit: entry.origin_commit ?? null,
+      origin_pr: entry.origin_pr ?? null,
       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);
@@ -244,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 }));
@@ -378,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/remote.mjs

@@ -91,7 +91,10 @@ class RemoteStore {
   }
 
   async write(args = {}) {
-    const { scope, key, value, tags, source_agent, trigger, org, ttl_days, clear_ttl, created_at } = args;
+    const {
+      scope, key, value, tags, source_agent, trigger, org, ttl_days, clear_ttl, created_at,
+      origin_repo, origin_branch, origin_commit, origin_pr,
+    } = args;
     const body = { scope, key, value };
     if (tags !== undefined) body.tags = tags;
     if (source_agent !== undefined) body.source_agent = source_agent;
@@ -100,6 +103,13 @@ class RemoteStore {
     if (ttl_days !== undefined) body.ttl_days = ttl_days;
     if (clear_ttl !== undefined) body.clear_ttl = clear_ttl;
     if (created_at !== undefined) body.created_at = created_at;
+    // Provenance — only sent when known. Omitting a field leaves whatever the
+    // row already recorded intact (the RPC coalesces), which is what makes a
+    // write from a machine with no git context non-destructive.
+    if (origin_repo !== undefined) body.origin_repo = origin_repo;
+    if (origin_branch !== undefined) body.origin_branch = origin_branch;
+    if (origin_commit !== undefined) body.origin_commit = origin_commit;
+    if (origin_pr !== undefined) body.origin_pr = origin_pr;
     const res = await this._rest('/memories', { method: 'POST', body });
     return { ok: res.ok, error: res.error, networkError: res.networkError };
   }

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,8 +14,19 @@
 //   --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
+// from git + the CI environment (repo, branch, commit, and the pull request
+// from LOREKIT_PR / GITHUB_REF); the dashboard turns it into links back to the
+// PR, branch and commit. Each can be overridden, and the whole thing skipped:
+//   --origin-repo <owner/name>  Override the derived repository
+//   --origin-branch <name>      Override the derived branch
+//   --origin-commit <sha>       Override the derived commit
+//   --origin-pr <n>             The pull request this lesson came out of
+//   --no-origin                 Record no provenance at all
+//
 // Store targeting (default: remote if configured, else local):
 //   --remote               Force write to the remote store
 //   --local                Force write to the local offline store
@@ -32,6 +43,8 @@ import { 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';
 
 // Read all of stdin to a string. Resolves to '' when stdin IS a TTY (no pipe).
 function readStdin() {
@@ -97,9 +110,56 @@ 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 ────────────────────────────────────────────────────────────
+  // Derived from git + CI unless --no-origin; explicit --origin-* flags win.
+  // A field that is neither supplied nor derivable is omitted, never sent as
+  // null — the server keeps the last KNOWN origin per field, so an omission
+  // must not erase what an earlier write recorded.
+  // An explicitly supplied PR number is a caller assertion, so a malformed one
+  // is a usage error — silently ignoring it would record no provenance while
+  // the user believes they set it. Derived values, by contrast, degrade quietly.
+  let originPr = null;
+  if (args['origin-pr'] !== undefined) {
+    originPr = Number(args['origin-pr']);
+    if (!Number.isInteger(originPr) || originPr < 1) {
+      err(`${c.red('Error:')} --origin-pr must be a positive integer (got ${args['origin-pr']})`);
+      return 1;
+    }
+  }
+
+  const origin = args['no-origin']
+    ? {}
+    : mergeOrigin(deriveOrigin({ cwd: root, env }), {
+        origin_repo: typeof args['origin-repo'] === 'string' ? args['origin-repo'] : null,
+        origin_branch: typeof args['origin-branch'] === 'string' ? args['origin-branch'] : null,
+        origin_commit: typeof args['origin-commit'] === 'string' ? args['origin-commit'] : null,
+        origin_pr: originPr,
+      });
+
   // ── Resolve deny constraints ───────────────────────────────────────────────
   const { localDenied, remoteDenied } = resolveDenies(root, { env });
 
@@ -161,7 +221,9 @@ export async function write(args) {
     ...(sourceAgent ? { source_agent: sourceAgent } : {}),
     ...(trigger ? { trigger } : {}),
     ...(ttlDays ? { ttl_days: ttlDays } : {}),
+    ...(clearTtl ? { clear_ttl: true } : {}),
     ...(orgSlug ? { org: orgSlug } : {}),
+    ...origin,
   };
 
   let result;
@@ -192,6 +254,7 @@ export async function write(args) {
       tags,
       source_agent: sourceAgent || null,
       trigger: trigger || null,
+      origin,
     }, null, 2));
   } else {
     const verb = inserted === true ? 'Created' : inserted === false ? 'Updated' : 'Written';
@@ -210,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,
   };
 }