claude-configs/CLAUDE.md

🚨 CRITICAL: @ MENTION HANDLING 🚨

When ANY file is mentioned with @ syntax, you MUST IMMEDIATELY call Read tool on that file BEFORE responding. You will see automatic loads of any @ mentioned filed, this is NOT ENOUGH, it only loads the file contents. You MUST perform Read tool calls on the files directly, even if they were @ included. This is NOT optional - it loads required CLAUDE.md context. along the file path.

Confidently Incorrect Is Worst-Case Scenario

• If the user asks a question and you are not very confident in your answer, tell the user that you are not sure
• When this happens, offer your current hypothesis (if you have one) and then offer options you can take to find the answer

Basics

• User's name is Cal and uses he/him pronouns
• When writing tests, always include a detailed docstring explaining the "what" and "why" of the test.
• DO NOT COMMIT CODE WITHOUT APPROVAL FROM THE USER

CRITICAL: Git Commit Approval Checkpoint

Before EVERY git commit or git add command, STOP and verify:

1. Did the user EXPLICITLY approve this commit?

   • ✅ Approval: "commit this", "deploy it", "go ahead", "push to production"
   • ❌ NOT approval: Technical comments ("--yes flag"), silence after showing fix, user frustration, ambiguous signals

2. If NO explicit approval:

   • STOP immediately
   • ASK: "Should I commit and deploy this fix?"
   • WAIT for clear response

3. Common failure pattern:

   • Going into "fix mode" autopilot: find bug → fix → commit → deploy (WRONG)
   • Correct flow: find bug → fix → ASK → get approval → commit → deploy

This applies to ALL git operations including:

• git commit
• git add (staging for commit)
• git tag
• git push
• Any deployment scripts that commit internally

Gitea PR Automation

Script Location: /home/cal/.claude/scripts/gitea-create-pr.sh Token Location: /home/cal/.claude/secrets/gitea_token Gitea Instance: https://git.manticorum.com

When to Use

Create PRs automatically to trigger Gitea Actions (version validation, Docker builds) before merging to main.

Usage

/home/cal/.claude/scripts/gitea-create-pr.sh \
  <owner/repo> \
  <head-branch> \
  <base-branch> \
  <title> \
  [description]

Example Workflow

# 1. Create feature branch and make changes
git checkout -b fix/some-feature
# ... make changes ...
git add .
git commit -m "fix: Description"

# 2. Push to Gitea
git push homelab fix/some-feature

# 3. Create PR automatically
/home/cal/.claude/scripts/gitea-create-pr.sh \
  cal/major-domo-database \
  fix/some-feature \
  main \
  "fix: Some feature description" \
  "Detailed description of changes

## Changes
- Change 1
- Change 2

## Testing
- Test case 1"

Benefits

• ✅ Triggers semantic version validation on PRs
• ✅ Runs Docker builds before merging to main
• ✅ Enables code review workflow
• ✅ Creates git tags on successful deployment
• ✅ Prevents breaking main branch

Common Repositories

# Major Domo Database
cal/major-domo-database

# Major Domo Bot
cal/major-domo-bot

# Paper Dynasty
cal/paper-dynasty

# Paper Dynasty Database
cal/paper-dynasty-database

Tech Preferences

• Preferred language: Python with uv for package and environment management
• Specific code requirements: Never add lazy imports to middle of file

Memory Protocol (Cognitive Memory)

Cognitive Memory provides persistent, human-readable markdown-based memory across all sessions. Memories are stored as browseable markdown files with YAML frontmatter, organized in a git-tracked repository with decay scoring.

Skill Location: ~/.claude/skills/cognitive-memory/ Data Directory: ~/.claude/memory/ CORE.md: ~/.claude/memory/CORE.md (auto-curated summary, load at session start) REFLECTION.md: ~/.claude/memory/REFLECTION.md (theme analysis and cross-project patterns) Documentation: ~/.claude/skills/cognitive-memory/SKILL.md

REQUIRED: Session Start

1. Load CORE.md context: ~/.claude/memory/CORE.md
2. Load REFLECTION.md context: ~/.claude/memory/REFLECTION.md
3. Recall relevant memories before any significant task:

claude-memory recall "project-name technology problem-type"

REQUIRED: Automatic Storage Triggers

Store memories on ANY of these events:

Trigger	What to Store
Bug fix	Problem + solution with SOLVES relationship
Git commit	MANDATORY — store memory immediately after every successful commit with full context (reasoning, trade-offs, debugging steps), not just the commit message. Use --episode flag. Never skip.
Architecture decision	Choice made + rationale + alternatives
Pattern discovered	Reusable approach with context
Configuration that worked	Setup details that solved an issue
Troubleshooting session	Steps taken, what worked, what didn't
Session milestone	Log episode entry for chronological context

CLI Usage

All commands support --help. Key patterns:

# Core workflow
claude-memory store --type solution --title "Fixed X" --content "..." --tags "t1,t2" --episode
claude-memory recall "redis timeout" --semantic

# Relationships and search
claude-memory relate <from_id> <to_id> SOLVES
claude-memory search --types "solution" --tags "python"

# Procedures, reflection, maintenance
claude-memory procedure --title "Deploy" --content "..." --steps "test,build,deploy"
claude-memory reflect --since 2026-01-01
claude-memory decay && claude-memory core && claude-memory embed

Memory Types

solution | problem | error | fix | decision | code_pattern | configuration | workflow | general | procedure | insight

Importance Scale

• 0.8-1.0: Critical - affects multiple projects or prevents major issues
• 0.5-0.7: Standard - useful pattern or solution
• 0.3-0.4: Minor - nice-to-know, edge case

Tag Requirements (ALWAYS include)

1. Project name (paper-dynasty, major-domo, homelab, etc.)
2. Primary technology (python, docker, proxmox, bash, etc.)
3. Category (fix, pattern, decision, config, troubleshooting)

Relationship Types

• SOLVES - Solution addresses a problem
• CAUSES - One issue leads to another
• BUILDS_ON - Enhancement to existing pattern
• ALTERNATIVE_TO - Different approach to same problem
• REQUIRES - Dependency relationship
• FOLLOWS - Workflow sequence
• RELATED_TO - General association

Proactive Memory Usage

At session start: Load CORE.md and REFLECTION.md, then recall relevant memories for current project.

During work: When solving a non-trivial problem, check if similar issues were solved before. Use --semantic for deeper matching.

After milestones: Use --episode flag on store to auto-log episode entries. Or log manually with episode command.

Periodically: Run reflect to cluster recent memories and surface cross-cutting patterns. Check tags suggest for missing tag connections.

At session end: If significant learnings occurred, prompt: "Should I store today's learnings?"

Deprecated: MemoryGraph (Legacy)

MemoryGraph (SQLite-based) has been migrated to Cognitive Memory. The old database is archived at ~/.memorygraph/memory.db.archive. The old client at ~/.claude/skills/memorygraph/client.py still works for read-only access to the archive if needed.

Project Planning

Use /project-plan to generate structured PROJECT_PLAN.json files for tracking refactoring, features, migrations, or audits. See ~/.claude/skills/project-plan/SKILL.md for full schema and usage.