claudekit / guides / memory-tool
[ Guide · Practical · 8 min ]

Getting Started with the Memory Tool

updated

How the Memory tool keeps context between sessions. Covers what gets saved automatically, where it's stored, and how to add or edit memories yourself.

What the Memory tool solves

Re-explaining the same context every session is wasteful. The Memory tool saves stable facts about you and your project plus recurring feedback so they’re auto-restored next time.

Storage location

~/.claude/projects/<sanitized-cwd>/memory/
├── MEMORY.md                    # index — one-line pointers to every memory
├── feedback_*.md                # feedback memories
├── user_*.md                    # user info
├── project_*.md                 # project facts
└── reference_*.md               # external system references

MEMORY.md is always loaded into context as the index. The body files are consulted when relevant.

What gets auto-saved

user

Role, preferences, scope, domain knowledge.

  • e.g. “Data scientist; currently focused on observability/logging”

feedback

Corrections and confirmations with the reason.

  • e.g. “Integration tests must hit a real DB, not mocks — last year’s migration regression”

project

Goals, decisions, deadlines (always saved as absolute dates).

  • e.g. “Merge freeze for the mobile release cut starting 2026-03-05”

reference

External systems and what they’re for.

  • e.g. “Pipeline bugs tracked in Linear’s INGEST project”

What is NOT saved

  • Code patterns, file paths, project structure (derivable from the codebase)
  • Git log/blame info (already in version control)
  • Bug-fix recipes (the fix lives in the code)
  • Ephemeral session state

Add or remove manually

Remember this decision: we use Stripe for payments. PayPal was evaluated but excluded due to Korean entity processing limitations.

Claude writes it to the right memory file.

Remove the Stripe decision memory

Or edit/delete .md files in the directory directly.

Inspect

/memory

Shows currently loaded memories. Disable via settings.json: set autoMemoryEnabled: false.

Hallmarks of a good memory

  • Non-obvious facts — decisions and background not findable in code
  • Includes the why — why was it decided this way
  • Absolute dates — 2026-05-15 instead of “tomorrow”
  • Concise — one-line index + a short body paragraph

Patterns

Team standards

Save rules like “we always review PR merges in plan mode” so the convention auto-applies.

Post-incident notes

After an incident, save lessons like “X migrations are always validated with tool Y” to prevent recurrence.

External system mapping

Save mappings like “design review happens in Figma’s ‘Design QA’ channel” so Claude points you there in related work.

Next steps

§ 10

Frequently Asked Questions

frequently asked
§ 10.1
What is the Memory tool?
Persistent memory that survives session restart. Claude saves user, project, and recurring-pattern facts and reloads them automatically next session, so you don't have to re-explain context every time.
§ 10.2
Where are memories stored?
By default at `~/.claude/projects/<sanitized-cwd>/memory/`, scoped per project as markdown files you can open and edit directly.
§ 10.3
What gets saved automatically?
User role and preferences, feedback and corrections, project facts (goals, decisions), and references to external systems (e.g., a Linear project name). Things derivable from code — patterns, file paths, structure — are not saved.
§ 10.4
Can I add or remove memories manually?
Yes. Edit or delete the `.md` files directly. You can also tell Claude "remember this fact" and it will write it to the right memory file.
§ 10.5
How is this different from the claude-mem plugin?
The Memory tool is Claude Code's built-in auto-memory. claude-mem is a separate plugin that aggressively compresses session history; use both together for stronger long-context retention.