Shared from "Claude-Code" on Inkdown
Claude Code's persistent file-based memory — how it remembers things across sessions.
The memory system lets Claude Code persist information across sessions. It stores memories as markdown files and maintains an index (MEMORY.md) for quick lookup.
| Type | Purpose | Example |
|---|---|---|
| user |
| About the person |
| "Prefers TypeScript over Python" |
| feedback | Corrections/confirmations | "Don't use semicolons" |
| project | Work context | "API is at /api/v2/users" |
| reference | External system pointers | "Jira project key is CC" |
~/.claude/projects/<git-root>/memory/
├── MEMORY.md # Index file (pointers to all memories)
├── user/
│ ├── preferences.md # Individual memory files
│ └── work-style.md
├── feedback/
│ └── code-style.md
├── project/
│ ├── architecture.md
│ └── deployment.md
└── reference/
└── external-systems.mdWrite content to individual .md files with YAML frontmatter:
---
type: project
created: 2025-01-15
---
The API uses GraphQL at /api/graphqlAdd pointer to MEMORY.md (the index):
- [API uses GraphQL](project/architecture.md)MEMORY.md is capped at:
When the cap is hit, old entries are removed.
Memory directory is resolved in priority order:
CLAUDE_MEMORY_DIRmemoryDir fieldPaths are validated to reject:
../)/)\\server\share)When feature('TEAMMEM') is enabled, shared memory is available:
<project-root>/.claude/memory/
├── MEMORY.md
├── user/
├── feedback/
├── project/
└── reference/Team memory is stored in the project directory (not ~/.claude/) so all team members share the same memories.
// Resolve team memory path
getTeamMemDir(projectRoot)
getTeamMemPath(projectRoot, type, name)Special instructions injected into the system prompt when team memory is active:
You have access to team memory files at <path>.
These memories are shared with all team members.For long-lived assistant sessions, memory works differently:
<project-root>/.claude/memory/
├── logs/
│ └── 2025/
│ └── 01/
│ ├── 2025-01-15.md # Append-only daily log
│ └── 2025-01-16.md
└── topics/ # Distilled from logs
├── architecture.md
└── decisions.mdInstead of maintaining a live MEMORY.md index:
/dream skill distills logs into topic filesscanForMemories(context)Scans for relevant memories before a query:
// Called at query start
const memories = await scanForMemories({
messages,
toolUseContext,
})
// Returns relevant memories based on:
// - Current conversation topic
// - Recent tool usage
// - User messagesfindRelevantMemories(messages)Finds memories relevant to the current conversation:
// Uses semantic matching on:
// - Keywords in messages
// - File paths mentioned
// - Tool names usedMemories have an age field in frontmatter:
---
type: project
created: 2025-01-15
age: fresh | recent | stale | old
---Age affects relevance scoring.
Memory instructions are injected into the system prompt:
## Memory
You have access to memory files that store important information
about this project and user preferences.
To search memories:
1. Check MEMORY.md for the index
2. Read relevant files with FileReadTool
3. Use GrepTool to search across all memory files| File | Purpose |
|---|---|
src/memdir/memdir.ts | Core memory system |
src/memdir/memoryTypes.ts | Memory type definitions |
src/memdir/paths.ts | Path resolution |
src/memdir/memoryScan.ts | Memory scanning |
src/memdir/findRelevantMemories.ts | Relevance matching |
src/memdir/memoryAge.ts | Age tracking |
src/memdir/teamMemPaths.ts | Team memory paths |
src/memdir/teamMemPrompts.ts | Team memory prompts |
src/services/SessionMemory/ | Session memory service |
src/services/extractMemories/ | Memory extraction |
src/services/teamMemorySync/ | Team memory sync |