Stop Managing CLAUDE.md Manually: Use agentsge for a Single Source of Truth

The Problem: Your Project Context is Drifting

If you use Claude Code alongside other AI dev tools, you're managing multiple, fragmented context files. You update CLAUDE.md with a new project convention, but forget to add it to .cursorrules. A critical lesson from a bug fix is trapped in a chat history. The next time you—or a teammate—start a new session, the AI agent starts from zero, rediscovering constraints you already solved.

This is the silent failure mode the agentsge project aims to fix. It's not enough to have an entry point like AGENTS.md or CLAUDE.md. Your repository needs a durable memory layer.

The Solution: A Centralized .agents/ Directory

agentsge is an open-source CLI tool that scaffolds a versioned, git-tracked memory system for your project. The core model is simple:

• AGENTS.md / CLAUDE.md is the front door. It gives the agent entrypoint instructions.
• .agents/ is the memory layer. It stores what the project has learned.

To initialize it in your repository, run:

npx agentsge init

This creates a .agents/ directory with this typical structure:

.agents/
  config.yaml
  rules/          # Mandatory rules
  knowledge/      # The core memory bank
    _index.md
    architecture/ # Why structural decisions were made
    patterns/     # Reusable implementation shapes
    lessons/      # Bug post-mortems & hidden causes
    conventions/  # Team rules not obvious from code
    dependencies/ # Non-obvious package rationales
  skills/         # Reusable workflows
  mcp/            # MCP server configs

All content is Markdown and YAML, living right in your git repo.

Why This Beats a Single CLAUDE.md File

A CLAUDE.md file is great for static instructions: "read these rules," "start here." It's terrible for evolving knowledge. The five knowledge types in .agents/ capture what you actually learn while coding:

• Architecture: "We chose GraphQL over REST because of our real-time subscription needs."
• Lesson: "The UI bug was caused by a backend cache race condition."
• Pattern: "Always extend the BaseAdapter when integrating new payment providers."

This is operational knowledge too specific for a README but too important to lose.

The Killer Feature: Cross-Agent Sync

This is where agentsge directly benefits your Claude Code workflow. Instead of manually maintaining CLAUDE.md, you let the tool sync from the central source of truth.

The .agents/ directory can drive and sync multiple agent-facing files:

• AGENTS.md
• CLAUDE.md
• .cursorrules
• GEMINI.md
• MCP configs

You maintain knowledge in one place (.agents/knowledge/lessons/), and agentsge ensures CLAUDE.md is updated with the relevant, distilled instructions. This eliminates drift and ensures every tool session starts with full project memory.

How to Integrate This With Claude Code Today

1. Initialize: Run npx agentsge init in your project root.
2. Populate: Start adding knowledge. For example, create .agents/knowledge/conventions/naming.md with your team's naming rules.
3. Sync: Use agentsge to generate or update your CLAUDE.md. The tool is designed to keep this file thin, pulling from the structured knowledge base.
4. Capture: As you work, move valuable insights from chat sessions into the appropriate .agents/ knowledge folder. Over time, this becomes your project's onboarding guide for any AI agent—or human.

The goal isn't more documentation overhead. It's to stop repeating yourself and to preserve the tacit knowledge that makes your project unique.