Claude Code Memory: Use Context & Project Knowledge

Claude Code has no memory between sessions—every conversation starts from scratch. The agent reads your project files on demand, but it won't remember your architecture decisions, your naming conventions, or the UI bugs you reported yesterday. Most developers type the same context over and over, paste the same screenshots, and burn through token budgets explaining what Claude Code could have read from a file.

The fix is writing project instructions (a markdown file Claude Code reads every session) and connecting MCP servers that surface tool outputs as persistent context. This post shows both methods, why screenshots alone cost too many tokens, and how named element capture replaces pixel guesses with executable facts.

What is Claude Code memory and how does it work?

Claude Code memory is whatever you write in .claude/instructions.md plus whatever MCP tools return. The agent has no conversation history across sessions—close the terminal or VS Code window, and it forgets everything. Project instructions give it a bootstrap file to read every time. MCP servers (Model Context Protocol) let tools like database inspectors, screenshot servers, or UI capture apps feed structured context into the prompt without you pasting anything.

When you start a Claude Code session, it reads .claude/instructions.md if present, scans your open files, and waits for you to ask. If you connected an MCP server (via claude mcp add), the agent can call tools like list_database_tables or pinvari_next_instruction—those outputs become context for the next edit. That's the memory: a markdown file you maintain and tool results the agent requests.

No magic. No embeddings. Just a file and a local server protocol.

How do I create project instructions for Claude Code?

Make a .claude folder in your project root. Inside, create instructions.md. Write anything the agent should know every session: your stack, naming rules, architecture patterns, deployment steps, UI component hierarchy, or common bugs.

Example structure:

# Project: Acme Dashboard

## Stack
- Next.js 14 App Router, TypeScript, Tailwind
- Supabase (Postgres + Auth), Vercel deploy
- ShadcN UI components in `src/components/ui`

## Naming conventions
- React components: PascalCase (`UserProfile.tsx`)
- API routes: kebab-case (`/api/user-settings`)
- Database tables: snake_case (`user_profiles`)

## Architecture rules
- Server components by default; "use client" only when needed
- All DB queries in `/src/lib/queries`, never in components
- Auth checks in middleware.ts, not per-page

## Common UI bugs
- The "Save" button in `/settings` is `AXButton` role, title "Save changes", id `btn-save`
- The user dropdown is `AXPopUpButton`, title "User menu", parent `AXGroup` role="navigation"

Claude Code loads this every session. When you say "fix the Save button styling," it knows the exact button name and where it lives. When you report a new bug, add the element name to the file—next session, Claude Code already knows it.

Save .claude/instructions.md, commit it. Done.

What are Claude Code skills and how do they relate to memory?

Claude Code skills are built-in capabilities like editing files, running shell commands, or searching the web. They're not memory—they're actions. But skills paired with MCP tools create a memory loop: a tool captures state (e.g., a UI screenshot + named element), Claude Code reads it, edits the right file, and you update project instructions with the result.

