The Agentic Field Notes

01-living-memory.md

The Agentic Field Notes

01 — The Living Memory Manifesto

A framework for collective agent intelligence across projects

---

The problem with AI agents and memory

An AI agent is only as good as what it knows at the moment it runs.

Without memory, every run starts from zero. The agent sees a commit, does its job, and forgets everything. It will flag the same pattern tomorrow that it flagged today. It will never get better at understanding this project, this team, these recurring mistakes.

With naive memory — just appending observations forever — you get the opposite problem. The memory grows, stales, contradicts itself. Old conventions that no longer apply. Patterns from a refactored module that doesn't exist anymore. The agent drowns in its own history and starts making confident decisions based on irrelevant past.

Neither is acceptable for a system meant to run in production, indefinitely, across multiple projects.

---

The core idea : memory as a living organism

Memory should behave like collective human knowledge in a team.

When one developer notices something once, it's a hunch. When three developers notice the same thing independently, it becomes a convention. When nobody has seen it in months, it fades. When the codebase changes and the pattern disappears, the knowledge disappears with it — naturally, without anyone having to manually clean it up.

This is what the scoring system emulates :

• +10 every time an observation is confirmed by any agent on any run
• -1 on every run, regardless — slow, constant decay
• Cap at 100 — no pattern becomes untouchable
• Floor at 0 — death. Clean, automatic, no ghosts.

A pattern that is real and recurring will be seen again and again. It will stay alive. A pattern that was a one-time anomaly will fade within weeks. The memory self-regulates.

---

Memory is per project, not per agent

This is a critical architectural decision.

Agents are generic. They are templates — SIMILARITY-HUNTER, ERROR-CHECKER, MEMORY-CURATOR — deployed identically across every project. They have no intrinsic knowledge of what they are reviewing.

Projects are specific. Project A has its own stack, its own conventions, its own recurring mistakes, its own history of bad commits. Project B has entirely different ones.

The memory belongs to the project, not to the agent.

When SIMILARITY-HUNTER runs on a project, it loads that project's memory. When it runs on another, it loads that one's memory. Same agent, different context, different intelligence. The agent is the tool. The memory is the knowledge.

This also means memory is owned and auditable by the team working on that project. It is not a black box inside an agent. It is a versioned markdown file, in a git repo, that a human can read, edit, and understand at any time.

---

Two layers of memory

Not all knowledge is equal.

Hard memory is written and maintained by humans. Stack conventions, architectural decisions, non-negotiable rules. It does not decay. It is not touched by agents. It is the foundation.

Soft memory is written by agents, curated by MEMORY-CURATOR. Observed patterns, recurring issues, emerging conventions. It lives, scores, and dies on its own. It is the accumulation of machine observation over time.

Agents read both. Agents write only to soft memory. Humans manage hard memory. Neither crosses into the other's territory.

---

The role of MEMORY-CURATOR

MEMORY-CURATOR is not a reviewer. It does not look at code.

It is the janitor, the librarian, and the statistician of the system — all at once.

It runs periodically. It reads what every agent has observed since its last run. It promotes confirmed patterns, decays cold ones, and deletes dead ones. It keeps the soft memory honest.

Without it, the system accumulates noise. With it, the memory stays lean, relevant, and trustworthy.

It is the least glamorous agent in the system. It is also the one that makes every other agent smarter over time.

---

What this enables

After weeks and months of running, the system develops a genuine understanding of each project it monitors.

It knows which parts of the codebase are fragile. It knows which patterns this team tends to miss. It knows what a "normal" commit looks like versus an anomalous one. It knows the difference between a one-time mistake and a systemic problem.

This is not AGI. It is not magic. It is pattern recognition accumulated over time, scored by frequency, kept honest by decay, and made transparent by a simple markdown file anyone can read.

It is what a senior developer does naturally after years on a project — except it never forgets a run, never gets tired, and works across every project simultaneously.

---

Principles

1. Memory belongs to the project, not the agent.
2. Frequency builds confidence. Absence erodes it.
3. No entry is permanent. Everything decays.
4. Humans own the foundation. Agents own the accumulation.
5. Transparency over magic — memory is always a readable file.

02-project-memory-structure.md

The Agentic Field Notes

02 — Project Memory Structure

How agents store, share, and consume knowledge across projects

---

The agents

SIMILARITY-HUNTER — triggered on every commit. Reads the diff, scans the codebase for similar patterns, flags locations that may need the same changes. ERROR-CHECKER — triggered on every commit. Reads the diff, looks for logical errors, edge cases, regressions, and inconsistencies introduced by the change. MEMORY-CURATOR — runs periodically. Never touches code. Consolidates daily observations into scored patterns, decays cold entries, deletes dead ones.

---

Memory structure per project

Every project gets its own memory directory. Agents are generic — memory is not.

