Three Memory Layers
Layer 1: Auto Memory
~/.claude/projects/<slug>/memory/
Fatos persistentes sobre usuario individual. Sobrevive todas as sessoes futuras.
Layer 2: Session Memory
~/.claude/session-memory/<uuid>.md
Notas in-session para context compaction. Lifetime: single session.
Layer 3: Team Memory
.../memory/team/
Shared memories synced server-side per GitHub repository.
graph TB
subgraph AL["Auto Memory (per-project, per-user)"]
AM["MEMORY.md index"] --> UF["user_role.md"]
AM --> FF["feedback_testing.md"]
AM --> PF["project_deadline.md"]
AM --> RF["reference_linear.md"]
end
subgraph SL["Session Memory (per-session)"]
SM["session-uuid.md"] --> CS["Current State"]
SM --> TS["Task Spec"]
SM --> WL["Worklog"]
end
subgraph TL["Team Memory (per-repo, shared)"]
TM["team/MEMORY.md"] --> TF1["team/patterns.md"]
TF1 --> API["(Server API)"]
TM --> API
end
UA["User and Claude conversation"] -->|"extractMemories
background agent"| AL
UA -->|"extractSessionMemory
post-sampling hook"| SL
UA -->|"write to team/
+ watcher push"| TL
style AL fill:#22201d,stroke:#7d9ab8,color:#b8b0a4
style SL fill:#22201d,stroke:#6e9468,color:#b8b0a4
style TL fill:#22201d,stroke:#c47a50,color:#b8b0a4
MEMORY.md & Topic Files
MEMORY.md -- O Index
Max 200 linhas / 25,000 bytes. Funciona como pointer list only, nao content storage. Sem frontmatter. Sempre injetado no system prompt.
---
name: Feedback -- No Mock Database
description: Integration tests must hit real database, never mocks
type: feedback
---
Content with Why and How sections.4 Memory Types
Role, goals, expertise level. Always private.
Corrections AND confirmations. Includes Why reasoning.
Ongoing work, goals, incidents. Dates must be absolute.
External system pointers (Linear, Grafana, Slack).
❌ O que NAO salvar
Extraction Pipeline & Relevance Recall
Memories sao extraidas APOS query loops completos, nunca durante conversas. Mutual exclusion com main agent via hasMemoryWritesSince().
Extraction
- Runs post-query as forked sub-agent
- Mutual exclusion via message cursor
- Shares parent's prompt cache
Relevance Recall
- Sonnet side-query selects up to 5 files
- Reads only first 30 lines (frontmatter range)
- Staleness: "This memory is N days old"
Session Memory Structure
10 Fixed Sections
Extraction Triggers
Team Memory Sync
Server-synced subdirectory, gated behind TEAMMEM build flag + OAuth.
Sync Contract
- Pull: Server wins per-key
- Push: Delta upload via SHA-256 hash
- Batch: 200KB max per PUT
- Deletions: Don't propagate
Secret Scanning
35+ secret patterns do gitleaks ruleset. Detection bloqueia push -- "secrets never reach the server."
Scope Routing per Type
always private
default private
bias toward team
usually team
Path Resolution & Disable Mechanisms
3-Tier Resolution
CLAUDE_COWORK_MEMORY_PATH_OVERRIDE(env var)autoMemoryDirectoryem settings.json (trusted sources only)- Default:
~/.claude/projects/<sanitized-git-root>/memory/
Security: Project settings intentionally excluded from override para prevenir repos maliciosos de redirecionar para ~/.ssh.
4 Disable Mechanisms
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1CLAUDE_CODE_SIMPLE=1autoMemoryEnabled: falsetengu_passport_quail (feature flag)