> ## Documentation Index
> Fetch the complete documentation index at: https://mainbranch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Clone the core files into your project">
    Run the following commands from your project root to copy the Agent Context System files:

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Run init">
    Initialize the system in your project:

    ```bash theme={null}
    ./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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## AGENTS.md and Claude's auto memory

<Info>
  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.
</Info>

## 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:

```bash theme={null}
agent-context validate
```