Treating AGENTS.md like a neural net: Kun Chen's guide to agent memory files

X postKun ChenOpinion

Kun Chen proposes an engineering framework for managing AGENTS.md and CLAUDE.md files: user-level preferences should be handwritten, while repository-level instructions should be treated like a neural network with a strict token budget and refined via backward passes on real session transcripts.

Key points

  1. Common failure modes in project memory files: empty skeletons, bloated ad-hoc rulebooks, stale instructions, and drift across different harness files.
  2. Separation of concerns: User-level files (~/.claude/CLAUDE.md) hold personal engineering values and should remain small, stable, and purely handwritten.
  3. Project-level memory acts as neural net weights: Each agent run represents a forward pass, while mistakes and rediscovery represent the loss.
  4. Backward passes rely on session transcripts from tools like Claude Code, Cursor, or Codex to identify systemic issues across batches rather than single anecdotes.
  5. Imposing a fixed token budget forces consolidation and pruning, preventing instruction dilution across extended development cycles.

Why it matters

Appending rules to agent instruction files whenever an LLM makes a mistake inevitably dilutes adherence and inflates inference costs. Framing prompt maintenance as an optimisation loop over logged execution traces offers a systematic approach to keeping agent harnesses effective.

Analysis

Chen provides a practical analogy mapping deep learning concepts directly to prompt and context management. Rather than viewing repository markdown files as static documentation, he treats them as latent weights loaded into every forward pass. By utilizing execution logs that agent harnesses already write to disk, developers can calculate empirical loss and prune obsolete instructions within an explicit token constraint.

Original post

Kun Chen

@kunchenguid · 23 August 2026

many people asked me how to write CLAUDE.md or AGENTS.md, and i see lots of bad advice flying around so i took some time to write down a guide in t.co/QLAWfVhCFV tl;dr - handwrite your user level AGENTS.md - for project level ones, you don't write it. you train it like

1.3k likes50 replies2.8k bookmarks93.5k views

View on X

Mentioned links

Links and tools from this entry

Summary generated by AI (Gemini 3.8 Flash, 27 September 2026). It may contain errors – the original source is authoritative.

Related entries

Similar in content, found by the AI search.

  • Article:Kun Chen

    Treating AGENTS.md as a Neural Net: Kun Chen Introduces Backpass

    Kun Chen argues that project-level memory files like AGENTS.md or CLAUDE.md should be treated as neural network weights. Rather than manually appending rules based on anecdotes, he applies a gradient-descent loop driven by actual session transcripts, implemented in the open-source CLI tool backpass.

    AI & LLMs· Tool

  • X post:Kun Chen

    backpass: Gradient Descent for AGENTS.md and CLAUDE.md

    Kun Chen recommends against immediately rewriting CLAUDE.md or AGENTS.md when switching to newly released AI models. Instead, teams should keep their existing setup initially and use the open-source CLI tool backpass to propose evidence-backed refinements derived from session transcripts.

    633bookmarks57.2kviews

    AI & LLMs· Tool

  • X post:Kun Chen

    Optimising AI Agent Skills via Backward Pass over Transcripts

    Kun Chen advocates systematically optimising AI assistant memory and skill files using a 'backward pass'. Instead of reacting to one-off anecdotes, large samples of session transcripts should be analysed to distill losses and update skills systematically.

    378bookmarks9.5kviews

    AI & LLMs· Discussion

  • Article:Anthropic

    How Claude Code Retains Project Context: CLAUDE.md and Auto Memory Explained

    Anthropic outlines the memory architecture of Claude Code. Because every session starts with a clean context window, the CLI tool relies on two complementary systems: user-defined CLAUDE.md files for explicit instructions and an auto memory feature that records learnings from user feedback.

    AI & LLMs· Resource

  • Repository:kunchenguid/backpass

    backpass: Gradient Descent for Agent Memory and AGENTS.md

    backpass is an open-source CLI tool that parses local agent transcripts to propose evidence-backed updates to project memory files like AGENTS.md or CLAUDE.md.

    776starsJavaScript

    AI & LLMs· Tool

Back to the knowledge base

Let's talk about your project

Get in touch

Locations

  • Mattersburg
    Johann Nepomuk Bergerstraße 7/2/14
    7210 Mattersburg, Austria
  • Vienna
    Ungargasse 64-66/3/404
    1030 Wien, Austria

Parts of this content were created with the assistance of AI.