@lorekit/cli 1.18.0 → 1.20.0

package/bin/lorekit.mjs

@@ -9,6 +9,7 @@ import { doctor } from '../src/doctor.mjs';
 import { list } from '../src/list.mjs';
 import { search } from '../src/search.mjs';
 import { show } from '../src/show.mjs';
+import { write } from '../src/write.mjs';
 import { stats } from '../src/stats.mjs';
 import { scopes } from '../src/scopes.mjs';
 import { diff } from '../src/diff.mjs';
@@ -17,6 +18,7 @@ import { lint } from '../src/lint.mjs';
 import { dedupe } from '../src/dedupe.mjs';
 import { hook } from '../src/hook.mjs';
 import { migrate } from '../src/migrate.mjs';
+import { bootstrap } from '../src/bootstrap.mjs';
 import { mcpServer } from '../src/mcp-server.mjs';
 import { traceCommand } from '../src/telemetry.mjs';
 import { loadDotEnv } from '../src/dotenv.mjs';
@@ -53,7 +55,13 @@ ${c.bold('Commands')}
               rendered in the same Offline/Remote split. --json, --scope <s>.
   show        Inspect one memory in full: its complete value, scope, key, updated
               date, tags, and which store(s) it lives in (noting any divergence
-              when it is in both). --json. Usage: show <scope> <key>.
+              when it is in both). Accepts show <scope> <key> or the combined
+              show <scope::key> shorthand (copy-paste directly from list output).
+              --json.
+  write       Create or update a memory. Accepts the same <scope::key> shorthand.
+              Value is a positional, --value flag, or piped stdin. Writes to the
+              remote store when configured, falling back to local. --local /
+              --remote to force.
   stats       Count the applicable memories per scope and per store (offline vs
               remote), with per-store and grand totals, in the same Offline/
               Remote split. --json, --scope <s>.
@@ -73,6 +81,9 @@ ${c.bold('Commands')}
   dedupe      Find likely-duplicate memories via a zero-dep word-overlap HEURISTIC
               (Jaccard >= threshold, not semantic), grouped into clusters per
               store. --json, --scope <s>, --threshold <0..1>.
+  bootstrap   Apply the BYOD schema to a user-supplied Supabase database.
+              Only needed when using LOREKIT_STORAGE_URL / LOREKIT_STORAGE_ANON_KEY.
+              See docs/byod.md for setup instructions.
   migrate     Relocate a LoreKit-format local store into the current layout.
               Dry-run by default; pass --yes to apply. Idempotent.
   hook        Hook engine for Claude Code / Cursor / Codex. Reads the host's
@@ -246,6 +257,39 @@ ${c.bold('Examples')}
   npx @lorekit/cli search sandbox
   npx @lorekit/cli grep "flaky test" --json
   npx @lorekit/cli search migration --scope global
+`,
+  write: `${c.bold('lorekit write')} — create or update a memory from the CLI
+
+${c.bold('Usage')}
+  npx @lorekit/cli write <scope> <key> <value> [options]
+  npx @lorekit/cli write <scope::key> <value> [options]
+  echo "value" | npx @lorekit/cli write <scope> <key> [options]
+
+Creates or updates a memory (upsert — overwrites if the key exists). Value can
+be a positional, --value, or piped stdin. Writes to the remote store when
+configured, falling back to local.
+
+${c.bold('Options')}
+  -d, --dir <path>         Target project root (default: current directory)
+      --value <text>       Memory value (alternative to positional / stdin)
+      --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)
+      --org <slug>         Write to this org's scope (remote only)
+      --remote             Force write to the remote store
+      --local              Force write to the local offline store
+      --json               Machine-readable output
+  -e, --endpoint <url>     Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
+  -t, --token <token>      Remote token override (else .mcp.json / LOREKIT_TOKEN)
+      --store <path>       Local project-tier store directory (default: .lorekit)
+
+${c.bold('Examples')}
+  npx @lorekit/cli write global my-key "Always prefer guard clauses"
+  npx @lorekit/cli write global::my-key "Always prefer guard clauses"
+  cat notes.md | npx @lorekit/cli write global my-key --tags "style,aw"
+  npx @lorekit/cli write global my-key "body" --local
+  npx @lorekit/cli write global my-key "body" --ttl-days 30 --remote
 `,
   show: `${c.bold('lorekit show')} — inspect one memory in full
 
