Why Your Claude Agent Repeats the Same Mistakes

Claude does not learn because a run ended.

It learns only when the next run receives a tested lesson from the previous one.

That distinction explains why many agent memory files grow while behavior stays flat. Notes are stored, but nothing decides which lesson is trustworthy, when it applies, or whether the agent should see it before acting.

The journal pattern fixes that gap with a small loop:

event -> observation -> candidate rule -> test -> accepted rule -> retrieval

This guide gives you the file structure, schemas, promotion test, and retrieval prompt needed to run that loop in a normal repository.

Start with evidence, not a permanent rule

Suppose an agent edits src/generated/client.ts. The build regenerates the file and erases the change.

A weak journal entry says:

Claude keeps editing the wrong files.

That sentence records frustration. It does not record evidence, scope, or a safe alternative.

Capture the event as an observation instead:

id: obs-2026-07-16-001
task: add_retry_header
trigger: modifying the generated API client
observed:
  - agent edited src/generated/client.ts
  - pnpm generate:client replaced the edit
evidence:
  changed_file: src/generated/client.ts
  generator_config: openapi/client.config.ts
  verification: git diff was empty after regeneration
status: observed

The observation stays narrow. It says what happened and how you verified it.

It does not claim that generated files are never editable in every repository. One incident cannot support that rule.

Use this evidence ladder:

This separation stops one bad run from becoming permanent doctrine.

Turn the observation into a testable rule

A useful rule tells the next agent what to do, where it applies, and how to verify the result.

id: rule-generated-api-client
derived_from:
  - obs-2026-07-16-001
scope:
  path_globs:
    - "src/generated/**"
  task_signals:
    - "API client"
    - "OpenAPI"
instruction: >
  Treat files under src/generated as outputs.
  Locate the generator input, change that source, regenerate,
  and inspect the resulting diff.
verification:
  - pnpm generate:client
  - git diff --check
status: testing

Now run a bounded task with explicit pass conditions:

TASK
Add a request header to the generated API client.
 
PASS
1. No direct edit remains under src/generated.
2. The generator input contains the change.
3. Regeneration produces the expected client diff.
4. Tests pass.

If the rule works, promote it to accepted. If it blocks a valid workflow, narrow the path or task signals. If the agent never received it, fix retrieval before rewriting the instruction.

That diagnosis matters:

• Rule absent: retrieval failed.
• Rule present but ambiguous: instruction failed.
• Rule followed but result wrong: the rule failed.
• Verification missing: the test design failed.

Without those states, every failure looks like “the model ignored me.”

Retrieve lessons before the decision

Anthropic describes context as a finite resource that should contain the smallest high-signal set needed for the task. Its guidance favors selective, just-in-time retrieval over loading every possible document up front. Anthropic: Effective context engineering for AI agents

Apply that principle to the journal.

Do not load the full archive at session start. Match accepted rules against:

• repository
• task type
• target path
• named tool
• risk level
• failure signature

Use two retrieval points.

At task start

Classify this task by repository, component, action type, and risk.
 
Retrieve no more than five accepted rules matching a strong signal:
- target path
- named tool
- action type
- known failure signature
 
For each rule, return:
- rule id
- why it matched
- required behavior
- verification step
 
Ignore observations and untested rules.
Stop if accepted rules conflict.

Before a risky action

ACTION: edit src/generated/client.ts
 
Retrieve accepted rules matching this action, path, or tool.
 
If a rule blocks the direct action:
1. Stop.
2. Name the compliant alternative.
3. Show the required verification.

A lesson retrieved after an edit can explain the failure. A lesson retrieved before it can prevent the failure.

Timing is part of memory quality.

Magnet: Tested Agent Journal

Start with files. Add a database only when matching and review volume make files painful.

.agent/
  journal/
    observations/
    tests/
    rules/
    retired/
  index.json
  prompts/
    capture.md
    promote.md
    retrieve.md

Run this protocol after any repeatable success, failure, correction, or recovery:

TESTED AGENT JOURNAL
 
1. CAPTURE
Record the event, task, evidence, and verifier output.
 
2. EVALUATE
Ask whether it may recur, whether evidence is inspectable,
and whether code should enforce the behavior instead.
 
3. TEST
Create one bounded task with explicit pass conditions.
 
4. PROMOTE
Add scope, instruction, verification, provenance, version,
and a review condition.
 
5. RETRIEVE
Load the accepted rule before the next matching decision.
 
6. REVIEW
Retire the rule when paths, commands, or constraints change.

You should see: the second matching run names one accepted rule before acting and produces verifier output after the change.

Move stable lessons into cheaper controls

The journal should not become a substitute for engineering.

If a linter can reject the mistake, write the linter. If permissions can prevent the action, change the permissions. If a test can encode the invariant, add the test.

Use this progression:

handoff -> observation -> tested rule -> skill or automated check

Each artifact has a different job:

Use memory for judgment. Use code for enforcement.

Measure behavior instead of file count

A large journal may mean the system is learning. It may also mean the system produces paperwork.

Track the loop:

• observations with inspectable evidence
• candidate rules tested
• rules accepted
• matching tasks where retrieval fired
• matching tasks where retrieval was missed
• repeated failure signatures
• rules retired or converted into checks

The main metric is repeat-error rate by failure signature.

If the same failure continues, locate the broken transition:

failure observed
-> evidence captured
-> response tested
-> rule accepted
-> rule retrieved
-> behavior verified

Do not solve a retrieval failure by adding more prose.

FAQ

Is an agent journal the same as memory?

No. Memory stores information. The journal adds evidence states, testing, promotion, retrieval, and retirement so selected lessons can change future behavior.

Do I need a vector database?

Start with files and metadata. Add semantic retrieval only when path, task, tool, and failure-signature matching no longer retrieves the right rules.

Should the agent write its own rules?

It can propose observations and candidate rules. Promotion should require verifier evidence and an accountable review step.

Failure modes

When not to use a journal

Skip the journal when:

• the task will not recur
• a deterministic check already catches the failure
• no verifier can tell whether behavior improved
• the lesson is a temporary handoff state
• the proposed rule cannot be scoped

More memory does not create continuity.

A tested lesson, retrieved before the matching decision, does.

Your next action: install the Tested Agent Journal for one recurring failure and run its promotion test twice.

Continue with Agent OS for solo developers or download the 30-point Agent OS checklist.