AI coding agents are powerful—until they’re not. You spend ten minutes explaining your project structure, your naming conventions, the reason you chose a particular auth pattern, and the agent nails the task. Then you start a new session and it’s back to square one. No memory. No context. Just a blank slate that’s about to suggest you use a pattern you explicitly ruled out three weeks ago.

This isn’t a bug. It’s how large language models work. They have no persistent memory between sessions by default. Every conversation starts fresh. For a quick one-off question, that’s fine. For an ongoing software project with real architectural decisions, accumulated conventions, and hard-won lessons, it’s a serious productivity drain.

The solution is a memory bank: a structured, human-readable file (or set of files) that you maintain alongside your codebase and feed to your AI agent at the start of every session. Done well, it transforms a forgetful assistant into a context-aware collaborator that actually understands your project.

A memory bank file is a persistent context document that lives in your repository and tells your AI coding agent everything it needs to know about your project before it writes a single line of code.

Think of it as onboarding documentation—but written for an AI, not a human. It captures the things that would take a new developer weeks to absorb: the architecture decisions, the conventions, the gotchas, the “we tried that and it didn’t work” moments. The most common names for this file are:

• memory.md — a general-purpose project context file
• .clinerules — used specifically by the Cline VS Code extension
• .cursorrules — used by Cursor to inject rules into every prompt
• AGENTS.md — used by some teams following OpenAI’s Codex conventions
• .windsurfrules — used by Windsurf

The format varies slightly by tool, but the underlying principle is the same: give the agent durable, structured context so it can make better decisions without you re-explaining everything from scratch.

Memory bank files work by injecting structured context into the agent’s prompt window at the start of a session or task. Each tool handles this slightly differently, but the mechanism is consistent.

When you open a project in Cursor and start a conversation, Cursor reads your .cursorrules file and prepends its contents to every prompt. Cline reads .clinerules from your project root and uses it to shape how it interprets your instructions. Windsurf does the same with .windsurfrules. Some tools let you configure multiple files or directories—Cline’s newer versions support a memory-bank/ folder with multiple .md files for different concerns.

The key insight is this: the agent doesn’t remember—you do, on its behalf. You’re not training the model. You’re not fine-tuning it. You’re simply providing structured context that the model uses to reason more accurately about your specific project.

Here’s the basic flow:

1. You create and maintain a memory bank file in your repo
2. At the start of each session, the agent reads it (automatically or via a prompt instruction)
3. The agent uses that context to inform every response in the session
4. When something changes in your project, you update the file

It’s low-tech, transparent, and surprisingly effective.

The contents of a good memory bank file fall into a handful of consistent categories. The goal is to answer the questions a thoughtful new team member would ask on their first day.

Start with a brief, plain-English description of what the project is, what problem it solves, and who uses it. This gives the agent a mental model to reason from.

# Project: Vaultly
Vaultly is a B2B SaaS document management platform for legal teams.
Users upload, tag, and share sensitive documents with role-based access control.
The product is in private beta with ~20 law firm clients.

List the languages, frameworks, databases, and infrastructure your project uses. Be specific—“we use React” is less useful than “we use React 18 with the App Router in Next.js 14, deployed on Vercel.”

• Frontend: Next.js 14 (App Router), TypeScript, Tailwind CSS
• Backend: Node.js with tRPC, Prisma ORM
• Database: PostgreSQL on Supabase
• Auth: Kinde (handles login, roles, permissions, and feature flags)
• Deployment: Vercel (frontend), Railway (background jobs)

This is where most of the value lives. Document the decisions your team has made about how code should be written—naming conventions, file structure, component patterns, API design rules.

## Conventions
- Components live in /components, grouped by feature (e.g., /components/documents/)
- Server components are default; use 'use client' only when necessary
- API routes follow REST conventions: GET /api/documents, POST /api/documents/:id
- All database queries go through the /lib/db layer—never query Prisma directly in components
- Error handling uses a shared Result<T, E> type—never throw raw errors in business logic

This is the most underrated section. Document not just what you decided, but why. This prevents the agent from suggesting you revisit decisions you’ve already made—and helps you remember your own reasoning months later.

## Decisions
- We chose tRPC over REST for internal API calls because we wanted end-to-end type safety
  without a separate schema layer. REST is used for public-facing endpoints only.
- We're not using React Query—tRPC's built-in hooks cover our caching needs for now.
- We evaluated Clerk and Auth0 before choosing Kinde. Key reasons: better pricing model
  for B2B, native support for organizations and roles, and a cleaner SDK.

Explicitly tell the agent what not to do. This is surprisingly powerful—agents will often suggest popular patterns that don’t fit your project.

## Do not
- Do not use the Pages Router—we are fully on App Router
- Do not suggest class components
- Do not use any.type annotations—enforce strict TypeScript
- Do not add new npm packages without flagging it first

Update this section regularly. Telling the agent what you’re currently working on helps it give more relevant suggestions.

## Current focus
We are building the document sharing flow. The upload component is done.
We are now working on the permission assignment UI and the share link generation logic.

Structure matters. A wall of text is harder for the model to parse than a well-organized document with clear headings and short, declarative statements.

