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

# How knowledge moves from sessions to shared context

> Understand how session learnings flow from raw notes into shared project knowledge, and how you control what gets promoted from personal to shared context.

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

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

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

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

  <Step title="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:

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

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

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

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

<CardGroup cols={2}>
  <Card title="Personal memory" icon="user">
    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.
  </Card>

  <Card title="Project memory" icon="users">
    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.
  </Card>
</CardGroup>

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.

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

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

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