--- name: agent-context-system description: A persistent local-only memory system for AI coding agents. Two files, one idea — AGENTS.md (committed, shared) + .agents.local.md (gitignored, personal). Agents read both at session start, update the scratchpad at session end, and promote stable patterns over time. Works across Claude Code, Cursor, Copilot, Windsurf. Subagent-ready. No plugins, no infrastructure, no background processes. license: MIT metadata: author: AndreaGriffiths11 version: "1.3.1" requires: bins: - bash ---

Agent Context System

The Problem

Agents start from zero every session. You spend an hour getting your coding agent up to speed on a project, close the session, and start from zero the next day. The agent forgot everything. Every session is a cold start.

This isn't a limitation of the model. It's a context delivery problem. The agents have the capacity to remember — they just don't have the right inputs at the right time in the right format.

The Solution

Two markdown files. One committed, one gitignored. The agent reads both at the start of every session and updates the local one at the end.

• AGENTS.md — Your project's source of truth. Committed and shared. Always in the agent's prompt. Under 120 lines. Contains compressed project knowledge: patterns, boundaries, gotchas, commands, architecture.

• .agents.local.md — Your personal scratchpad. Gitignored. Grows over time as the agent logs what it learns each session. Session notes, dead ends, preferences, patterns that haven't been promoted yet.

That's it. No plugins, no infrastructure, no background processes. The convention lives inside the files themselves, and the agent follows it.

How It Works

1. Setup

Run the init script. It creates .agents.local.md from a template, ensures it's gitignored, and wires up your agent tool's config (CLAUDE.md symlink for Claude Code, .cursorrules for Cursor, .windsurfrules for Windsurf, copilot-instructions.md for Copilot).

# If you cloned the template repo:
./scripts/init-agent-context.sh

# If you installed as a skill (npx skills add):
bash .agents/skills/agent-context-system/scripts/init-agent-context.sh

Then edit AGENTS.md with your project specifics: name, stack, commands, actual patterns and gotchas from your codebase. This is the highest-leverage edit you'll make.

2. During Sessions

The agent reads both files at session start. AGENTS.md gives it compressed project knowledge. .agents.local.md gives it accumulated learnings from past sessions. The agent now has context that persists across sessions.

At session end, the agent proposes the session log entry to the user before writing. The agent must not append directly — it shows the proposed entry and waits for user approval before writing to .agents.local.md. Most agents (Copilot Chat, Cursor, Windsurf) don't have session-end hooks, so this depends on Rule 7 in AGENTS.md being seen and acted on, or the user saying "log this session." Claude Code handles this automatically via auto memory.

3. Over Time

The scratchpad grows. When it hits 300 lines, the agent compresses: deduplicate, merge related entries, keep it tight. During compression, if a pattern has shown up across 3+ sessions, the agent flags it in the scratchpad's "Ready to Promote" section using the same pipe-delimited format that AGENTS.md expects.

You decide when to move flagged items from the scratchpad into AGENTS.md. The scratchpad is where things are experimental. AGENTS.md is where proven knowledge lives.

Session notes → .agents.local.md → agent flags stable patterns → you promote to AGENTS.md
                    (personal)                                        (shared)

Scripts

The template includes five scripts:

init-agent-context.sh

Sets up the local agent scratchpad and agent tool integrations. Run once per clone. Safe to re-run.

• Creates .agents.local.md from template
• Ensures .agents.local.md is gitignored
• Asks which agents you use (Claude, Cursor, Windsurf, Copilot) and wires up the right config
• Creates CLAUDE.md symlink for Claude Code (since it doesn't read AGENTS.md yet)
• Adds agent context directive to .cursorrules, .windsurfrules, or copilot-instructions.md

compress.sh

Compresses the scratchpad when it exceeds 300 lines. Deduplicates, merges related entries, flags stable patterns for promotion. Not yet implemented — instructions for the agent are in AGENTS.md's Local Context section.

promote.sh

Moves flagged items from .agents.local.md's "Ready to Promote" section into AGENTS.md. Not yet implemented — currently a manual step.

validate.sh

Validates AGENTS.md stays under 120 lines and checks format consistency. Not yet implemented.

publish-template.sh

Push to GitHub and mark as a template repo. Run once. Creates a private GitHub repo and marks it as a template so you can use it to create new projects with gh repo create my-project --template YOUR_USERNAME/agent-context-system --private.

Knowledge Flow

Knowledge doesn't just sit in one place. It flows.

Learnings start as session notes in .agents.local.md. The agent writes them at the end of each session. During compression, if a pattern has shown up across 3+ sessions, the agent flags it in the scratchpad's "Ready to Promote" section using the same pipe-delimited format that AGENTS.md expects. Then you decide when to move it into AGENTS.md.

Session notes → .agents.local.md → agent flags stable patterns → you promote to AGENTS.md
                    (personal)                                        (shared)

The scratchpad is where things are still experimental. AGENTS.md is where proven knowledge lives. The agent flags candidates. You make the call.

AGENTS.md Template Structure

The template AGENTS.md includes:

Project

Basic metadata: name, stack, package manager. Keep it one-liners.

Commands

Executable commands for build, test, lint, dev server. These go early because agents need them immediately.

Architecture

One line per directory. The agent gets high-level structure on every turn without needing to look anything up.

Project Knowledge (Compressed)

This is the most important section. Three subsections:

• Patterns — pattern | where-to-see-it format. Named exports only, server components default, Zustand for client state, Result types not try/catch.
• Boundaries — rule | reason format. Never modify src/generated, env vars through src/config, no default exports, no inline styles.
• Gotchas — trap | fix format. pnpm build hides type errors, dev sessions expire after 24h, integration tests need DB up.

Vercel's evals showed passive context (always in the prompt) achieves 100% pass rate vs 53% when agents must decide to look things up. This section is passive context. The agent gets it on every turn automatically.

Rules

Numbered list. Read AGENTS.md and .agents.local.md first. Plan before code. Locate files before changing. Only touch what the task requires. Run tests after every change. Summarize changes.

Deep References

Points to agent_docs/ for when a task needs more depth than the compressed version provides. Conventions, architecture, gotchas — full detail, loaded on demand.

Local Context

Instructions for reading and updating .agents.local.md. Explains session-to-session learning, compression protocol, promotion pathway. Tells subagents to explicitly read the scratchpad (they don't inherit main conversation history).

.agents.local.md Template Structure

The template .agents.local.md includes:

Preferences

Your style, code preferences, planning preferences. Friendly vs technical tone. Minimal changes vs comprehensive refactors. Always state the plan before writing code.

Patterns

Settled truths about this project. Promote recurring session learnings here.

Gotchas

...