@lanes-sh/link 0.1.0

package/src/cli/commands/operate/outputs.ts

@@ -0,0 +1,206 @@
+import { listProfiles } from '#profile';
+import { fileURLToPath } from 'node:url';
+import { deployedUrl, endpointUrl } from '../../endpoint-url.ts';
+import { announce, heading, print, style, warn } from '../../output.ts';
+import { ensureProfileToken, openRuntime, type GlobalFlags } from '../../runtime.ts';
+
+export interface OutputsFlags extends GlobalFlags {
+  readonly show?: boolean | undefined;
+  readonly json?: boolean | undefined;
+}
+
+interface Health {
+  readonly profile: string;
+  readonly profiles: readonly string[];
+}
+
+/**
+ * What an agent harness needs to reach this endpoint.
+ *
+ * The unit here is the **endpoint**, not the profile. One `lanes link start`
+ * serves every profile in the workspace from one URL under one token, so
+ * printing a registration per profile — which this did while the ports were
+ * per profile — now emits commands that authenticate against tokens the server
+ * does not accept.
+ *
+ * Deliberately not a registration command that runs: nothing here writes to any
+ * agent's config file, because which file that is, and what belongs in it, is
+ * the harness's business.
+ */
+export async function outputs(flags: OutputsFlags): Promise<void> {
+  const runtime = await openRuntime(flags);
+
+  try {
+    const { token } = await ensureProfileToken(runtime.credentials, runtime.config.auth.token_ref);
+    const declared = runtime.config.targets[runtime.target]?.deploy;
+    const deployed = await deployedUrl(declared);
+    const url = deployed ?? (await endpointUrl(runtime.config, runtime.target));
+
+    const live = await health(url, token);
+    const mine = live?.profile === runtime.resolution.profile;
+
+    // Live if it is up, otherwise what `start` would serve: the whole
+    // workspace, since `--only` is the exception rather than the default.
+    const profiles = mine
+      ? live.profiles
+      : await listProfiles(runtime.resolution.workspaceRoot);
+
+    if (flags.json) {
+      print(
+        JSON.stringify(
+          {
+            url,
+            running: mine,
+            deployed: deployed !== null,
+            target: runtime.target,
+            primary: runtime.resolution.profile,
+            profiles,
+            ...(flags.show ? { token } : {}),
+          },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
+    announce(runtime.resolution);
+
+    heading('Endpoint');
+    print(
+      `  ${url}  ${mine ? style.green(deployed ? 'deployed' : 'running') : style.dim(deployed ? 'not answering' : 'not running')}`,
+    );
+    if (deployed && declared) {
+      // The URL is the platform's, not the configured host and port: those
+      // govern where `lanes link start` listens locally and mean nothing to a
+      // deployed revision, which listens on whatever $PORT it was given.
+      print(style.dim(`  ${declared.platform} service "${declared.service}" for target "${runtime.target}".`));
+    }
+
+    if (live && !mine) {
+      // Two workspaces can assign the same port. Saying so beats reporting an
+      // endpoint as up when it belongs to something else entirely.
+      print(warn(`something else is serving this port: profile "${live.profile}"`));
+    }
+
+    heading(`Profiles reachable through it (${profiles.length})`);
+    for (const profile of profiles) {
+      print(`  ${profile}${profile === runtime.resolution.profile ? style.dim('  (endpoint owner)') : ''}`);
+    }
+    print(style.dim('  Each call names one, in its `profile` argument.'));
+
+    if (flags.show) {
+      heading('Token');
+      print(`  ${token}`);
+    }
+
+    heading('Register with your agent');
+    print(
+      style.dim(
+        '  Not run for you: which config file an agent reads is its business, not ours.',
+      ),
+    );
+    print('');
+
+    const invocation = await tokenInvocation(runtime.config.auth.token_ref, token, flags.profile);
+
+    print(
+      `  claude mcp add --transport http lanes-link ${url} \\\n` +
+        `    --header "Authorization: Bearer $(${invocation.command})"`,
+    );
+    print('');
+
+    if (!invocation.onPath) {
+      // The failure this prevents is nasty: an unresolvable command substitutes
+      // to the empty string, the header becomes "Bearer ", and the only symptom
+      // is a 401 that looks like a bad token rather than a missing binary.
+      print(warn('lanes is not on your PATH, so the short form would substitute to nothing.'));
+      print(style.dim('  The command above uses this checkout instead. To shorten it permanently:'));
+      print(`      cd ${process.cwd()} && bun link`);
+      print('');
+    }
+
+    print(
+      style.dim(
+        '  One registration covers every profile above. The $(…) keeps the token out of your\n' +
+          '  agent\'s context and out of the transcript — but note it is resolved once, when you\n' +
+          '  run the command, and stored as a literal. After "lanes link token rotate" you have to\n' +
+          '  register again. Other harnesses take the same two facts — URL and bearer token.',
+      ),
+    );
+  } finally {
+    await runtime.close();
+  }
+}
+
+/**
+ * The command that prints this endpoint's token, verified to actually work.
+ *
+ * `$(lanes link token show --raw)` is the right shape, and useless if `lanes`
+ * does not resolve: the substitution yields an empty string, the header becomes
+ * `Bearer `, and the endpoint answers 401 — which reads as a bad token rather
+ * than a missing binary. So the short form is offered only after running it and
+ * checking it returns *this* token; otherwise the printed command names this
+ * checkout, which always works.
+ */
+async function tokenInvocation(
+  tokenRef: string,
+  expected: string,
+  profile: string | undefined,
+): Promise<{ command: string; onPath: boolean }> {
+  const suffix = profile ? ` --profile ${profile}` : '';
+  const short = `lanes link token show --raw${suffix}`;
+
+  const resolved = Bun.which('lanes');
+  if (resolved) {
+    try {
+      const result = Bun.spawnSync([resolved, 'link', 'token', 'show', '--raw', ...(profile ? ['--profile', profile] : [])]);
+      // Compared against the token rather than merely checking it exited zero:
+      // a `lanes` on PATH could belong to a different workspace entirely,
+      // and would hand the harness a token this endpoint rejects.
+      if (result.success && new TextDecoder().decode(result.stdout).trim() === expected) {
+        return { command: short, onPath: true };
+      }
+    } catch {
+      // Falls through to the checkout-relative form.
+    }
+  }
+
+  // `lanes.ts`, not `main.ts`: main.ts exports `run` and no longer executes on
+  // import, so `bun run main.ts token show --raw` prints nothing and exits 0 —
+  // which is the empty-token failure this whole function exists to avoid,
+  // reintroduced by the fallback meant to prevent it.
+  const entry = fileURLToPath(new URL('../../lanes.ts', import.meta.url));
+  return { command: `bun run ${entry} link token show --raw${suffix}`, onPath: false };
+}
+
+/**
+ * Ask the endpoint who it is.
+ *
+ * The profile name is checked by the caller, not just the port: two workspaces
+ * can assign the same port, and reporting "running" because something
+ * unrelated answers would send someone to register an endpoint serving another
+ * workspace's accounts.
+ *
+ * The token is sent because `/health` names profiles only to a caller that
+ * holds one. Anonymously it answers `{status: "ok"}` and nothing else — that
+ * list is what this endpoint holds, and a deployed URL is readable by anyone.
+ * An endpoint that answers without naming itself is therefore reported as
+ * something else's, which is the honest reading: this token does not open it.
+ */
+async function health(url: string, token: string): Promise<Health | null> {
+  try {
+    const probe = new URL(url);
+    probe.pathname = '/health';
+    const response = await fetch(probe, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(700),
+    });
+    if (!response.ok) return null;
+
+    const body = (await response.json()) as Partial<Health>;
+    return body.profile ? { profile: body.profile, profiles: body.profiles ?? [body.profile] } : null;
+  } catch {
+    return null;
+  }
+}

package/src/cli/commands/operate/policy.ts

@@ -0,0 +1,80 @@
+import { loadConfigFile } from '#profile';
+import { ConfigDocument } from '../../config-edit.ts';
+import { announce, heading, ok, print, style, table } from '../../output.ts';
+import { resolveProfile, type GlobalFlags } from '../../runtime.ts';
+import { nextAfterEdit, publishProfileEdit } from '../../publish.ts';
+
+/**
+ * `lanes link policy` and `lanes link config show` — reading and editing what is granted.
+ *
+ * Both are control-plane operations under ADR-007: a policy change authorises
+ * future agent behaviour, so it originates here and never over MCP.
+ */
+
+export async function policyList(flags: GlobalFlags): Promise<void> {
+  const { resolution, config } = await resolveProfile(flags);
+  announce(resolution);
+
+  if (config.policy.allow.length === 0 && config.policy.deny.length === 0) {
+    print(style.dim('No rules. Default deny is in effect: nothing is reachable.'));
+    return;
+  }
+
+  const expiry = (rule: { capability: string; expires_at?: string | undefined }) =>
+    rule.expires_at ? style.dim(`until ${rule.expires_at}`) : '';
+
+  if (config.policy.allow.length > 0) {
+    heading('Allow');
+    table(config.policy.allow.map((rule) => [`  ${style.green('+')}`, rule.capability, expiry(rule)]));
+  }
+
+  if (config.policy.deny.length > 0) {
+    heading('Deny');
+    print(style.dim('  A deny beats any allow, whatever the order in the file.'));
+    table(config.policy.deny.map((rule) => [`  ${style.red('-')}`, rule.capability, expiry(rule)]));
+  }
+
+  print('');
+  print(
+    style.dim('Rules cover every account of a provider. For different grants, use a second profile.'),
+  );
+}
+
+export async function policyRule(
+  effect: 'allow' | 'deny',
+  capability: string,
+  flags: GlobalFlags,
+): Promise<void> {
+  const { resolution, config, target } = await resolveProfile(flags);
+  const document = await ConfigDocument.open(resolution.workspaceRoot, resolution.profile);
+
+  if (config.policy[effect].some((rule) => rule.capability === capability)) {
+    print(style.dim(`${effect} ${capability} is already declared.`));
+    return;
+  }
+
+  // A bare string, because that is what the file should read like. The object
+  // form exists for `expires_at` and is not worth writing by default.
+  document.addTo(['policy', effect], capability, { inline: true });
+  // Validation runs before the write, so a rule naming a provider with no
+  // connection fails here rather than silently granting nothing at runtime.
+  await document.save();
+
+  announce(resolution);
+  print(ok(`${effect} ${style.bold(capability)}`));
+
+  if (effect === 'deny' && config.policy.allow.some((rule) => rule.capability === '*')) {
+    print(style.dim('  This narrows the catch-all allow; a deny always wins.'));
+  }
+
+  // A deny the endpoint has not heard about is still granting what it names, so
+  // a policy edit publishes itself exactly as connecting does (ADR-029).
+  print(style.dim(`  ${nextAfterEdit(await publishProfileEdit({ resolution, config, target }))}`));
+}
+
+export async function configShow(flags: GlobalFlags): Promise<void> {
+  const { resolution } = await resolveProfile(flags);
+  announce(resolution);
+  const { config } = await loadConfigFile(resolution.profilePath);
+  print(JSON.stringify(config, null, 2));
+}

package/src/cli/commands/operate/serve.ts

@@ -0,0 +1,55 @@
+import { startEndpoint } from '#server/endpoint.ts';
+import { streamLogger } from '#server/logging.ts';
+import { announce, ok, print, style, warn } from '../../output.ts';
+import { resolveProfile, type GlobalFlags } from '../../runtime.ts';
+
+/** `lanes link start` — reconcile, then serve every profile on one endpoint. */
+
+export async function start(
+  flags: GlobalFlags & {
+    port?: number | undefined;
+    /** `--only` serves just the resolved profile, rather than the whole workspace. */
+    only?: boolean | undefined;
+  },
+): Promise<void> {
+  const { resolution } = await resolveProfile(flags);
+  announce(resolution);
+
+  // The bootstrap itself lives in `endpoint.ts`, shared with the container
+  // entrypoint. What stays here is what a terminal wants: the plan, printed as
+  // it is applied, and the endpoint at the end.
+  const endpoint = await startEndpoint({
+    flags,
+    port: flags.port,
+    only: flags.only,
+    mintToken: true,
+    // Stderr, not stdout: `--json` and `--raw` callers parse the other stream.
+    // A refused credential is the event worth seeing while this runs in the
+    // foreground, and until now nothing printed it.
+    log: streamLogger((line) => process.stderr.write(`${line}\n`)),
+    reporter: {
+      reconciled({ profile, plan, ofMany }) {
+        if (ofMany) print(style.dim(`  ${profile}`));
+        print(plan);
+        print(ok(`reconciled ${ofMany ? profile : ''}`.trim()));
+      },
+      tokenMinted({ target }) {
+        print(warn(`minted a token — run: lanes link outputs --show --target ${target}`));
+      },
+    },
+  });
+
+  print(ok(`serving ${style.bold(endpoint.url)}`));
+  print(style.dim(`      profiles: ${endpoint.profiles.join(', ')}`));
+  print(style.dim('Ctrl-C to stop.'));
+
+  const shutdown = async (): Promise<void> => {
+    await endpoint.stop();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', () => void shutdown());
+  process.on('SIGTERM', () => void shutdown());
+
+  await new Promise(() => {});
+}

package/src/cli/commands/operate/status.ts

@@ -0,0 +1,133 @@
+import { listProfiles } from '#profile';
+import { oneProfile, visibleCapabilities } from '#server/mcp';
+import { toPolicyDocument } from '#registry';
+import { announce, emit, heading, print, style, table } from '../../output.ts';
+import { openRuntime, ownerPrincipal, type GlobalFlags } from '../../runtime.ts';
+import { deploymentIdentity } from '../../endpoint-url.ts';
+
+/** `lanes link status` — connections, what is reachable through them, and where. */
+
+export interface StatusFlags extends GlobalFlags {
+  readonly json?: boolean | undefined;
+}
+
+/**
+ * Deliberately no `running` field, unlike `outputs`.
+ *
+ * `status` answers from config, the database, and policy — no network call. A
+ * health probe would make the command that tells you what is configured depend
+ * on something being up, and `outputs --json` already reports liveness.
+ *
+ * Which is why a deployed target prints its *identity* rather than its address.
+ * This used to print `http://<host>:<port>/mcp` unconditionally, so
+ * `status --target cloud` named a loopback port with nothing behind it — the
+ * bug `endpoint-url.ts` records having already fixed in `mcp add`. Reaching for
+ * `endpointUrl` here would fix the lie by surrendering the property above: it
+ * shells out to `gcloud`, costs seconds, needs the CLI installed and
+ * authenticated, and swallows every failure back into loopback — so on a fresh
+ * machine or in CI it would print the same wrong answer, more slowly.
+ *
+ * A deployment's address is the platform's to assign and `outputs --target` is
+ * the command that asks. Which service it is, though, is in the config, and a
+ * config-only command can say that much honestly.
+ */
+export async function status(flags: StatusFlags): Promise<void> {
+  const runtime = await openRuntime(flags);
+  try {
+    const records = await runtime.state.connections.list();
+    const byKey = new Map(records.map((record) => [`${record.provider}.${record.id}`, record]));
+
+    const connections = runtime.config.connections.map((connection) => {
+      const key = `${connection.provider}.${connection.id}`;
+      return {
+        key,
+        provider: connection.provider,
+        id: connection.id,
+        account: connection.account,
+        state: byKey.get(key)?.status ?? 'not reconciled',
+      };
+    });
+
+    const capabilities = visibleCapabilities({
+      profiles: oneProfile(runtime.resolution.profile, {
+        config: runtime.config,
+        registry: runtime.registry,
+        dispatcher: runtime.dispatcher,
+        policy: toPolicyDocument(runtime.config),
+      }),
+      principal: ownerPrincipal(runtime.config.instance.profile),
+    });
+
+    // What is registered but has no connection yet — the other half of "what is
+    // set up", and the half an agent needs to answer "what else could I use?".
+    const connected = new Set(connections.map((connection) => connection.provider));
+    const notConnected = runtime.registry
+      .list()
+      .map((entry) => entry.manifest.id)
+      .filter((id) => !connected.has(id))
+      .sort();
+
+    // Null rather than a different shape: `endpoint` stays a string-or-null so a
+    // consumer that reads it keeps working, and `deployment` carries what
+    // replaces it. Silently turning a string into an object would be a cost
+    // paid by every reader for the benefit of none.
+    const local = `http://${runtime.config.instance.host}:${runtime.config.instance.port}/mcp`;
+    const deployment = deploymentIdentity(runtime.config.targets[runtime.target]?.deploy);
+    const endpoint = deployment ? null : local;
+
+    return emit(
+      flags.json,
+      {
+        profile: runtime.resolution.profile,
+        profiles: await listProfiles(runtime.resolution.workspaceRoot),
+        target: runtime.target,
+        endpoint,
+        deployment,
+        connections,
+        capabilities,
+        notConnected,
+      },
+      () => {
+        announce(runtime.resolution);
+
+        heading('Connections');
+        if (connections.length === 0) {
+          print(style.dim('  none — run: lanes link connect example'));
+        } else {
+          table(
+            connections.map((connection) => [
+              `  ${style.bold(connection.key)}`,
+              connection.state === 'active'
+                ? style.green(connection.state)
+                : style.yellow(connection.state),
+              style.dim(connection.account),
+            ]),
+          );
+        }
+
+        heading('Reachable capabilities');
+        if (capabilities.length === 0) {
+          print(style.dim('  none — default deny is in effect and nothing is granted'));
+        } else {
+          for (const capability of capabilities) print(`  ${capability}`);
+        }
+
+        heading('Endpoint');
+        if (!deployment) {
+          print(`  ${local}  ${style.dim('(when running)')}`);
+        } else {
+          const { platform, service, region } = deployment;
+          print(`  ${platform} service ${style.bold(service)} in ${region}`);
+          print(
+            style.dim(
+              '  the address is the platform\'s to assign — run: ' +
+                `lanes link outputs --target ${runtime.target}`,
+            ),
+          );
+        }
+      },
+    );
+  } finally {
+    await runtime.close();
+  }
+}

package/src/cli/commands/operate/token.ts

@@ -0,0 +1,70 @@
+import { announce, ok, print, style, warn } from '../../output.ts';
+import { ensureProfileToken, openRuntime, type GlobalFlags } from '../../runtime.ts';
+
+/** `lanes link token` — the one bearer token this endpoint accepts. */
+
+/** The token, or enough of it to recognise. One shape, so the two commands agree. */
+function show(token: string, reveal: boolean | undefined): string {
+  return reveal ? token : `${token.slice(0, 8)}…  ${style.dim('(--show to reveal)')}`;
+}
+
+export async function tokenShow(
+  flags: GlobalFlags & { show?: boolean | undefined; raw?: boolean | undefined },
+): Promise<void> {
+  const runtime = await openRuntime(flags);
+  try {
+    const { token, created } = await ensureProfileToken(
+      runtime.credentials,
+      runtime.config.auth.token_ref,
+    );
+
+    // `--raw` prints the token and nothing else, for command substitution:
+    //
+    //   claude mcp add … --header "Authorization: Bearer $(lanes link token show --raw)"
+    //
+    // That is the recommended way to register an instance, and the reason is
+    // not convenience. A token pasted from `--show` passes through the agent's
+    // context and into its transcript; substituted by the shell it goes from
+    // this process to the harness and is never seen by the model at all.
+    if (flags.raw) {
+      process.stdout.write(`${token}\n`);
+      return;
+    }
+
+    announce(runtime.resolution);
+    if (created) print(warn('no token existed; a new one was minted'));
+    print(show(token, flags.show));
+  } finally {
+    await runtime.close();
+  }
+}
+
+export async function tokenRotate(
+  flags: GlobalFlags & { show?: boolean | undefined },
+): Promise<void> {
+  const runtime = await openRuntime(flags);
+  try {
+    announce(runtime.resolution);
+
+    const { generateProfileToken } = await import('#auth');
+    const token = generateProfileToken();
+    await runtime.credentials.set(runtime.config.auth.token_ref, token);
+
+    print(ok('token rotated'));
+    // Gated the way `tokenShow` gates it, and for the reason given above: a
+    // token printed here goes into the transcript of whatever ran the command.
+    // Rotating is what an operator does *because* a token leaked, so printing
+    // the replacement unasked is the one moment it costs the most.
+    print(`  ${show(token, flags.show)}`);
+    print();
+    // Rotating invalidates every agent using this endpoint, which is the cost
+    // of one token per endpoint rather than one per agent. Say so plainly —
+    // and say how, because `claude mcp add` stores the substituted value rather
+    // than the command, so nothing re-reads this on its own.
+    print(warn('every agent configured with the old token must be re-registered'));
+    print(style.dim('  A harness stores the token it was given, not the command that produced it.'));
+    print(style.dim('  Run: lanes link outputs   for the command to re-run.'));
+  } finally {
+    await runtime.close();
+  }
+}

package/src/cli/commands/operate.ts

@@ -0,0 +1,27 @@
+/**
+ * Running an instance and looking at it — everything that is neither
+ * `connect` nor the owner layer.
+ *
+ * Seven files, one per verb group, because every private helper here served
+ * exactly one command and nothing crossed between them:
+ *
+ *   inspect.ts   check, plan, doctor — the gate order, cheapest failure first
+ *   status.ts    connections, reachable capabilities, endpoint
+ *   outputs.ts   what an agent harness needs, and proving the short form works
+ *   serve.ts     start
+ *   audit.ts     audit tail and verify, and the Markdown rendering of tail
+ *   token.ts     token show, token rotate
+ *   policy.ts    policy list/allow/deny, config show
+ *
+ * This file stays a barrel because `./operate.ts` is the spelling `main.ts` and
+ * `operate.test.ts` bind, and Bun will not resolve that to `operate/index.ts`.
+ */
+
+export { check, doctor, plan } from './operate/inspect.ts';
+export { status } from './operate/status.ts';
+export { outputs, type OutputsFlags } from './operate/outputs.ts';
+export { start } from './operate/serve.ts';
+export { auditTail, auditVerify, markdownCell } from './operate/audit.ts';
+export { attachFile } from './operate/attach.ts';
+export { tokenRotate, tokenShow } from './operate/token.ts';
+export { configShow, policyList, policyRule } from './operate/policy.ts';

package/src/cli/commands/owner/memory.ts

@@ -0,0 +1,110 @@
+import { ConfigError } from '#profile';
+import { scopeNamespace } from '#dispatch';
+import { scopeBlobStore, type BlobStore } from '#stores/blobs';
+import { memoryStorage } from '#providers/owner.ts';
+import { heading, ok, print, style, table } from '../../output.ts';
+import type { Runtime } from '../../runtime.ts';
+import {
+  agreed,
+  ownerConnection,
+  readStdin,
+  required,
+  withRuntime,
+  type OwnerFlags,
+} from './shared.ts';
+
+/** `lanes link memory` — the owner's persistent, accumulated knowledge. */
+
+export async function memoryList(flags: OwnerFlags): Promise<void> {
+  await withRuntime(flags, async (runtime) => {
+    const store = memoryStore(runtime, flags);
+    const entries = (await memoryStorage.all(store)).filter(
+      (entry) => !flags.tag || entry.tags.includes(flags.tag),
+    );
+
+    heading(`Memory (${entries.length})`);
+    if (entries.length === 0) {
+      print(style.dim('  none — write one with: lanes link memory write <id> --title <title>'));
+      return;
+    }
+
+    table(
+      entries.map((entry) => [
+        `  ${entry.id}`,
+        entry.title,
+        entry.tags.length > 0 ? style.dim(entry.tags.join(', ')) : '',
+        style.dim(entry.updatedAt.slice(0, 10)),
+      ]),
+    );
+  });
+}
+
+export async function memoryGet(id: string | undefined, flags: OwnerFlags): Promise<void> {
+  const entryId = required(id, 'lanes link memory get <id>');
+
+  await withRuntime(flags, async (runtime) => {
+    const entry = await memoryStorage.read(memoryStore(runtime, flags), entryId);
+    if (!entry) throw new ConfigError(`No memory entry "${entryId}" in this profile.`);
+
+    print('');
+    print(entry.body);
+  });
+}
+
+export async function memoryWrite(id: string | undefined, flags: OwnerFlags): Promise<void> {
+  const given = required(id, 'lanes link memory write <id> --title <title>   (body on stdin)');
+  const text = await readStdin(
+    `lanes link memory write ${given} --title "<title>"`,
+    'the entry body',
+  );
+
+  await withRuntime(flags, async (runtime) => {
+    const store = memoryStore(runtime, flags);
+    const existing = await memoryStorage.read(store, given);
+
+    // The title is what a listing and a search show, so it is worth keeping
+    // when a rewrite does not supply one — losing it silently would leave an
+    // entry titled after its own id for no reason the owner asked for.
+    const title = flags.title ?? existing?.title ?? given;
+    const document = memoryStorage.serialise({
+      title,
+      tags: flags.tag ? [flags.tag] : (existing?.tags ?? []),
+      updatedAt: new Date().toISOString(),
+      body: text,
+    });
+
+    await store.put(memoryStorage.key(given), new TextEncoder().encode(document), {
+      contentType: 'text/markdown',
+    });
+
+    print(ok(`${existing ? 'replaced' : 'wrote'} memory entry ${style.bold(given)}`));
+  });
+}
+
+export async function memoryForget(id: string | undefined, flags: OwnerFlags): Promise<void> {
+  const entryId = required(id, 'lanes link memory forget <id>');
+
+  await withRuntime(flags, async (runtime) => {
+    const store = memoryStore(runtime, flags);
+    const entry = await memoryStorage.read(store, entryId);
+    if (!entry) throw new ConfigError(`No memory entry "${entryId}" in this profile.`);
+
+    print(`  ${style.bold(entry.id)}  ${entry.title}`);
+    if (!(await agreed(flags, 'Forget this entry?'))) return;
+
+    await store.delete(memoryStorage.key(entryId));
+    print(ok(`forgot memory entry ${style.bold(entryId)}`));
+  });
+}
+
+/**
+ * The blob namespace core would scope this provider to.
+ *
+ * Built here from `scopeNamespace` and `scopeBlobStore` — the same two
+ * functions `buildProviderContext` uses — rather than from a path spelled out
+ * again, so the CLI cannot address a different directory from the provider.
+ */
+export function memoryStore(runtime: Runtime, flags: OwnerFlags): BlobStore {
+  const connection = ownerConnection(runtime.config, 'memory', flags);
+  return scopeBlobStore(runtime.storage, scopeNamespace('memory', connection));
+}