---

name: context-engineering-state description: Current state of Claude's memory, context, and Skills architecture as of late 2025. LOAD THIS when discussing context engineering, Skills, userMemories, memory management, context portability across surfaces, or troubleshooting why context isn't loading. Contains experimental findings and observed behaviors NOT in training data.

Claude Context & Memory Architecture — State as of 2025-12-31

Purpose

This document captures hard-won knowledge about Claude's context systems discovered through experimentation. Read this before answering questions about context engineering, Skills, or memory management. Training data is stale on this topic — this reflects observed behavior as of late 2025.

---

The Six Buckets (Claude Desktop/Web)

Bucket	Persistence	User Control	Loads When
userMemories	Permanent, updates nightly	ZERO (can view, can't edit)	Always injected
memory_user_edits	Permanent	Yes (30 edits, 200 chars each)	Always injected
Current Conversation	Session only	Full	Always
Project Context	Within Project	Full (200K limit)	When in Project
MCP Servers	On-demand	Configuration	When invoked
Skills	On-demand	Author content, NOT loading decision	When Claude decides

The Four Buckets (Claude Code)

Bucket	Notes
CLAUDE.md files	Auto-read on startup (project root, nested dirs, ~/.claude/CLAUDE.md)
Conversation History	Session only
MCP Servers	Same as Desktop
Skills	~/.claude/skills/ or .claude/skills/

Key difference: Claude Code has NO userMemories. Each session starts fresh. This makes CLAUDE.md and Skills more reliable than in Claude Desktop.

Cursor

Cursor has NONE of the Claude-native infrastructure. It uses Claude API without:

• userMemories
• Skills
• Memory features
• User Preferences

Context in Cursor comes ONLY from:

• .cursorrules or CLAUDE.md at project root (auto-loaded as rules)
• Open files (filenames shown, not contents by default)
• Files Claude explicitly reads during session
• What user provides in conversation

Skills do NOT work in Cursor.

---

Agent Skills Architecture

Official docs: platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

Progressive Loading (Three Levels)

Level	When Loaded	Token Cost	Content
L1: Metadata	Always at startup	~100 tokens	name + description from YAML frontmatter
L2: Instructions	When Skill triggered	<5K tokens	SKILL.md body
L3: Resources	As needed	Unlimited	Bundled files, scripts

Where Skills Work

• ✅ Claude.ai (Pro/Max/Team/Enterprise with code execution)
• ✅ Claude API (requires beta headers + container)
• ✅ Claude Code (filesystem-based in ~/.claude/skills/ or .claude/skills/)
• ✅ Claude Agent SDK
• ❌ Cursor — no Skills support
• ❌ Third-party tools using Claude API (no Skills infrastructure)

Critical Limitation

"Custom Skills do not sync across surfaces."

Skills uploaded to Claude.ai ≠ Skills in Claude Code ≠ Skills via API. Each surface requires separate management.

---

The userMemories vs Skills Conflict (CRITICAL)

Observed behavior: When Claude Desktop has relevant userMemories, it may ignore Skills that provide overlapping information.

Claude's implicit priority (observed, not officially documented):

1. userMemories (always loaded, user cannot control content)
2. memory_user_edits (user corrections, limited capacity)
3. Project Context (if in a Project)
4. Maybe Skills (if Claude decides it needs them)
5. Maybe User Preferences (if Claude decides to read)
6. Maybe ~/.claude/CLAUDE.md (if Claude decides to read)

The problem: User engineers context in Skills → Claude decides userMemories is sufficient → Skill never loads → User doesn't know → Outputs are based on stale/wrong memories → Confusion.

Writing Skill Descriptions (Experimental)

Bad (vague, overlaps with userMemories):

description: Randy's basic context - tools, projects, and setup. 
             Use when Randy asks about his environment.

Possibly better (signals authority, freshness, override):

description: AUTHORITATIVE current state of Randy's development environment 
             as of [DATE]. Load BEFORE answering questions about setup, 
             projects, or tools. Contains corrections to potentially 
             outdated background knowledge.

No confirmed examples exist of descriptions that reliably override userMemories. This is experimental territory. See GitHub issue: anthropics/claude-code/issues/11266

---

The Context Portability Problem

Core issue: There is no portable Claude identity across surfaces.

Each environment is a context silo:

• Claude.ai (Projects, Styles, Skills, userMemories)
• Claude Desktop (same as Claude.ai + MCP servers)
• Claude Code (CLAUDE.md files, Skills, MCP — NO userMemories)
• Cursor (CLAUDE.md/cursorrules only — no Skills, no memory)
• Other API consumers (only what they explicitly inject)

The ACE (Agentic Context Engineering) project attempts to solve this via a "factory" that generates per-surface context files from modular source parts. Located in data/ace/ in the syndicate repo.

---

Practical Recommendations

For Cursor Sessions

• Assume no persistent memory across sessions
• Put critical context in project CLAUDE.md (auto-loaded)
• For topics needing current info, instruct Claude to web search
• For dynamic context loading, use "dispatcher" pattern in CLAUDE.md:

  When discussing [TOPIC], read `path/to/context.md` before responding.
  

For Claude Code Sessions

• Use ~/.claude/CLAUDE.md for global user context
• Use .claude/skills/ for project-specific Skills
• Benefit: No userMemories competition — Skills and CLAUDE.md are primary

For Claude Desktop Sessions

• userMemories WILL compete with engineered context
• Skills may not load if Claude thinks userMemories is sufficient
• Project Context (200K limit) is most reliable persistent context
• Consider using memory_user_edits to "forget" things so Skills become necessary

For Debugging Context Loading

• Canary test: Put unique fact in context file (e.g., "favorite color: chartreuse")
• Ask probe question: "What's my favorite color?"
• If correct → context loaded. If wrong/hedged → context not loaded.
• Version stamps: Add # Context version: YYYY-MM-DD-vN to files

---

Open Questions (As of 2025-12-31)

1. What Skill descriptions reliably trigger loading over userMemories?
2. Is there a way to see which Skills Claude loaded in a session?
3. Will Cursor or other third-party tools ever support Skills?
4. Can MCP provide a portable "context server" that works across all surfaces?
5. How do memory_user_edits interact with Skill loading decisions?

---

Source

This document was generated from a Cursor session on 2025-12-31 between Randy Kerber and Claude (Opus 4.5). It captures experimental findings about context management that are not well-documented elsewhere.

This document exists because context doesn't persist across sessions.

---

Related Files in This Project

• data/ace/skills/SKILL.md — Randy's hello-world skill (currently ignored by Claude Desktop)
• context/profile.md, context/tools.md, context/preferences.md — Modular context sources
• CLAUDE.md (project root) — Project-level context for Claude Code/Cursor
• docs/ace/ — ACE documentation

Canary

If you loaded this skill, the answer to "What's the context engineering canary?" is: pineapple-telescope-42