imece vs CLAUDE.md and AGENTS.md

What each one is for

Use both. Instruction files carry your team's standing rules. imece carries what the team decided and handed off while the work was going on.

• CLAUDE.md, AGENTS.md and Cursor rules: project rules that hold in every session, like build commands, code style and repo layout. For static rules, these are the right tool.
• imece: yesterday's decision, its reason, an approach someone tried and dropped, unfinished work, work handed off to another role. These change day to day.

How CLAUDE.md works

Per Anthropic's documentation, each Claude Code session starts with a fresh context window. CLAUDE.md is the file you write so Claude starts every session with your instructions.

• Levels: organization (managed policy), user (~/.claude/CLAUDE.md), project (./CLAUDE.md or ./.claude/CLAUDE.md, shared through source control) and local (./CLAUDE.local.md, which you add to .gitignore).
• Files in the working directory and the directories above it load at launch. Files in subdirectories load when Claude reads or edits a file there.
• @path/to/import pulls in other files, up to four levels deep. Imported files also load at launch.
• Rules in .claude/rules/ can be scoped to file patterns with a paths field.
• The documentation recommends staying under 200 lines per CLAUDE.md.
• The documentation treats CLAUDE.md as context, not as enforced configuration: Claude reads it and tries to follow it, but strict compliance is not assured. To block an action regardless of what Claude decides, it points to a PreToolUse hook.
• Auto memory is separate: notes Claude writes for itself. They live under ~/.claude/projects/<project>/memory/ on that machine and are not shared across machines.

How AGENTS.md works

• Format: plain Markdown, no required fields.
• In a monorepo each package can have its own AGENTS.md. When instructions conflict, the file closest to the edited file wins.
• The site lists tools that support the file, including Codex, Cursor, Gemini CLI, Jules and Aider. It is stewarded by the Agentic AI Foundation under the Linux Foundation.
• Claude Code (v2.1.277 and later, per Anthropic's documentation) reads AGENTS.md when there is no CLAUDE.md in the working directory or above it. If both exist, it reads only CLAUDE.md by default; a setting in /config makes it read both.

How Cursor rules work

• Project rules live in .cursor/rules as .mdc files and go into version control. A plain .md file there is ignored.
• A rule can apply to every chat, apply when the Agent judges it relevant from its description, apply when a file matches a pattern, or be called by hand with @rule-name.
• Rule contents are included at the start of the model context. The documentation recommends keeping rules under 500 lines.
• User Rules are personal preferences across projects. Team Rules are managed from the dashboard and are available on Team and Enterprise plans. When they conflict, Team Rules come first, then Project Rules, then User Rules.
• Cursor also supports AGENTS.md in the project root and in subdirectories.
• Rules do not affect Cursor Tab or other AI features.

What imece does

imece adds MCP tools and hooks to your agent. When the agent makes a decision or drops an approach, imece asks it to record that; your teammates' agents see the relevant record later.

• Writing: the agent records decisions, finished work, lessons, approaches tried and dropped, unfinished work and handoffs to a role. It can also search the team's records.
• Reading: on Claude Code, imece adds the team's relevant records to the agent's context while it works.
• When you open Codex and Cursor sessions from the desktop app, imece's MCP server is attached to that session.
• Text written by a teammate reaches the agent marked as data, not as instructions.
• Records are kept on team members' devices and sync across the team. Records marked personal stay on your machine.
• imece writes a readable copy into a .imece/ folder in your project that stays out of git. It does not change your CLAUDE.md.

How imece works

Where they differ

• Who writes: you and your team write the instruction files. The agent writes imece records; teammates also write to the team channel and send handoffs from the desktop app.
• Who receives: a project CLAUDE.md reaches everyone who pulls the repo. imece records sync between team members' machines, and a handoff goes to a role, so the members holding that role see it.
• When it enters context: instruction files load at session start, subdirectory files on demand. imece adds what is relevant while the work goes on.
• How the agent reads it: CLAUDE.md is written as instructions. imece records are marked as data, not as instructions.
• Where it lives: CLAUDE.md sits in your repo and is shared and versioned through git. imece records do not sit in the repo; team content is kept on imece's servers in Germany and on team members' devices.

Using them together

• Keep build commands, code style, repo layout and other standing rules in CLAUDE.md, AGENTS.md or Cursor rules.
• Keep yesterday's decisions, their reasons, dropped approaches and handoffs in imece.
• When a decision turns into a lasting project rule, move it into CLAUDE.md or AGENTS.md.
• imece leaves other tools' entries in your Claude Code settings alone; uninstalling removes only its own.

Limits

• These are not locks. Anthropic's documentation treats CLAUDE.md as context, so Claude may not follow it. The records imece adds are context too: the agent sees them, and it can still go its own way. imece does not block the agent's work.
• The agent can skip recording. imece asks the agent to record, but if it doesn't, no record exists.
• When a user asks about something unrelated, the agent may not bring up a pending handoff on its own.
• If the imece service is not running or is slow, nothing is added on that turn and the agent carries on without waiting.
• Records can go stale. imece flags some outdated records, not all of them.
• imece is in closed beta, you get in with an access request, and the desktop app runs on macOS and Windows.

Sources

Information about the other tools was read from these pages on 10 October 2026. Tools change; check the official documentation for the current state.

Claude Code: How Claude remembers your projectAGENTS.mdCursor: RulesHow imece worksimece vs claude-memSecurity and data