Guide · Agentic AI · as of 4 November 2026

Every mistake becomes a rule: how our AI agents learn from their own work.

By , Managing Director, BRev Digital ·

Our software is written by AI coding agents, mostly Claude Code, working in parallel on one machine in Dubai. Each session starts with an empty head. Left alone, an agent would make last week’s mistake again this week, with the same confidence. So we built what we call the learning engine: a set of files, habits and small programs that turn every bug, every wasted session and every correction into a rule the next session loads by itself. Here is how it works, the numbers from our own machine, what went wrong on the way, and how to start one for your team.

Custom software development in Dubai

Why an agent forgets

Each session starts from zero.

Anthropic’s documentation says it plainly: each Claude Code session begins with a fresh context window. Two things carry knowledge across: CLAUDE.md files, which you write, and auto memory, notes Claude writes itself when you correct it. Both load at the start of every session. The same page adds the sentence that shaped everything we built: Claude treats memory as context, not enforced configuration. A rule in a file is advice the agent reads. If something must never happen, the documentation points to a hook, a small program that runs before a tool call and can refuse it. Session transcripts do not keep lessons either. Claude Code deletes old transcripts after a retention period, while the memory files are kept. A lesson that stays inside one session’s conversation is gone within weeks.

The engine, part by part

counted on our machine on 4 November 2026

Six parts, one loop.

  • A defect log. Every bug gets an entry in the same change as its fix: who found it, where, the mechanism, the measured blast radius, the cause, the fix and the test that pins it. 546 entries so far.
  • A mechanism index. Each entry names the shape of the bug, not just the symptom, so the next agent can hunt the shape before anyone reports it.
  • Lessons that apply to any project: 14 topic files, 4,285 lines, each rule written as “never X, always Y, because Z” with the real case that taught it.
  • Project rules split by area, loaded only when an agent touches matching files. Our main project file went from about 102 KB to 22 KB.
  • Hooks for what must not depend on the agent’s judgement: 8 hook commands on 5 events, from keeping secrets out of the chat to stopping runaway loops.
  • Reviewer agents that read new code against those rules: 14 of them in our main project, from a security auditor to a UI inspector.

Part one

a defect becomes a rule the same day

Log the shape, not just the bug.

The rule is short: a failure that is fixed and not written down will be paid for twice. So the entry goes in with the fix, not afterwards, while the numbers are still on the screen. Blast radius is measured, never estimated. “Affects some customers” is worth nothing; “17 of 36 files, one of them ten times out” makes the next person act. The field that pays most is the mechanism. In one week four defects on four unrelated screens turned out to be the same shape: one fact worked out in two places that were free to disagree. Once that shape had a name, an agent searched for it on purpose and found two more that no one had reported. A symptom repeats rarely. A mechanism repeats all the time.

Part two

one home per rule, loaded when it matters

A rule written twice will drift.

Early on, we copied rules wherever they seemed useful. Then a type-checking budget was stated in two files, both numbers were wrong, and the real figure was a third. Now each rule has exactly one home. Lessons that apply to any project live in one shared library; anything naming a file, a script or a number lives with that project. The other store points to it and never repeats it. Size was the second lesson. Anthropic suggests keeping each CLAUDE.md under 200 lines, because longer files cost context and reduce how well the instructions are followed. Ours had grown to about 102 KB and was loaded into every session and every helper agent. On 27 October we split it into seven files that load only when an agent opens matching code: the database rules when it touches the database, the interface rules when it opens a screen. The main file is now 22 KB. It is still 390 lines, so we are not done.

Part three

a note asks, a hook blocks

If it must not happen, do not ask nicely.

Some lessons are too important to leave as advice. Those become hooks. One runs before every tool call and keeps passwords and keys out of the conversation. Another watches for an agent repeating the same command in a loop and refuses the fifth identical call in half an hour. A third adds our morning checklist to the conversation when someone types “good morning”. Others check, at the end of each session, that nothing was left unpushed. The pattern is simple. When a written rule is broken twice, we stop rewording it and ask whether a program can check it instead. A program does not get tired, and it does not decide this case is different.

Part four

