AI coding agents are becoming much more useful, but there is one problem I keep running into:
They forget project-specific lessons.
Not because the model is bad. Not because the prompt is missing one more paragraph. The problem is structural.
Most coding agents work inside a temporary conversation context. They can understand what you tell them during the session, but once that context is gone, the same mistakes can easily happen again.
For example:
- an agent edits generated files manually instead of updating the source schema
- it moves business logic into React components even though the project uses stores/services
- it runs the wrong test command
- it ignores a previous debugging conclusion
- it repeats a fix that already failed last week
- it forgets that a specific folder has special conventions
This creates a strange workflow where developers keep telling agents the same things again and again.
At some point, “please remember this” should become part of the project itself.
The obvious solution: a lessons file
A simple idea is to create something like this:
LESSONS.md
- Do not edit generated GraphQL types manually.
- Use MobX stores for business logic.
- Run pnpm test:unit before changing payment logic.
- Do not modify files in src/generated/.
This is already better than nothing.
It makes implicit project knowledge explicit. It can be versioned in Git. It can be read by different agents.
But after working with this idea, I started to feel that a plain file is not enough.
The problem is not storing lessons.
The problem is retrieving the right lesson at the right moment.
Why plain lesson files do not scale well
A flat markdown file works when there are five lessons.
It becomes much less useful when there are fifty, a hundred, or several hundred.
Some problems appear quickly:
- The file becomes noisy
Agents may read too much irrelevant context.
A lesson about GraphQL code generation is not useful when the agent is editing CSS.
A lesson about payment validation is not useful when changing a README.
If every agent reads every lesson every time, memory becomes noise.
- Lessons lose context
A lesson like this is technically correct:
Do not edit generated files manually.
But it is missing important context:
- Which files are generated?
- Which command regenerates them?
- What caused the original mistake?
- Which rule does this relate to?
- Is this always true or only true for one package?
- Is this still current?
The lesson exists, but it is disconnected from the codebase.
- Lessons become stale
Projects evolve.
A command changes.
A folder is renamed.
An architectural rule is replaced.
A plain file rarely tells you whether a lesson is fresh, outdated, or only partially valid.
- Agents cannot easily reason about relationships
In real projects, knowledge is connected.
A mistake may be connected to:
- a file path
- a command
- an architectural rule
- a tool
- a package
- a domain area
- a previous failed fix
- another lesson
A flat file does not represent those relationships well.
That is why I started thinking about lessons as a graph.
Graph-based lessons
A graph-based lessons system treats a lesson not as an isolated note, but as a connected piece of project knowledge.
Instead of this:
Do not edit generated GraphQL types manually.
You can model it more like this:
Lesson:
Do not edit generated GraphQL types manually.
Update the schema and run codegen instead.
Connected context:
affected files:
- src/generated/graphql/*
- packages/api/generated/*
command:
- pnpm codegen
related rule:
- generated files are read-only
mistake type:
- manual edit of generated output
domain:
- GraphQL
- API types
freshness:
- confirmed recently
Now the lesson is no longer just text.
It has relationships.
Before an agent edits src/generated/graphql/User.ts, it can retrieve lessons connected to that path.
Before it changes payment validation, it can retrieve lessons connected to the payment domain.
Before it runs tests, it can retrieve the correct command connected to the current package.
This is closer to how developers actually remember project knowledge.
We do not remember everything as one giant document. We remember connections:
“This file is generated.”
“This folder belongs to the payment domain.”
“That command failed before.”
“This convention exists because of that production bug.”
A useful agent memory system should work the same way.
What should a lesson contain?
A lesson should probably include more than just a sentence.
For example:
Lesson:
Business logic should stay in MobX stores, not React components.
Reason:
The project separates domain logic from UI rendering.
Moving logic into components makes testing and reuse harder.
Applies to:
- src/stores/*
- src/features/* Related concepts:
- MobX
- domain logic
- React components
- separation of concerns Mistake type:
- architectural violation Suggested behavior: If a change requires business logic, add it to the store/service layer first. Keep React components mostly declarative.
This gives the agent enough information to act correctly, not just read a rule.
Human memory vs agent memory
One important question is:
Should agents be allowed to create lessons automatically?
I think the answer is: yes, but carefully.
For example, after a failed change, an agent could propose:
Proposed lesson:
Do not use npm in this repository. The project uses pnpm.
Evidence:
npm install created a package-lock.json and broke dependency consistency.
Suggested scope:
whole repository
Related command:
pnpm install
But I would not want every agent to permanently write lessons without review.
A better workflow may be:
- Agent detects a reusable lesson.
- Agent proposes the lesson.
- Human approves, edits, or rejects it.
- Approved lesson becomes part of the repository.
- Future agents can retrieve it when relevant.
This keeps memory useful without letting it turn into uncontrolled noise.
Why this matters more with multiple coding agents
Many developers now use more than one AI coding tool.
For example:
- Claude Code
- Cursor
- Codex CLI
- GitHub Copilot
- Gemini CLI
- Aider
- Roo
- Cline
- Windsurf
Each tool has its own configuration style.
Some use markdown instruction files.
Some use rules.
Some use commands.
Some support MCP.
Some have their own project config structure.
This creates another problem: project knowledge becomes fragmented.
You may have one rule in CLAUDE.md, another in .cursor/rules, another in AGENTS.md, and another in some tool-specific config.
Eventually, your agents are not working from the same understanding of the project.
That is the broader problem I am trying to solve with AgentsMesh.
What is AgentsMesh?
AgentsMesh is an open-source CLI/library for managing AI coding assistant configuration from one canonical source.
The idea is simple:
Define project knowledge once in .agentsmesh/, then generate native config files for different AI coding tools.
AgentsMesh can manage things like:
- rules
- commands
- agents
- skills
- hooks
- permissions
- MCP servers
- ignore patterns
- graph-based lessons
The lessons system is the part I find most interesting.
It is designed as structured, connected memory rather than a plain file full of notes.
The goal is not just to store instructions.
The goal is to help agents retrieve the right project knowledge at the right time.
Example workflow
Imagine an agent makes a mistake.
It manually edits a generated GraphQL type.
The build passes locally, but later codegen overwrites the change.
Instead of just saying in chat:
Do not do that again.
The project can record a lesson:
Lesson:
Do not manually edit generated GraphQL types.
Update the schema and regenerate types instead.
Connected files:
- src/generated/graphql/*
- packages/api/generated/* Command: pnpm codegen Related rule: generated files are read-only Mistake type: editing generated output
Later, another agent wants to edit a file inside src/generated/graphql/.
Before making the change, it can retrieve the lesson connected to that path.
The agent does not need to read every project instruction.
It only needs the relevant memory.
The real challenge: avoiding bad memory
Long-term memory sounds useful, but bad memory can be worse than no memory.
A lessons system needs safeguards.
Some questions I am still thinking about:
Should lessons expire?
Some lessons should probably become stale automatically.
For example, a command may change from:
pnpm test
to:
pnpm test:unit
If old lessons remain forever, agents may follow outdated instructions.
Should every lesson need approval?
Fully automatic memory can become noisy.
But requiring manual approval for every lesson may create too much friction.
A good system may need different trust levels:
- proposed
- approved
- deprecated
- archived
How do you prevent overfitting?
One failed interaction does not always mean there is a general rule.
If an agent makes one bad change, the lesson should not necessarily become:
Never touch this file.
A useful lesson should capture the actual reusable principle, not just fear from one mistake.
How much context is enough?
Too little context makes lessons vague.
Too much context makes them expensive and noisy.
The ideal lesson should be small, specific, and connected to the right parts of the project.
Why I think graph-based memory is worth exploring
Prompt files are useful.
Rules are useful.
Documentation is useful.
But AI coding agents need something more precise than “read this giant instruction file before every task.”
They need contextual recall.
When editing generated files, recall codegen lessons.
When touching payment logic, recall payment-related lessons.
When changing architecture, recall architectural constraints.
When running commands, recall the correct package manager and test scripts.
That is why I think graph-based project memory is a promising direction.
Not because graphs are trendy.
But because software projects are already graphs:
- files depend on files
- commands affect packages
- rules apply to directories
- mistakes happen in domains
- conventions relate to architecture
- fixes relate to previous bugs
Agent memory should reflect that structure.
Final thoughts
I do not think the future of AI coding agents is just bigger context windows.
Bigger context helps, but it does not solve everything.
The real improvement may come from better project memory:
- structured
- versioned
- reviewable
- connected to the codebase
- retrievable by relevance
- shared across tools
That is what I am experimenting with in AgentsMesh.
The core idea is simple:
Agents should not repeat the same project-specific mistakes forever.
When a mistake teaches something useful, that lesson should become part of the project.
GitHub: https://github.com/sampleXbro/agentsmesh
I would love feedback from developers building with AI coding agents:
How would you design long-term project memory so it helps agents avoid repeated mistakes without becoming noisy, stale, or over-engineered?