Remember
Zero-friction memory. Say it, the agent stores it in the right place — project or global — automatically.
Step 1: Detect Scope
Every fact is either project-scoped or global. This determines which files get read and written.
| Signals | Scope |
|---|---|
| This project's stack, deploy commands, scripts, ports, env vars, current work, conventions | Project |
| Coding rules ("always do X", "never do Y"), workflow patterns, how to use skills, decision rules, default tech choices | Global |
| A skill that exists or how to find it | Global (→ skills/AGENTS.md) |
| Ambiguous | Ask the user: "Should this be project-specific or global (applies to all projects)?" |
Step 2: Read (scope-dependent)
Project scope
Read these files. Requires /scaffold-project to have been run first — if .claude/primitives/ doesn't exist, warn and stop.
- •
.claude/primitives/stack.md - •
.claude/primitives/conventions.md - •
.claude/primitives/local-dev.md - •
.claude/primitives/active-context.md
Global scope
Read these files:
- •
~/.claude/CLAUDE.md - •
~/.claude/skills/AGENTS.md
Step 3: Classify
Project classification
| The fact is about... | Store in | Section |
|---|---|---|
| Deploy commands, CI/CD, server info, GitHub Actions | local-dev.md | Deployment |
| Dev commands, scripts, ports, env vars, gotchas | local-dev.md | Relevant section |
| Framework, library, version change, MCP server, tool | stack.md | Relevant section |
| File naming, component patterns, import style, conventions | conventions.md | Relevant section |
| Current work, sprint focus, active issue, blocker, decision | active-context.md | Relevant section |
| Domain term, acronym, jargon definition | glossary.md | (add row to table) — only if glossary.md exists |
| System structure, data flow, module boundaries, architectural constraints | architecture.md | Relevant section — only if architecture.md exists |
| Unclear | Ask the user | — |
Project disambiguation rules:
- •One-time fact about what's happening NOW →
active-context.md - •Permanent fact about how the project WORKS →
stack.md,conventions.md, orlocal-dev.md - •Mentions a specific tool, library, or server →
stack.md - •"Don't do X" or "always do Y" rule →
conventions.mdorlocal-dev.mdCommon Gotchas
Global classification
| The fact is about... | Store in | Section |
|---|---|---|
| How to approach code, coding rules, what to avoid | CLAUDE.md | Coding Principles |
| Workflow steps, when to use which skill | CLAUDE.md | Workflow |
| How sessions should start or end | CLAUDE.md | Session Protocol |
| When to ask vs when to just proceed | CLAUDE.md | Decision Framework |
| Default tech stack, commit style, error handling | CLAUDE.md | Defaults |
| User or team context (who works here, communication style) | CLAUDE.md | Who You're Working With |
| A skill that exists, or how to navigate skills | skills/AGENTS.md | Orient Here or Skill Map |
| Unclear | Ask the user | — |
Step 4: Write
Add the fact to the correct file and section. Rules:
- •Append, don't replace. Add to the appropriate section. Don't rewrite the whole file.
- •Be concise. One line if possible. A short paragraph at most.
- •Use the existing format. If the section has a table, add a row. If it has a list, add a bullet.
- •Update the date. If the file has a
**Last Updated:**field, update it to today's date.
Step 5: Confirm
Tell the user exactly what was stored and where:
Stored in
<file path>under <Section>:<the fact, as written>
Examples
Project-scoped
Input: "remember we deploy with npm run deploy:prod to staging"
Scope: Project (deploy command for this project)
Classification: Deploy command → local-dev.md → Deployment
Action: Add - **Staging:** \npm run deploy:prod`to the Deployment section **Confirmation:** Stored in.claude/primitives/local-dev.md` under Deployment
Input: "remember we have a Sentry MCP server for error monitoring"
Scope: Project (tool available in this project)
Classification: MCP server → stack.md → Tools / MCP Servers
Action: Add - Sentry MCP — error monitoring and issue tracking to Tools / MCP Servers
Confirmation: Stored in .claude/primitives/stack.md under Tools / MCP Servers
Input: "remember don't use npx supabase, use supabase directly"
Scope: Project (this project's gotcha)
Classification: Gotcha → local-dev.md → Common Gotchas
Action: Add - Never use \npx supabase` — use `supabase` directlyto Common Gotchas **Confirmation:** Stored in.claude/primitives/local-dev.md` under Common Gotchas
Global-scoped
Input: "remember: always run the linter before committing"
Scope: Global (coding rule, applies everywhere)
Classification: Coding rule → CLAUDE.md → Coding Principles
Action: Add - **Lint before commit** — always run the linter before committing to the Don't/Core Rules list
Confirmation: Stored in ~/.claude/CLAUDE.md under Coding Principles
Input: "remember: when in doubt about error handling, log the raw error in dev"
Scope: Global (decision rule)
Classification: Decision pattern → CLAUDE.md → Decision Framework or Defaults
Action: Add a row or bullet in the appropriate section
Confirmation: Stored in ~/.claude/CLAUDE.md under Defaults
Input: "remember: there's a scaffold-project skill for setting up new projects"
Scope: Global (skill knowledge)
Classification: Skill navigation → skills/AGENTS.md → Orient Here
Action: (Only if not already there) Add orient row
Confirmation: Stored in ~/.claude/skills/AGENTS.md under Orient Here
What This Skill Does NOT Do
- •Does not delete or overwrite existing content
- •Does not store secrets or sensitive values (warn if user tries)
- •Does not run
/scaffold-projectfor you (prerequisite for project-scoped facts) - •Does not modify spec files, security plans, or any workflow artifact