Skip to main content
Knowledge in the Agent Context System doesn’t stay in one place. It moves — from rough session notes, through a personal scratchpad, into stable shared knowledge your whole team can rely on. This flow is deliberate: experimental knowledge lives in one place, proven knowledge lives in another, and you decide when something is ready to cross that line.

​
The promotion pathway

Session notes → .agents.local.md → agent flags stable patterns → you promote to AGENTS.md
                    (personal)                                        (shared)
Your scratchpad (.agents.local.md) is where knowledge starts. It’s experimental, personal, and gitignored. AGENTS.md is where knowledge ends up — proven, shared, committed. The agent handles the writing and flagging. You handle the final promotion decision.

​
The four-phase workflow

1

Write — agent logs learnings at session end

At the end of each session, the agent appends an entry to .agents.local.md (or to the daily log in .agents/logs/YYYY-MM-DD.md if you’re using the memory system). The entry records what changed, what worked, what didn’t, decisions made, and patterns noticed.The agent shows you the proposed entry before writing it. It does not append without your approval.A session log entry looks like this:
### 2026-03-25 — Refactor auth middleware

- **Done:** Extracted token validation into middleware/auth.ts
- **Worked:** Result<T> pattern kept error handling consistent
- **Didn't work:** Tried JWT library v9 — breaks with our Node version, use v8
- **Decided:** All auth errors return 401, never 403, per security review
- **Learned:** Middleware runs before rate limiting — order matters
2

Compress — scratchpad compresses at 300 lines

When .agents.local.md hits 300 lines, the agent compresses it: deduplicating entries, merging related notes, and removing noise. The scratchpad stays tight and useful rather than growing into an unmanageable log.The agent logs each compression in the ## Compression Log section of the scratchpad so you have a record of what was consolidated and when.
3

Flag — recurring patterns get marked 'Ready to Promote'

During compression, the agent looks for patterns that have appeared across 3 or more separate sessions. When it finds one, it flags it in the scratchpad’s ## Ready to Promote section, formatted in the pipe-delimited shorthand that AGENTS.md expects:
## Ready to Promote

| Category | Item | Detail |
|----------|------|--------|
| Gotcha   | JWT library version | Use v8 — v9 breaks with our Node version |
| Pattern  | Result<T> for errors | All services return Result<T>, never throw |
| Boundary | Auth errors → 401 | Never return 403 for auth failures |
The agent flags candidates. It does not touch AGENTS.md without your explicit action.
4

Promote — move stable patterns to AGENTS.md

Once the agent has flagged patterns, you decide what gets promoted. Run agent-context promote to review flagged items interactively, or use --autopromote to automatically append all flagged items to AGENTS.md.
# Review and selectively promote
./agent-context promote

# Auto-append all flagged patterns
./agent-context promote --autopromote
Promoted items move from your personal, experimental scratchpad into the committed, shared source of truth that every agent on your team reads.

​
Session logging reality

Agents don’t have session-end hooks. A session ends when you stop talking — there’s no automatic trigger that fires the logging step. Logging happens in one of two ways:
  1. You prompt it. Say “log this session” or “update the scratchpad” before closing the window. This is the reliable path for most agents.
  2. The agent proactively logs. Some agents follow the rule in AGENTS.md that says to log at session end. This is less reliable without the explicit prompt.
Claude Code is the exception. It shipped auto memory in late 2025. Claude writes its own notes to ~/.claude/projects/<project>/memory/ and loads them at session start automatically — essentially the .agents.local.md concept built into the tool. If you use Claude Code exclusively, you get session-to-session learning without prompting. For every other agent, build the habit: when meaningful work was done, ask for the log before you close the session.

​
Personal memory vs. project memory

The system maintains a clear line between two kinds of knowledge:

Personal memory

Lives in .agents.local.md and .agents/. Gitignored. Contains what the agent has learned about you — your preferences, your workflow, your project’s quirks as you’ve encountered them. Never shared with your team.

Project memory

Lives in AGENTS.md. Committed and shared. Contains what every agent needs to know about your project — the rules, the patterns, the architecture decisions that apply to everyone working on the codebase.
This distinction matters because these two types of knowledge serve different audiences. Your scratchpad can hold half-baked ideas, failed experiments, and personal quirks — that’s exactly what it’s for. AGENTS.md should only hold what’s proven, settled, and universally applicable to anyone touching the project.
Think of .agents.local.md as a notebook you carry. Think of AGENTS.md as the team wiki. Things start in the notebook. The good ones eventually make it to the wiki.

​
What gets promoted

Not everything in your scratchpad belongs in AGENTS.md. Promote a pattern when it meets all three criteria:
  • It has appeared across 3 or more separate sessions (the agent’s threshold for flagging)
  • It applies to anyone working on the project, not just to your personal workflow
  • It fits within the 120-line budget — AGENTS.md must stay lean
Patterns, architectural boundaries, and gotchas are good candidates. Personal preferences, half-resolved dead ends, and session-specific notes are not.
Every line you add to AGENTS.md is a line loaded into every session, for every agent, on every turn. Promote selectively. Dense, high-signal content outperforms comprehensive coverage.