pal-e-docs

Convention: Memory Scope

convention-memory-scope Convention

active convention
Project

Convention: Memory Scope

Claude Code memory (~/.claude/projects/.../memory/) and pal-e-docs serve different purposes. Mixing them causes bloat, staleness, and truncation. This convention defines what goes where.

Decision Gate

Ask: "Is this about HOW to work, or WHAT is happening?"
Memory (behavioral) pal-e-docs (state)
<strong>Purpose</strong> How Lucas wants Betty Sue to work What's happening across projects
<strong>Changes</strong> Rarely — when Lucas corrects behavior Constantly — every phase, deploy, bug
<strong>Loaded</strong> Auto-injected at session start (no tool call) Queried via MCP tools + vectors
<strong>Examples</strong> feedback corrections, user preferences, identity, naming conventions project status, plan progress, deployment state, architecture, incidents, SOPs
<strong>Risk if stale</strong> Low — behavioral rules are stable High — stale project state creates false confidence
<strong>Target size</strong> MEMORY.md under 100 lines, ~30 topic files 500+ notes, 5600+ blocks, vectorized

What Belongs in Memory

  • Feedback corrections — "don't mock the DB," "continuous kanban not sprints," "tofu plan needs -lock=false"
  • User preferences — communication style, review expectations, design philosophy
  • Identity — project names, naming conventions, organizational taxonomy
  • Repo locations — short pointers to working directories (stable, rarely change)

What Does NOT Belong in Memory

  • Project status — what's deployed, what's broken, what PR merged → project pages and plan notes
  • Phase progress — session snapshots, what got completed → phase notes with status fields
  • Deployment details — Keycloak config, CI pipeline state, secrets → SOPs and reference notes
  • Architecture — how systems connect → architecture diagram notes
  • Lessons learned — operational wisdom → deployment-lessons note or SOPs

Why This Matters

MEMORY.md has a 200-line truncation limit. At 224 lines, critical content was being cut. 76% of the content was project state duplicated from pal-e-docs — "262 notes" when there were 500+, phases marked "IN PROGRESS" that were completed. Stale state is worse than no state because it creates false confidence.
With vectors live on pal-e-docs (semantic search across 500+ notes), project state is queryable dynamically — current, relevant, and ranked by meaning. Memory should carry only what vectors can't: behavioral corrections that shape HOW Betty Sue works, not WHAT she works on.

Backup Procedure

Before making bulk changes to memory files:
Rollback: tar xzf ~/.claude/backups/memory-YYYY-MM-DD.tar.gz -C ~/.claude/projects/-home-ldraney-pal-e-platform/
Memory files are NOT in git (auto-memory writes would make the repo perpetually dirty). Tar backups live in ~/.claude/backups/.
  • phase-pal-e-docs-f13-context-intelligence — the phase that created this convention
  • agent-betty-sue — Betty Sue's personality and session bootstrap
  • convention-block-first-access — how to query pal-e-docs efficiently (TOC → section → full note)