Recommendations & Action Plan

Concrete, phased plan from immediate fixes to a full semantic memory routing pipeline.

Phase 1: CLAUDE.md Fixes 30 min Critical

Highest-impact changes. Zero infrastructure required.

R1. Add "Always-On Rules" Section

Inline the 5 most universal behavioral rules directly in CLAUDE.md. These are short enough to embed (~5 lines) and should never require a file read:

# Always-On Rules (apply to every task)
- One fix at a time: only implement the specific approved change. Don't bundle extras.
- Verify claims: label uncertain statements as "Claim:" and offer to verify before acting.
- Evidence first: debug from logs/data, never speculation. Cite the log line.
- No magic strings: use constants or enums, never string literals for property checks.
- Timebox debugging to ~1h, then build a minimal reproduction to isolate variables.

R2. Add Missing Triggers

Add these to the appropriate sections of CLAUDE.md:

# In the Projects section or a new "Context Triggers" section:
- Before working on CVs or job applications — read [cv.md](memory/cv.md)
- Before working on the video platform downloader/server ownership —
  read [project_video_platform_ownership.md](memory/project_video_platform_ownership.md)
- Before working on SC/stripchat protocol —
  read [reference_streamonitor.md](memory/reference_streamonitor.md)
- Before generating PDFs from HTML —
  read [reference_pdf_convert.md](memory/reference_pdf_convert.md)

R3. Link Project Memories from Project Entries

Instead of just listing directories, add memory links:

- **Video Platform** (local): `~/Documents/wip/video-repos/video-platform/`
  See [project_video_platform_ownership.md] for service boundaries,
  [reference_streamonitor.md] for SC protocol.

R4. Add Orphan to MEMORY.md

Add svelte5-pitfalls-detail.md to the MEMORY.md index (it's 11 KB and currently invisible).

Phase 2: Consolidate Memories 1 hour

Reduce file count by merging overlapping memories. This improves signal-to-noise ratio in the MEMORY.md index.

Net result: -4 files, zero information loss, cleaner MEMORY.md index.

Standardize Frontmatter

Add YAML frontmatter to all files that lack it (browser-automation, google-docs, hetzner-deploy, local-apps, plane, svelte5-pitfalls, xvfb). The type field enables programmatic filtering.

Group MEMORY.md by Type

Instead of a flat list, organize under headers for faster triage:

# Memory Index

## Behavioral Rules (always apply)
- [feedback_one_fix_at_a_time.md](...) — Only implement the specific approved change
- [feedback_verify_claims.md](...) — Label claims, offer to verify before acting
...

## Tool Guides (triggered by CLAUDE.md)
- [hetzner-deploy.md](...) — Deploy script, server, monorepo handling
...

## Project Knowledge (load when working on project)
- [project_video_platform_ownership.md](...) — Service ownership boundaries
...

## Reference (load on demand)
- [reference_pdf_convert.md](...) — Use weasyprint for HTML-to-PDF
...

## User Profile
- [user_identity.md](...) — Visar Domi's personal details
- [user_role.md](...) — Professional profile

Phase 3: SessionStart Hook 2-3 hours

Build a hook that injects universal behavioral rules at every session start, plus dynamic context.

The Hook Script

#!/bin/bash
# ~/.claude/hooks/session-context.sh
# Inject always-on rules + dynamic context at session start

MEMORY_DIR="$HOME/.claude/projects/-home-visar/memory"

# Always-on behavioral rules (compact form)
RULES="## Session Context (auto-injected)

### Always-On Rules
1. One fix at a time - only the approved change, no extras
2. Verify claims before acting - label uncertainty
3. Evidence-first debugging - cite logs, not speculation
4. No magic strings - use constants/enums
5. Timebox debugging to ~1h, then build minimal repro
6. No overflow-hidden as safety net - fix root causes"

# Dynamic context
GIT_INFO=""
if git rev-parse --git-dir >/dev/null 2>&1; then
  BRANCH=$(git branch --show-current 2>/dev/null)
  RECENT=$(git log --oneline -3 2>/dev/null)
  GIT_INFO="
### Git State
Branch: $BRANCH
Recent commits:
$RECENT"
fi

CONTEXT="$RULES$GIT_INFO"

jq -n --arg ctx "$CONTEXT" '{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": $ctx
  }
}'

Hook Configuration

