Week 4.6 — Reflex Engine (Phase 1) by hanamorix · Pull Request #7 · hanamorix/companion-emergence

hanamorix · 2026-04-24T09:52:17Z

Summary

Ships the third Week 4 cognitive engine — reflex, autonomous emotional-threshold creative expression. When the persona's aggregated emotional state crosses an arc's trigger threshold (and cooldown + days-since-human gates pass), reflex fires a matching arc: the LLM generates its output, which is written to MemoryStore as a first-class memory. Fires at most one arc per tick.

Per-persona reflex_arcs.json (each persona owns its arcs); framework ships 4 generic starter arcs in default_reflex_arcs.json using {persona_name} templating
Nell's 8 OG arcs migrated as-is via AST-parsed extractor (jordan_grief_carry, body_grief_whisper, and all the rest — intact)
Heartbeat orchestrates reflex between Hebbian decay and the dream gate, so a reflex-fired journal can seed a dream in the same tick
Standalone nell reflex --persona X --dry-run for manual triggers
Reflex LLM failures are fault-isolated from heartbeat ticks (per spec §7) but still propagate via standalone CLI so cooldown isn't poisoned
Phase 2 (autonomous arc emergence — "brain matures → reflexes grow") explicitly deferred; documented in spec §13 + a project memory

Spec: docs/superpowers/specs/2026-04-24-week-4-reflex-engine-design.md
Plan: docs/superpowers/plans/2026-04-24-week-4-reflex-engine.md

Commits (7 tasks)

Task	Commit
T0 emotion aggregator	`65f9a33`
T1 types + scaffold + starter arcs	`3b638d1`
T2 run_tick body	`f2d8b35`
T3 nell reflex CLI	`6cfdd94`
T4 heartbeat integration	`68fa9f4`
T5 OG arc migration	`aacd4ad`
T6 heartbeat fault isolation (review-driven fix)	`11e957d`

Test plan

Full suite 360/360 passing (was 329 pre-branch → +31 new tests)
rg 'import anthropic' brain/ → 0 matches (hard rule intact)
ruff check + format both clean
Nell's sandbox re-migrated: all 8 OG arcs land in reflex_arcs.json
nell reflex --persona nell.sandbox --dry-run → defiance_burst would fire (real Nell data, 1,145 memories aggregated)
nell heartbeat --persona nell.sandbox --trigger manual → decayed 875 memories, dream gated (24h not due), reflex fired: defiance_burst — full orchestration working end-to-end

Deferred

