AGENTS.md Is Not Enough: Building Project Memory for AI Coding Agents

Dav — Tue, 14 Apr 2026 08:56:27 +0000

Most AI coding workflows still treat project context as chat
state.

That works until you switch tools, start a new session, or try to
keep multiple agent-specific files aligned:

AGENTS.md
CLAUDE.md
.cursorrules
GEMINI.md
Copilot instructions
separate MCP configs

Those files drift. New sessions start from zero. The project keeps
learning, but the next agent never sees it.

I built agentsge to move project intelligence into the
repository itself.

Site: https://agents.ge
Repo: https://github.com/larsen66/agentsge
npm: https://www.npmjs.com/package/agentsge

## The problem

Most teams using AI coding tools are quietly accumulating the same
failure mode:

One tool gets updated instructions.
Another tool still reads old rules.
Session knowledge stays trapped in chat history.
A new agent has to rediscover the same architecture, conventions, and hidden constraints again.

In practice, the repo ends up with fragmented context.

You might have one file telling Claude Code how to behave, another
file for Cursor, a third for Copilot, and no durable place for
“this is how this project actually works”.

The repo has code.
The team has tacit knowledge.
The agents get a partial, drifting copy of both.

## What I wanted instead

I wanted a simple primitive:

one repository-owned memory layer
one place for durable rules and project knowledge
one source of truth that multiple agent tools can inherit

That became:

AGENTS.md as the entrypoint
.agents/ as the durable project memory

The core model is:

AGENTS.md says what to do. .agents/ remembers what the
project learned.

## What agentsge does

agentsge is an open-source CLI that makes a repository agent-
ready.

Run:


bash
  npx agentsge init

  It creates a versioned .agents/ directory and scaffolds the repo
  for AI agent onboarding.

  Typical structure:

  .agents/
    config.yaml
    rules/
      _capture.md
    knowledge/
      _index.md
      architecture/
      patterns/
      lessons/
      conventions/
      dependencies/
    skills/
    mcp/
      config.yaml

  This gives the repo a place to store:

  - project metadata
  - mandatory rules
  - architecture decisions
  - recurring implementation patterns
  - bug lessons
  - team conventions
  - MCP definitions

  All in markdown and YAML, stored in git.

  ## Why not just use AGENTS.md?

  AGENTS.md is useful, but by itself it is not enough.

  It solves entrypoint instructions.
  It does not solve durable project memory.

  A single markdown file is fine for:

  - “read these rules”
  - “start here”
  - “follow this workflow”

  It is much worse for:

  - evolving architecture knowledge
  - accumulating lessons from bugs
  - keeping typed project memory organized
  - syncing multiple agent surfaces over time

  A repo needs both:

  - a front door
  - a memory layer

  AGENTS.md is the front door.
  .agents/ is the memory layer.

  ## Why not just keep everything in README?

  Because README has a different job.

  README should explain the project to humans at a broad level.
  Project memory is operational and specific.

  Examples of things that belong in durable project knowledge but
  not in README:

  - “This subsystem looks independent, but breaks if env X is
    missing”
  - “The bug looked like a frontend issue, but the real cause was a
    backend cache race”
  - “We always extend this adapter instead of writing directly to
    that integration point”
  - “This dependency exists because the obvious alternative failed
    in production”

  That kind of knowledge is too detailed, too volatile, or too
  implementation-specific for README, but too important to lose.

  ## The knowledge model

  I kept the memory model intentionally small.

  There are five knowledge types:

  - architecture
  - pattern
  - lesson
  - convention
  - dependency

  That gives enough structure to be useful without turning the repo
  into a database.

  Examples:

  - architecture: why a structural decision was made, including
    rejected alternatives
  - pattern: a reusable implementation shape across multiple files
  - lesson: a bug where the symptom pointed away from the cause
  - convention: a team rule that is not obvious from code alone
  - dependency: a non-obvious reason a package or workaround exists

  The goal is not to create documentation overhead.

  The goal is to preserve the kinds of context that future agents
  and future contributors would otherwise have to rediscover.

  ## Cross-agent sync

  Another problem I wanted to fix was tool fragmentation.

  Even if the repo has good context, every tool wants it in a
  different shape.

  So agentsge can sync agent-facing surfaces from the project’s
  source of truth.

  That means .agents/ can drive:

  - AGENTS.md
  - CLAUDE.md
  - .cursorrules
  - GEMINI.md
  - MCP config targets for different tools

  Instead of manually maintaining parallel copies, the repo owns the
  knowledge and tool-specific files stay thin.

  ## Automatic knowledge capture

  One part I found especially interesting was capture.

  Most useful project knowledge is not written during setup.
  It emerges while doing real work.

  A bug gets fixed.
  A weird constraint gets discovered.
  A pattern becomes obvious after the third repeated change.

  So agentsge also supports hook-based capture.

  The idea is:

  - session starts
  - file changes get logged
  - session ends
  - the diff is analyzed
  - candidate knowledge items go into pending/
  - a human accepts or rejects them

  That keeps the system from becoming either:

  - a static config generator
  - or an uncontrolled note dump

  ## What I like about this approach

  A few properties matter to me:

  ### 1. The project owns the context

  Not the vendor.
  Not the chat thread.
  Not one specific tool.

  ### 2. It stays in git

  That means:

  - reviewable
  - diffable
  - portable
  - easy to delete
  - easy to move between tools

  ### 3. It is intentionally boring

  Markdown and YAML are not magical.
  That is the point.

  ### 4. It separates entrypoint from memory

  This turned out to be a much cleaner model than trying to stuff
  everything into one file.

  ## Current state

  The public site and docs are here:

  - https://agents.ge
  - https://agents.ge/docs

  The site is prerendered and crawlable, and I also added:

  - route-level metadata
  - structured data
  - robots.txt
  - sitemap.xml
  - llms.txt
  - llms-full.txt

  because I wanted the project to be understandable not just to
  users, but also to search engines and LLM-based discovery systems.

  ## Example

  The basic starting point is still intentionally simple:

  npx agentsge init

  After that, the repo can onboard an agent with:

  - project config
  - required rules
  - existing knowledge
  - reusable workflows
  - synced entrypoints

  ## What I’m trying to learn

  I’m still interested in feedback on a few open questions:

  1. Is .agents/ a good primitive, or is this too much structure?
  2. Is the five-type knowledge model about right, or too
     opinionated?
  3. Is cross-agent sync genuinely useful, or just compensating for
     poor tooling ecosystems?
  4. How much project memory should be explicit versus auto-
     captured?

  If this sounds useful, I’d love feedback.

  - Site: https://agents.ge
  - Repo: https://github.com/larsen66/agentsge
  - npm: https://www.npmjs.com/package/agentsge


  Если хочешь, я могу сразу ещё подготовить:
  - более короткую версию статьи
  - Reddit post
  - X thread на 5-7 твитов
  - первую картинку/cover text для dev.to article


