@lorekit/cli 1.17.1 → 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.17.1",
+  "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/adapters/claude.mjs

@@ -9,6 +9,7 @@ export const claude = {
       case 'SessionStart':
         return 'read';
       case 'PostToolUse':
+        return 'confirm';
       case 'PostToolUseFailure':
         return 'failure';
       case 'Stop':
@@ -23,11 +24,22 @@ export const claude = {
     return event === 'PostToolUseFailure';
   },
 
+  // Returns true when the PostToolUse event was a successful lorekit memory
+  // write. Claude Code reports MCP tool names as
+  // "mcp__<server-label>__memory_write" (underscores) — we match the suffix
+  // so any server label works. A successful write response always contains
+  // a string `id` field returned by the memory_write RPC.
+  isLoreWrite(toolName, toolResponse) {
+    if (!toolName || !String(toolName).endsWith('memory_write')) return false;
+    return toolResponse != null && typeof toolResponse === 'object' && typeof toolResponse.id === 'string';
+  },
+
   parse(input) {
     return {
       cwd: input.cwd || null,
       sessionId: input.session_id || null,
       toolName: input.tool_name || 'tool',
+      toolInput: input.tool_input || null,
       toolResponse: input.tool_response || null,
       event: input.hook_event_name || null,
     };

package/src/core/lessons.mjs

@@ -174,6 +174,14 @@ 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.
+export function loreUrl(writeScope) {
+  const base = 'https://lorekit.io/lore';
+  if (!writeScope || writeScope === 'global') return base;
+  return `${base}?scope=${encodeURIComponent(writeScope)}`;
+}
+
 // 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.
@@ -182,13 +190,28 @@ export function retrospectiveNudge(scope, control) {
   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}`
+    `as an observation; else skip.${hint}${instruction}\n` +
+    `View lore: ${url}`
   );
 }
 
+// Terse confirmation emitted via PostToolUse when a memory.write succeeded.
+// `key` is the lesson key from the tool response (may be null when the response
+// shape doesn't surface it). Includes a deep link to the scope's Lore Explorer
+// page so the user can verify immediately.
+export function writeConfirmation(scope, key) {
+  const writeScope = scope.repoScope || 'global';
+  const keyPart = key ? ` · ${key}` : '';
+  const url = key
+    ? `${loreUrl(writeScope)}&q=${encodeURIComponent(key)}`
+    : loreUrl(writeScope);
+  return `LoreKit: memory saved to ${writeScope}${keyPart}\nView: ${url}`;
+}
+
 // The nudge emitted when a tool failure is detected.
 // `control` is the resolved control object (optional) — carries tagsDefault and
 // scopeDefaults when the repo/user config defines them.

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

@@ -8,6 +8,9 @@ import {
   SKILLS,
   resolveProjectRoot,
   skillInstallDir,
+  settingsPath,
+  CLAUDE_HOOK_EVENTS,
+  LOREKIT_HOOK_RE,
   readLorekitServer,
   readMcpConfig,
   tokenKind,
@@ -63,6 +66,22 @@ export async function doctor(args) {
     }
   }
 
+  // 2.5. Duplicate-hook detection — warn when the same lorekit hook event is
+  // wired in both the project settings and the global settings. This causes
+  // Claude Code to fire the hook twice per event, producing doubled terminal
+  // output. Common after running `lorekit install` once with --project and
+  // once with --global (or via the marketplace plugin on top of a CLI install).
+  const dupeEvents = detectDuplicateHooks(root);
+  if (dupeEvents.length > 0) {
+    record(
+      'warn',
+      'hooks duplicate',
+      `${dupeEvents.join(', ')} registered in BOTH project and global settings — ` +
+        `Claude Code fires them twice. Remove one scope: ` +
+        `run \`lorekit uninstall --project\` or \`lorekit uninstall --global\`.`,
+    );
+  }
+
   // 3. Resolved control model — which mode, and who decided it.
   const control = loadControl(root, { env: withOverrides(args) });
   record('info', 'memory mode', `${control.mode}  ${c.dim('— decided by ' + control.decidedBy)}`);
