Memory Template Guide

Memory Template for Claude Code

This is a working example of the MEMORY.md index file and memory structure described in the setup guide. Copy this as your starting point, then let Claude evolve it as you work.

How It Works

The pre_message.sh hook injects MEMORY.md into every prompt
Claude reads the index, clicks through to specific files when relevant
The extract-memories.sh Stop hook auto-saves new memories after conversations
The daily lint catches orphans, broken links, stale entries
The dream consolidation merges, prunes, and cross-references overnight

You don't maintain this manually. Claude does. You just correct it when it's wrong.

Example MEMORY.md

This is the index file at ~/.claude/projects/-home-$USER-dev/memory/MEMORY.md. Keep it under 200 lines. Each entry is one line with a markdown link to the actual file.

# Memory

## Environment
- This machine is a dedicated dev server. Run commands directly, no SSH needed.
- [tmux workflow](user_tmux_workflow.md) - cs alias for roaming Claude sessions between devices
- Node.js v24, PostgreSQL with pgvector, Bun runtime available
- System timezone: Europe/London

## References
- [Deploy tokens](reference_deploy_tokens.md) - Vercel, Supabase deploy commands and tokens
- [API keys](reference_api_keys.md) - third-party service credentials and endpoints
- [Useful repos](reference_useful_repos.md) - evaluated tools and libraries with verdicts

## Project
- [Main app status](project_main_app.md) - current phase, blockers, recent decisions
- [Side project](project_side_project.md) - status and priorities
- [Security audit](project_security_audit.md) - last audit date, findings, fixes applied

## Feedback
- [Testing preference](feedback_testing.md) - use integration tests, not mocks
- [Domain name](feedback_domain.md) - always use myapp.com, never .io or .dev
- [Design workflow](feedback_design_workflow.md) - never skip design phase, always start with reference images
- [Commit style](feedback_commits.md) - conventional commits, no Co-Authored-By lines
- [Error handling](feedback_errors.md) - always use proper error boundaries, no silent catches

Example Memory Files

User Profile (`user_role.md`)

---
name: User profile
description: Role, expertise, preferences for tailoring responses
type: user
confidence: high
verified: 2026-04-01
---

Senior full-stack developer. Primary stack: Next.js, TypeScript, Supabase, Tailwind.
Comfortable with DevOps, Docker, PostgreSQL. New to mobile (React Native/Expo).

Prefers concise responses. Knows what they're doing - don't over-explain basics.
When explaining, focus on the "why" not the "how".

Feedback (`feedback_testing.md`)

---
name: Use real databases in tests
description: Integration tests must hit a real database, not mocks - learned from prod migration failure
type: feedback
confidence: high
verified: 2026-04-01
---

Integration tests must hit a real database, not mocks.

**Why:** Got burned when mocked tests passed but a prod migration failed. Mock/prod divergence masked the issue for weeks.

**How to apply:** When writing test files, always use the test database connection. If a test needs data, seed it in beforeEach and clean in afterEach. Never mock Supabase/Prisma/Drizzle clients.

Project Status (`project_main_app.md`)

---
name: Main app current status
description: Current development phase, recent decisions, active blockers
type: project
confidence: high
verified: 2026-04-05
---

## Status
- Phase: Beta testing with 5 pilot users
- Last deploy: 2026-04-03 (fixed onboarding flow)
- Next milestone: Payment integration (Stripe)

## Recent decisions
- Chose Stripe over Lemon Squeezy for payment processing (better webhooks, team familiar)
- Moved from middleware.ts to proxy.ts for auth (Next.js 16 breaking change)
- Pricing: freemium with $29/mo pro tier

## Blockers
- Waiting on Stripe account approval (submitted 2026-04-01)
- Need to fix mobile responsive layout on settings page

Reference (`reference_deploy_tokens.md`)

---
name: Deployment tokens and commands
description: Vercel and Supabase deploy commands with project IDs
type: reference
confidence: high
verified: 2026-04-05
---

## Vercel
- Project ID: prj_xxxxx
- Deploy: `vercel --prod` (auto-deploys from main branch via GitHub)
- Preview: push to any non-main branch

## Supabase
- Project ref: abcdefghijk
- Dashboard: https://supabase.com/dashboard/project/abcdefghijk
- Push migrations: `supabase db push`
- Generate types: `supabase gen types typescript --project-id abcdefghijk > src/types/database.ts`

