You open a fresh chat with your AI coding assistant and, once again, it acts like it has never seen your project. It re-reads the same files, forgets the decision you made an hour ago, and quietly burns through tokens doing it. If that sounds familiar, you’ve hit the two-headed memory problem — and Serena MCP is the tool most people are missing to fix half of it.
Serena is a free, open-source add-on that gives Claude Code, OpenAI Codex, Google Antigravity, GitHub Copilot, and Cursor something they don’t have out of the box: a precise, token-efficient memory of your codebase. This guide explains what “memory” really means for an AI coding agent, how each major tool handles it today, and how to plug Serena into all of them.
🧠 The Two Kinds of Memory a Coding Agent Needs
Here’s the confusion at the root of the whole topic: “memory” means two completely different things for an AI agent.
1. Remembering you. Your preferences, your conventions, the architectural decisions you’ve already made. “Use tabs, not spaces.” “Tests live in /spec.” “We don’t use that library anymore.” This is the memory that instruction files and the newer auto-memory features handle.
2. Knowing your codebase. Where is the checkout function defined? What calls it? Which files break if I rename this? This isn’t about remembering you — it’s about the agent finding the right code without slurping your entire repository into its context window.
Almost every tool on the market has gotten good at the first kind and left the second kind alone. That’s the gap.
Why a big context window isn’t the same as memory
A common reaction is “just use a model with a huge context window.” But a bigger window doesn’t solve this. You still pay — in tokens and latency — to stuff files into that window every session, the model still loses precision as the context fills up, and it still “forgets” earlier turns as the conversation grows. (We dig into this in Learn About AI Context Windows.) A window is short-term working space. Memory is something you don’t have to rebuild from scratch every time.
🔧 How Each AI Coding Tool Remembers Today
Every major agentic coding tool has converged on roughly the same pattern: a hand-written instructions file plus, increasingly, an auto-memory layer the agent maintains itself. Both are about remembering you.
Claude Code uses CLAUDE.md files — plain-Markdown instructions loaded at the start of every session, with project, personal, and organization scopes. The /memory command lets you view and prune what’s loaded, and Claude also keeps its own accumulating auto-memory of build commands and conventions, plus context compaction for long sessions.
OpenAI Codex uses AGENTS.md — an open “README for agents” format that it reads from your home directory down through the project tree. Codex can also summarize past sessions into a generated memory layer under ~/.codex/memories/.
Google Antigravity is Google’s agent-first platform that replaced the old Gemini CLI in June 2026 (if you still search “Gemini CLI,” this is where it went — the new command-line tool is agy). Its agents keep a persistent “brain” — community tooling documents it as a ~/.gemini/antigravity/brain/ directory holding task plans, implementation notes, and walkthroughs as the agent works.
GitHub Copilot reads .github/copilot-instructions.md from your repo, and in 2026 added Copilot Memory, which remembers preferences across sessions (unused memories auto-expire after about 28 days).
Cursor uses .cursor/rules files plus Cursor Memories, an auto-maintained knowledge base that replaced the older Notepads feature.
Notice the pattern? Every one of these remembers you and your conventions. None of them actually indexes your codebase at the symbol level. To find a function, they still fall back to reading whole files and running text searches. That’s exactly the gap Serena fills.
⭐ What Serena Actually Is
Serena is an open-source (MIT-licensed) MCP toolkit from a group called Oraios, and its tagline says it best: “the IDE for your coding agent.” It runs locally on your machine and connects to your AI tool through the Model Context Protocol (MCP) — the same universal “USB port for AI tools” standard the whole industry is standardizing on.
Here’s the load-bearing idea. Serena runs a Language Server Protocol (LSP) backend — the exact same technology that powers Go to Definition, Find All References, and safe Rename in your normal code editor. Instead of the agent reading an entire file to find one function, it calls symbol-level tools like find_symbol, find_referencing_symbols, and replace_symbol_body. It asks for the one thing it needs and edits exactly that symbol.
LSP vs. grep vs. RAG — why “exact” beats “fuzzy” for code
There are three ways an agent can find code, and they’re not equal:
- Whole-file reads + grep (the default): imprecise and token-hungry. To understand one function the agent reads hundreds of surrounding lines it doesn’t need.
- RAG / embeddings (vector search): fuzzy similarity over chunked text. It’s approximate, and the index can go stale the moment you edit.
- Serena’s LSP approach: an exact, always-current structural map of your code. It knows precisely where a symbol lives and who references it — because it’s using your language’s real compiler-grade understanding, not a guess.
Serena supports 40+ programming languages through this LSP backend (the count keeps climbing — check the repo for the current list), covering Python, JavaScript/TypeScript, Go, Rust, Java, C#, and many more.
Serena has its own memory, too
Here’s the bonus that makes Serena punch above its weight: it doesn’t just do retrieval. On its first encounter with a project, Serena runs an onboarding step and writes plain-Markdown project notes into a .serena/memories/ folder — files you can read, edit, and commit alongside your code. So Serena actually delivers both kinds of memory: precise codebase knowledge and persistent project notes that survive between sessions and work across every tool you connect it to.
💸 Why Serena Matters: Tokens and Precision
The payoff is simple to feel even if you’re not counting tokens: your agent gets faster, cheaper, and more accurate on real projects.
Every whole-file read is money — tokens you pay for on the way in. Retrieving a single symbol instead of a 400-line file is the difference between a sip and a gulp. Serena’s own docs describe the approach as far more token-efficient rather than quoting a specific percentage, and there’s no official benchmark to point to — but the mechanism is obvious once you picture it. Fewer tokens in means lower cost and less noise for the model to get lost in.
Precision is the other half. Because edits target an exact symbol rather than a fuzzy chunk of text, changes are safer and scale to large repositories where “read the whole file” simply falls apart. One experienced reviewer’s rule of thumb: on a tiny project you won’t notice the difference, but past roughly 20,000 lines of code, Serena starts to pay for itself. Treat that as a gut check, not a law.
🔌 How to Add Serena to Your Agent (via MCP)
Because Serena speaks MCP, you set up one server and connect it to whichever tools you use. Commands evolve, so treat these as the current shape and confirm against Serena’s docs when you set it up.
Prerequisites and running the server
Serena runs through uv/uvx, Astral’s Python tool runner — install that first. Then you can launch the server straight from source with no separate install:
uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-serverOn a large repo, index it once for speed:
serena project indexHeads-up for first-timers: Serena also opens a small web dashboard on localhost when it runs, showing logs and tool activity. That’s expected, not a bug.
Register it with your tool
Claude Code — a single command:
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwdOpenAI Codex — add a block to ~/.codex/config.toml:
[mcp_servers.serena]command = "serena"args = ["start-mcp-server", "--project-from-cwd", "--context=codex"]GitHub Copilot, Cursor, and Google Antigravity each register MCP servers their own way (a JSON config file or an in-app MCP settings panel). Serena ships a matching --context flag for each one — --context=copilot-cli, --context=vscode, --context=ide-assistant, and --context=antigravity — which tailors its toolset to that client. Add Serena as a standard stdio MCP server in your tool’s MCP settings, point it at your project with --project-from-cwd (or --project <path>), and pick the matching context flag. Check Serena’s “Clients” docs for the exact keys for your specific tool, since these are the fastest-moving part.
One honest setup note: each programming language needs its language server available, and that’s the most common friction point. Some install automatically; others need the language’s toolchain already on your machine.
🤔 Do You Actually Need Serena?
Not always — and it’s worth being honest about that so you don’t over-engineer a weekend project. If your codebase is small enough that the agent can comfortably hold the relevant files in context, the built-in CLAUDE.md/AGENTS.md-style memory is plenty. Serena earns its place when your project is large, long-lived, or spread across many files — exactly when whole-file reading gets slow, expensive, and error-prone. Bigger and older the codebase, bigger the win.
🔒 Is Serena Private?
Mostly yes, with one honest caveat. Serena itself runs entirely on your machine — the language server and the index never phone home, and the project is open-source so you can verify that. What Serena can’t change is the model you’re using: whatever code snippets your AI agent retrieves, it still sends to whatever cloud LLM you chose (Claude, GPT, Gemini, and so on). The upside is that Serena actually reduces how much of your code the model ever sees, because it fetches targeted symbols instead of whole files.
❓ Frequently Asked Questions
What is Serena MCP in one sentence? It’s a free, open-source MCP server that gives your AI coding agent IDE-grade, symbol-level knowledge of your codebase — so it finds and edits the exact code it needs instead of re-reading whole files.
How is Serena different from CLAUDE.md or AGENTS.md? Those files remember you — your preferences and conventions. Serena gives the agent precise codebase retrieval and editing tools (and, as a bonus, keeps its own project notes). Different problems; use both.
Does Serena work with Cursor, Codex, Copilot, and Antigravity? Yes. Anything that speaks MCP — Claude Code, Codex, Cursor, GitHub Copilot, Google Antigravity, Claude Desktop, VS Code, and more.
Does it cost anything? Serena is free and open-source (MIT). You still pay for your LLM’s tokens — but Serena tends to lower that bill by sending less code to the model.
Is Serena like RAG or a vector database for code? No. RAG uses fuzzy similarity search over chunked text that can go stale. Serena uses your language server’s exact, always-current understanding of symbols and references — precise, not approximate.
Why does my agent keep re-reading files and forgetting my project? Because raw agents only “see” code by reading files, and only remember what’s in the current context window. Memory files fix the forgetting-you half; Serena fixes the reading-everything half.
📚 Further Reading
- Serena on GitHub — the source, README, and setup docs.
- Learn About AI Context Windows — why a big window still isn’t memory.
- Learning Software Development in the Age of AI — where tools like this fit in a modern workflow.
- What Is an Embedding? — the fuzzy-search approach Serena deliberately avoids for code.
📦 Recommended Reading
Serena is free, and so are the tools it plugs into — but if you want to get genuinely good at building software with AI agents, these books are worth every penny:
📘 Books for Coding With AI Agents
- AI-Assisted Programming — Tom Taulli (O’Reilly) – A practical, up-to-date guide to planning, coding, testing, and shipping software with AI tools like Copilot and Claude — a natural companion to setting up Serena.
- Refactoring: Improving the Design of Existing Code — Martin Fowler (2nd Edition) – The definitive book on safely restructuring code. Since Serena’s whole point is precise, symbol-level edits, this is the mindset that makes those edits count.
- The Pragmatic Programmer — David Thomas & Andrew Hunt (20th Anniversary Edition) – The timeless guide to thinking like a professional developer — the judgment you’ll still need even when an AI writes the first draft.
✅ Pro tip: Start with AI-Assisted Programming for the modern workflow, then let Refactoring and The Pragmatic Programmer sharpen the craft that keeps your AI-built code maintainable.