---
title: AGENTS.md
description: Copy-paste AGENTS.md template for mem/ctl MCP usage
---

# AGENTS.md

Copy this into your repository root as `AGENTS.md`. This works with any MCP-compatible agent (Claude Code, Cursor, VS Code, Windsurf, Cline, etc.).

Some agents read a different filename. Use `generate --link` to create symlinks automatically, or create them manually:

```bash
# Automatic: generate AGENTS.md and symlink CLAUDE.md + GEMINI.md to it
npx memctl generate --claude --gemini --link

# Manual
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
```

```md
# memctl Rules

MCP server: `memctl`. Use it for all persistent project memory.

## Session Start

1. `context` action=`bootstrap` -- load project context
2. `session` action=`start` sessionId=`<id>`
3. `activity` action=`memo_read` -- check handoff notes
4. `branch` action=`get` includeRelatedContext=`true`

## Before Editing

- `context` action=`context_for` filePaths=`[<files you will edit>]`
- `context` action=`smart_retrieve` intent=`<what you need>`

## While Coding

- Store decisions, lessons, issues: `context` action=`functionality_set` type=`<type>` id=`<id>` content=`<content>`
- Search before storing: `memory` action=`search` query=`<query>`
- Update branch plan: `branch` action=`set` content=`<plan>` status=`in_progress`

## After Completing Work

- Store lessons: `context` action=`functionality_set` type=`lessons_learned` id=`<id>` content=`<lesson>`

## Session End (MANDATORY)

You MUST execute these steps after fully responding to the user. Never skip this.

1. `activity` action=`memo_leave` message=`<handoff note>`
2. `session` action=`end` sessionId=`<id>` summary=`<structured summary>`

Summary must include: what was accomplished, key decisions made, open questions, and what files were modified. Keep it concise (1-2 paragraphs). Do NOT include code snippets, file contents, git output, or command results.

## Rules

- Always bootstrap at session start
- Always end session before stopping, no exceptions
- Always load context before editing files
- Never store secrets, tokens, or API keys
- Search before storing to avoid duplicates
- Do not store code, file contents, git output, or command results in memory
```

## Importing and exporting

Generate agent config files from your stored context:

```bash
# Write AGENTS.md to the current directory
npx memctl generate

# Pick specific agents
npx memctl generate --claude           # + CLAUDE.md
npx memctl generate --claude-rule      # + .claude/rules/memctl.md
npx memctl generate --gemini           # + GEMINI.md
npx memctl generate --cursor           # + .cursorrules
npx memctl generate --cursor-rule      # + .cursor/rules/memctl.mdc
npx memctl generate --copilot          # + .github/copilot-instructions.md
npx memctl generate --windsurf         # + .windsurf/rules/memctl.md
npx memctl generate --cline            # + .clinerules/memctl.md
npx memctl generate --roo              # + .roo/rules/memctl.md
npx memctl generate --codex            # + codex.md
npx memctl generate --amazonq          # + .amazonq/rules/memctl.md
npx memctl generate --all              # all of the above

# Symlink instead of copying (avoids content drift)
npx memctl generate --all --link

# Import an existing AGENTS.md into memctl
npx memctl import AGENTS.md
```

With `--link`, files that share the `agents_md` format (CLAUDE.md, GEMINI.md, copilot-instructions.md, `.windsurf/rules/memctl.md`, `.clinerules/memctl.md`, `.roo/rules/memctl.md`, `.amazonq/rules/memctl.md`, `codex.md`) become symlinks. `.cursorrules` is always a real file because it uses a different format. Files that support YAML frontmatter (Windsurf, Cursor rules, Copilot) get tool-native activation metadata prepended automatically. See [generate docs](/docs/cli/import-export#generate) for details.

For pipe-friendly output, use `export` instead:

```bash
npx memctl export agents_md > custom-path/AGENTS.md
npx memctl export cursorrules > .cursorrules
```

Or via MCP tools:

```
import_export.export_agents_md   - generate AGENTS.md from stored context
import_export.agents_md_import   - parse and import AGENTS.md content (supports dryRun)
import_export.cursorrules_import - parse and import .cursorrules content
```

Need full tool details? See [MCP Tools](/docs/mcp-server/tools).