@@ -290,6 +309,48 @@ async function deepCheckLocal(store, scope, record) {
   await store.delete({ scope: writeScope, key, force: true });
 }
 
+// Returns the list of CLAUDE_HOOK_EVENTS whose lorekit hook command appears in
+// BOTH the project settings file (.claude/settings.json) and the global one
+// (~/.claude/settings.json). An empty array means no duplicates — healthy.
+function detectDuplicateHooks(root) {
+  const dupes = [];
+  const projectFile = settingsPath(root, 'project');
+  const globalFile = settingsPath(root, 'global');
+
+  let projectHooks = {};
+  let globalHooks = {};
+  try {
+    const cfg = JSON.parse(fs.readFileSync(projectFile, 'utf8'));
+    if (cfg && typeof cfg.hooks === 'object') projectHooks = cfg.hooks;
+  } catch { /* absent or unparseable — treat as empty */ }
+  try {
+    const cfg = JSON.parse(fs.readFileSync(globalFile, 'utf8'));
+    if (cfg && typeof cfg.hooks === 'object') globalHooks = cfg.hooks;
+  } catch { /* absent or unparseable — treat as empty */ }
+
+  for (const event of CLAUDE_HOOK_EVENTS) {
+    const hasInProject = hooksForEvent(projectHooks, event).some((cmd) => LOREKIT_HOOK_RE.test(cmd));
+    const hasInGlobal = hooksForEvent(globalHooks, event).some((cmd) => LOREKIT_HOOK_RE.test(cmd));
+    if (hasInProject && hasInGlobal) dupes.push(event);
+  }
+  return dupes;
+}
+
+// Extract the flat list of hook command strings for one event from a hooks
+// object. Handles the nested-group shape Claude Code uses:
+// { [event]: [ { hooks: [ { type, command } ] } ] }
+function hooksForEvent(hooksObj, event) {
+  const groups = Array.isArray(hooksObj[event]) ? hooksObj[event] : [];
+  const commands = [];
+  for (const group of groups) {
+    const inner = group && Array.isArray(group.hooks) ? group.hooks : [];
+    for (const h of inner) {
+      if (h && typeof h.command === 'string') commands.push(h.command);
+    }
+  }
+  return commands;
+}
+
 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/hook.mjs

@@ -15,6 +15,7 @@ import {
   failureQuery,
   relevantLessons,
   formatRelevantLessons,
+  writeConfirmation,
 } from './core/lessons.mjs';
 import { isFailure } from './core/failure.mjs';
 import { firstTimeThisSession } from './core/state.mjs';
@@ -109,6 +110,26 @@ async function run(args) {
     return 0;
   }
 
+  if (intent === 'confirm') {
+    // Fire only when a lorekit memory write actually succeeded — the adapter's
+    // isLoreWrite() inspects the tool name and the response shape. Any error
+    // is swallowed (exit 0 — never block the host).
+    try {
+      if (adapter.isLoreWrite && adapter.isLoreWrite(parsed.toolName, parsed.toolResponse)) {
+        // The lesson key comes from the tool INPUT (what the agent sent), not
+        // the response (which only carries id + created_at). toolInput is
+        // populated by the adapter's parse() from the raw hook stdin.
+        const key = (parsed.toolInput && typeof parsed.toolInput.key === 'string')
+          ? parsed.toolInput.key
+          : null;
+        emit(writeConfirmation(scope, key));
+      }
+    } catch {
+      // best-effort — never break the host
+    }
+    return 0;
+  }
+
   if (intent === 'failure') {
     const known = adapter.guaranteedFailure ? adapter.guaranteedFailure(event) : false;
     if (!known && !isFailure(parsed.toolName, parsed.toolResponse)) return 0;

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