Thoughts – Atomic Claim Specification
Purpose
This document defines the core cognitive unit used by Lucille: the Thought.
A Thought is the smallest meaningful unit of reasoning in the system. Everything higher-level (insights, plans, summaries, notifications) is built from Thoughts.
This spec is intentionally domain-agnostic and future-proof.
⸻
Definition
Thought = Atomic Claim Event
A Thought is a single, time-scoped claim about the user’s state or world, backed by evidence, that may optionally propose a next action.
A Thought must be: • Atomic – one claim only • Composable – many Thoughts can form an Insight • Auditable – has evidence or provenance • Ignorable – the user is not forced to act • Recomputable – can be regenerated or invalidated
⸻
Conceptual Shape
Thought { claim // human-readable single sentence subject // typed reference (what this is about) scope // time window + context kind // intent category evidence // provenance / inputs confidence // optional (0–1) proposal // optional plan fragment }
This is a conceptual model, not a database schema.
⸻
Required Fields
- Claim • A single factual or evaluative statement • Human-readable • No instructions, no compound clauses
Examples • “You worked 32 hours this month.” • “Your meditation streak broke yesterday.” • “Most of your work time went to Project X.”
⸻
- Subject
A typed reference, not free text.
Subjects answer: “What is this Thought about?”
Examples • metric:work_hours • project:clockify:<external_id> • habit:meditation • time_window:this_week • goal:monthly_focus
Subjects are the primary mechanism for grouping and deduplication.
⸻
- Scope
Defines when and where the Thought applies.
Must include a time boundary.
Examples • 2026-01-01 → 2026-01-31 • week starting 2026-01-22 (UTC) • last 7 days
⸻
- Kind
Describes why Lucille surfaced the Thought (intent), not the domain.
Initial canonical kinds: • observation – neutral fact • progress – movement toward/away from a target • risk – potential future issue • suggestion – optional next step • prompt – reflective question • memory – durable state worth remembering
Kinds are stable and few.
⸻
- Evidence
Minimal traceability for how the Thought was produced.
Examples • { source: "clockify", entries: 52, total_hours: 32.1 } • { source: "habit_tracker", days: 6 } • { derived_from: [rollup_id_1, rollup_id_2] }
Evidence enables trust, debugging, and recomputation.
⸻
Optional Fields
Confidence • Float in range 0.0 – 1.0 • Used later when Thoughts conflict or are aggregated
Proposal • A plan fragment, not a task • Non-binding, optional
Example • “Consider adding two focused work blocks this week.”
⸻
What a Thought Is Not
A Thought is not: • a task • a notification • a plan • a summary • an insight • an LLM paragraph
Those are downstream products of Thoughts.
⸻
Composition Rule
Multiple Thoughts can be grouped into an Insight, but: • Thoughts remain independent • Thoughts may exist without Insights • Insights never replace Thoughts
⸻
Deduplication Principle
At most one active Thought should exist for:
(kind, subject, scope, claim)
New Thoughts replace older equivalent ones rather than accumulating.
⸻
Design Rationale
This model allows Lucille to: • operate autonomously • support many domains (work, habits, mood, planning) • evolve without schema rewrites • remain explainable and trustworthy
Thoughts are the cognitive atoms of Lucille.
⸻
Status
This specification is frozen.
Future changes must be additive or layered on top (e.g. Insights), not breaking.
⸻
Operational Pipeline Contract (v1, signal notes)
For signal.user.note, Lucille also stores an operational pipeline envelope in payload_json.pipeline:
• version: integer contract version
• stages.capture: capture content and dedupe provenance
• stages.enrich_recommend: downstream enrichment recommendations
• stages.classify: structured note labels/confidence/decisions
• stages.embed: embedding/vector-reference status
• readiness: processing_status plus unresolved blockers
This envelope is additive and does not replace the atomic Thought model. During migration, legacy top-level payload keys are kept for compatibility.