Agent Instructions

MCP config alone tells the agent that memctl exists. Agent instruction files tell it how and when to use it. Without instructions, agents may ignore memctl after the first prompt or use it inconsistently.

There are three layers of reinforcement, from weakest to strongest:

1. Instruction files (CLAUDE.md, AGENTS.md, .cursorrules) - loaded at session start, can get lost during context compaction
2. Per-turn hooks (UserPromptSubmit) - inject a short reminder into every single turn, survives compaction
3. Compaction hooks (SessionStart with compact matcher) - re-inject full instructions after context window fills up

For Claude Code, use all three. For agents without hooks (Codex, Cursor, Windsurf), instruction files are your only option, so make them explicit and imperative.

How it works

Quick setup

The fastest way to set up both MCP config and agent instructions:

npx memctl auth
npx memctl init --all

The init wizard writes MCP configs for all supported agents and creates AGENTS.md with memctl usage instructions.

To also generate agent-specific instruction files from your stored context:

npx memctl generate --all

This writes AGENTS.md, CLAUDE.md, .claude/rules/memctl.md, GEMINI.md, .cursorrules, .cursor/rules/memctl.mdc, .github/copilot-instructions.md, .windsurf/rules/memctl.md, .clinerules/memctl.md, .roo/rules/memctl.md, codex.md, and .amazonq/rules/memctl.md. Files that support YAML frontmatter (Windsurf, Cursor rules, Copilot) get tool-native activation metadata prepended automatically.

Use --link to symlink compatible files to AGENTS.md so they stay in sync:

npx memctl generate --all --link

What goes in the instruction file

The default AGENTS.md template covers the full memctl workflow:

1. Session start - bootstrap context, start session, read memos
2. Before coding - load coding style, architecture, constraints for relevant files
3. While coding - store decisions, update branch plans
4. Session end - leave memos, end session with summary
5. Maintenance - periodic cleanup of stale memories

See the full template at AGENTS.md template.

Per-agent setup

Claude Code

Claude Code loads CLAUDE.md and AGENTS.md at session start, but these instructions can get lost during long sessions when context compaction kicks in. The solution is hooks.

Recommended setup (MCP + instructions + hooks):

npx memctl init --claude
npx memctl generate --claude --link

Then install the memctl plugin for automatic per-turn reminders:

/plugin marketplace add memctl/memctl
/plugin install memctl@memctl

The plugin adds three hooks:

• SessionStart - bootstraps memctl context, re-injects after compaction
• UserPromptSubmit - injects a short memctl reminder into every turn via additionalContext
• Stop - captures assistant responses for session history

Without the plugin, you can set up hooks manually:

npx memctl hook-adapter --agent claude --write

Then copy .memctl/hooks/claude.settings.local.json.example into .claude/settings.local.json.

Why hooks matter: CLAUDE.md loads once at session start. During long sessions, context compaction summarizes the conversation and can lose early instructions. The UserPromptSubmit hook injects a short reminder on every turn, so Claude never forgets about memctl. The SessionStart hook with compact matcher re-injects full instructions after every compaction.

Codex

Codex reads AGENTS.md and codex.md once per run (not every turn) and has no hook system. This means your only chance to tell Codex about memctl is the instruction file. Make it explicit and imperative.

npx memctl init --codex
npx memctl generate --codex

This creates .codex/config.toml (MCP config in TOML format), AGENTS.md (default instructions), and codex.md (Codex-specific instructions).

The .codex/config.toml format:

[mcp_servers.memctl]
command = "npx"
args = ["-y", "memctl@latest"]

[mcp_servers.memctl.env]
MEMCTL_ORG = "your-org"
MEMCTL_PROJECT = "your-project"

Limitations: Since Codex loads instructions once and has no hooks, it may stop using memctl during long sessions. The default AGENTS.md template uses strong imperative language ("You MUST", "ALWAYS", "NEVER skip") to maximize compliance. If Codex still drops off, add a manual reminder in your prompt: "Use the memctl tools to check context before making changes."

Tip: If your AGENTS.md exceeds 32 KiB, Codex truncates it. Increase the limit in .codex/config.toml:

project_doc_max_bytes = 65536

Cursor

Cursor reads .cursorrules (legacy) and .cursor/rules/*.mdc (modern) from the project. MCP config goes in .cursor/mcp.json.

npx memctl init --cursor
npx memctl generate --cursor-rule

The --cursor-rule flag writes .cursor/rules/memctl.mdc with YAML frontmatter (alwaysApply: true) so Cursor loads it on every turn. The legacy --cursor flag still writes .cursorrules in the old format.

VS Code + GitHub Copilot

Copilot reads .github/copilot-instructions.md. MCP config goes in .vscode/mcp.json.

npx memctl init --vscode
npx memctl generate --copilot --link

Windsurf

Windsurf reads .windsurf/rules/*.md from the project. MCP config is global at ~/.codeium/windsurf/mcp_config.json.

npx memctl init --windsurf
npx memctl generate --windsurf

The --windsurf flag writes .windsurf/rules/memctl.md with YAML frontmatter (trigger: always_on) so Windsurf loads it automatically.

Cline

Cline reads .clinerules/ directory from the project root. MCP config is set through the extension UI (see Agent Setup).

npx memctl generate --cline --link

The --cline flag writes .clinerules/memctl.md. There is no memctl init --cline because Cline's MCP config lives in VS Code extension storage, which varies by OS. Configure it manually through the Cline sidebar.

Roo Code

Roo reads rules from .roo/rules/. MCP config goes in .roo/mcp.json.

npx memctl init --roo
npx memctl generate --roo --link

With --link, .roo/rules/memctl.md is symlinked to AGENTS.md.

Continue

Continue reads rules from .continue/rules/. MCP config uses YAML format in .continue/config.yaml.

There is no memctl init --continue because Continue uses YAML config. Set it up manually (see Agent Setup).

After configuring MCP, generate AGENTS.md and copy it into .continue/rules/:

npx memctl generate
cp AGENTS.md .continue/rules/memctl.md

Amazon Q

Amazon Q reads MCP config from .amazonq/mcp.json and rules from .amazonq/rules/.

npx memctl init --amazonq
npx memctl generate --amazonq

The --amazonq flag writes .amazonq/rules/memctl.md.

Zed

Zed uses MCP tools directly through context_servers in Zed settings. There is no instruction file, so Zed relies on the MCP tool descriptions to guide usage. Configure manually (see Agent Setup).

JetBrains IDEs

JetBrains IDEs (IntelliJ, WebStorm, PyCharm, GoLand) support MCP via the AI Assistant plugin. Configure through Settings UI (see Agent Setup). There is no instruction file format.

Aider

Aider has no MCP support. Export context as a file and pass it on each run:

npx memctl export agents_md > AGENTS.md
aider --read AGENTS.md

After a session, import changes back:

npx memctl import AGENTS.md

Hooks for automatic capture

For agents that support lifecycle hooks, use memctl hook-adapter to generate templates that automatically capture session context:

npx memctl hook-adapter --agent all --write

This writes a shared dispatcher script and agent-specific config examples to .memctl/hooks/. See Hooks for details.

Keeping instructions fresh

As your project context evolves, regenerate instruction files from stored memories:

npx memctl generate --all --link

With --link, all agents_md-format files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .clinerules/memctl.md, .roo/rules/memctl.md, codex.md) are symlinked to AGENTS.md. Edit one, and all stay in sync. Files with tool-native frontmatter (.windsurf/rules/memctl.md, .cursor/rules/memctl.mdc, .github/copilot-instructions.md) and .cursorrules are always written as separate files.