${adapter.displayName}: guideline not written (${gerr instan

Error message

${adapter.displayName}: guideline not written (${gerr instanceof Error ? gerr.message : String(gerr)})

What it means

During `agentmemory connect`, runAdapter writes per-agent guideline files that teach the agent to use memory automatically. If an individual guideline write fails (filesystem permission, missing directory, path conflict), it catches the error and logs '<adapter>: guideline not written (<reason>)' via p.log.warn, continuing with the rest of the adapter setup instead of aborting.

Source

Thrown at src/cli/connect/index.ts:122

    // effort: never fail the connect over the guideline.
    if (
      opts.guidelines !== false &&
      (result.kind === "installed" || result.kind === "already-wired")
    ) {
      try {
        const g = writeGuideline(adapter.name, {
          cwd: process.cwd(),
          dryRun: opts.dryRun,
        });
        if (g.kind === "written") {
          p.log.message(
            `  ${pc.dim("guideline")} ${g.scope} → ${g.path} (memory auto-use)`,
          );
        } else if (g.kind === "would-write") {
          p.log.message(`  ${pc.dim("[dry-run] guideline")} → ${g.path}`);
        }
      } catch (gerr) {
        p.log.warn(
          `${adapter.displayName}: guideline not written (${gerr instanceof Error ? gerr.message : String(gerr)})`,
        );
      }
    }
    return result;
  } catch (err) {
    p.log.error(
      `${adapter.displayName}: ${err instanceof Error ? err.message : String(err)}`,
    );
    return { kind: "skipped", reason: "exception" };
  }
}

export async function runConnect(args: string[]): Promise<void> {
  const { dryRun, force, all, withHooks, guidelines, positional } =
    parseFlags(args);
  const allowWindowsAdapter =
    positional.length === 1 && positional[0]?.toLowerCase() === "copilot-cli";

View on GitHub (pinned to e04ba88819)

Solutions

Read the parenthesized reason and fix the filesystem issue: check permissions with ls -la <guideline-path> and chown/chmod as needed.
Create the missing parent directory before re-running connect.
Re-run `agentmemory connect` after fixing so the guideline step retries.
If the path is intentionally protected, skip that adapter's guideline or run connect from a writable checkout.

Example fix

// before: read-only skills dir
// Claude Code: guideline not written (EACCES: permission denied, open '.../skills/...')
// after
chmod u+w ~/.claude/skills && npx agentmemory connect

Defensive patterns

Strategy: try-catch

Validate before calling

import { accessSync, constants } from "node:fs";
try { accessSync(guidelineDir, constants.W_OK); }
catch { console.error(`cannot write guideline dir ${guidelineDir}`); }

Try / catch

try {
  await writeGuideline(g);
} catch (gerr) {
  console.warn(`guideline not written: ${gerr instanceof Error ? gerr.message : String(gerr)}`);
  // continue — remaining guidelines/adapter steps still run
}

Prevention

Run connect from a writable checkout/user.
Pre-create guideline parent directories with correct ownership.
Avoid running under restrictive sandboxes/CI users without write access to config dirs.
Re-run connect after fixing permissions so the skipped guideline is retried.

When it happens

Trigger: The adapter's guideline install step throws for one g: read-only target path, nonexistent parent directory, permission denied, or an adapter-specific dry-run/plan error surfaced as an exception.

Common situations: Running connect in a sandboxed/CI directory where the guideline path (e.g. AGENTS.md or skill folders) is not writable; path already exists as a directory; running without the repo checked out at the expected location.

Related errors

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/93530e09a559b173. Report an issue: GitHub.