cg-annotate

Context Guard — Annotate

Add a persistent annotation to a topic file that survives across sessions.

When to Use

Use /cg-annotate <topic> "note text" to save important findings, decisions, or state that should be recalled in future sessions — even after context compaction.

Examples:

• /cg-annotate makine-corpus "TDK min_chars raised to 50 after curator bypass"
• /cg-annotate tokenizer "i/ı distinction fixed in case folding layer"
• /cg-annotate build "vcpkg baseline updated to 2026-03-09"

Steps

1. Determine project key

ANNOT_BASE="$HOME/.claude/annotations"
if echo "${PWD}" | grep -qi "cedra"; then
  PROJECT_KEY="C--cedra"
else
  PROJECT_KEY=$(basename "${PWD}" | tr ' ' '-')
fi
echo "Project key: $PROJECT_KEY"

2. Determine topic

The topic is the first argument (e.g., "makine-corpus", "tokenizer", "build"). If not provided, ask the user: "Which topic? (e.g., makine-corpus, tokenizer, build)"

3. Ensure annotation file exists

ANNOT_FILE="$ANNOT_BASE/$PROJECT_KEY/${TOPIC}.md"
mkdir -p "$(dirname "$ANNOT_FILE")"
if [ ! -f "$ANNOT_FILE" ]; then
  printf '# Annotations: %s\n' "${TOPIC}" > "$ANNOT_FILE"
  printf '<!-- Context Guard v0.4.1 | project: %s -->\n' "${PWD}" >> "$ANNOT_FILE"
fi

4. Append the annotation

DATE=$(date +%Y-%m-%d)
printf '\n## %s\n' "$DATE" >> "$ANNOT_FILE"
printf -- '- %s\n' "$NOTE" >> "$ANNOT_FILE"

5. Confirm

echo "Annotation saved → $ANNOT_FILE"
echo "  Topic: $TOPIC"
echo "  Note: $NOTE"

Output Format

Annotation saved → ~/.claude/annotations/{project}/{topic}.md
  Topic: {topic}
  Note: {note text}

If the user provides a multi-bullet note (e.g., multiple facts), write each as a separate - bullet in the same ## DATE section.

After saving, confirm with the path and note text so the user can verify.