› используй md форматирование


• # AGENTS.md Is Not Enough: Building Project Memory for AI Coding
  Agents

  How I stopped repo context from drifting across Claude Code,
  Cursor, Codex, Copilot, and other AI coding tools.

  Most AI coding workflows still treat project context as chat
  state.

  That works until you switch tools, start a new session, or try to
  keep multiple agent-specific files aligned:

  - AGENTS.md
  - CLAUDE.md
  - .cursorrules
  - GEMINI.md
  - Copilot instructions
  - separate MCP configs

  Those files drift. New sessions start from zero. The project keeps
  learning, but the next agent never sees it.

  I built agentsge to move project intelligence into the repository
  itself.

  - Site: https://agents.ge (https://agents.ge)
  - Repo: https://github.com/larsen66/agentsge
    (https://github.com/larsen66/agentsge)
  - npm: https://www.npmjs.com/package/agentsge
    (https://www.npmjs.com/package/agentsge)

  ## The problem

  Most teams using AI coding tools are quietly accumulating the same
  failure mode:

  1. One tool gets updated instructions.
  2. Another tool still reads old rules.
  3. Session knowledge stays trapped in chat history.
  4. A new agent has to rediscover the same architecture,
     conventions, and hidden constraints again.

  In practice, the repo ends up with fragmented context.

  You might have one file telling Claude Code how to behave, another
  file for Cursor, a third for Copilot, and no durable place for
  “this is how this project actually works”.

  The repo has code.
  The team has tacit knowledge.
  The agents get a partial, drifting copy of both.

  ## What I wanted instead

  I wanted a simple primitive:

  - one repository-owned memory layer
  - one place for durable rules and project knowledge
  - one source of truth that multiple agent tools can inherit

  That became:

  - AGENTS.md as the entrypoint
  - .agents/ as the durable project memory

  The core model is:

  > AGENTS.md says what to do. .agents/ remembers what the project
  > learned.

  ## What agentsge does

  agentsge is an open-source CLI that makes a repository agent-
  ready.

  Run:

  npx agentsge init

  It creates a versioned .agents/ directory and scaffolds the repo
  for AI agent onboarding.

  Typical structure:

  .agents/
    config.yaml
    rules/
      _capture.md
    knowledge/
      _index.md
      architecture/
      patterns/
      lessons/
      conventions/
      dependencies/
    skills/
    mcp/
      config.yaml

  This gives the repo a place to store:

  - project metadata
  - mandatory rules
  - architecture decisions
  - recurring implementation patterns
  - bug lessons
  - team conventions
  - MCP definitions

  All in Markdown and YAML, stored in git.

  ## Why not just use AGENTS.md?

  AGENTS.md is useful, but by itself it is not enough.

  It solves entrypoint instructions.
  It does not solve durable project memory.

  A single Markdown file is fine for:

  - “read these rules”
  - “start here”
  - “follow this workflow”

  It is much worse for:

  - evolving architecture knowledge
  - accumulating lessons from bugs
  - keeping typed project memory organized
  - syncing multiple agent surfaces over time

  A repo needs both:

  - a front door
  - a memory layer

  AGENTS.md is the front door.
  .agents/ is the memory layer.

  ## Why not just keep everything in README?

  Because README has a different job.

  README should explain the project to humans at a broad level.
  Project memory is operational and specific.

  Examples of things that belong in durable project knowledge but
  not in README:

  - “This subsystem looks independent, but breaks if env X is
    missing”
  - “The bug looked like a frontend issue, but the real cause was a
    backend cache race”
  - “We always extend this adapter instead of writing directly to
    that integration point”
  - “This dependency exists because the obvious alternative failed
    in production”

  That kind of knowledge is too detailed, too volatile, or too
  implementation-specific for README, but too important to lose.

  ## The knowledge model

  I kept the memory model intentionally small.

  There are five knowledge types:

  - architecture
  - pattern
  - lesson
  - convention
  - dependency

  That gives enough structure to be useful without turning the repo
  into a database.

  Examples:

  - architecture: why a structural decision was made, including
    rejected alternatives
  - pattern: a reusable implementation shape across multiple files
  - lesson: a bug where the symptom pointed away from the cause
  - convention: a team rule that is not obvious from code alone
  - dependency: a non-obvious reason a package or workaround exists

  The goal is not to create documentation overhead.

  The goal is to preserve the kinds of context that future agents
  and future contributors would otherwise have to rediscover.

  ## Cross-agent sync

  Another problem I wanted to fix was tool fragmentation.

  Even if the repo has good context, every tool wants it in a
  different shape.

  So agentsge can sync agent-facing surfaces from the project’s
  source of truth.

  That means .agents/ can drive:

  - AGENTS.md
  - CLAUDE.md
  - .cursorrules
  - GEMINI.md
  - MCP config targets for different tools

  Instead of manually maintaining parallel copies, the repo owns the
  knowledge and tool-specific files stay thin.

  ## Automatic knowledge capture

  One part I found especially interesting was capture.

  Most useful project knowledge is not written during setup.
  It emerges while doing real work.

  A bug gets fixed.
  A weird constraint gets discovered.
  A pattern becomes obvious after the third repeated change.

  So agentsge also supports hook-based capture.

  The idea is:

  - session starts
  - file changes get logged
  - session ends
  - the diff is analyzed
  - candidate knowledge items go into pending/
  - a human accepts or rejects them

  That keeps the system from becoming either:

  - a static config generator
  - or an uncontrolled note dump

  ## What I like about this approach

  A few properties matter to me.

  ### 1. The project owns the context

  Not the vendor.
  Not the chat thread.
  Not one specific tool.

  ### 2. It stays in git

  That means it is:

  - reviewable
  - diffable
  - portable
  - easy to delete
  - easy to move between tools

  ### 3. It is intentionally boring

  Markdown and YAML are not magical.
  That is the point.

  ### 4. It separates entrypoint from memory

  This turned out to be a much cleaner model than trying to stuff
  everything into one file.

  ## Current state

  The public site and docs are here:

  - https://agents.ge (https://agents.ge)
  - https://agents.ge/docs (https://agents.ge/docs)

  The site is prerendered and crawlable, and I also added:

  - route-level metadata
  - structured data
  - robots.txt
  - sitemap.xml
  - llms.txt
  - llms-full.txt

  because I wanted the project to be understandable not just to
  users, but also to search engines and LLM-based discovery systems.

  ## Example

  The basic starting point is still intentionally simple:

  npx agentsge init

  After that, the repo can onboard an agent with:

  - project config
  - required rules
  - existing knowledge
  - reusable workflows
  - synced entrypoints

  ## What I’m trying to learn

  I’m still interested in feedback on a few open questions:

  1. Is .agents/ a good primitive, or is this too much structure?
  2. Is the five-type knowledge model about right, or too
     opinionated?
  3. Is cross-agent sync genuinely useful, or just compensating for
     poor tooling ecosystems?
  4. How much project memory should be explicit versus auto-
     captured?

  If this sounds useful, I’d love feedback.

  - Site: https://agents.ge (
  - Repo: https://github.com/larsen66/agentsge
  - npm: https://www.npmjs.com/package/agentsge

DEV Community: Dav

AGENTS.md Is Not Enough: Building Project Memory for AI Coding Agents