Memory System - Core Definition

Storage

All memories are stored in the Supabase memories table:

memories
  id UUID PK
  user_id UUID FK → auth.users
  category TEXT NOT NULL      -- 'project', 'preference', 'decision', 'knowledge'
  subcategory TEXT            -- project slug, topic name, or NULL
  key TEXT NOT NULL           -- slugified title (unique per user+category+subcategory)
  value TEXT NOT NULL         -- markdown content
  tags TEXT[]                 -- categorization tags
  confidence TEXT             -- 'high', 'medium', 'low'
  source TEXT                 -- 'explicit', 'inferred', 'rem-sleep', 'memory-init'
  deprecated BOOLEAN DEFAULT false
  created_at TIMESTAMPTZ
  updated_at TIMESTAMPTZ
  UNIQUE(user_id, category, subcategory, key)

Data Storage Rules

• NEVER write memory data to local files (no ~/.claude/memory/ directory)
• Use ToolSearch to discover Supabase MCP tools, then INSERT/UPDATE/SELECT on the memories table
• Local files are not used — all memory is in the database
• Temp files in /tmp/ are acceptable for transient processing

Category Mapping

Content Type	category	subcategory	Examples
Project-specific decisions	project	<project-slug>	"We use Zustand for state"
Cross-project decisions	decision	NULL	"Always use conventional commits"
User preferences	preference	NULL or topic	"Prefer functional components"
General knowledge	knowledge	<topic>	"React 19 server components patterns"

Operations

Write

1. Determine correct category and subcategory
2. Query existing memories for duplicates: SELECT * FROM memories WHERE user_id = auth.uid() AND category = ... AND subcategory = ... AND key = ...
3. If updating existing memory: UPDATE value and updated_at timestamp
4. If new memory: INSERT with proper fields
5. Assign confidence level and tags

Read

1. Query by category and/or subcategory
2. Filter out entries where deprecated = true or confidence = 'low' (unless explicitly requested)
3. Order by updated_at DESC for recency

Search

Query with text matching:

SELECT * FROM memories
WHERE user_id = auth.uid()
  AND (key ILIKE '%search_term%' OR value ILIKE '%search_term%')
  AND deprecated = false
ORDER BY updated_at DESC

Self-Modification Rules

• Never delete: Set deprecated = true instead of deleting rows
• Merge duplicates: If two entries have >50% content overlap, consolidate into one and deprecate the other
• One concept per entry: If a memory covers multiple distinct topics, split into separate rows
• Recency wins: When content conflicts, prefer the newer entry

Confidence Levels

Level	Meaning	When to Use
high	Explicitly stated or repeatedly confirmed	User directly states preference, architectural decision
medium	Inferred from patterns	Observed behavior across multiple sessions
low	Single observation, uncertain	One-off comment, may be context-dependent

Project Name Derivation

To determine the current project name for the subcategory field:

# Priority 1: git remote basename
git remote get-url origin 2>/dev/null | sed 's|.*/||;s|\.git$||'

# Priority 2: current directory basename
basename "$PWD"

Always normalize to lowercase with hyphens (e.g., Stories → stories, My Project → my-project).