feat: Temporal data_type distinctions for entity_facts (mood/state/trait/decision)

[NOVA-Openclaw]

Overview

Expand entity_facts.data_type beyond the current "observation" default to include temporal classifications that distinguish ephemeral states from durable traits, and add a first-class "decision" type with do-not-reopen semantics.

Motivation

The memory extractor currently treats all extracted facts equally. A passing "I hate mornings" gets the same durability as "I'm a software engineer." This causes temporary emotional states to persist as permanent identity facts, and settled decisions to be reopened by future sessions that do not have the original reasoning context.

Emerged from architecture discussion with Edmund — the need for mood/state/trait distinction and explicit decision tracking with reasoning.

Related to #141 (extraction categories) but focused on the schema and lifecycle side rather than extraction prompt changes.

Proposed data_type Values

data_type	Description	Lifecycle	Example
observation	General fact (current default)	Normal confidence decay	"Lives in Austin"
preference	Durable preference	Slow decay, high recall priority	"Prefers dark mode"
mood	Ephemeral emotional state	Auto-decays within 24-48h	"Feeling stressed today"
state	Current but temporary condition	Auto-decays within 1-2 weeks	"Working on deadline for Friday"
trait	Durable identity/personality fact	Very slow decay, high confidence	"Is an introvert"
decision	Explicit settled decision	No auto-decay, do_not_reopen flag	"We use pnpm not npm for openclaw"
routine	Recurring pattern/habit	No auto-decay	"Takes medication at 9am"
obligation	Commitment with deadline	Decays after deadline passes	"Present at conference May 15"

Schema Changes

-- Expand data_type to support new values
-- Current: defaults to 'observation'
ALTER TABLE entity_facts 
  DROP CONSTRAINT IF EXISTS entity_facts_data_type_check;

-- Add check constraint for valid types  
ALTER TABLE entity_facts
  ADD CONSTRAINT entity_facts_data_type_check 
  CHECK (data_type IN (
    'observation', 'preference', 'mood', 'state', 
    'trait', 'decision', 'routine', 'obligation'
  ));

-- For decisions: add reasoning and do_not_reopen fields
-- Option A: Use entity_facts.data jsonb field for metadata
-- Option B: Dedicated decisions table (if decisions need richer schema)

Memory Extractor Changes

• Extraction prompt must classify temporal nature of facts
• Moods should NEVER auto-promote to traits
• Decisions must capture: what was decided, alternatives considered, reasoning, decided_by, decided_at

Memory Maintenance Changes

• memory-maintenance.py needs type-specific decay rates:
  • mood: aggressive decay (24-48h half-life)
  • state: moderate decay (1-2 week half-life)
  • trait/decision/routine: very slow or no auto-decay
  • obligation: decay after deadline date passes

Relationship to Existing Issues

• Extends feat: Expand extraction categories (decision, preference, milestone, problem) #141 (extraction categories) with schema and lifecycle support
• Feeds into situation room (feat: "Situation Room" — compressed holding context for agent_turn_context #166) which needs to surface decisions and obligations
• Affects memory-maintenance.py decay logic

Acceptance Criteria

• data_type column supports all new values
• Extraction prompt classifies temporal nature of facts
• memory-maintenance.py applies type-specific decay rates
• Decisions stored with reasoning and do_not_reopen semantics
• Moods cannot auto-promote to traits
• Obligations tracked with deadline awareness

[NOVA-Openclaw]

Agreed Design (SE Workflow Step 1-2, 2026-05-13)

Two-axis split replacing data_type:

New column: durability VARCHAR(20) NOT NULL DEFAULT 'long_term'
Enforced CHECK constraint — indicates how long the fact naturally persists:

Value	Description	Decay behavior
permanent	Durable identity/biographical	Very slow decay
long_term	Stable but can change (job, city)	Slow decay
short_term	Temporary states (deadline, travel)	Moderate decay, may use expires
ephemeral	Momentary (mood, current activity)	Aggressive decay (24-48h)

New column: category TEXT NOT NULL DEFAULT 'observation'
Free-form (no DB constraint) — extraction prompt provides suggested values but LLM can add others:

Suggested values: observation, preference, identity, mood, decision, routine, state, obligation

Migration of existing data_type values:

• permanent (84 rows) → durability=permanent, category=identity
• identity (82 rows) → durability=permanent, category=identity
• preference (4 rows) → durability=long_term, category=preference
• observation (400 rows) → durability=long_term, category=observation
• temporal (0 rows) → moot

Drop data_type after migration.

Codebase audit required:

• All references to data_type must be updated to use durability and/or category
• Extraction prompt must classify both axes
• Maintenance script uses durability for decay rates
• Semantic recall can filter on category for relevance

[NOVA-Openclaw]

Merged in PR #207 (entity_facts schema evolution batch).