projects/
  alpha/
    memory/
      hard/
        conventions.md       ← human-maintained, never decays
        stack.md             ← human-maintained, never decays
      soft/
        patterns.md          ← curated by MEMORY-CURATOR, scored
      logs/
        daily/
          2026-03-15.md      ← raw observations from agents
          2026-03-16.md
          2026-03-17.md
        archive/
          2026-02.md         ← processed logs, compressed by MEMORY-CURATOR

  beta/
    memory/
      hard/
        conventions.md
        stack.md
      soft/
        patterns.md
      logs/
        daily/
          2026-03-17.md
        archive/

  gamma/
    memory/
      hard/
        conventions.md
        stack.md
      soft/
        patterns.md
      logs/
        daily/
        archive/

---

What gets stored : daily logs

Raw, unfiltered. Every agent appends its observations after a run. No scoring, no deduplication at this stage.

projects/alpha/memory/logs/daily/2026-03-17.md

[SIMILARITY-HUNTER] Input fields added in PaymentForm.php — 
similar unvalidated fields found in SubscriptionForm.php:112 and ProfileForm.php:87

[SIMILARITY-HUNTER] New status constant STATUS_PENDING added — 
similar pattern without constants in OrderController.php:203, InvoiceService.php:56

[ERROR-CHECKER] Null check missing on $user->profile before access in AuthController.php:34

[ERROR-CHECKER] Loop added without break condition in SyncService.php:78 — 
potential infinite loop if API returns empty array

[ERROR-CHECKER] New migration does not handle rollback — down() method is empty

projects/beta/memory/logs/daily/2026-03-17.md

[SIMILARITY-HUNTER] Pagination logic duplicated across 3 controllers — 
UserController.php:145, ProductController.php:98, OrderController.php:211

[ERROR-CHECKER] Hardcoded environment URL found in PaymentGateway.php:23

[ERROR-CHECKER] New feature flag added but never cleaned up from previous sprint — 
FEATURE_NEW_DASHBOARD still present in 6 files

---

What gets curated : soft memory

After MEMORY-CURATOR runs, confirmed patterns land in patterns.md with a score. This is what agents load as context on their next run.

projects/alpha/memory/soft/patterns.md

[94] Form fields added without server-side validation
[71] Status values hardcoded as strings instead of constants
[58] Null checks missing before object property access
[32] Migration down() methods left empty
[17] API response not checked for empty array before iteration
[4]  Unnamed anonymous functions used in event listeners

projects/beta/memory/soft/patterns.md

[88] Pagination logic duplicated across controllers instead of shared service
[63] Hardcoded environment-specific values in service classes
[41] Stale feature flags never removed after sprint completion
[12] Raw SQL queries mixed with ORM in the same module

projects/gamma/memory/soft/patterns.md

[77] Missing index on foreign keys in migrations
[29] Console.log statements reaching production builds

---

What gets loaded : memory in use

When an agent starts a run, it receives three context blocks :

1. Hard memory — always injected, full content. Tells the agent what this project is, how it is built, what conventions the team follows.

# stack.md (alpha)
PHP 8.2 / Laravel 11 / MySQL 8
Frontend : Vanilla JS, no framework
Deployment : shared hosting via FTP
No test suite currently in place

# conventions.md (alpha)
- All form inputs must be validated server-side in a dedicated FormRequest class
- Status values must be defined as constants in a dedicated Enum
- Migrations must always implement a rollback in down()
- No hardcoded strings for environment-specific values

2. Soft memory — injected with scores, high scores first, truncated after threshold. Tells the agent what this project tends to get wrong, ranked by confidence.

Known recurring patterns (ranked by confidence) :

[94] Form fields added without server-side validation
[71] Status values hardcoded as strings instead of constants
[58] Null checks missing before object property access
[32] Migration down() methods left empty
...

3. The task — the commit diff, injected last. This is what the agent actually works on. Everything above is context. This is the job.

---

The difference between stored and used

Stored memory is everything that has ever been observed — raw logs, archived runs, the full history of patterns including dead ones before deletion. It lives on disk. It is the record. Used memory is the filtered, scored, ranked subset that gets injected into an agent's context window at runtime. It is lean by design. An agent never loads the full history — it loads the current state of what is known and relevant. The gap between the two is what MEMORY-CURATOR manages. It decides what crosses from stored to used, what stays alive, and what disappears.

---

Cross-project isolation

Agents never share memory across projects. Alpha's patterns never influence a run on Beta. This is intentional. A pattern that is endemic to one codebase says nothing about another. Injecting cross-project memory would dilute signal with noise and produce confident but irrelevant observations. Each project's memory is its own closed loop. The agents are shared. The knowledge is not.

03-agent-memory.md

The Agentic Field Notes

03 — The Agent Memory Manifesto

