@lorekit/cli 1.18.0 → 1.19.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';
@@ -53,7 +54,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>.
@@ -246,6 +253,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 +306,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 +511,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 +519,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 +536,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 +613,8 @@ async function main() {
       return traceCommand('dedupe', args, VERSION, () => dedupe(args));
     case 'migrate':
       return traceCommand('migrate', args, VERSION, () => migrate(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.19.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

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/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),
+  };
+}