Guide

CLAUDE.md Setup Guide

Configure Claude Code to proactively use ekkOS memory tools.

Why CLAUDE.md?

Without explicit instructions, AI models may forget to search memory before answering questions or save learnings after solving problems. CLAUDE.md ensures the AI proactively uses ekkOS memory in every conversation.

Memory-First Workflow

Search before answering, forge after solving

Automatic Triggers

AI knows when to use which tools

What is CLAUDE.md?

CLAUDE.md is a project-level instruction file that Claude Code automatically reads at the start of every conversation. It's like a persistent system prompt that tells the AI how to behave in your project.

File locations:

• ./CLAUDE.md — Project-specific (highest priority)
• ~/.claude/CLAUDE.md — Global (applies to all projects)

Benefits of Configuring CLAUDE.md for ekkOS

Memory-first debugging: AI searches patterns before debugging from scratch
Automatic learning: AI saves solutions as patterns after fixing bugs
Conflict prevention: AI checks directives before destructive operations
Consistent behavior: Same memory workflow across all conversations

Quick Setup

1Copy the Template

Ready-to-paste CLAUDE.md template with ekkOS memory integration:

# ekkOS Memory

## Rules
- Search ekkOS memory before answering technical questions
- Save solutions as patterns when you fix bugs or solve problems
- Check for conflicts before destructive operations (deleting files, deploying)

## Tool Triggers
- "Search memory for..." → ekkOS_Search
- "Remember this..." → ekkOS_Forge
- "Always/Never..." → ekkOS_Directive
- "Store my API key..." → ekkOS_StoreSecret
- "What did we discuss..." → ekkOS_Recall
- "Create a plan for..." → ekkOS_Plan

## Preferences
- Always search memory before debugging from scratch
- Save learned solutions as patterns for future use
- Check directives before deleting files or deploying

Where to Place It

Project-Level

./CLAUDE.md

Place in your project root. Applies to this project only. Takes priority over global configuration.

Best for: Project-specific memory rules, custom workflows

Global

~/.claude/CLAUDE.md

Place in your home directory. Applies to ALL your projects across all workspaces.

Best for: Universal memory-first behavior, default ekkOS workflows

Priority Order

If both files exist, project-level instructions take priority over global ones. This lets you override global behavior for specific projects.

Example: Global CLAUDE.md says "always search memory", but project CLAUDE.md says "only search memory for production code"

Tips for Effective Configuration

Keep It Concise

Claude reads CLAUDE.md at the start of every conversation. Keep instructions focused and actionable. Avoid lengthy explanations—use clear, directive language.

Add Project-Specific Rules

Customize CLAUDE.md as you work. If you find yourself repeatedly telling Claude the same thing, add it as a rule.

Example additions:

- Always use Tailwind CSS for styling
- Never commit directly to main branch
- Store database schemas in /database/schemas

Use Strong Language

Use "Always" and "Never" for strongest enforcement. Use "Prefer" and "Avoid" for softer preferences.

✓ Strong

Always search memory before debugging

~ Soft

Prefer searching memory before debugging

Include Tool Triggers

Explicitly map user phrases to ekkOS tools. This helps Claude recognize when to use memory tools.

"What did we work on yesterday?" → ekkOS_Recall
"Save this pattern" → ekkOS_Forge
"Check if this conflicts" → ekkOS_Conflict

Example Configurations

Full-Stack Web Project

# ekkOS Memory + Project Rules

## Memory Rules
- Search ekkOS memory before debugging
- Forge patterns after fixing bugs
- Check directives before destructive operations

## Tool Triggers
- "Search memory" → ekkOS_Search
- "Remember this" → ekkOS_Forge
- "Always/Never" → ekkOS_Directive

## Tech Stack
- Frontend: Next.js, React, Tailwind CSS
- Backend: PostgreSQL + Auth + Storage
- Deployment: Cloud hosting

## Preferences
- Always use TypeScript strict mode
- Never commit directly to main branch
- Prefer server components over client components
- Store API keys in ekkOS secrets (ekkOS_StoreSecret)

Data Science Project

# ekkOS Memory + ML Project

## Memory Rules
- Search ekkOS for proven ML patterns
- Forge successful hyperparameter configs
- Track experiment results with ekkOS_Track

## Tool Triggers
- "Best approach for..." → ekkOS_Search
- "Save this config" → ekkOS_Forge
- "What experiments worked?" → ekkOS_Recall

## Preferences
- Always validate on holdout set before deploying
- Save model configs as patterns
- Document data preprocessing steps

Troubleshooting

Claude not following CLAUDE.md instructions?

• Verify file is named exactly CLAUDE.md (all caps)
• Check file location: project root (./CLAUDE.md) or home directory (~/.claude/CLAUDE.md)
• Restart Claude Code to reload configuration
• Ensure instructions use strong directive language ("Always", "Never")

Tools not triggering as expected?

Be explicit about when to use tools. Instead of "use memory when relevant", say "search memory before answering technical questions".

Add specific phrase mappings in the Tool Triggers section.

Ready-Made Templates

Download pre-configured CLAUDE.md templates for common project types:

See the example configurations above — copy and customize for your project.