Skill: alexunitario-sketch/prompt-assemble (version 1.0.4)

--- name: prompt-assemble description: Token-safe prompt assembly with memory orchestration. Use for any agent that needs to construct LLM prompts with memory retrieval. Guarantees no API failure due to token overflow. Implements two-phase context construction, memory safety valve, and hard limits on memory injection. --- # Prompt Assemble ## Overview A standardized, token-safe prompt assembly framework that guarantees API stability. Implements **Two-Phase Context Construction** and **Memory Safety Valve** to prevent token overflow while maximizing relevant context. **Design Goals:** - ✅ Never fail due to memory-related token overflow - ✅ Memory is always discardable enhancement, never rigid dependency - ✅ Token budget decisions centralized at prompt assemble layer ## When to Use Use this skill when: 1. Building or modifying any agent that constructs prompts 2. Implementing memory retrieval systems 3. Adding new prompt-related logic to existing agents 4. Any scenario where token budget safety is required ## Core Workflow ``` User Input ↓ Need-Memory Decision ↓ Minimal Context Build ↓ Memory Retrieval (Optional) ↓ Memory Summarization ↓ Token Estimation ↓ Safety Valve Decision ↓ Final Prompt → LLM Call ``` ## Phase Details ### Phase 0: Base Configuration ```python # Model Context Windows (2026-02-04) # - MiniMax-M2.1: 204,000 tokens (default) # - Claude 3.5 Sonnet: 200,000 tokens # - GPT-4o: 128,000 tokens MAX_TOKENS = 204000 # Set to your model's context limit SAFETY_MARGIN = 0.75 * MAX_TOKENS # Conservative: 75% threshold = 153,000 tokens MEMORY_TOP_K = 3 # Max 3 memories MEMORY_SUMMARY_MAX = 3 lines # Max 3 lines per memory ``` **Design Philosophy**: - Leave 25% buffer for safety (model overhead, estimation errors, spikes) - Better to underutilize capacity than to overflow ### Phase 1: Minimal Context - System prompt - Recent N messages (N=3, trimmed) - Current user input - **No memory by default** ### Phase 2: Memory Need Decision ```python def need_memory(user_input): triggers = [ "previously", "earlier we discussed", "do you remember", "as I mentioned before", "continuing from", "before we", "last time", "previously mentioned" ] for trigger in triggers: if trigger.lower() in user_input.lower(): return True return False ``` ### Phase 3: Memory Retrieval (Optional) ```python memories = memory_search(query=user_input, top_k=MEMORY_TOP_K) for mem in memories: summarized_memories.append(summarize(mem, max_lines=MEMORY_SUMMARY_MAX)) ``` ### Phase 4: Token Estimation Calculate estimated tokens for base_context + summarized_memories. ### Phase 5: Safety Valve (Critical) ```python if estimated_tokens > SAFETY_MARGIN: base_context.append("[System Notice] Relevant memory skipped due to token budget.") return assemble(base_context) ``` **Hard Rules:** - ❌ Never downgrade system prompt - ❌ Never truncate user input - ❌ No "lucky splicing" - ✅ Only memory layer is expendable ### Phase 6: Final Assembly ```python final_prompt = assemble(base_context + summarized_memories) return final_prompt ``` ## Memory Data Standards ### Allowed in Long-Term Memory - ✅ User preferences / identity / long-term goals - ✅ Confirmed important conclusions - ✅ System-level settings and rules ### Forbidden in Long-Term Memory - ❌ Raw conversation logs - ❌ Reasoning traces - ❌ Temporary discussions - ❌ Information recoverable from chat history ## Quick Start Copy `scripts/prompt_assemble.py` to your agent and use: ```python from prompt_assemble import build_prompt # In your agent's prompt construction: final_prompt = build_prompt(user_input, memory_search_fn, get_recent_dialog_fn) ``` ## Resources ### scripts/ - `prompt_assemble.py` - Complete implementation with all phases (PromptAssembler class) ### references/ - `memory_standards.md` - Detailed memory content guidelines - `token_estimation.md` - Token counting strategies

path: references/memory_standards.md
content: # Memory Data Standards

## Overview

