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

ArticleKun ChenTool

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.

Key points

  1. Project memory files typically degrade into four states: empty, bloated (diluting instruction following), stale, or drifted across different harnesses.
  2. Two distinct levels: user-level files (~/AGENTS.md) hold personal preferences and must be handwritten; project-level files act as weights steering agent behavior.
  3. The neural net mapping: AGENTS.md represents weights, an agent session is a forward pass, mistakes in transcripts represent loss, and updating instructions is the backward pass.
  4. Training principles: evidence must come from verbatim transcript quotes, changes should be batched across sessions, step sizes kept small (e.g. five edits), and token budgets strictly respected.
  5. Skills as a release valve: broadly relevant or safety-critical instructions stay in the core file, while narrow triggers are extracted into skills or pruned.
  6. The backpass tool (MIT licence) parses transcripts from local harnesses, deterministically aggregates gradients, proposes minimal diffs, and enforces human review before applying changes.

Why it matters

As repositories adopt agentic coding harnesses, bloated instruction files lead to context waste and instruction dilution. Applying a rigorous, loss-driven update cycle ensures agent instructions stay accurate, relevant, and bounded within a strict token budget.

Analysis

Chen provides a structured framework for what has largely been an ad-hoc practice. By framing AGENTS.md maintenance as gradient descent, he introduces clear constraints: deterministic batching, verbatim transcript evidence, and token budgets. Automating transcript distillation while maintaining a manual human gate strikes an effective balance between pragmatic automation and developer control.

Mentioned links

Found in

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.

  • 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

  • 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

  • X post:Kun Chen

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

    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.

    2.8kbookmarks93.5kviews

    AI & LLMs· Opinion

  • 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

  • X post:PostHog

    The Evolving Role of AGENTS.md and CLAUDE.md Context Files

    This discussion explores the effectiveness of using context files like AGENTS.md or CLAUDE.md to guide AI coding assistants. While some developers find them essential for project-specific instructions, others argue they often become technical debt that grows stale and hinders model performance.

    1.1kbookmarks48kviews

    AI & LLMs

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.