Set up Agent Context System with Claude Code and CLAUDE.md

Configure persistent project memory for Claude Code via AGENTS.md and a CLAUDE.md symlink. Learn how Claude’s built-in auto memory complements the system.

Claude Code reads context files at session start, but it looks for CLAUDE.md rather than AGENTS.md by default. The Agent Context System handles this by creating a CLAUDE.md symlink that points to AGENTS.md during init — so Claude picks up your project knowledge without any manual file duplication. Claude Code also shipped built-in auto memory in late 2025, which works alongside AGENTS.md rather than replacing it.

Install

1. Clone the core files into your project

   Run the following commands from your project root to copy the Agent Context System files:

   git clone https://github.com/AndreaGriffiths11/agent-context-system.git /tmp/acs
   cp /tmp/acs/AGENTS.md /tmp/acs/agent-context ./
   cp -r /tmp/acs/agent_docs /tmp/acs/scripts ./
   rm -rf /tmp/acs
   
2. Run init

   Initialize the system in your project:

   ./agent-context init
   

   The init command:

   • Creates .agents.local.md from the template
   • Adds .agents.local.md to .gitignore
   • Creates a CLAUDE.md symlink pointing to AGENTS.md

   After this step, Claude Code will load your AGENTS.md content on every session start through the symlink.

3. Edit AGENTS.md

   Open AGENTS.md and replace the placeholder content with real information about your project: name, stack, package manager, build commands, and the patterns, boundaries, and gotchas that are specific to your codebase.

   Keep the file under 120 lines. Frontier LLMs follow roughly 150–200 instructions reliably, and Claude Code’s system prompt already uses about 50. A tight AGENTS.md gets followed. A bloated one gets deprioritized.

AGENTS.md and Claude’s auto memory

Claude Code’s auto memory (released late 2025) writes session learnings to ~/.claude/projects/<project>/memory/ and loads them at the start of each session. This is Claude’s built-in version of .agents.local.md — personal, local, session-to-session learning.

The two systems complement each other rather than overlap:

• Auto memory handles personal learnings — what you prefer, what you tried, what worked in past sessions. Claude manages this automatically, without any prompting.
• AGENTS.md handles shared project context — patterns the whole team should follow, architectural boundaries, commands, gotchas. It is committed to version control and works with every agent tool, not just Claude.

If you use Claude Code exclusively, auto memory covers session logging on its own. The value of AGENTS.md for you is the structured promotion pathway and cross-agent compatibility — when a pattern stabilizes, you have a clear place to put it where any agent tool can find it.

Session logging

Unlike Cursor, Windsurf, and Copilot, Claude Code handles session logging automatically through auto memory. You do not need to prompt “log this session” — Claude writes its own notes at session end and loads them at the next session start.

If you want to log to the shared .agents.local.md scratchpad (for patterns you intend to promote to AGENTS.md), you can prompt Claude to do so at the end of a session. Claude will propose the entry and wait for your approval before writing.

What gets created

After running ./agent-context init, your project will have:

File	Description
AGENTS.md	Committed project knowledge file. Always loaded. Keep under 120 lines.
.agents.local.md	Gitignored personal scratchpad. Grows as the agent logs session learnings.
CLAUDE.md	Symlink to AGENTS.md. Claude Code reads this instead of AGENTS.md directly.
agent_docs/	Deeper reference docs loaded on demand, not on every turn.
scripts/	Init, validate, promote, and other maintenance scripts.

Validate your setup

Run the following to check that the system is configured correctly:

agent-context validate