learning from the sessions themselves

The transcripts are data too.

Code is not the only thing that teaches. Every session leaves a transcript, so a small script reads a week of them and reports where the effort went. In late October it showed that 92% of our usage came from sessions whose context had grown past 300,000 tokens, and that 89 helper agents had been started without a model chosen, so each one ran on the largest. Both findings became rules the same day: one task per session, and helper agents default to a smaller model unless the work needs judgement. Every session reads them now. Nobody had to remember.

What went wrong on the way

The engine learned these the hard way.

  • A list that excused tests from the main check was a comment in a file. When it became data that the build checks, 89 tests turned out to be running nowhere, and six of them were failing.
  • One group of tests was red for 32 days while the main check stayed green, because nothing ran it. Silence from a test suite is not evidence that it passed.
  • Three defects got past 3,094 passing tests and were found in 20 minutes of one real upload. A green suite proves the code does what the test says, not that the feature works.
  • The memory itself grows. Ours is 323 files, so it lives in its own git history and gets pruned: finished work moves to an archive, and a pruned line can always be read back.

How to start one this week

Five files and one habit.

  • Keep a defect log in the repository. Seven lines per bug, written in the same change as the fix: found by, where, mechanism, blast radius, cause, fix, pinned by.
  • Write rules as “never X, always Y, because Z”, with the real case that taught it. A rule without its reason gets relaxed by the first agent that finds it inconvenient.
  • Keep CLAUDE.md short. Move area-specific rules into .claude/rules files with paths, so they load only when they apply.
  • Turn anything that must never happen into a hook. A PreToolUse hook can refuse a command whatever the agent decides.
  • Read your own transcripts once a week before the retention period deletes them. Where the time went is usually the first lesson.

Why we built it

Agents that hold real keys have to remember.

We are an AI lab in Dubai. The agents we build for UAE businesses read accounts, answer customers and write to real systems. An agent that repeats last month’s mistake in a client’s data is not a learning experience, it is an incident. The learning engine is how we make sure the second time does not happen, and we bring the same discipline to the agents we build for you.

AI agents, built in Dubai

Questions

Questions about Claude Code memory.

  • Does Claude Code have memory?

    Yes, two kinds. CLAUDE.md files hold instructions you write, at project, user or organisation level. Auto memory holds notes Claude writes itself from your corrections. Both load at the start of every session. Each session otherwise starts with a fresh context window.

  • Where is Claude Code memory stored?

    Auto memory lives in ~/.claude/projects/<project>/memory/, with a MEMORY.md index and one file per memory. It is machine-local and shared by every worktree of the same repository. CLAUDE.md files live in your project, in ~/.claude for personal rules, or in an organisation-wide location.

  • How long should CLAUDE.md be?

    Anthropic suggests under 200 lines per file, because longer files use more context and reduce adherence. Move rules that apply to only part of the code into .claude/rules files with path patterns, which load only when Claude works with matching files.

  • What are CLAUDE.md best practices?

    Keep it short and specific, give each rule one home, write the reason next to the rule, move area-specific rules into path-scoped files, and turn anything that must never happen into a hook rather than a sentence.

  • Can AI agents learn from their mistakes?

    Not by themselves between sessions. They can if the lesson is written where the next session loads it: a rule file, a memory entry, a test or a hook. The work is making that writing a habit, done in the same change as the fix.

  • What is the difference between hooks and CLAUDE.md?

    CLAUDE.md is context the model reads and usually follows. A hook is a program Claude Code runs at a fixed point, such as before a tool call, and a PreToolUse hook can deny the call whatever the model decided.

Sources

read 4 November 2026

Check it at the source.

  1. Claude Code: how Claude remembers your project (CLAUDE.md, auto memory, path-scoped rules, size guidance)
  2. Claude Code: hooks reference (hook events, and how a PreToolUse hook denies a call)
  3. Claude Code: get started with hooks (worked examples)

A question?

Want agents that remember?

Tell us where your team’s AI tools keep repeating a mistake. We will show you where the lesson should live, and what should be a hook instead.

Talk to usWhatsApp +971 50 728 5494hello@brevdigital.com