[Feature] Short@Tags — Semantic Compression Protocol for AI Context Windows

Problem

CLAUDE.md files grow. Context windows compact. Institutional knowledge gets lost in the compression.

Every team using Claude Code hits this: your CLAUDE.md starts at 30 lines, grows to 300, then context compaction strips the nuance that made those rules meaningful. You end up re-teaching the same lessons every session.

Proposed Solution: Short@Tags

A lightweight semantic compression protocol where single tags carry the full weight of institutional decisions, incidents, and policies.

Format:

• @tag — Actionable entities (agents, systems, commands). grep-friendly.
• #tag — Abstract concepts (principles, categories, rules). grep-friendly.

Example — before:

Never write secrets to the filesystem. Always use Azure Key Vault.
Route secrets through stdin pipes, never CLI args or stdout.
This rule exists because on 2026-03-04 we had 16 credential 
exposures when Playwright tool inputs were logged to the session transcript.

After:

#COMPUSEC #VAULT_ONLY: Secrets go vault → env var → stdin pipe → consumer. 
Never filesystem. Never CLI args. Never stdout. (Incident 2026-03-04: 16 exposures via Playwright transcript logging)

One tag (#COMPUSEC) now instantly evokes the entire security posture across every file where it appears. grep -r "#COMPUSEC" finds every security-relevant rule in the project.

How It Works in Practice

We've been running this in production across a 870+ script codebase for months. The tag system emerged organically from real incidents:

| Tag | Encodes | Origin |
|-----|---------|--------|
| #ANTI_SPIRAL | Stop after 2 failed attempts, don't brute-force | 15 failed auth attempts locked an account |
| #SLOW_IS_FAST | Write the ticket before the code | 715 lines written, then 4 governance blocks because no ticket existed |
| #EINSTEIN_RULE | 3 identical failures = change method, don't retry | AI hallucination loops doing same thing expecting different results |
| @JOBSLOT | Activate domain-expert persona before fixing domain problems | Generic AI "fixes" that missed domain depth |
| #NEVER_SIMULATE | No stubs, no placeholders, no skeleton files | AI generating empty files that looked like progress |

Each tag is a compressed incident report. The AI reads #ANTI_SPIRAL and immediately knows the full behavioral protocol without needing the 200-word explanation in context.

Why This Matters for Claude Code

1. Context window efficiency — Tags compress paragraphs into tokens. A CLAUDE.md with 50 tagged rules fits where 50 paragraphs wouldn't survive compaction.

1. Cross-file consistency — When #COMPUSEC appears in CLAUDE.md, memory files, and hook scripts, grep connects them all. No orphaned rules.

1. Institutional memory survives compaction — When context compresses, #ANTI_SPIRAL survives as a single token. The full protocol is reconstructed from the tag's semantic weight, not from preserved paragraphs.

1. Human-AI shared vocabulary — The operator says "that's an #ANTI_SPIRAL situation" and both sides instantly align. No explanation needed.

1. Composable — Tags combine: #COMPUSEC #VAULT_ONLY @MARVIN = "security rule, vault-only secrets, reviewed by the security persona." Three tokens, full context.

What Could Be Built

• Native tag registry in Claude Code settings (like settings.json but for semantic tags)
• Tag-aware compaction — preserve tagged lines during context compression (they're high-density by design)
• Tag inheritance — project-level tags in CLAUDE.md, org-level in ~/.claude/settings
• Tag discovery — Claude suggests tags when it detects recurring patterns ("You've mentioned this secret-handling rule 4 times — want to tag it #VAULT_ONLY?")

Prior Art

This draws from:

• Hashtag systems (Twitter/X) — but typed and weighted
• Semantic web metadata — but human-readable and zero-infrastructure
• Einstein's "Never memorize what you can look up" — tags are lookup keys, not storage

Implementation Status

We have a working implementation including:

• Tag registry schema (config/shortag_registry.json)
• Type system (@mention = actionable, #hashtag = abstract)
• Precedence hierarchy (execution > concept > pipe)
• Contextual weighting (0.0–1.0 relevance scoring)
• Alias and pipe relationships between tags

Happy to share the full spec and implementation if there's interest.

---

Built by a veteran/caregiver running a self-funded startup on Claude Code Max. The short@tags system wasn't designed in theory — it was forged from 3 months of daily production usage where every lost context window cost real time and money.