CLAUDE.md files provide hierarchical context that Claude Code loads automatically. They should be kept up-to-date to ensure accurate infrastructure knowledge.
Hierarchical Loading
Context loads from general to specific, with each level adding more detail:
~/.claude/CLAUDE.md
User-level: Personal preferences, global settings, cross-project patterns
~/projects/CLAUDE.md
Infrastructure-level: Server info, core services, naming conventions, network architecture
~/projects/{service}/CLAUDE.md
Service-level: Specific deployment details, configs, troubleshooting for that service
What Belongs in CLAUDE.md
Include
Exclude
Current architecture and services
Temporary states or WIP notes
Network topology and ports
Secrets or credentials
Standard deployment procedures
Session-specific context
Naming conventions and standards
Personal opinions (use OpenMemory)
Common troubleshooting steps
One-time fixes (use OpenMemory)
Integration points and dependencies
Historical changes (use git)
Keeping CLAUDE.md Updated
💡
Best Practice
After deploying a new service or making significant changes, update the relevant CLAUDE.md file. This ensures future sessions have accurate context.
# Example: Update project CLAUDE.md after deploying new service# 1. Add to ~/projects/CLAUDE.md if it's a core service# 2. Create ~/projects/{service}/CLAUDE.md for service-specific details# Standard sections for service CLAUDE.md:
## Project Overview
# What the service does, current status
## Architecture
# How it connects to other services
## Configuration
# Key settings, environment variables
## Common Operations
# Deploy, restart, check logs
## Troubleshooting
# Known issues and solutions
The /cmemory Command
The /cmemory slash command saves proven facts and lessons learned to OpenMemory, an AI-powered semantic memory system.
When to Use /cmemory
📝
Use /cmemory after completing a task where you learned something valuable - a gotcha, a solution to a tricky problem, or a decision rationale that should be remembered.
# Good times to run /cmemory:# After solving a tricky problem
User: "Finally fixed that postgres connection timeout. /cmemory"
# After discovering a gotcha
User: "Turns out the OAuth2 proxy needs keycloak-net. /cmemory"
# After making an important decision
User: "We chose Redis over Memcached for sessions. /cmemory"
# After a successful deployment with lessons
User: "Service deployed. Had to use --privileged flag. /cmemory"
What /cmemory Saves vs Skips
SAVE (Experiential Knowledge)
SKIP (Belongs in Files)
Lessons from failures or mistakes
Current IP addresses, hostnames
Proven solutions to specific problems
Standard deployment procedures
User preferences discovered
Information already in CLAUDE.md
Gotchas and edge cases
General documentation
Decision rationale (the "why")
Temporary states
Performance lessons learned
Config values (put in files)
Memory Categories
Each memory is stored with a category for better organization and retrieval:
gotcha
Things commonly forgotten or that trip people up
lesson
Knowledge gained from experience
solution
How we solved a specific problem
decision
Why we chose approach A over B
preference
User's preferred way of doing things
fact
Important factual information
How OpenMemory Works
OpenMemory uses semantic search to find relevant memories even when exact words don't match.
Storage Architecture
Memory Text
->
Gemini Embeddings
->
768-dim Vector
Qdrant Vector DB
+
PostgreSQL Metadata
Data Elements Stored
# Each memory contains:
{
"text": "[project] The actual lesson with full context",
"category": "gotcha | lesson | solution | decision | preference",
"metadata": {
"project": "service-name",
"timestamp": "2025-11-25T12:00:00Z",
"source": "claude-code",
"embedding_model": "text-embedding-004",
"embedding_dim": 768
}
}
How Relevant Memories Are Found
When Claude encounters a problem, it can search OpenMemory semantically:
Current Context
->
Generate Query Embedding
|
Vector Similarity Search
->
Top N Relevant Memories
🔍
Semantic Search Power
Searching for "postgres connection issues" will find memories about "database timeout errors" or "psql authentication failed" because the AI understands they're related concepts.
MCP Integration
OpenMemory is accessible via MCP tools from any session:
# Available MCP operations:add_memory# Store new memory with category and metadatasearch_memories# Semantic search by meaninglist_memories# List with filtering and paginationdelete_memory# Remove specific memory by ID# Access points:# - MCP Proxy: http://localhost:9090/openmemory/mcp# - Direct API: http://localhost:8765# - UI: https://openmemory.ai-servicers.com
Best Practices Summary
For CLAUDE.md Files
Keep current: Update after significant changes to services
Be specific: Include actual commands, ports, URLs
Follow hierarchy: General info in project root, specifics in service directories
Include troubleshooting: Document common issues and solutions
Version control: CLAUDE.md files should be in git
For /cmemory Usage
Quality over quantity: Only save truly valuable lessons
Be experiential: Save things learned from doing, not just reading
Include context: Mention the project/service in the memory text
Use after success: Run after solving problems or completing tasks
Check for duplicates: The command searches before saving
The Two Systems Work Together
🔄
CLAUDE.md tells Claude "what is" (current state, how things work) OpenMemory tells Claude "what we learned" (lessons, gotchas, decisions)
# Save current session learnings/cmemory# Search memories via API
curl -X POST 'http://localhost:8765/api/v1/memories/search' \
-H 'Content-Type: application/json' \
-d '{"query": "postgres connection", "limit": 5}'
# List recent memories
curl 'http://localhost:8765/api/v1/memories/?page=1&size=10'