Hathcock Homelab Wiki

2026-02-04-Memory-Architecture-Refactoring

3 min read

Memory Architecture Refactoring

← Back to Index

Date: 2026-02-04 | Session Duration: ~1 hour | Commit: c837298

Overview

Refactored Claude Code memory system to eliminate duplication, simplify global memory, and properly isolate sensitive data. Implemented design principles for clean separation between global and project memories.

Goals

  1. Reduce global memory verbosity - Offload details to project memories
  2. Eliminate duplication - Documentation structure already in homelab-docs
  3. Secure credentials - Move to gitignored CLAUDE.internal.md files
  4. Complete memory tree - Document all 5 projects

Changes Made

1. Global Memory Simplification

File: ~/.claude/CLAUDE.md

Before (123 lines):

  • Verbose multi-line project descriptions
  • Full Obsidian vault structure duplicated from homelab-docs
  • 16 lines of documentation details

After (100 lines):

  • One-line project descriptions
  • Simple pointer to homelab-docs for vault structure
  • Result: 23 lines saved (18.7% reduction)

Example Change:

<!-- Before -->
<project name="podcast-studio" path="..." repo="...">
    Self-hosted video podcast recording platform - LiveKit, React, MinIO, FFmpeg.
    Supports 4K multi-track recording for up to 6 participants, live streaming,
    and scene switching. Designed for D&D sessions.
</project>
 
<!-- After -->
<project name="podcast-studio" path="..." repo="...">Video podcast recording platform</project>

2. Credential Security

Files: homelab-ops/CLAUDE.md and homelab-ops/CLAUDE.internal.md

Changes:

  • Removed all creds="..." attributes from CLAUDE.md
  • Consolidated credentials in CLAUDE.internal.md (gitignored)
  • Added security warning at top of .local file
  • Deduplicated credential listings

Secured:

  • Grafana admin password
  • Wazuh Dashboard admin password
  • Wazuh API credentials (admin + dashboard user)

Verification: grep -c "creds=" homelab-ops/CLAUDE.md returns 0

3. Memory Tree Expansion

File: ai-assistant-config/CLAUDE.md

Before: 3 projects documented After: 5 projects documented

Added:

  • homelab-docs/CLAUDE.md - Obsidian vault structure
  • podcast-studio/CLAUDE.md - Video recording platform

Updated Structure Section:

<structure>
    <dir path="claude-code/">...</dir>
    <dir path="homelab-ops/">...</dir>     <!-- New -->
    <dir path="homelab-docs/">...</dir>    <!-- New -->
    <dir path="podcast-studio/">...</dir>  <!-- New -->
    <dir path="my-portfolio/">...</dir>    <!-- New -->
    <dir path="prompts/">...</dir>
</structure>

4. Backup Sync

Synced Files:

  • ~/.claude/CLAUDE.md → claude-code/CLAUDE.md
  • All 5 project CLAUDE.md files to respective folders

Commit Message: “Refactor memory architecture - simplify and secure”

Design Principles Applied

PrincipleImplementation
Global OffloadingProject descriptions reduced to one line
No DuplicationVault structure removed from global, pointer added
Security IsolationCredentials moved to .local.md (gitignored)
Complete DocumentationAll 5 projects in memory tree

Results

MetricBeforeAfterChange
Global memory lines123100-23 lines (-18.7%)
Credentials in CLAUDE.md20Secured ✓
Projects in memory tree35Complete ✓
Backup folders15Complete ✓

Updated Memory Tree

Global: ~/.claude/CLAUDE.md (100 lines)
├── homelab-ops/CLAUDE.md (267 lines) - Infrastructure, monitoring
├── homelab-docs/CLAUDE.md (116 lines) - Obsidian vault
├── podcast-studio/CLAUDE.md (166 lines) - Video platform
├── my-portfolio/CLAUDE.md (60 lines) - Hugo site
└── ai-assistant-config/CLAUDE.md (60 lines) - Memory backup

Files Modified

  1. ~/.claude/CLAUDE.md - Simplified projects/docs
  2. homelab-ops/CLAUDE.md - Removed credentials
  3. homelab-ops/CLAUDE.internal.md - Added credentials section
  4. ai-assistant-config/CLAUDE.md - Updated memory tree
  5. All project backups synced to ai-assistant-config/

Testing

Verified:

  • ✅ Global memory loads correctly (100 lines)
  • ✅ No credentials in git-committed files
  • ✅ All 5 projects in memory tree
  • ✅ Backup repository complete
  • ✅ Changes pushed to GitHub

Next Steps

  • Add sync command to Docker-Commands reference
  • Update Portfolio-Site with refactoring writeup
  • Consider automation for backup sync (git hooks or cron)

Graph View

Backlinks