@@ -266,6 +310,7 @@ ${c.bold('Options')}
 
 ${c.bold('Examples')}
   npx @lorekit/cli show global prefer-guard-clauses
+  npx @lorekit/cli show global::prefer-guard-clauses
   npx @lorekit/cli show project::widget build-flags --json
 `,
   stats: `${c.bold('lorekit stats')} — count the applicable memories per scope and per store
@@ -470,6 +515,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',
 ];
 
 // Commands that write to disk / talk to the network on a human's behalf. These
@@ -477,7 +523,7 @@ const KNOWN_FLAGS = [
 // never fail on a stray flag, and only ever receive flags we control).
 const HUMAN_COMMANDS = new Set([
   'install', 'uninstall', 'doctor', 'list', 'search', 'show', 'stats', 'scopes',
-  'diff', 'tree', 'lint', 'dedupe', 'migrate',
+  'diff', 'tree', 'lint', 'dedupe', 'migrate', 'write',
 ]);
 
 // Command aliases — canonicalized before help / dispatch so `lorekit ls --help`
@@ -494,7 +540,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'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'json', 'remote', 'local'],
     known: KNOWN_FLAGS,
   });
 
@@ -571,6 +617,10 @@ async function main() {
       return traceCommand('dedupe', args, VERSION, () => dedupe(args));
     case 'migrate':
       return traceCommand('migrate', args, VERSION, () => migrate(args));
+    case 'bootstrap':
+      return traceCommand('bootstrap', args, VERSION, () => bootstrap(args));
+    case 'write':
+      return traceCommand('write', args, VERSION, () => write(args));
     default:
       err(`${c.red('Unknown command:')} ${command}\n`);
       log(HELP);

package/package.json

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

package/src/bootstrap.mjs

@@ -0,0 +1,141 @@
+// `lorekit bootstrap` — apply the BYOD schema to a user-supplied Supabase database.
+//
+// Reads LOREKIT_STORAGE_URL and LOREKIT_STORAGE_SERVICE_KEY from the environment.
+// If neither is set, prints a helpful message and exits 0 — bootstrap is only
+// needed for BYOD (Bring Your Own Database) setups.
+//
+// Because Supabase's JS client does not expose a raw SQL execution method for DDL,
+// this command instructs the user to run the SQL file directly with psql when no
+// direct execution path is available. It validates connectivity using the anon key
+// and confirms the bootstrap.sql path for the user.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import { log, err, heading, status, c } from './util.mjs';
+
+// The bootstrap.sql file is at <repo-root>/supabase/byod/bootstrap.sql.
+// This file lives at packages/cli/src/bootstrap.mjs, so the relative path
+// from here to the repo root is ../../../  (src → cli → packages → root).
+const BOOTSTRAP_SQL_PATH = fileURLToPath(
+  new URL('../../../supabase/byod/bootstrap.sql', import.meta.url),
+);
+
+export async function bootstrap(_args) {
+  heading('LoreKit bootstrap');
+
+  const storageUrl = process.env['LOREKIT_STORAGE_URL'];
+  const storageServiceKey = process.env['LOREKIT_STORAGE_SERVICE_KEY'];
+  const storageAnonKey = process.env['LOREKIT_STORAGE_ANON_KEY'];
+
+  // If no BYOD env vars are set, this command is a no-op — it's only for BYOD.
+  if (!storageUrl && !storageServiceKey) {
+    log('');
+    log(
+      `  ${c.cyan('•')} No BYOD storage configured — ${c.dim('bootstrap is only needed for custom databases.')}`,
+    );
+    log('');
+    log('  Set LOREKIT_STORAGE_URL and LOREKIT_STORAGE_SERVICE_KEY to use your own');
+    log('  Supabase project, then re-run this command.');
+    log('');
+    log('  See docs/byod.md for setup instructions.');
+    return 0;
+  }
+
+  if (!storageUrl) {
+    err(`${c.red('Error:')} LOREKIT_STORAGE_SERVICE_KEY is set but LOREKIT_STORAGE_URL is missing.`);
+    err('  Both variables are required. Set LOREKIT_STORAGE_URL and try again.');
+    return 1;
+  }
+
+  // Locate the bootstrap SQL file.
+  let sqlPath = BOOTSTRAP_SQL_PATH;
+
+  // When running from a published npm package, the SQL file is not bundled
+  // with the CLI. Fall back to looking for it relative to CWD (for dev use).
+  if (!fs.existsSync(sqlPath)) {
+    const cwdPath = path.resolve(process.cwd(), 'supabase/byod/bootstrap.sql');
+    if (fs.existsSync(cwdPath)) {
+      sqlPath = cwdPath;
+    } else {
+      err(`${c.red('Error:')} bootstrap.sql not found at expected path:`);
+      err(`  ${sqlPath}`);
+      err('');
+      err('  Apply the schema manually with psql:');
+      err('    psql "$DATABASE_URL" -f supabase/byod/bootstrap.sql');
+      err('');
+      err('  Or download it from the LoreKit repository:');
+      err('    https://github.com/mthines/lorekit/blob/main/supabase/byod/bootstrap.sql');
+      return 1;
+    }
+  }
+
+  status('pass', 'bootstrap.sql', sqlPath);
+  status('info', 'storage url', storageUrl);
+
+  // Test connectivity using the anon key if available (non-DDL path).
+  if (storageAnonKey) {
+    try {
+      const { createClient } = await import('@supabase/supabase-js');
+      const db = createClient(storageUrl, storageAnonKey, {
+        auth: { persistSession: false, autoRefreshToken: false },
+      });
+      // Simple ping: list memories (will return 0 rows or error if schema not applied yet).
+      const { error } = await db.from('memories').select('id').limit(1);
+      if (error && error.code === '42P01') {
+        // Table does not exist yet — that's expected before bootstrap.
+        status('info', 'connectivity', 'connected — schema not yet applied (run bootstrap)');
+      } else if (error) {
+        status('warn', 'connectivity', `connected but got: ${error.message}`);
+      } else {
+        status('pass', 'connectivity', 'connected and schema already present');
+      }
+    } catch (e) {
+      status('warn', 'connectivity', `could not verify: ${e && e.message ? e.message : String(e)}`);
+    }
+  } else {
+    status('info', 'connectivity', 'skipped — LOREKIT_STORAGE_ANON_KEY not set');
+  }
+
+  // Supabase JS client cannot execute raw DDL SQL directly.
+  // The correct path is psql or the Supabase dashboard SQL editor.
+  log('');
+  log(`  ${c.bold('To apply the schema, run:')}`);
+  log('');
+  log(`    ${c.cyan('psql "$DATABASE_URL" -f')} ${sqlPath}`);
+  log('');
+  log(`  Or paste the contents of ${c.dim(sqlPath)}`);
+  log('  into the Supabase dashboard → SQL Editor.');
+  log('');
+
+  if (storageServiceKey) {
+    status(
+      'info',
+      'service key',
+      'LOREKIT_STORAGE_SERVICE_KEY is set — use it as $DATABASE_URL password with psql',
+    );
+    log('');
+    log(`  ${c.dim('Example:')}`);
+    log(
+      `    ${c.cyan('DATABASE_URL')}="postgresql://postgres.${parseRef(storageUrl)}:${storageServiceKey}@aws-0-us-east-1.pooler.supabase.com:6543/postgres"`,
+    );
+    log(`    ${c.cyan('psql "$DATABASE_URL"')} -f ${sqlPath}`);
+    log('');
+    log(
+      `  ${c.dim('(Replace the host/port above with the exact connection string from your')}`,
+    );
+    log(`  ${c.dim('Supabase dashboard → Settings → Database → Connection string.)')}`);
+  }
+
+  return 0;
+}
+
+// Extract the project ref from a Supabase URL for display in the example.
+function parseRef(url) {
+  try {
+    const host = new URL(url).hostname; // e.g. abcdefgh.supabase.co
+    return host.split('.')[0];
+  } catch {
+    return '<project-ref>';
+  }
+}

package/src/diff.mjs

@@ -132,7 +132,7 @@ function renderSet(title, subtitle, groups, pick) {
     log(`  ${c.bold(g.scope)}`);
     for (const e of pick(g)) {
       const when = e.updated ? `  ${c.dim(`(updated ${shortDate(e.updated)})`)}` : '';
-      log(`    ${c.cyan('•')} ${e.key}${when}`);
+      log(`    ${c.cyan('•')} ${g.scope}::${e.key}${when}`);
       if (e.value) log(`      ${c.dim(preview(e.value))}`);
     }
   }
@@ -148,7 +148,7 @@ function renderConflicts(groups) {
   for (const g of present) {
     log(`  ${c.bold(g.scope)}`);
     for (const conflict of g.conflicting) {
-      log(`    ${c.yellow('•')} ${conflict.key}`);
+      log(`    ${c.yellow('•')} ${g.scope}::${conflict.key}`);
       log(`      ${c.dim('offline')} ${preview(conflict.local.value)}`);
       log(`      ${c.dim('remote ')} ${preview(conflict.remote.value)}`);
     }

package/src/doctor.mjs

@@ -98,6 +98,9 @@ export async function doctor(args) {
     await checkRemote(control, root, args, record);
   }
 
+  // 4b. BYOD storage connectivity check.
+  await checkBYODStorage(record);
+
   // 5. Scope.
   const scope = deriveScope(root);
   if (scope.hasRemote) {
@@ -351,6 +354,40 @@ function hooksForEvent(hooksObj, event) {
   return commands;
 }
 
+async function checkBYODStorage(record) {
+  const storageUrl = process.env['LOREKIT_STORAGE_URL'];
+  const storageAnonKey = process.env['LOREKIT_STORAGE_ANON_KEY'];
+
+  if (!storageUrl && !storageAnonKey) {
+    return; // No BYOD configured — skip silently.
+  }
+
+  if (storageUrl && !storageAnonKey) {
+    record('fail', 'byod storage', 'LOREKIT_STORAGE_URL is set but LOREKIT_STORAGE_ANON_KEY is missing');
+    return;
+  }
+
+  if (!storageUrl && storageAnonKey) {
+    record('fail', 'byod storage', 'LOREKIT_STORAGE_ANON_KEY is set but LOREKIT_STORAGE_URL is missing');
+    return;
+  }
+
+  try {
+    const { createClient } = await import('@supabase/supabase-js');
+    const db = createClient(storageUrl, storageAnonKey, {
+      auth: { persistSession: false, autoRefreshToken: false },
+    });
+    const { error } = await db.from('memories').select('id').limit(1);
+    if (error && error.code !== '42P01') {
+      record('fail', 'byod storage', `connectivity error: ${error.message}`);
+    } else {
+      record('pass', 'byod storage', `ok — ${storageUrl}`);
+    }
+  } catch (e) {
+    record('fail', 'byod storage', `could not connect: ${e && e.message ? e.message : String(e)}`);
+  }
+}
+
 function gitTracked(root, dir) {
   // Heuristic: is the store dir ignored by git? If `git check-ignore` names it,
   // it is private; otherwise it will be committed (team-shared).

package/src/lessons-view.mjs

@@ -16,6 +16,19 @@ import { log, heading, status, c } from './util.mjs';
 import { resolvePrecedence, matchesQuery } from './lessons-pure.mjs';
 export { resolvePrecedence, matchesQuery };
 
+// Parse a combined `scope::key` string into { scope, key }, or return null when
+// the input contains no `::`. Uses the FIRST occurrence of `::` as the separator
+// so nested scopes like `branch::owner/repo::feat/x` are handled correctly.
+// Exported so `show`, `write`, and any future commands share one implementation.
+export function parseScopeKey(s) {
+  const idx = s.indexOf('::');
+  if (idx === -1) return null;
+  const scope = s.slice(0, idx).trim();
+  const key = s.slice(idx + 2).trim();
+  if (!scope || !key) return null;
+  return { scope, key };
+}
+
 // The scopes that apply to the current directory, most-specific → broadest:
 // project, branch, repo, global. De-duplicated (a repo with no branch scope,
 // or a project whose name collides, never lists a scope twice). Pure — takes an
@@ -443,7 +456,7 @@ export function renderSection(header, section) {
     }
     for (const e of g.entries) {
       const when = e.updated ? `  ${c.dim(`(updated ${shortDate(e.updated)})`)}` : '';
-      log(`    ${c.cyan('•')} ${e.key}${when}`);
+      log(`    ${c.cyan('•')} ${g.scope}::${e.key}${when}`);
       if (e.value) log(`      ${c.dim(preview(e.value))}`);
     }
   }

package/src/lint.mjs

@@ -117,7 +117,7 @@ function renderLintSection(header, section) {
       continue;
     }
     for (const f of g.findings) {
-      log(`    ${c.yellow('•')} ${f.key}  ${c.dim(`[${f.rule}]`)} ${f.message}`);
+      log(`    ${c.yellow('•')} ${g.scope}::${f.key}  ${c.dim(`[${f.rule}]`)} ${f.message}`);
     }
   }
 }

package/src/show.mjs

@@ -4,6 +4,11 @@
 // stores — possibly with different values — both are shown and the divergence is
 // flagged.
 //
+// Two positional shapes are accepted:
+//   show <scope> <key>     — classic two-positional form
+//   show <scope::key>      — combined shorthand (the same format `list` prints,
+//                            so you can copy-paste a key directly from list output)
+//
 // Uses each store's real `read({scope, key})` method (both stores expose it),
 // not a filtered `list` — a single-record lookup is what `read` is for, and it
 // already hides archived entries. Graceful by design (mirrors `list`/`search`):
@@ -13,7 +18,7 @@ import process from 'node:process';
 import { resolveProjectRoot } from './config.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { normalizeEntry, shortDate, describeError, recordsDiverge } from './lessons-view.mjs';
+import { normalizeEntry, shortDate, describeError, recordsDiverge, parseScopeKey } from './lessons-view.mjs';
 import { log, err, heading, status, c } from './util.mjs';
 
 // Read one scope::key from a store, normalizing the result into a small,
@@ -40,11 +45,24 @@ export async function show(args) {
   const env = { ...process.env };
   if (args.store) env.LOREKIT_STORE = args.store;
 
-  // Both positionals are required: `show <scope> <key>`.
-  const scope = typeof args._[1] === 'string' ? args._[1] : '';
-  const key = typeof args._[2] === 'string' ? args._[2] : '';
+  // Two positional shapes are accepted:
+  //   show <scope> <key>    — classic two-positional form (backward-compatible)
+  //   show <scope::key>     — combined shorthand mirroring `list` output format
+  let scope, key;
+  const first = typeof args._[1] === 'string' ? args._[1] : '';
+  const parsed = parseScopeKey(first);
+  if (parsed) {
+    // Combined scope::key — e.g. `show global::claude-mcp-registration-can-hang`
+    scope = parsed.scope;
+    key = parsed.key;
+  } else {
+    // Classic two-positional form — e.g. `show global claude-mcp-registration-can-hang`
+    scope = first;
+    key = typeof args._[2] === 'string' ? args._[2] : '';
+  }
   if (!scope || !key) {
     err(`${c.red('Usage:')} lorekit show <scope> <key> [--json]`);
+    err(`       lorekit show <scope::key> [--json]`);
     err(`Both a scope and a key are required. Run ${c.cyan('lorekit show --help')} for options.`);
     return 1;
   }

package/src/tree.mjs

@@ -121,7 +121,7 @@ function renderTreeSection(header, section) {
       const when = e.updated ? `  ${c.dim(`(updated ${shortDate(e.updated)})`)}` : '';
       const mark = e.winning ? c.green('✓') : c.yellow('↳');
       const tag = e.winning ? '' : `  ${c.dim(`shadowed by ${e.shadowedBy}`)}`;
-      log(`    ${mark} ${e.key}${tag}${when}`);
+      log(`    ${mark} ${g.scope}::${e.key}${tag}${when}`);
       if (e.value) log(`      ${c.dim(preview(e.value))}`);
     }
   }

package/src/write.mjs

@@ -0,0 +1,214 @@
+// `lorekit write <scope> <key> [value]` — create or update a memory from the CLI.
+//
+// Two positional shapes are accepted:
+//   write <scope> <key> [value]       — classic two-positional form
+//   write <scope::key> [value]        — combined shorthand (the same format `list`
+//                                       prints, so you can copy-paste a key directly)
+//
+// When no value is supplied as a positional or via --value, the command reads
+// the full stdin (useful for piping). In all cases the value is required — an
+// empty string produces a usage error (prefer `lorekit delete` to remove a key).
+//
+// Optional write-metadata flags mirror the hosted `memory.write` parameters:
+//   --tags <a,b,c>         Comma-separated tag list (default: no tags)
+//   --source-agent <name>  Which agent recorded this lesson (default: none)
+//   --trigger <slug>       What prompted the write (default: none)
+//   --ttl-days <n>         Days until the memory auto-expires (1–365)
+//   --org <slug>           Write to this org (remote only)
+//
+// Store targeting (default: remote if configured, else local):
+//   --remote               Force write to the remote store
+//   --local                Force write to the local offline store
+//
+// The command writes to ONE store at a time (unlike the read commands that show
+// both). Dual-write would silently create a divergence on subsequent `diff`.
+//
+// Output: a confirmation line (human) or a JSON object (--json) with the
+// resolved scope, key, store written, and a boolean `inserted` (true = created,
+// false = updated) when the remote reports it.
+import process from 'node:process';
+import { resolveProjectRoot } from './config.mjs';
+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';
+
+// Read all of stdin to a string. Resolves to '' when stdin IS a TTY (no pipe).
+function readStdin() {
+  if (process.stdin.isTTY) return '';
+  return new Promise((resolve) => {
+    const chunks = [];
+    process.stdin.on('data', (d) => chunks.push(d));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8').trimEnd()));
+    process.stdin.resume();
+  });
+}
+
+export async function write(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = { ...process.env };
+  if (args.store) env.LOREKIT_STORE = args.store;
+
+  // ── Parse positionals: two forms ──────────────────────────────────────────
+  // Form A: `write scope key [value]`   → _[1]=scope, _[2]=key, _[3]=value?
+  // Form B: `write scope::key [value]`  → _[1]='scope::key', _[2]=value?
+  let scope, key, positionalValue;
+
+  const first = typeof args._[1] === 'string' ? args._[1] : '';
+  const parsed = parseScopeKey(first);
+
+  if (parsed) {
+    // Form B: combined scope::key
+    scope = parsed.scope;
+    key = parsed.key;
+    positionalValue = typeof args._[2] === 'string' ? args._[2] : undefined;
+  } else {
+    // Form A: separate scope and key
+    scope = first;
+    key = typeof args._[2] === 'string' ? args._[2] : '';
+    positionalValue = typeof args._[3] === 'string' ? args._[3] : undefined;
+  }
+
+  if (!scope || !key) {
+    err(`${c.red('Usage:')} lorekit write <scope> <key> [value] [options]`);
+    err(`       lorekit write <scope::key> [value] [options]`);
+    err(`Both a scope and a key are required. Run ${c.cyan('lorekit write --help')} for options.`);
+    return 1;
+  }
+
+  // ── Resolve value: flag → positional → stdin ───────────────────────────────
+  let value;
+  if (typeof args.value === 'string') {
+    value = args.value;
+  } else if (positionalValue !== undefined) {
+    value = positionalValue;
+  } else {
+    value = await readStdin();
+  }
+
+  if (!value) {
+    err(`${c.red('Error:')} a non-empty value is required`);
+    err(`Pipe a value via stdin, pass it as a positional, or use --value <text>.`);
+    err(`Run ${c.cyan('lorekit write --help')} for options.`);
+    return 1;
+  }
+
+  // ── Parse optional metadata flags ─────────────────────────────────────────
+  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;
+  const orgSlug = typeof args.org === 'string' ? args.org : undefined;
+
+  // ── Resolve deny constraints ───────────────────────────────────────────────
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
+
+  // ── Resolve stores and pick the target ────────────────────────────────────
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+
+  const forceRemote = Boolean(args.remote);
+  const forceLocal = Boolean(args.local);
+  const remoteUsable = !remoteDenied && remote.usable();
+
+  if (forceRemote && forceLocal) {
+    err(`${c.red('Error:')} --remote and --local are mutually exclusive`);
+    return 1;
+  }
+
+  let targetStore, storeName;
+
+  if (forceRemote) {
+    if (remoteDenied) {
+      err(`${c.red('Error:')} remote store is disabled by deny constraint (${remoteDenied.source})`);
+      return 1;
+    }
+    if (!remote.usable()) {
+      err(`${c.red('Error:')} remote store is not configured — ${remoteUnavailableReason(connection)}`);
+      return 1;
+    }
+    targetStore = remote;
+    storeName = 'remote';
+  } else if (forceLocal) {
+    if (localDenied) {
+      err(`${c.red('Error:')} local store is disabled by deny constraint (${localDenied.source})`);
+      return 1;
+    }
+    targetStore = local;
+    storeName = 'local';
+  } else if (remoteUsable) {
+    targetStore = remote;
+    storeName = 'remote';
+  } else if (!localDenied) {
+    targetStore = local;
+    storeName = 'local';
+  } else {
+    err(`${c.red('Error:')} no writable store available`);
+    err(`Remote: ${remoteUnavailableReason(connection)}`);
+    if (localDenied) err(`Local:  disabled by deny constraint (${localDenied.source})`);
+    return 1;
+  }
+
+  // ── Write ──────────────────────────────────────────────────────────────────
+  const writeArgs = {
+    scope,
+    key,
+    value: String(value),
+    ...(tags.length ? { tags } : {}),
+    ...(sourceAgent ? { source_agent: sourceAgent } : {}),
+    ...(trigger ? { trigger } : {}),
+    ...(ttlDays ? { ttl_days: ttlDays } : {}),
+    ...(orgSlug ? { org: orgSlug } : {}),
+  };
+
+  let result;
+  try {
+    result = await targetStore.write(writeArgs);
+  } catch (e) {
+    err(`${c.red('Error:')} ${(e && e.message) || String(e)}`);
+    return 1;
+  }
+
+  if (!result || result.ok === false) {
+    const detail = result && result.error ? result.error : 'unknown error';
+    err(`${c.red('Error writing to')} ${storeName} store: ${detail}`);
+    return 1;
+  }
+
+  // `inserted` is additive from the remote (memory_write RPC 00011). Local store
+  // returns { ok, entry } with no explicit field; treat absence as unknown.
+  const inserted = result.inserted ?? null;
+
+  if (args.json) {
+    log(JSON.stringify({
+      scope,
+      key,
+      store: storeName,
+      inserted,
+      value: String(value),
+      tags,
+      source_agent: sourceAgent || null,
+      trigger: trigger || null,
+    }, null, 2));
+  } else {
+    const verb = inserted === true ? 'Created' : inserted === false ? 'Updated' : 'Written';
+    heading('LoreKit memory written');
+    log(`  ${c.dim('store')}  ${storeName}`);
+    log(`  ${c.dim('scope')}  ${scope}`);
+    log(`  ${c.dim('key')}    ${key}`);
+    if (tags.length) log(`  ${c.dim('tags')}   ${tags.join(', ')}`);
+    status('pass', verb, `${scope}::${key}`);
+    log('');
+  }
+
+  return {
+    exitCode: 0,
+    'lorekit.cli.write.store': storeName,
+    'lorekit.cli.write.inserted': inserted,
+    'lorekit.cli.write.has_tags': tags.length > 0,
+    'lorekit.cli.write.has_ttl': Boolean(ttlDays),
+  };
+}