Memory Types Cheat Sheet

Type	What to store	Example
user	Your role, expertise, how you like to work	"Senior dev, prefers terse responses, deep Go expertise but new to React"
feedback	Corrections AND confirmed approaches	"Never mock the DB" / "Bundled PR was the right call for refactors"
project	Status, decisions, blockers, deadlines	"Payment integration blocked on Stripe approval, due Apr 15"
reference	External system pointers, credentials, evaluated tools	"Bugs tracked in Linear project INGEST" / "Evaluated claude-mem, verdict: not needed"

Behavioral Feedback (the secret sauce)

These are the memories that make Claude proactively helpful. Without them, Claude has the tools but doesn't know when to reach for them:

---
name: Suggest relevant skills
description: Proactively suggest /skills when the user describes a task that matches one
type: feedback
confidence: high
---

When the user describes a task, proactively suggest the relevant skill before starting work.

**Why:** Skills contain structured workflows that produce better results than ad-hoc prompting. But the user won't always remember which skill to use.

**How to apply:**
- User says "let's build a new feature" -> suggest /brainstorming first
- User says "this bug is weird" -> suggest /systematic-debugging
- User says "let's review this before merging" -> suggest /requesting-code-review
- User says "build me a landing page" -> suggest /frontend-design
- User describes UI work -> suggest 21st.dev MCP tools for component generation

---
name: Never skip design phase
description: Always start UI/website work with design - reference images, Stitch, iterate, then build
type: feedback
confidence: high
---

NEVER jump straight to code for UI work. Always follow the design-first workflow.

**Why:** Building UI without a design spec leads to endless revision cycles. Getting the design right first saves hours of rework.

**How to apply:**
1. Gather reference images or screenshots
2. Use Stitch MCP to generate design system + screen layouts
3. Iterate on the design until it's right
4. Create design.md with the final spec
5. THEN build from the spec using 21st.dev for components

---
name: Suggest parallel agents when task fits
description: Proactively suggest worktree agents, fork-workers, or coordinator mode for parallelizable work
type: feedback
confidence: high
---

When the user has a task that could be parallelized, suggest using subagents or worktree isolation.

**Why:** Single-threaded work is slow. Many tasks have independent parts that can run simultaneously.

**How to apply:**
- Independent code changes across files -> /dispatching-parallel-agents
- Feature branch that needs isolated testing -> /using-git-worktrees
- Research + implementation -> spawn research agent, then implement based on findings
- Code review -> use worktree agent as second reviewer

---
name: Surface relevant tools proactively
description: Flag high-quality repos, tools, or posts relevant to the user's stack without being asked
type: feedback
confidence: high
---

When doing research or evaluating tools, check if similar or competing tools exist that the user should know about. If a repo has significant stars and touches the user's stack, mention it even if they didn't ask.

**Why:** The user found GitNexus (22k stars) and Karpathy's LLM Wiki gist before the AI feed caught them. The system should surface relevant things proactively.

**How to apply:** During tool research, always check for alternatives. When the AI feed surfaces something relevant, flag it in the next briefing or session.

What NOT to save

Code patterns or architecture (read the code)
Git history (use git log)
Debugging solutions (the fix is in the code)
Ephemeral task details (use tasks, not memory)
Anything already in CLAUDE.md

Confidence Levels

Add confidence: high|medium|low to frontmatter:

high - directly stated, verified in code, or confirmed by test
medium - inferred from context, partially confirmed
low - single observation, may not generalize

Low-confidence memories get pruned faster during dream consolidation. High-confidence ones survive.

Bootstrapping Your Memory

Start a Claude session and say:

I want to set up the persistent memory system. Create the memory directory at
~/.claude/projects/-home-[MY_USERNAME]-dev/memory/ with:

1. MEMORY.md index file (start minimal, 5-10 entries)
2. A user_role.md with my profile (ask me questions to fill it in)
3. A feedback file for my most important coding preferences

Then set up the pre_message.sh hook to inject MEMORY.md into every prompt.

Claude will ask you questions, create the files, and the system starts compounding from there. Every session makes it smarter.

Part of the Claude Code setup guide and tooling reference. Built by nullhex.