[Discussion] Structured CLAUDE.md Metatag System — #hashtags, @agent personas, topic triggers for persistent AI memory

Problem

CLAUDE.md files are powerful but unstructured. As projects grow complex (50+ rules, multiple agent personas, cross-domain workflows), flat markdown becomes hard to navigate — both for humans and for the AI parsing it. There's no convention for:

• Cross-referencing rules, agents, and concepts within CLAUDE.md
• Topic-based routing (e.g., "when working on trading, read trading.md")
• Behavioral tagging that the AI can grep and self-enforce
• Persistent memory that survives context compaction

What We Built

Over ~4 months of daily Claude Code usage, we developed a metatag system inside CLAUDE.md/MEMORY.md that gives the AI a structured instruction vocabulary:

1. #HASHTAG Short-Tags (Einstein Rule: "Never memorize what you can look up")

Every rule, decision, and artifact gets a short-tag at creation. The AI can grep for any concept instantly:

- **VAULT-ONLY SECRETS** #VAULT_ONLY #COMPUSEC — Azure Key Vault only. No .env files...
- **CONSISTENCY OVER BOOST** #CONSISTENCY_OVER_BOOST — Steady compound gains, not spikes...

2. @AGENT Persona References

Named agents with defined roles, referenced inline. The AI knows who owns what:

- **@JARVIS** — CTO: strategic orchestration
- **@MARVIN** — Security (CISSP-level pentest persona)
- **@C-3PO** — Helpdesk entry point, SLA monitoring

3. Topic Trigger Tables

A routing table that tells the AI which memory file to load based on work context:

| When working on... | Read this file |
|---|---|
| trading, 3commas, signals | `trading.md` |
| GPU, VRAM, tensor, llama | `cluster.md` |
| NAS, SSH, Docker, systemd | `infrastructure.md` |

4. Behavioral Stats (LitRPG Telemetry)

AI self-monitoring stats that surface problematic patterns:

• @AUT (autonomics) — is the AI self-governing or asking too many questions?
• @FUD (fear/uncertainty/doubt) — is the AI hedging instead of acting?
• @PERSEVERATION — is the AI retrying the same failed approach?

Why This Matters

We searched for prior art extensively — two academic papers (Santos et al., Chatlatanagulchai et al.) studied 581 CLAUDE.md files total. None contained anything resembling this pattern. The gap between "prompt engineering conventions" and "agent memory architecture" appears unoccupied.

Related research that's converging on similar ideas from the academic side:

• A-MEM (Zettelkasten-inspired, arXiv:2502.12110)
• MemOS (Memory OS for LLMs, arXiv:2505.22101)
• "Memory in the Age of AI Agents" survey (arXiv:2512.13564)
• "Decoding Configuration of AI Coding Agents" (arXiv:2511.09268)

What We're Proposing

Not a spec change — just sharing a pattern that works. If others find it useful:

1. Convention for #SHORT_TAGS — machine-greppable rule identifiers in CLAUDE.md
2. Convention for @AGENT references — named persona routing within instructions
3. Topic trigger tables — context-sensitive file loading based on work domain
4. Periphery bias mitigation — repeating critical rules at the end of CLAUDE.md (LLMs attend more to beginning and end of context)

Happy to share our full CLAUDE.md/MEMORY.md structure if there's interest. This emerged from real daily usage, not theory.