// Add to ~/.claude/settings.json hooks.SessionStart array:
{
  "matcher": "startup|resume",
  "hooks": [{
    "type": "command",
    "command": "/home/visar/.claude/hooks/session-context.sh",
    "timeout": 5000
  }]
}

Phase 4: Path-Scoped Rules 1 hour

Convert project-specific knowledge into path-scoped rules that auto-trigger when Claude accesses matching files. This is the most reliable routing mechanism — mechanically enforced by the harness.

Example Rules

# ~/.claude/rules/svelte-conventions.md
---
paths:
  - "**/*.svelte"
  - "**/+page.svelte"
  - "**/+layout.svelte"
  - "**/svelte.config.*"
---
# Svelte 5 Conventions
Read svelte5-pitfalls.md before writing Svelte code. Key rules:
- Use $state, $derived, $effect runes (not $: reactive)
- Never call imperative library APIs inside $effect
- Use an adapter boundary with requestAnimationFrame
- Check the full pitfalls list in memory/svelte5-pitfalls.md

# ~/.claude/rules/service-worker-safety.md
---
paths:
  - "**/sw.js"
  - "**/sw.ts"
  - "**/service-worker.*"
---
# Service Worker Rules
- SW fetch handler must NOT use respondWith(fetch())
- This breaks ES module caching and causes triple module evaluation
- See memory/feedback_sw_fetch_handler.md for details

# ~/.claude/rules/cv-work.md
---
paths:
  - "**/cv/**"
  - "**/resume/**"
  - "**/visar-job-search/**"
---
# CV Work Rules
- Read memory/cv.md before any CV changes
- Never overwrite CV versions - always create vN+1
- Must hit recruiter keywords: TypeScript, React, Node.js, SQL, CI/CD

# ~/.claude/rules/deploy-safety.md
---
paths:
  - "**/deploy*"
  - "**/Dockerfile"
  - "**/.github/workflows/**"
  - "**/systemd/**"
---
# Deployment Rules
- Read memory/hetzner-deploy.md before deploy changes
- Use systemctl for services - never manual kill/start
- Read memory/feedback_systemd_services.md for lifecycle rules

Phase 5: MCP Semantic Search Weekend project

For when keyword matching isn't enough. Gives Claude an explicit search_memories tool.

Option A: Use Existing MCP Server

Install memorious-mcp (local ChromaDB, full privacy):

# Add to ~/.claude/.mcp.json
{
  "mcpServers": {
    "memory-search": {
      "command": "uvx",
      "args": ["memorious-mcp"],
      "env": {
        "MEMORIOUS_DB_PATH": "/home/visar/.claude/semantic-memory"
      }
    }
  }
}

Then index your existing memory files into it.

Option B: Build Custom MCP Server

A minimal TypeScript MCP server (~50 lines) that:

1. Reads all memory files at startup
2. Embeds them with nomic-embed-text via Ollama
3. Exposes a search_memories(query) tool
4. Returns top-3 most relevant memories with file paths

Your RTX 3060 runs local embeddings with sub-50ms latency. For ~20 files, the entire index fits in memory.

Option C: Embed in SessionStart Hook

Upgrade the Phase 3 hook to query Ollama embeddings:

#!/bin/bash
# memory-router-semantic.sh
INPUT=$(cat)
# Extract initial context/query if available from hook input
# Embed query via Ollama
QUERY_EMBEDDING=$(curl -s http://localhost:11434/api/embeddings \
  -d "{\"model\":\"nomic-embed-text\",\"prompt\":\"$QUERY\"}" | jq '.embedding')
# Compare against pre-computed memory embeddings
# Return top-3 as additionalContext
...

Phase 6: Full Pipeline Optional

Only needed if you have 50+ memory files or find Phases 1-5 insufficient.

Total upfront latency: <600ms. Well within SessionStart timeout (5s default).

Ongoing Maintenance

Archival Convention

When memories become obsolete:

1. Move to memory/archived/ subdirectory
2. Remove from MEMORY.md index
3. Run chezmoi re-add

Regular Review Cadence

• Monthly: Scan MEMORY.md for stale entries. Check if any feedback rules have been superseded.
• Per-project milestone: Review project-specific memories. Update or archive.
• After major framework updates: Check svelte5-pitfalls, local-apps, etc.

Dream/Consolidation

When Claude Code's /dream feature becomes generally available, schedule it as a cron job to auto-consolidate. Until then, manually consolidate after intensive development weeks.

Anti-Patterns to Avoid

Summary: What to Do Now