Not every agent needs to remember

---

Memory is not a default

In most AI systems, memory is treated as a universal good. More context, more history, more knowledge — the assumption is that an agent with more information will always perform better.

This is wrong.

Memory has a cost. Every piece of context injected into an agent's window is a token spent, a potential distraction, a source of noise. An agent that receives irrelevant history does not ignore it — it reasons through it, weighs it, and produces answers colored by it.

Memory should be a deliberate choice, not a default behavior.

---

Two kinds of agents

Some agents are stateless by nature.

Their job is self-contained. A formatting agent, a translation agent, a report generator — they receive a task, they execute it, they are done. The history of the project they are working on is irrelevant to their output. Injecting memory into these agents does not make them smarter. It makes them slower and less focused.

Some agents are context-dependent by nature.

Their job is to reason about a specific project over time. A pattern detector, a code reviewer, an anomaly spotter — they need to know what this project looks like, what this team tends to miss, what has been seen before. Without memory, they start from zero on every run. They will flag the same thing tomorrow that they flagged today. They will never develop an understanding of the project they are watching.

These two kinds of agents have fundamentally different needs. The system should treat them differently.

---

Memory as a declared property

An agent's relationship to memory is not decided at runtime. It is declared upfront, as part of the agent's definition.

SIMILARITY-HUNTER   memory: true
ERROR-CHECKER       memory: true
MEMORY-CURATOR      memory: true
FORMATTER           memory: false
TRANSLATOR          memory: false
REPORT-GENERATOR    memory: false

This declaration is a contract. It tells the system — and any human reading the config — exactly what this agent expects to receive before it starts working.

The DISPATCHER reads this contract. If memory is true, it loads the project's hard and soft memory before constructing the task payload. If memory is false, it skips that step entirely. No guesswork, no overhead.

---

What this changes

A stateless agent is fully portable. It can run on any project, any task, any context without configuration. Its quality does not depend on what has been accumulated before.

A context-dependent agent is project-aware. It gets sharper over time. The first time it runs on a project it knows very little. After weeks of runs, it carries a scored map of that project's recurring patterns, known weaknesses, and established conventions. It is not the same agent it was on day one.

These are not better or worse agents. They are different tools for different jobs. The system should reflect that distinction explicitly rather than treating all agents as interchangeable.

---

The DISPATCHER's responsibility

The DISPATCHER sits between ROUTER and the agents. Its job is to prepare each agent's context before it runs.

For a stateless agent, preparation is simple — task in, agent out.

For a context-dependent agent, preparation means assembling three layers in order :

1. Hard memory — the stable foundation. Stack, conventions, architectural decisions. Written by humans, never decays.
2. Soft memory — the accumulated intelligence. Scored patterns, recurring observations, known weaknesses. Written by agents, curated by MEMORY-CURATOR.
3. The task — what the agent actually needs to do right now.

The task always comes last. Context first, work second. An agent that receives its task before its context is an agent reasoning in the dark.

---

Principles

1. Memory is earned, not given. An agent receives memory because its job requires it, not by default.
2. Stateless agents are a feature. Portability and focus are valuable. Not every agent should accumulate state.
3. Memory is declared, not inferred. The system never guesses whether an agent needs context. It is told.
4. Context before task, always. An agent must understand where it is before it can understand what to do.
5. The DISPATCHER owns preparation. Agents do not load their own memory. They receive it, already assembled.

README.md

The Agentic Field Notes

A collection of working documents on agentic system design — built around OpenClaw, n8n, and the practical realities of running multi-agent workflows in production.

These are not academic papers. They are field notes — written while building, refined while thinking, useful while doing.

---

Index

01 — The Living Memory Manifesto Memory as a living organism. How agents accumulate knowledge over time without drowning in their own history. The scoring system that keeps memory honest : +10 on confirmation, -1 on every run, death at zero.

02 — Project Memory Structure How memory is organized on disk. What agents store, what gets curated, what gets loaded at runtime. Concrete examples across multiple projects with real log and pattern formats.

03 — The Agent Memory Manifesto Not every agent needs to remember. The case for stateless agents, memory as a declared property, and why the DISPATCHER owns context preparation — not the agents themselves.

---

The agents referenced throughout

Agent	Role	Memory
ROUTER	Identifies project and task from any trigger	false
DISPATCHER	Assembles context, prepares agent payloads	false
SIMILARITY-HUNTER	Finds similar patterns in the codebase	true
ERROR-CHECKER	Reviews changes for errors and regressions	true
MEMORY-CURATOR	Curates soft memory, scores and prunes patterns	true

---

Core principles across all notes

• Agents are generic. Memory is project-specific.
• Few agents, laser accurate. No agent does two jobs.
• Context before task, always.
• Memory is a readable file, never a black box.
• n8n handles determinism. Agents handle reasoning.