Agent Context System — 代理 上下文 系统

代理 上下文 系统 The Problem

代理s 启动 from zero every 会话. You spend an hour 获取ting your coding 代理 up to speed on a project, close the 会话, and 启动 from zero the next day. The 代理 forgot everything. Every 会话 is a cold 启动.

This isn't a limitation of the 模型. It's a 上下文 delivery problem. The 代理s have the capacity to remember — they just don't have the right 输入s at the right time in the right 格式化.

The Solution

Two markdown files. One committed, one gitignored. The 代理 reads 机器人h at the 启动 of every 会话 and 更新s the local one at the end.

代理S.md — Your project's source of truth. Committed and 分享d. Always in the 代理's prompt. Under 120 lines. ContAIns 压缩ed project knowledge: patterns, boundaries, gotchas, commands, architecture.

.代理s.local.md — Your personal scratchpad. Gitignored. Grows over time as the 代理 记录s what it learns each 会话. 会话 notes, dead ends, preferences, patterns that haven't been promoted yet.

That's it. No 插件s, no infrastructure, no background processes. The convention lives inside the files themselves, and the 代理 follows it.

How It Works

• 设置up

运行 the init script. It 创建s .代理s.local.md from a template, ensures it's gitignored, and wires up your 代理 工具'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-代理-上下文.sh

# If you 安装ed as a 技能 (npx 技能s 添加): bash .代理s/技能s/代理-上下文-系统/scripts/init-代理-上下文.sh

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

• During 会话s

The 代理 reads 机器人h files at 会话 启动. 代理S.md gives it 压缩ed project knowledge. .代理s.local.md gives it accumulated learnings from past 会话s. The 代理 now has 上下文 that persists across 会话s.

At 会话 end, the 代理 proposes the 会话 记录 entry to the user before writing. The 代理 must not 应用end directly — it shows the proposed entry and wAIts for user 应用roval before writing to .代理s.local.md. Most 代理s (Copilot Chat, Cursor, Windsurf) don't have 会话-end hooks, so this depends on Rule 7 in 代理S.md being seen and acted on, or the user saying "记录 this 会话." Claude Code handles this automatically via auto memory.

• Over Time

The scratchpad grows. When it hits 300 lines, the 代理 压缩es: deduplicate, merge related entries, keep it tight. During 压缩ion, if a pattern has shown up across 3+ 会话s, the 代理 flags it in the scratchpad's "Ready to Promote" section using the same pipe-delimited 格式化 that 代理S.md expects.

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

会话 notes → .代理s.local.md → 代理 flags stable patterns → you promote to 代理S.md (personal) (分享d)

Scripts

The template includes five scripts:

init-代理-上下文.sh

设置s up the local 代理 scratchpad and 代理 工具 integrations. 运行 once per clone. Safe to re-运行.

创建s .代理s.local.md from template Ensures .代理s.local.md is gitignored Asks which 代理s you use (Claude, Cursor, Windsurf, Copilot) and wires up the right config 创建s CLAUDE.md symlink for Claude Code (since it doesn't read 代理S.md yet) 添加s 代理 上下文 directive to .cursorrules, .windsurfrules, or copilot-instructions.md 压缩.sh

压缩es the scratchpad when it exceeds 300 lines. Deduplicates, merges related entries, flags stable patterns for promotion. Not yet implemented — instructions for the 代理 are in 代理S.md's Local 上下文 section.

promote.sh

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

验证.sh

验证s 代理S.md stays under 120 lines and 检查s 格式化 consistency. Not yet implemented.

publish-template.sh

Push to GitHub and mark as a template repo. 运行 once. 创建s a private GitHub repo and marks it as a template so you can use it to 创建 new projects with gh repo 创建 my-project --template YOUR_USERNAME/代理-上下文-系统 --private.

Knowledge Flow

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

Learnings 启动 as 会话 notes in .代理s.local.md. The 代理 writes them at the end of each 会话. During 压缩ion, if a pattern has shown up across 3+ 会话s, the 代理 flags it in the scratchpad's "Ready to Promote" section using the same pipe-delimited 格式化 that 代理S.md expects. Then you decide when to move it into 代理S.md.

会话 notes → .代理s.local.md → 代理 flags stable patterns → you promote to 代理S.md (personal) (分享d)

The scrat