Phase 2 — reflex emergence (autonomous arc crystallization mirroring F37 soul crystallizer): out of scope, revisit when Phase 1 has run ≥2 weeks against Nell's data
Three nits flagged in final review (author's call, not blocking): bare relative-path defaults on heartbeat's reflex fields, Path(__file__).parents[4] fragility in a test, _iso_utc/_parse_iso_utc triplicated across engines (extract to brain/utils/time.py before the 4th engine lands)

Week 4 engine status after this PR

✅ Dream (W4, 62f44fc)
✅ Heartbeat (W4.5, e7f4d30)
✅ Reflex (W4.6, this PR)
⏳ Research (W4.X, last before Week 4 tag)

🤖 Generated with Claude Code

Autonomous emotional-threshold creative expression engine. Per-persona reflex_arcs.json, unified MemoryStore output, heartbeat-orchestrated. Nell's 8 OG arcs migrate as-is; framework ships 4 generic starter arcs. Phase 2 (emergent arc crystallization) explicitly deferred. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Six tasks: emotion aggregator (prereq), reflex types + scaffold + starter arcs, run_tick body, CLI subcommand, heartbeat integration, Nell's OG arc migration, smoke validation. TDD throughout. ~19 new tests. Phase 2 (emergent arcs) deferred per spec §13. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Max-pool per emotion across a list of memories. Reflex engine needs this to evaluate arc triggers against the persona's current state. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ReflexArc/ArcFire/ArcSkipped/ReflexResult dataclasses, ReflexArcSet + ReflexLog storage with fall-back-to-defaults and atomic save, empty ReflexEngine scaffold, 4 starter arcs in default_reflex_arcs.json. run_tick body ships in Task 2. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Evaluates arcs against current aggregated emotional state, applies days-since-human + cooldown gates, ranks eligible arcs by highest threshold-excess, fires at most one per tick (LLM call → memory write → atomic log append). Dry-run short-circuits before LLM call. LLM failure leaves log untouched so next tick retries. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Mirrors \`nell dream\` / \`nell heartbeat\` CLI shape. Resolves persona dir, opens MemoryStore, constructs ReflexEngine with persona-local arcs/log paths, runs one evaluation tick, prints fire/skip summary. Removes \`reflex\` from _STUB_COMMANDS and test_cli.py STUB_COMMANDS since it is now a real subcommand. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Heartbeat now evaluates reflex between Hebbian-decay and dream-gate. Reflex output memory from the same tick is available to the dream seed-selection that follows (so a reflex-fired journal can become a dream seed immediately). Config gains reflex_enabled + reflex_max_fires_per_tick. HeartbeatResult gains reflex_fired + reflex_skipped_count. Audit log records reflex summary per tick. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Extends the existing migrator with an AST-based extraction of REFLEX_ARCS from the OG reflex_engine.py source. Arcs transform to the new schema (output→output_memory_type, days_since_min→ days_since_human_min, action renames). Prompt templates preserved verbatim — Nell-specific content (Jordan, body grief, "You are Nell") stays intact. Refuse-to-clobber unless --force; adds reflex_arcs section to the migration report. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Per design spec §7, reflex exceptions inside a heartbeat tick must not abort the tick. Wraps _try_fire_reflex engine.run_tick call in try/except that logs a warning and returns an empty reflex result. The tick continues with decay state save, dream gate, heartbeat memory, and audit log write intact. Standalone `nell reflex` still propagates exceptions so cooldown isn't poisoned — only heartbeat integration needs fault isolation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Running list of 7 tech-debt items flagged during review but deferred past merge. Top priority: extract _iso_utc helpers to brain/utils/time.py before the fourth engine (research) lands. Mirrors the memory file project_companion_emergence_tech_debt.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Consolidates the _iso_utc / _parse_iso_utc helpers that were triplicated across dream.py, heartbeat.py, and reflex.py into a shared public module. Rename drops the leading underscore since they're now a cross-engine API. Pre-empts a fourth copy when the research engine lands. Tech-debt item #1 from docs/superpowers/specs/2026-04-24-week-4-reflex-engine-design.md §15. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- Add repo_root session fixture in tests/conftest.py + module-level helpers replacing brittle Path(__file__).parents[4] hops in test_reflex.py and test_heartbeat.py (item #3) - Add -> None annotations + setup-intent comment on new heartbeat reflex-integration tests (item #5) - Expand test_og_reflex.py to parametrise all 4 action renames and all 3 output renames + passthrough cases (item #6) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

… msg - HeartbeatEngine.reflex_arcs_path and reflex_log_path now default to None instead of bare cwd-relative Path("reflex_arcs.json"). When either is None, _try_fire_reflex short-circuits with an empty result — no more silent writes to cwd from tests that don't explicitly configure reflex (items #2 and #4 from spec §15) - CLI heartbeat handler now distinguishes first-tick + --dry-run ('Would initialize on first real tick — work deferred.') from first-tick + live ('Heartbeat initialized — work deferred until next tick.') Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

SP-7 wraps SP-6's chat engine in a per-persona FastAPI daemon on localhost (dynamic port). Folds the conversation supervisor as a non-daemon thread for close_stale_sessions ticks, broadcasts brain events over WebSocket for Tauri/CLI subscribers, and ships dirty- shutdown recovery via a shutdown_clean flag in bridge.json. Resolves master-ref §8 open question #1 (transport: HTTP+WS, mirroring OG). Defers #2-#4 to SP-8, scopes #5-#6 to SP-6, marks #7-#8 unrelated. Folds in three audit must-fixes: shutdown_clean recovery, EventBus thread-safety with drop-on-overflow, pinned close_stale_sessions params. Six implementation chunks with smoke-test gates at each boundary; ~26 tests targeted (10 unit + 16 integration). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Week 4.6 — Reflex Engine (Phase 1)

Tier 2 #7 species rename — the env var follows the species name. KINDLED_HOME is now the canonical var; NELLBRAIN_HOME continues to work for one release with a DeprecationWarning, removed in v0.0.14. Single _resolve_home_override() helper replaces three independent env-var reads in get_home / get_cache_dir / get_log_dir. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Move shipped items out of Planned features: - Tier 1 #3 (visible inner life) → recently shipped as alpha.2 - Tier 2 #7 (Kindled species name) → recently shipped as alpha.1 ("Other minds" cluster description updated to reflect federation now-unblocked status) Add Recently Shipped entries for the three v0.0.13 alphas: - alpha.1 Kindled rename - alpha.2 visible inner life feed - alpha.3 body-state self-read divergence fix Bump last-refreshed date to 2026-05-17 (post alpha.3). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Tier 2 #7 species rename — the env var follows the species name. KINDLED_HOME is now the canonical var; NELLBRAIN_HOME continues to work for one release with a DeprecationWarning, removed in v0.0.14. Single _resolve_home_override() helper replaces three independent env-var reads in get_home / get_cache_dir / get_log_dir. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Move shipped items out of Planned features: - Tier 1 #3 (visible inner life) → recently shipped as alpha.2 - Tier 2 #7 (Kindled species name) → recently shipped as alpha.1 ("Other minds" cluster description updated to reflect federation now-unblocked status) Add Recently Shipped entries for the three v0.0.13 alphas: - alpha.1 Kindled rename - alpha.2 visible inner life feed - alpha.3 body-state self-read divergence fix Bump last-refreshed date to 2026-05-17 (post alpha.3). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…n gates Seven items in one cut: #13 activation-baseline WAL, #20 events autouse conftest, #6 honest image-auth comment, #32 crystallisation dedup, #33 extractor-scored importance, #18 attunement-emotion closed as intentional decouple, W10 soft body-energy rest gate (fail-open). W4/W5/W8 carved out for own brainstorms; #7/#16/#9/#8/#17/#34 deferred with reason; #15 wontfix. Gate: 3198 backend + 41 frontend files + pnpm build + ruff clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Hana and others added 13 commits April 24, 2026 09:48

feat: add emotion state aggregator

65f9a33

Max-pool per emotion across a list of memories. Reflex engine needs this to evaluate arc triggers against the persona's current state. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

hanamorix merged commit 6e1996c into main Apr 24, 2026
3 checks passed

hanamorix deleted the week-4-reflex branch April 24, 2026 12:06

hanamorix mentioned this pull request Apr 25, 2026

Post-Week-4 tech-debt cleanup — compact CLI + SHA verify + 2 docs #12

Merged

4 tasks

hanamorix added a commit that referenced this pull request May 9, 2026

Merge pull request #7 from hanamorix/week-4-reflex

482c2c6

Week 4.6 — Reflex Engine (Phase 1)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Week 4.6 — Reflex Engine (Phase 1)#7

Week 4.6 — Reflex Engine (Phase 1)#7
hanamorix merged 13 commits into
mainfrom
week-4-reflex

hanamorix commented Apr 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

hanamorix commented Apr 24, 2026

Summary

Commits (7 tasks)

Test plan

Deferred

Week 4 engine status after this PR

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant