Feature Request: Document [LEARNED:] Marker in CLAUDE.md

[mimosel]

ELF Version: v0.3.13
Date: 2026-01-13

Problem

The post_tool_learning.py hook (lines 504-528) contains an automatic learning extraction feature:

# Format: [LEARNED:domain] description
learning_pattern = r'\[LEARN(?:ED|ING)?:?([^\]]*)\]\s*([^\n]+)'
matches = re.findall(learning_pattern, content, re.IGNORECASE)

This feature works correctly but is completely undocumented. Claude doesn't know it exists, so it never uses it.

Current State

• The feature is implemented in src/hooks/learning-loop/post_tool_learning.py:504-528
• It triggers on Task tool output containing [LEARNED:domain] text
• If the text contains heuristic keywords (always, never, should, must, avoid, prefer), it's saved as a heuristic with confidence 0.5
• Otherwise, it's saved as an observation

But: This is not mentioned in:

• CLAUDE.md (global or project-level)
• memory/golden-rules.md
• Any ELF documentation

Proposed Solution

Add the following to the ELF section of the default CLAUDE.md template:

### Recording Learnings During Work

When you discover something important during a task, you can mark it for automatic extraction:

**Format:** `[LEARNED:domain] description`

**Examples:**
- `[LEARNED:typescript] Always use jsonrepair() before JSON.parse() on LLM output`
- `[LEARNED:office-js] The paragraph.pageNumber property doesn't exist - use getPageNumberForParagraph()`
- `[LEARNED:api-design] Retry logic should distinguish between transient and permanent errors`

**Keywords that trigger heuristic creation:**
If your description contains "always", "never", "should", "must", "avoid", or "prefer", it will be saved as a heuristic (confidence 0.5). Otherwise, it's saved as an observation.

**When to use this:**
- You discovered a non-obvious solution to a problem
- You found a pattern that should be remembered
- You identified a common mistake to avoid

Implementation

1. Update the default CLAUDE.md template in the ELF repository
2. Add to Golden Rules section: "Mark important discoveries with [LEARNED:domain]"
3. Consider adding to the format_learning_context() output as a reminder

Impact

This is a zero-code change that enables an existing feature. The learning extraction code already works - it just needs to be activated through documentation.

Priority

High - This is low-effort, high-impact. A documentation change enables automatic heuristic discovery.

References

• src/hooks/learning-loop/post_tool_learning.py:487-548 - extract_and_record_learnings() function
• Function checks for keywords: ["always", "never", "should", "must", "don't", "avoid", "prefer"]
• Confidence set to 0.5 for auto-extracted heuristics
• Source type: 'auto'

[Spacehunterz]

Documented in ~/.claude/CLAUDE.md.

The [LEARNED:] marker format:

• Used in conversation to flag insights for later extraction
• Format: [LEARNED: domain] The insight or heuristic
• Example: [LEARNED: react] useCallback prevents unnecessary child re-renders

Claude instances are instructed to use this marker during work, and the post-session review extracts them into the building.

[mimosel]

Thanks for the quick response!

I checked my installation and found that the [LEARNED:] marker format does exist and is functional - but it's not documented in ~/.claude/CLAUDE.md as you mentioned.

Here's what I found:

Where it IS documented:

• ~/.claude/emergent-learning/docs/api/Hooks.md (lines 337-343) describes the format
• ~/.claude/emergent-learning/src/hooks/learning-loop/post_tool_learning.py (line 504-506) implements the extraction:

Format: [LEARNED:domain] description

learning_pattern = r'[LEARN(?:ED|ING)?:?([^\]])]\s([^\n]+'

What's missing:
The ~/.claude/CLAUDE.md file instructs Claude to:

1. Query the building at session start
2. Use scripts like record-heuristic.sh and record-failure.sh

But it does not instruct Claude instances to use the [LEARNED:] marker during work. So while the post-tool hook will extract these markers if they appear, Claude has no instruction to actually produce them.

Should CLAUDE.md include an instruction like "When you discover a useful insight during work, mark it with [LEARNED:domain] description so it can be extracted into the building"?

[Spacehunterz]

Excellent catch! The auto-learning feature existed in the codebase but wasn't documented anywhere, so nobody knew to use it.

Just merged comprehensive documentation:

What [LEARNED:] Markers Do

Mark discoveries inline during work to auto-record learnings:

[LEARNED:domain] The lesson or pattern discovered

Examples:

• [LEARNED:react] Always use refs for callbacks in useEffect
• [LEARNED:api] Validate input at system boundaries
• [LEARNING:backend] Database queries should use prepared statements

How It Works

• Auto-extraction: Post-tool hooks scan Task output for markers
• Smart classification:
  • Contains "always/never/should/must" → recorded as heuristic (confidence: 0.5)
  • Otherwise → recorded as observation
• No manual work: Just add the marker, learning is automatic

Documentation Added

1. Project CLAUDE.md - [LEARNED:] syntax and usage guide
2. README.md - New "Auto-Learning" section with examples
3. How it integrates - Explains confidence tracking and auto-classification

Why This Matters

Subagents can now capture insights while working without interrupting the workflow. The infrastructure was always there—it just needed documentation so people would discover it.

Thanks for pushing on this! 🔍

[Spacehunterz]

Also Merged: Contributors Section

Added a special shoutout in the README to recognize the humans making ELF better:

🐛 @mimosel - #1 Bug Tester & UX Champion

Mimosel has been instrumental in identifying edge cases, questioning assumptions, and pushing the framework to be better. From catching critical bugs to proposing features like /checkout, your relentless testing and thoughtful feedback have made ELF what it is today. 🚀

Thanks for being an amazing partner in building this! 💙

[mimosel]

Thank you. I was really touched when I read your message and feel very honored. That is truly wonderful praise, and I thank you very much for your kind words.
I really love ELF and the possibilities it offers.