Follow these structural principles:

• Use Markdown headings to separate concerns—the model handles Markdown well and uses it to understand hierarchy
• Write in short, declarative sentences—“We use Prisma for all database access” is better than a paragraph explaining your ORM philosophy
• Put the most important context near the top—models weight earlier tokens more heavily in long contexts
• Use code blocks for actual code patterns—showing an example is more reliable than describing one
• Keep it under 2,000 words—longer files eat into your context window and dilute the signal

A practical template structure looks like this:

Even experienced developers make these errors when setting up a memory bank for the first time.

A memory bank file is a living document. If your stack changes, your conventions evolve, or you make a new architectural decision, the file needs to reflect that. A stale memory bank is worse than no memory bank—it actively misleads the agent.

Build a habit: when you make a significant decision or change a convention, update the file before you close your editor. Treat it like a changelog entry.

“We use standard patterns” tells the agent nothing. “We use the repository pattern for data access, with a dedicated class per domain entity in /lib/repositories/” tells it exactly what to do. Specificity is the whole point.

You don’t need to document every function or every file. Focus on the things that are non-obvious, project-specific, or frequently misunderstood. If a convention is standard across the industry, you don’t need to explain it. If it’s specific to your project or team, you do.

Decisions without rationale get second-guessed. If you document that you’re using a particular pattern but don’t explain why, the agent (and future-you) will wonder if it’s still the right call. Always include a brief reason for non-obvious choices.

Some tools read the memory bank automatically. Others need a prompt instruction. If you’re using a tool that doesn’t auto-inject context, start every session with: “Before we begin, read memory.md and use it as context for everything we work on today.”

A well-maintained memory bank compounds in value. Here’s how to keep it useful as your project grows.

Treat updates as part of the definition of done. When you finish a feature or make an architectural change, updating the memory bank is part of closing out that work—not an afterthought.

Version it with your code. The memory bank file lives in your repo and gets committed alongside code changes. This means you have a history of how your project’s conventions evolved, and every team member has access to the same context.

Review it at the start of new work cycles. At the beginning of a sprint or a new feature, skim the memory bank. It’s a useful forcing function to check whether your documented conventions still reflect reality.

Split it when it gets too long. If your file grows beyond 2,000–3,000 words, consider splitting it. Cline supports a memory-bank/ directory with multiple files. You might have architecture.md, conventions.md, decisions.md, and current-sprint.md as separate files.

Use it for onboarding humans too. A well-written memory bank is also excellent onboarding documentation for new developers. If it’s clear enough for an AI to use, it’s clear enough for a person.

Memory banks aren’t equally valuable in every context. They shine in specific situations.

Long-running projects with accumulated decisions. The longer a project runs, the more context accumulates. A memory bank prevents that context from living only in the heads of the original developers.

Solo developers working across multiple projects. If you’re context-switching between three side projects, a memory bank for each one means you can pick up exactly where you left off—without a 10-minute re-orientation session every time.

Teams using AI agents collaboratively. When multiple developers on a team use AI agents, a shared memory bank ensures everyone’s agent is working from the same understanding of the project. It’s a lightweight way to standardize how AI assistance is used across a team.

Projects with strict conventions or compliance requirements. If your project has non-negotiable rules—security patterns, data handling requirements, accessibility standards—the memory bank is where you encode them so the agent never suggests something that violates them.

Onboarding new contributors. When a new developer joins and starts using an AI agent, the memory bank immediately gives their agent the same project context as a developer who’s been on the project for months.

If you’re building a product that uses Kinde for authentication, authorization, user management, or feature flags, your memory bank should document how you’ve integrated Kinde—and the agent will be far more useful when helping you extend that integration.

A practical Kinde-specific section in your memory bank might look like this:

## Auth and permissions (Kinde)
- We use Kinde for all authentication and authorization
- Users authenticate via Kinde's hosted login page (no custom auth UI)
- Roles are defined in Kinde: admin, editor, viewer
- Permissions are checked server-side using getKindeServerSession() in Next.js
- Feature flags are managed in Kinde and fetched via the Kinde SDK
- Organization-level access is enforced—users can only access documents in their org
- Do not implement any custom auth logic—always use Kinde's SDK methods

With this in place, the agent understands your auth model, knows which SDK methods to use, and won’t suggest rolling custom session logic or implementing its own RBAC system.

Kinde’s documentation covers the SDK methods, workflow configuration, and feature flag setup you’ll want to reference when writing this section. The Kinde docs are well-structured and worth reading before you write your Kinde-specific memory bank entries—that way your documentation accurately reflects how the SDK actually works.

You can explore Kinde’s full documentation at https://docs.kinde.com/ to find the specific pages relevant to your integration.

• Get started with Kinde — An overview of Kinde’s capabilities including authentication, user management, organizations, and feature flags, useful for understanding what to document in your memory bank’s auth section.
• Feature flags — How Kinde’s feature flag system works, including how to create and evaluate flags via the SDK—worth documenting in your memory bank if your project uses Kinde flags to gate features.
• Kinde’s SDKs — An overview of all available Kinde SDKs across frameworks, so you can document the exact SDK your project uses and the methods your agent should rely on.