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

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

### Example Workflow

```bash
# 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

```bash
# 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:

```bash
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:

```bash
# 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.