Introduction
Good profile entries share a shape: they are short, they generalize across sessions, and they are written in third person. Bad profile entries are either too vague to be useful ("User is a developer") or too specific to the moment ("User asked about route handlers today"). Understanding the shape lets you both audit what the agent writes and seed your own entries effectively.
Key Concepts
- Generalization: The entry should be true across sessions, not just today.
- Third-person framing: Profile entries describe "the user" objectively; they are not first-person notes.
- Behavioral, not descriptive: "Prefers code-first responses" beats "is a careful person".
- Density: Pack multiple related facts into a single entry to respect the character cap.
Real World Context
A user notices their USER.md has eight entries, several of which are near-duplicates: "Prefers concise replies", "Likes short answers", "Wants minimal prose". The agent's drift toward repetition is normal; the human's job is to consolidate them into one stronger entry like "Wants terse, code-first answers; prose only when the why is non-obvious."
Deep Dive
A few examples worth contrasting:
| Weak entry | Strong entry |
|---|---|
| User is a developer | Senior backend engineer, Go and TypeScript primary, comfortable with Postgres internals |
| User likes tests | Writes table-driven tests with subtests; uses make test as the run command |
| User cares about safety | Wants explicit confirmation before destructive shell commands and force-pushes |
| User asked for Tailwind today | (skip; project-specific, lives in MEMORY.md or AGENTS.md) |
The weak entries fail in different ways. "User is a developer" is true but adds nothing the agent could not assume. "User likes tests" is too vague to drive a behavior. "User cares about safety" is descriptive but not actionable. The strong entries, by contrast, give the agent a concrete way to change its output.
A useful heuristic: when you read a USER.md entry, you should be able to predict at least one specific behavior change in the next session. If you cannot, the entry is probably too vague.
The character cap (~1,375) keeps the file from drifting into a sprawling biography. Treat each entry as expensive. A USER.md with five great entries beats one with twelve mediocre ones.
Finally, profile insights compound across sessions, not within them. The agent does not aggressively rewrite USER.md mid-conversation. Most write triggers fire when something stable has been clearly stated or repeatedly demonstrated.
Common Pitfalls
- Letting near-duplicates accumulate: "Concise", "terse", "short" three times in the file means three entries that should be one.
- Writing project-specific facts into the profile: "Likes Tailwind" is a project preference for this codebase, not an identity trait.
Best Practices
- Audit and consolidate: A monthly pass to merge near-duplicates keeps the profile dense and useful.
- Prefer behavioral language: Entries that imply a behavior change are stronger than entries that describe a trait.
Summary
- Strong profile entries are short, behavioral, third-person, and dense.
- Weak entries are vague ("is a developer") or session-specific ("asked about X today").
- The character cap forces density; treat each entry as expensive.
- Audit and consolidate monthly to prevent drift.
Code Examples
# Before consolidation:
- User prefers concise replies.
- User likes short answers.
- User wants minimal prose.
# After consolidation:
- Wants terse, code-first answers; prose only when the why is non-obvious.
# Result: same intent, one entry instead of three.