For example, the pinvari_next_instruction MCP tool (from PinVari's MCP server) returns a resolved accessibility element, a screenshot cropped to that region, and the spoken instruction. Claude Code uses the edit skill to fix the CSS, then you add the element path to .claude/instructions.md so it remembers the component next time.

Skills execute. MCP tools provide context. Project instructions persist it. The three together replace the "paste-screenshot-describe-verbally-hope-it-guesses" workflow.

How do Claude Code and Cursor handle memory differently?

Cursor keeps chat history in the editor sidebar but still forgets when you close VS Code. Claude Code starts clean every time but reads project instructions automatically. Both benefit from MCP servers that replace screenshots with named element data—neither has a magic memory layer.

The real difference: Claude Code's MCP tooling is first-party and better documented (see claude-code-mcp for setup). Cursor requires manual server configs. If you're choosing between them, read claude-code-vs-cursor for the full comparison.

What is the fastest way to give Claude Code UI context?

The fastest way is point-and-speak capture with a named element resolver. Hold a hotkey, circle or point at the UI element, speak the instruction, and let an MCP tool resolve the exact accessibility element (role, label, frame) plus a cropped screenshot. The tool hands Claude Code a structured payload—no manual description, no pasting, no token waste.

How it works (PinVari example):

1. Press ⌥⌘A, circle the "Save" button, say "make this blue."
2. PinVari screenshots, transcribes on-device, resolves the AX element (AXButton, title "Save changes", frame {x:320, y:480, w:80, h:36}).
3. The capture appears in the notch island. Open Claude Code, which calls pinvari_next_instruction via MCP.
4. Claude Code receives: "instruction": "make this blue", "element": "AXButton 'Save changes'", "screenshot_base64": "..." (cropped to the button).
5. It edits Button.module.css, changes background: #gray to background: #3b82f6.

Total time: ~8 seconds. No typing element paths. No describing "the button in the top-right corner." No ambiguity. The accessibility tree names every element; PinVari reads it, Claude Code acts on it.

If you're still pasting full-screen screenshots and describing positions in words, you're wasting 1,000+ tokens per bug and training the agent to guess. Switch to named capture. Install PinVari (/#pricing), connect with claude mcp add --scope user pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp", and point-and-speak. Done.

How do I connect an MCP server to Claude Code?

Run claude mcp add with the server path and any required arguments. Claude Code writes the config to ~/.config/claude-code/mcp.json. Restart the CLI and the agent can call the server's tools.

Example (PinVari MCP server):

claude mcp add --scope user pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp"

The --scope user makes it available across all projects. The -- separator passes everything after to the server's entrypoint. PinVari's connector is at ~/.pinvari/mcp/pinvari-mcp (installed when you download the app). The app must be running—the connector talks to it on 127.0.0.1:3402.

To verify it worked:

cat ~/.config/claude-code/mcp.json

You'll see a "pinvari" entry with the command and args. Restart claude-code, type a prompt like "what's the next capture?" and Claude Code will call pinvari_next_instruction if a capture is waiting.

Other MCP servers (screenshot tools, database inspectors, file watchers) follow the same pattern. Read claude-code-mcp for the full list of available servers.

Should I use screenshots or MCP tools for UI bugs?

Use MCP tools that resolve named elements. A screenshot costs 1,000+ tokens and requires you to describe what's in it ("the blue button on the right, below the header"). Claude Code guesses the element from pixels and your description—it might edit the wrong button or miss nested components.

An MCP tool like pinvari_next_instruction resolves the exact element via the accessibility tree, returns the role and title, and crops the screenshot to just that region. Claude Code gets a labeled instruction ("AXButton 'Submit'") and a 200×200px image instead of a 3000×2000px full screen. Token cost drops ~80%, accuracy goes to 100%.

When to use screenshots anyway:

• You're debugging a canvas/WebGL surface (no AX tree → OCR fallback or manual description).
• You need to show visual layout bugs (spacing, alignment) where the element name doesn't matter.
• The agent needs to see surrounding context (neighboring elements, page structure).

For everything else—button styling, form validation errors, dropdown behavior—named element capture is faster and cheaper. See best-screenshot-mcp-servers for other options if PinVari doesn't fit your stack.

How do I organize project instructions for a team?

Commit .claude/instructions.md to your repo. Every developer on the team shares the same context—no more "I forgot to tell Claude Code about the staging URL" or "it edited the wrong API route because I didn't explain the folder structure."

Team-focused structure:

# Project: Acme SaaS

## Environments
- **Local:** `http://localhost:3000`, db: `postgres://localhost/acme_dev`
- **Staging:** `https://staging.acme.app`, db: Supabase (project ID: `abc123`)
- **Production:** `https://app.acme.app`, db: Supabase (project ID: `xyz789`)

## Deploy checklist
1. Run `pnpm test` (must pass)
2. Bump version in `package.json`
3. Push to `main` → Vercel auto-deploys to production
4. Tag release: `git tag v1.2.3 && git push --tags`

## UI component registry
- **Primary button:** `src/components/ui/Button.tsx`, AX role `AXButton`, default class `btn-primary`
- **User dropdown:** `src/components/layout/UserMenu.tsx`, AX role `AXPopUpButton`, title "User menu"
- **Settings modal:** `src/components/modals/SettingsModal.tsx`, AX role `AXDialog`, title "Settings"

## Common bugs (last 30 days)
- `btn-save` loses focus ring on Safari → add `:focus-visible` to `Button.module.css`
- User dropdown z-index conflicts with modals → set `z-50` in `UserMenu.tsx`

When a team member reports a bug, they add the element name to the registry. Next session, Claude Code knows it. No Slack threads explaining the same button twice.

If the file grows past 500 lines, split it: .claude/instructions.md (general), .claude/ui-elements.md (component registry), .claude/deploy.md (ops). Link them in the main file with See ui-elements.md for the full component list.

FAQ

Does Claude Code remember previous conversations?

No. Claude Code has no memory between sessions. Every time you start the CLI or restart VS Code, it starts fresh. The only persistent memory is what you write in .claude/instructions.md or what MCP tools return when called.

How many tokens does a screenshot cost in Claude Code?

A full-screen screenshot (2560×1600) costs approximately 1,200–1,500 tokens. A cropped screenshot (300×200, just the element you circled) costs 150–250 tokens. If you're pasting five screenshots per bug report, you're burning 6,000+ tokens before Claude Code writes a single line. Use an MCP tool that resolves named elements and crops the image—token cost drops by 80%.

Can Claude Code read my entire codebase at once?

Yes, but it's expensive. Claude Code can scan your project and load every file into context, but a 50-file Next.js app might cost 30,000+ tokens just for the initial prompt. Instead, point it at specific files (@src/components/Button.tsx) or write summaries in .claude/instructions.md. The agent reads files on demand—you don't need to load everything unless you're doing a full refactor.

What's the difference between Claude Code skills and MCP tools?

Skills are built-in actions (edit, search, run shell commands). MCP tools are external servers you connect that provide context or execute custom logic. For example, the edit skill writes to a file. The pinvari_next_instruction MCP tool reads a UI capture from PinVari and returns the named element + screenshot. Skills act, tools inform.

How do I update project instructions without breaking Claude Code?

Edit .claude/instructions.md like any markdown file. Claude Code reads it fresh every session, so changes take effect immediately—no restart needed unless you change MCP config. Keep the file under 2,000 lines to avoid token bloat. If a section becomes outdated (e.g., old deploy steps), delete it or move it to a separate .claude/archive/ folder.

Is Claude Code better than Cursor for long-running projects?

Both work. Claude Code forces you to write explicit project instructions, which helps teams stay aligned. Cursor keeps chat history in the editor, which feels more conversational but doesn't persist across restarts. If you're terminal-first and use agentic coding workflows, Claude Code + MCP is faster. If you're editor-first and prefer inline chat, Cursor fits. Neither is strictly better—choose based on where you spend your time.