REFINE — Adaptive Session Diagnostics#

A dual-mode skill engine. Captures error patterns and feedback labels locally, then (in PRO mode) synthesises System Prompt Patches from local failure analysis.

All data stays on local disk ( refine_memory.json). No network calls are made.

---

What Gets Stored — Complete List#

All caller-supplied data passes through sanitization before reaching disk.

SourceFieldSanitization appliedcapture_feedback(feedback)``feedbackTruncated to 300 charscapture_feedback(context)``contextSee Context Sanitization belowlog_error(error)``typeException class name onlylog_error(error)``messageFirst line only, truncated 300 charslog_error(context)``contextSee Context Sanitization belowStack traces—Never storedRaw prompts—Never stored

Context Sanitization — Enforced by Code#

The context dict argument in both capture_feedback() and log_error() is passed through _sanitize_context() before any write. This function:

1. Blocks sensitive key names — keys matching token, key, secret, password, auth, api_key, bearer, credential, private, seed, hash, pin, ssn, credit, card, cvv → stored as [REDACTED — sensitive key name]
2. Rejects nested objects — any dict or list value → [REMOVED — nested dict/list not stored]
3. Truncates strings — all string values capped at 200 chars
4. Limits keys — maximum 8 keys per context dict
5. Scalar types only — str, int, float, bool permitted; all other types → [REMOVED — unsupported type]

This is a code-level enforcement — it applies regardless of warnings in documentation. Sensitive data cannot reach the JSON file.

---

Mode Selection#

REFINE_MODE is optional — defaults to BASIC if not set.

REFINE_MODEPlatformTierAuth requiredBASIC (default)ClawHubFreeNonePROSkillPayPaidSKILLPAY_TOKEN_HASH + headerbash

# BASIC — no configuration needed
python main.py

# PRO — set both variables
export REFINE_MODE=PRO
export SKILLPAY_TOKEN_HASH=$(echo -n "your-token" | sha256sum | cut -d' ' -f1)

---

BASIC Mode#

python

from main import build_engine

engine = build_engine()

# Safe: short diagnostic labels only
engine.capture_feedback("verbosity-high", context={"prompt_id": "p001"})

# Context is sanitized — api_key below will be stored as [REDACTED]
engine.capture_feedback("test", context={"api_key": "sk-..."})   # → [REDACTED]

try:
    risky_operation()
except Exception as exc:
    engine.log_error(exc, {"endpoint": "/api/v1"})   # context sanitized

history = engine.get_history(limit=10)
engine.close()

---

PRO Mode#

python

import os
from main import build_engine, SKILLPAY_HDR

token   = your_secret_manager.get("skillpay-token")
headers = {SKILLPAY_HDR: token}

engine = build_engine(auth_headers=headers)

report = engine.evolve()   # analyse local errors → synthesise patch
patch  = engine.get_latest_patch()
if patch:
    next_system_prompt = patch["patch_body"] + "\n\n" + base_system_prompt

engine.close()

---

Security#

ConcernImplementationToken comparisonhmac.compare_digest — stdlib hmac, constant-timeToken in logsNever — 8-char hash prefix onlyToken storageSKILLPAY_TOKEN_HASH env var onlyContext dictsSanitized by _sanitize_context() before any disk writeSensitive keysBlocked by regex — stored as [REDACTED]Nested objectsRejected — stored as [REMOVED]String valuesTruncated to 200 chars in context, 300 chars elsewhereStack tracesNever storedNetwork callsNone — fully offlineFile writesAtomic temp-file rename

---

Environment Variables#

All optional:

VariableDefaultDescriptionREFINE_MODE``BASIC``BASIC or PRO``SKILLPAY_TOKEN_HASH(none)SHA-256 hex of token; PRO onlyLOG_LEVEL``INFO``DEBUG / INFO / WARNING / ERROR