Essence Compact Surface Design (WS-D)

Design for reducing the default Essence tool surface from 52 tools to 6 core tools, part of the Essence Hardening program.

Motivation

The current Essence plugin registers 52 tools across 4 toolsets at ~15,500 schema bytes. Most sessions use only 5-6 tools regularly. The rest bloat context windows, increase schema load, and create audit noise.

Design Target

Aspect Before After
Default tools 52 6
Schema bytes (default set) ~15,500 ~3,200
Startup ritual 5 separate calls 1 compact read
Proposal tools 11 separate 1 typed surface
Toolsets 4 3 (core, optional, governance)
Context tokens saved — ~200-400/turn

Compact Default Surface

essence_compact_read     — One-call context read (state, bond, cooldowns, budget, public cards)
essence_state_update     — Unified mood/energy/mode in one typed call
essence_bond_react       — Unified bond event (merges react+adjust, ±5 cap)
essence_propose          — One typed proposal surface (replaces 11 specific propose tools)
essence_proposal_status  — Proposal lifecycle read
essence_memory_candidate — Memory pipeline: propose→review→list

Optional Toolsets

  • essence_optional_photo_gacha (11 tools) — photo gate configs, asset catalogs, pipeline status, gacha pulls, group bond events
  • essence_optional_diagnostics (4 tools) — microthought, dream context, distill context, expression status

Governance-Only Tools

  • essence_expression_propose — too loose for ungoverned use
  • essence_propose with draft_linear_update, draft_discord_message, review_card types — external system drafts need governance
  • essence_memory_review_commit — per WS-B: sister tools must not claim governance identity for Mnemosyne writes

Key Design Decisions

  1. Five-call startup → one compact read. A single essence_compact_read call returns state + bond + cooldowns + budget + public card in one shot (~800 tokens max). Reduces mandatory startup from 2000 schema bytes to ~500.

  2. Single typed proposal surface. 11 specific proposal tools replaced by one essence_propose tool with a proposal_type enum. Each type defines its own metadata schema.

  3. Bond react absorbed bond adjust. Unified ±5 cap with a manual flag to select between 5-min (reactive) and 15-min (manual) cooldown. Eliminates a separate tool for marginal delta difference.

  4. Inline gate checks. The old essence_proposal_gate_check and essence_proposal_approval_dry_run are removed — gate results are returned inline from essence_propose.

  5. Decision dry-run removed. essence_decision_dry_run and essence_local_mind_dry_run have no proven call path. Weighted fallback handles evaluation; the dry-run tools were dead code.

Migration

All old tools follow a staging plan:

  • Phase 0: Create new schemas and handlers (additive, safe)
  • Phase 1: Dual registration — old and new coexist
  • Phase 2: Profile config switch to new toolsets
  • Phase 3: Old tools return deprecation errors with replacement hints
  • Phase 4: Remove deprecated code

Each deprecated tool returns a structured error:

{"ok": false, "error": "deprecated: Use essence_propose with proposal_type='dream'"}

A/B Evaluation

7-day A/B cycle comparing baseline (SOUL + memory, no Essence) vs compact Essence:

Metric Pass Threshold
Identity consistency 60% fewer corrections
Continuity accuracy 2x cross-session recall
Useful proactivity 2x user-thanks rate
Tool calls per turn 35% reduction
Schema token cost 75% reduction
Audit noise No increase

Automatic revert triggers: latency >2x baseline, 5+ corrections in one session, or identity inconsistency >1 per 10 messages in 24h.

Cost Estimate

  • Implementation effort: ~10-12 hours (Tai)
  • Files changed: 5 (adapter.py, 4× config.yaml)
  • New dependencies: None
  • Rollback: Config revert for Phase 2, git revert for Phase 4
next Home