This document defines what should and should NOT be stored in long-term memory systems.

---

## ✅ Allowed Content

### 1. User Preferences / Identity / Long-Term Goals
- User name, pronouns, timezone
- Communication preferences (language, channel)
- Long-term projects and goals
- Personal values and priorities

**Example:**
```
User: Alex
Timezone: UTC+8
Preferred: PDF output, Telegram delivery
Projects: Research analysis, daily briefs
```

### 2. Confirmed Important Conclusions
- Decisions made and confirmed by user
- Established facts and findings
- Important lessons learned
- Verified information

**Example:**
```
OneDrive sync: Local folder "octavius_museum" maps to root
Strike reporting: Always include next 5 days
```

### 3. System-Level Settings and Rules
- Architecture decisions
- Token safety rules
- Agent behaviors and constraints
- Operational procedures

**Example:**
```
Memory injection: Two-phase only, no full load
Token budget: Safety margin at 85%
Safety valve: Memory is expendable
```

---

## ❌ Forbidden Content

### 1. Raw Conversation Logs
- Exact copies of chat messages
- Unprocessed dialogue history
- Conversation transcripts

**Why:** Can be recovered from chat history; takes up token space.

### 2. Reasoning Traces
- Internal monologue or thought process
- Hypothesis and testing steps
- Debugging attempts
- "Mental notes" not finalized

**Why:** Only relevant during the conversation; not reusable.

### 3. Temporary Discussions
- On-going debates
- Incomplete decisions
- Draft ideas not yet confirmed
- Exploratory conversations

**Why:** May change; not confirmed facts.

### 4. Recoverable Information
- Information that exists elsewhere (docs, files)
- Data that can be retrieved from tools
- Duplicate information
- Time-sensitive content (dates, events)

**Why:** Duplication wastes tokens; may become outdated.

---

## Memory Quality Checklist

Before storing in long-term memory, ask:

1. ☐ Is this a reusable fact? (not conversation)
2. ☐ Has the user confirmed this? (not draft)
3. ☐ Is this not recoverable elsewhere?
4. ☐ Is this stable over time? (not time-sensitive)
5. ☐ Does this justify token cost?

If all yes → Store in long-term memory.
If any no → Discard or keep in session only.


path: references/token_estimation.md
content: # Token Estimation Strategies

## Overview

Different approaches to estimating token count for prompt assembly.

---

## Simple Estimation (Recommended)

**Formula:** `tokens ≈ characters / 3.5`

```python
def estimate_tokens(text: str) -> int:
    return len(text) // 3.5
```

**Accuracy:** ±20% (sufficient for safety checks)

**Pros:**
- Simple, fast
- No external dependencies
- Works for mixed languages

**Cons:**
- Not precise
- Overestimates for English
- Underestimates for code

---

## BPE-Based Estimation

More accurate but requires library.

```python
import tiktoken

def estimate_tokens(text: str, model: str = "claude-3-5-sonnet-20241022") -> int:
    encoding = tiktoken.encoding_for_model(model)
    return len(encoding.encode(text))
```

**Accuracy:** ±5%

**Pros:**
- Accurate for specific model
- Handles special tokens

**Cons:**
- Requires `tiktoken` library
- Model-specific
- Slower

---

## Language-Aware Estimation

Adjust ratio based on detected language.

```python
def estimate_tokens(text: str) -> int:
    # Rough heuristics
    if any(ord(c) > 127 for c in text):  # Contains non-ASCII (likely Chinese)
        return len(text) // 2
    else:
        return len(text) // 4
```

**Accuracy:** ±15%

---

## Practical Recommendations

### For Safety Valve
Use **simple estimation** - precision not critical, just need a safety buffer.

### For Exact Limits
Use **tiktoken** - necessary when near model limits.

### For Mixed Content
Use **language-aware** - better accuracy for multilingual prompts.

---

## Model Limits Reference

| Model | Context Limit |
|-------|---------------|
| Claude 3.5 Sonnet | 200K |
| Claude 3 Opus | 200K |
| GPT-4o | 128K |
| MiniMax-M2.1 | 256K |

**Always set SAFETY_MARGIN = 0.85** to leave buffer for model variations.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)