Set up Agent Context System with Cursor or Windsurf

Configure persistent project memory for Cursor and Windsurf using agent-specific rules files that direct each tool to read AGENTS.md at session start.

Cursor and Windsurf both support project-level instruction files that load automatically at session start. The Agent Context System uses these files — .cursorrules for Cursor and .windsurfrules for Windsurf — to direct each tool to read AGENTS.md before beginning any task. The setup process is identical for both; only the config file name differs.

Install

1. Clone the core files into your project

   Run the following commands from your project root:

   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 script will ask which agents you use. Select Cursor, Windsurf, or both. It creates the appropriate config file with a directive pointing to AGENTS.md and ensures .agents.local.md is gitignored.

3. Edit AGENTS.md

   Open AGENTS.md and replace the placeholder content with real information about your project. The more accurate the file, the more useful every session becomes. Keep it under 120 lines.

Config files

The init script creates the rules file for your tool. If you need to create or recreate it manually, the content is the same for both:

Cursor

Cursor reads .cursorrules at session start. Create this file in your project root:

.cursorrules

Read AGENTS.md before starting

Cursor loads .cursorrules automatically — no further configuration required.

Windsurf

Windsurf reads .windsurfrules at session start. Create this file in your project root:

.windsurfrules

Read AGENTS.md before starting

Windsurf loads .windsurfrules automatically — no further configuration required.

Session logging

Neither Cursor nor Windsurf exposes session-end hooks, so the Agent Context System cannot log sessions automatically. To save what happened in a session to .agents.local.md, tell the agent at the end of your conversation:

log this session

The agent will propose a session log entry covering what changed, what worked, what did not, and any patterns or gotchas discovered. Review the proposal and approve it before the agent writes to .agents.local.md.

Session logging depends on the agent seeing Rule 7 in AGENTS.md and acting on it, or you explicitly prompting it. If you close the editor without logging, that session’s learnings are lost. Building the habit of ending sessions with “log this session” is worth it — the scratchpad is where patterns start their journey into AGENTS.md.

Validate your setup

After init, confirm that the system is wired up correctly:

agent-context validate