AI Coding Agent Memory Across Tools

To make your AI coding agent remember the project across tools, you need to centralize project context in a persistent, structured file (like AGENTS.md or CLAUDE.md) that the agent reads at the start of each session, and configure your tools to reference that same file. This gives the agent a shared memory that survives switching between your IDE, CLI, and chat interfaces.

Why AI Agents Forget

AI coding agents are stateless by default. Each time you start a new session—whether in VS Code, a terminal, or a web chat—the model begins with only the system prompt and whatever files you explicitly attach. It does not retain anything from previous conversations or edits unless you provide that context again. This is why an agent that was just helping you refactor a module suddenly asks “What is this project about?” when you open a new tool. The problem is not the model’s intelligence; it’s the lack of a persistent memory layer.

Tools like Cursor, GitHub Copilot, and Claude Code have started addressing this with project-level memory files. These are plain-text markdown files that live in your repository and contain instructions, architecture notes, coding conventions, and any other context you want the agent to always have. When the agent starts, it reads this file and uses it as a baseline. The key is that the file is stored in the repo, not in the tool’s internal state, so any tool that reads the repo can access it.

How Project Memory Files Work

The most common pattern is a file named AGENTS.md (used by Cursor, Sourcegraph, and others) or CLAUDE.md (used by Claude Code). Some tools also support .cursorrules or .github/copilot-instructions.md. These files are written in plain Markdown and contain sections like:

• Project overview – what the project does, its main components, and its tech stack.
• Build and test commands – how to run the project, run tests, and lint.
• Coding conventions – naming rules, formatting, error-handling patterns, and preferred libraries.
• Architecture decisions – why certain patterns were chosen, and what to avoid.
• Common tasks – step-by-step instructions for frequent operations like adding a new API endpoint.

When the agent starts, it reads this file and treats it as authoritative. It will follow the instructions even if they contradict the model’s default behavior. For example, if you write “Always use TypeScript strict mode”, the agent will generate TypeScript with strict type checking, even if it would normally generate looser code.

Setting Up Cross-Tool Memory

To make the same memory available across all your tools, you need to ensure each tool is configured to read the same file. Here are the steps:

1. Create a single source of truth – Put your project memory in a file like AGENTS.md at the root of your repository. This is the most widely supported name.
2. Configure each tool to use it – In Cursor, you can set the “Project Rules” to point to this file. In Claude Code, you can use the --memory flag or set the CLAUDE_MEMORY_FILE environment variable. For GitHub Copilot, you can add the file to .github/copilot-instructions.md or reference it in the settings.
3. Keep the file updated – As the project evolves, update the memory file. When you change a dependency or a coding pattern, reflect that in the file. This is the maintenance cost, but it’s what keeps the agent’s memory accurate.
4. Use environment variables for secrets – Do not put API keys or passwords in the memory file. Use environment variables or a .env file that the agent can read but that is not committed to the repo.

What to Put in the Memory File

The more specific and actionable the instructions, the better the agent will perform. Here are concrete examples of what to include:

• Project structure – “The frontend is in src/, the backend in server/. Shared types are in src/types.ts.”
• Testing conventions – “Use Jest for unit tests. Test files are co-located with source files and named *.test.ts.”
• Error handling – “All API routes must return a JSON error object with a code and message field.”
• Code style – “Use 2-space indentation. Prefer named exports. Avoid default exports.”
• Common pitfalls – “The database connection is slow, so always use connection pooling. Never use SELECT *.”

You can also include a “Do not” section to prevent the agent from doing things you dislike, like using a particular library or modifying generated files.

Common Problems and Solutions

Even with a memory file, you may encounter issues. Here are the most common ones and how to fix them:

• Agent ignores the file – Make sure the file is in the root directory and is named exactly as your tool expects. Some tools only read AGENTS.md from the current working directory, so if you run the agent from a subfolder, it won’t find it. Use a symlink or a global configuration to point to the root file.
• Memory file becomes too large – If the file is hundreds of lines, the agent may not read it all, or it may prioritize the beginning. Keep it concise. Use separate files for different concerns (e.g., docs/architecture.md) and reference them from the main file.
• Conflicting instructions from multiple tools – If you have different memory files for different tools (e.g., .cursorrules and CLAUDE.md), they might conflict. Consolidate to a single file and have all tools point to it.
• Outdated memory – If you change a convention but forget to update the file, the agent will follow the old rule. Make updating the memory file part of your code review process.

Comparison of Tools’ Memory Features

Different tools have different levels of support. Here is a rough comparison:

• Cursor – Supports AGENTS.md and .cursorrules. The rules are applied to all code generation and chat. You can also set global rules for all projects.
• GitHub Copilot – Uses .github/copilot-instructions.md in the repo. This is read by Copilot in the IDE and in the chat. It does not support dynamic memory per session, but it does provide consistent context.
• Claude Code – Supports CLAUDE.md and also allows you to pass additional memory files via the --memory flag. It also has a @ mention syntax to reference specific files in the conversation.
• Sourcegraph Cody – Uses AGENTS.md and also supports embedding the file in the codebase context.

All of these tools read the file at the start of each session, so as long as you keep the file updated, the memory is consistent across tools.

Costs and Limitations

The main cost is maintenance: you have to keep the memory file up to date. This is a manual process unless you automate it with a script that scans your codebase and updates the file. Some teams use a pre-commit hook to check that the memory file is still accurate, but that is rare.

Another limitation is that the agent’s memory is still limited to what is in the file. It cannot recall past conversations or edits unless you explicitly include them. For example, if you fixed a bug in a previous session, the agent won’t remember that fix unless you write it down. To make the agent remember more, you can maintain a CHANGELOG.md or a decisions.md file that records what was done and why.

Finally, the memory file is not a replacement for good documentation. It is a prompt for the agent, not a full knowledge base. For complex projects, you may need to combine it with a proper documentation site that the agent can access via a tool like docs or readthedocs.

Frequently Asked Questions

Can I use the same memory file for multiple tools? Yes, as long as the tools support the same file name. AGENTS.md is becoming a de facto standard. If a tool does not support it, you can create a symlink or a small wrapper script that copies the content to the tool’s expected location.

What if my project is a monorepo with multiple packages? You can have a root AGENTS.md for global rules and then subdirectory AGENTS.md files for package-specific rules. Most tools will read the file closest to the file being edited, so you can have granular control.

Does the agent remember the file after I edit it mid-session? No. The agent reads the file at the start of the session. If you change it mid-session, you need to restart the session or explicitly tell the agent to re-read the file. Some tools have a command like “reload context” to do this.

Is there a risk of the agent leaking sensitive info from the memory file? Yes, if you put secrets in the file and then share the repo, they will be exposed. Always use environment variables for secrets. Also, be careful with what you write about users or internal systems.

Can I use the memory file to give the agent a persona or tone? Yes, you can add a section like “You are a senior Python developer who writes clean, idiomatic code.” This can influence the style of the generated code and comments.

What if the agent still forgets something? If the agent misses context, it’s usually because the file is too long or the instruction is ambiguous. Try breaking the file into smaller, focused sections and use clear, imperative language. Also, you can explicitly reference the file in your prompt, e.g., “Read AGENTS.md before answering.”

Related

• Adjust Vibrations in LG G7: Full Guide
• TSMC 1nm Factory Plans: What We Know
• Rechargeable vs Disposable Batteries: Cost & Best Uses