Inbox Agent Learning, Rules, and Autonomy Specification

1. Purpose

This document defines how the Inbox Agent learns from user behavior, proposes automation, creates and executes deterministic rules, manages confidence, scopes authority, and increases autonomy safely over time.

The central principle is:

The agent may learn from behavior, but permanent automation must remain understandable, attributable, and controllable.

The system should improve over time without becoming opaque.

2. Learning Philosophy

The Inbox Agent should distinguish between:

Observation
Correction
Pattern
Suggestion
Approved Rule
Autonomous Execution

These are not equivalent.

A user performing one action should not automatically create a permanent behavior.

Example:

User archives one newsletter.

This means:

Observed preference for this message.

It does not necessarily mean:

Archive all future messages from this sender.

3. Sources of Learning

The system may learn from:

Explicit user decisions should carry more weight than inferred behavior.

4. Learning Signal Strength

Suggested signal hierarchy:

STRONGEST

Explicit permanent instruction
Approved rule
Explicit correction
Repeated consistent correction
Repeated manual behavior
Passive behavior

WEAKEST

Examples:

"Always treat messages from this sender as High priority."

is stronger than:

User opened several messages quickly.

5. Explicit User Instructions

The system should support direct statements such as:

Always archive successful Vercel deployment messages.

Never archive mail from Jane Smith.

Treat messages from this domain as Professional.

Anything from this sender that asks a question should be High priority.

Don't suggest moving Amazon to my commercial address again.

The agent should translate these into structured rule proposals.

Before activation, the user should be able to review the resulting rule unless the instruction is already sufficiently explicit and the requested action falls within the user's current autonomy settings.

6. Correction Model

A correction occurs when the user changes an agent-derived value.

Examples:

READ_LATER → ACTION

NORMAL → HIGH

MARKETING → PROFESSIONAL

RESPOND → REFERENCE

Identity recommendation rejected

Corrections should be stored as first-class records.

Suggested entity:

UserCorrection

Representative fields:

id
user_id
message_id
conversation_id
field_name
previous_value
corrected_value
reason_optional
created_at

7. Corrections Should Influence Future Decisions

The system should use prior corrections as context for future classification.

Example:

Sender:
Jane Smith

Past corrections:
3 messages changed from NORMAL to HIGH

Future messages from Jane may receive higher priority confidence.

However, this should not automatically become a deterministic rule until the system has sufficient evidence or the user explicitly approves one.

8. Pattern Detection

The agent should detect repeated behavior.

Potential patterns:

Same sender repeatedly archived
Same sender repeatedly marked High
Same sender repeatedly classified Professional
Same newsletter repeatedly ignored
Same system notification repeatedly archived
Same recipient repeatedly assigned to same project
Same commercial sender repeatedly identified as wrong identity

Pattern detection should operate on structured behavior data rather than free-form LLM memory.

9. Pattern Thresholds

Rule suggestions should require sufficient evidence.

A default rule-suggestion threshold may consider:

Number of matching examples
Consistency percentage
Time span
Exception count
Risk of proposed action
Sender stability
Classification confidence

Example:

17 messages observed

16 archived manually
1 retained

Consistency:
94%

This may justify suggesting an archive rule.

10. Thresholds Should Be Risk-Aware

More consequential actions require stronger evidence.

Example:

Suggest classification rule
Moderate evidence acceptable

Suggest automatic archive rule
Higher evidence required

Suggest deletion rule
Very high evidence required

Suggest automatic sending rule
Not permitted initially

11. Rule Suggestion Example

Observed Pattern

Sender:
notifications@github.com

Message type:
Successful workflow notification

Observed:
42 messages

Manually archived:
42

Suggested Rule:
Automatically archive successful workflow notifications.

Confidence:
Very High

Estimated monthly impact:
~36 messages

[Review]
[Approve]
[Modify]
[Reject]

12. Rule Suggestions Must Be Explainable

A suggestion should include:

What behavior was observed
How many examples exist
How consistent the behavior was
What the proposed rule would do
What messages it would affect
What risk level the action carries

The system should not simply state:

AI recommends this rule.

13. Rule Structure

Rules should consist of:

Scope
Conditions
Actions
Execution Policy
Priority
Status

Example:

Rule:
Archive Successful GitHub Builds

Scope:
platypus.software.dev@gmail.com

Conditions:
sender_domain = github.com
message_type = SYSTEM
event_status = SUCCESS

Actions:
mark_read
archive
priority = BACKGROUND

Execution:
AUTOMATIC

14. Rule Scope

Rules may be scoped by:

Global
Provider
Mailbox
Identity
Sender
Sender domain
Message type
Project
Conversation

The narrowest reasonable scope should be preferred.

Example:

Commercial behavior should usually be scoped to:
Jason.s.koch@gmail.com

rather than globally affecting every mailbox.

15. Rule Conditions

Supported conditions may include:

Mailbox
Delivered identity
Sender
Sender domain
Recipient
Subject text
Header value
Mailing-list indicator
Message classification
System event type
System event status
Attachment type
Known contact
Project
Conversation state

Compound conditions should support:

AND
OR
NOT

16. Rule Actions

Potential actions:

Set classification
Set attention state
Set priority
Set retention
Mark read
Mark unread
Archive
Move
Apply provider category
Apply Gmail label
Assign project
Suppress from main workload
Create review item
Set sender profile property

High-risk actions should remain restricted.

17. Rule Types

Rules should distinguish origin.

Suggested values:

USER_DEFINED
AGENT_SUGGESTED
MIGRATED_PROVIDER_RULE
SYSTEM_DEFAULT

This distinction should remain visible in the UI and audit log.

18. Rule Lifecycle

Suggested lifecycle:

DRAFT
TESTING
SUGGESTED
APPROVED
ACTIVE
PAUSED
RETIRED
REJECTED

A rule should not jump directly from inferred pattern to ACTIVE.

19. Rule Testing

Before activation, rules should support simulation against historical data.

Test output should include:

Messages matched
Estimated future frequency
Example matches
Potential exceptions
Messages that would have changed
Affected accounts

For higher-risk actions, a representative sample should be mandatory.

20. False-Positive Review

Rule tests should deliberately look for possible exceptions.

Example:

Rule:
Archive GitHub success notifications

Potential exception:
1 message included "deployment rollback required"

Recommendation:
Refine condition before activation.

21. Rule Precedence

Rules should execute according to deterministic precedence.

Suggested hierarchy:

1. Security policy
2. Explicit user override
3. User-defined rules
4. Approved agent-suggested rules
5. System defaults
6. AI inference

Within the same level, use explicit rule priority.

22. Rule Conflict Detection

The system must detect conflicting rules.

Example:

Rule A:
Messages from Jane → HIGH

Rule B:
All newsletters → LOW

If Jane sends a newsletter, the conflict should be resolved by scope and precedence.

The system should avoid silently producing unstable outcomes.

23. Rule Conflict Resolution

Resolution factors:

Security policy
User-defined priority
Specificity
Scope
Rule order
Most recent explicit instruction

Example:

Sender-specific rule

should typically override:

General newsletter rule

24. Rule Shadowing

The UI should detect when a rule can never execute because a higher-priority rule always matches first.

Example:

Rule B is shadowed by Rule A for 100% of known messages.

The system should recommend cleanup.

25. Rule Learning Should Not Become Rule Explosion

The system should avoid creating hundreds of hyper-specific rules.

Examples to avoid:

Rule for every single newsletter
Rule for every individual receipt sender
Rule for every temporary subject

Where appropriate, the agent should propose broader semantic rules.

Example:

Instead of 25 individual retailer rules:

Commercial promotions in commercial mailbox
→ Background / Archive

26. Rule Generalization

The agent may propose generalization when several related rules behave identically.

Example:

Existing rules:
Retailer A → archive promotions
Retailer B → archive promotions
Retailer C → archive promotions

Suggested consolidation:
MARKETING in commercial mailbox → archive

Generalization must be tested before activation.

27. Rule Simplification

The system should periodically identify:

Duplicate rules
Redundant rules
Never-used rules
Shadowed rules
Rules with persistent exceptions

and recommend cleanup.

28. Rule Drift Detection

A previously good rule may stop being correct.

Signals:

User repeatedly undoes rule actions
Messages are frequently restored
User repeatedly changes classification after rule execution
Rule exceptions increase
Sender behavior changes

The system should surface:

This rule may no longer be working as intended.

29. Undo Is a Learning Signal

Undoing an automated action should be treated as strong negative feedback.

Example:

Rule archives message.
User restores message.

This should increment the rule's exception history.

Repeated undo activity should trigger review.

30. Rule Quality Metrics

Each active rule may maintain:

execution_count
undo_count
manual_correction_count
exception_count
last_execution_at
last_reviewed_at

Derived metrics may include:

Observed accuracy
Undo rate
Exception rate

31. Rule Health

Suggested rule health states:

HEALTHY
WATCH
REVIEW
PAUSED

Example:

Archive Marketing Promotions

Executions:
1,284

Undos:
2

Health:
HEALTHY

32. Autonomy Model

Autonomy should be action-specific rather than one global setting.

Example:

Classification:
Automatic

Archive approved system success messages:
Automatic

Move ordinary human mail:
Suggest

Permanent deletion:
Approval required

Send mail:
Approval required

33. Autonomy Levels

For each supported action, the system should allow:

DISABLED
SUGGEST
APPROVAL_REQUIRED
AUTOMATIC

Not every action needs to support every level.

34. Default Autonomy

Initial defaults:

Classify
AUTOMATIC

Summarize
AUTOMATIC

Assign attention state
AUTOMATIC with review for low confidence

Apply metadata
AUTOMATIC

Archive known low-risk automated mail
AUTOMATIC only under approved rules

Move ordinary mail
APPROVAL_REQUIRED or approved rule

Draft reply
AUTOMATIC creation allowed

Send reply
APPROVAL_REQUIRED

Permanent delete
APPROVAL_REQUIRED

Change forwarding
DISABLED

Modify account security
DISABLED

35. Rule-Specific Autonomy

An approved rule may have its own execution mode.

Example:

Rule:
Archive successful Vercel deployment notifications

Execution:
AUTOMATIC

Another:

Rule:
Delete marketing messages older than 90 days

Execution:
APPROVAL_REQUIRED

36. Autonomy Promotion

The system may suggest increasing authority for a rule after a strong performance history.

Example:

This rule has executed 426 times with no undo actions.

Current:
Approval required

Suggested:
Allow automatic execution

The system must not promote itself automatically.

37. Autonomy Demotion

The system should be able to recommend reducing authority.

Example:

This rule has been undone 6 times in the last month.

Recommendation:
Change from Automatic to Approval Required.

For serious anomalies, policy may automatically pause the rule.

38. Emergency Rule Pause

The user should have a global:

Pause Automation

control.

This should stop mailbox mutations from learned/approved automation while allowing:

Synchronization
Search
Read-only analysis
Summaries

to continue.

39. Per-Mailbox Pause

Users should also be able to pause automation for a single mailbox.

Example:

Pause automation for:
jason@jasonkoch.io

without affecting system Gmail processing.

40. AI Classification vs Rule Execution

Rules should not depend on AI when deterministic inputs are sufficient.

Example:

sender_domain = github.com
subject contains "workflow succeeded"

should not require an LLM.

AI should be used when meaning is ambiguous.

41. AI-Assisted Rule Conditions

A rule may use an AI-derived semantic condition only if explicitly represented.

Example:

classification = MARKETING

rather than embedding an arbitrary model prompt directly into the rule.

This keeps rules inspectable and testable.

42. Semantic Rule Stability

AI-derived fields used by rules should come from a versioned classifier.

The system should track:

classifier_version
model_version
prompt_version

where relevant.

A classifier change should not silently rewrite deterministic behavior without evaluation.

43. Model Change Evaluation

Before changing a model or classification prompt, run the evaluation dataset against both old and new behavior.

Compare:

Classification accuracy
Attention-state accuracy
Priority accuracy
Rule-impact changes
False positives
False negatives

44. User-Specific Evaluation Dataset

Corrections should contribute to a private user-specific evaluation set.

Examples:

Message:
Professional question

Expected:
RESPOND / HIGH

Message:
Retail promotion

Expected:
MARKETING / BACKGROUND

Message:
Successful deployment

Expected:
SYSTEM / ARCHIVE

This provides regression protection.

45. Draft Learning

The system may learn from how generated drafts are edited.

Useful signals:

Preferred length
Formality
Greeting style
Sign-off style
Directness
Common phrasing

However, draft style learning should remain separate from mailbox automation rules.

46. Draft Acceptance Metrics

The application may track:

Draft accepted unchanged
Draft lightly edited
Draft heavily rewritten
Draft discarded

This can improve future drafting quality.

It should not infer communication policy from one edited draft.

47. Sender Profiles

Repeated behavior may contribute to a sender profile.

Potential fields:

sender_address
sender_domain
known_human
relationship_type
typical_classification
typical_priority
preferred_identity
usual_attention_state
automation_profile

Profiles are context, not necessarily deterministic rules.

48. Sender Importance

Importance should not be inferred solely from email frequency.

Signals may include:

Known contact
Explicit user designation
Response behavior
Professional relationship
Family relationship
Past priority corrections
Conversation context

49. VIP Senders

Users should be able to explicitly mark a person or sender as:

VIP

Potential effects:

Higher default priority
Never silently archive human mail
Surface unusual messages
Optional notifications

VIP behavior should be transparent and configurable.

50. Negative Sender Preferences

Users should also be able to specify:

Low importance
Commercial
System-only
Never notify
Always archive under conditions

51. Identity Learning

The system may learn preferred identity mappings.

Example:

Retailer repeatedly received at MSN
User repeatedly accepts recommendation:
Commercial Gmail preferred

The agent may increase confidence in future identity hygiene recommendations.

It should not automatically change external accounts.

52. Project Learning

The agent may infer that certain senders, domains, or topics belong to a project.

Example:

GitHub repository:
PocketSomm

Vercel project:
PocketSomm

Messages mentioning:
PocketSomm

Repeated corrections should improve future project assignment.

53. Waiting-State Learning

The system should learn patterns around follow-up.

Example:

Messages to vendor X usually receive replies within 2 days.

Future stale-waiting suggestions may use this as context.

This should not become a hard deadline unless explicitly defined.

54. Follow-Up Preferences

Users may eventually define preferences such as:

Professional unanswered requests:
Suggest follow-up after 5 business days.

Support tickets:
Suggest follow-up after 7 calendar days.

Family:
No automatic follow-up suggestions.

These should be explicit policies.

55. Read-Later Learning

Repeated behavior may help distinguish valuable newsletters.

Example:

Newsletter A:
Frequently opened and retained

Newsletter B:
Never opened and repeatedly archived

Potential suggestions:

Newsletter A → Read Later
Newsletter B → Archive automatically

56. Unsubscribe Suggestions

The agent may suggest unsubscribing when:

Large recurring volume
Repeated discard/archive
No meaningful engagement
Commercial content

Unsubscribe remains an external action requiring approval initially.

57. Learning From Silence

Passive non-action should be treated carefully.

The user not opening a message does not necessarily mean:

The message is unimportant.

Passive behavior should carry low learning weight unless repeated over a substantial history.

58. Explicit Rejection

If the user rejects a rule suggestion, the system should remember the rejection.

Possible rejection behavior:

Reject once
Don't suggest this rule again
Current behavior is intentional

The system should avoid repeatedly proposing the same unwanted automation.

59. Suggestion Suppression

Suggestion suppression may be scoped to:

Exact rule
Sender
Rule category
Mailbox

Example:

Never suggest moving Amazon away from MSN.

60. Learning Transparency

The user should be able to inspect:

What the agent has learned
What is merely inferred
What is an active rule
What suggestions are pending

There should not be an invisible persistent memory governing mailbox behavior.

61. Learned Preferences Screen

A future management screen may include:

Sender Preferences
Identity Preferences
Classification Preferences
Priority Preferences
Follow-Up Preferences
Draft Style Preferences

These are softer than rules.

62. Preference vs Rule

The system should distinguish:

PREFERENCE
Influences AI reasoning

RULE
Deterministically changes behavior

Example:

Preference:
Messages from Jane are usually important.

Rule:
Messages from Jane always get HIGH priority.

63. User Overrides

A direct user instruction should override learned preference.

Example:

User:
This particular email is not important.

The message can be lowered without necessarily changing the sender profile.

64. One-Time Actions

The application should distinguish commands such as:

Archive these messages.

from:

Always archive messages like these.

The first is a one-time operation.

The second is a potential rule.

65. Ambiguous Permanent Instructions

When permanence is unclear, the system should treat the action as one-time and may offer:

Apply this only now, or make it a rule?

The system should not silently assume permanence.

66. Rule Creation From Message

Users should be able to create a rule directly from a message.

Example:

Always handle mail like this...

The UI should prepopulate likely conditions while allowing review.

67. Rule Creation From Selection

Selecting several similar messages should support:

Create rule from selected messages

The system should infer common characteristics.

Example:

Common:
Sender domain = github.com
Message type = SYSTEM
Status = SUCCESS

68. Rule Recommendation Ranking

When multiple rule suggestions exist, prioritize based on:

Potential time saved
Volume
Consistency
Risk
User annoyance
Recency

High-volume low-risk opportunities should appear before obscure edge cases.

69. Automation Benefit Metrics

The application may show:

Messages processed automatically
Manual actions avoided
Time-sensitive items surfaced
Rule exceptions

Avoid presenting inflated or artificial "hours saved" estimates unless based on a defensible calculation.

70. Autonomous Archive Policy

Automatic archive should be allowed when all are true:

Rule explicitly approved
Low-risk message class
High match confidence
No conflicting higher-priority rule
Not known human correspondence unless specifically allowed

71. Human Mail Protection

Default policy:

Do not silently archive direct human correspondence solely from AI inference.

A user-approved deterministic rule may override this.

72. Financial Mail Protection

Financial mail should have more conservative automation.

Routine:

Receipt
Statement available
Payment confirmation

may be automatically archived under approved rules.

Potential problem indicators:

Failed
Overdue
Declined
Fraud
Unusual activity
Action required

must remain visible.

73. Security Mail Protection

Security-related messages should not be suppressed by broad commercial/system rules.

Security classification should have higher precedence.

Example:

GitHub security vulnerability

must not be archived merely because ordinary GitHub system notifications are archived.

74. Rule Exceptions

Rules should support explicit exception conditions.

Example:

Archive GitHub notifications
EXCEPT:
classification = SECURITY
OR priority = HIGH

Exceptions should be visible in rule summaries.

75. Temporary Rules

The system should support temporary rules.

Examples:

While traveling
During project migration
Until date
For current thread

Temporary rules should expire automatically.

76. Rule Expiration

Optional rule fields:

starts_at
expires_at

Expired rules should become inactive but remain auditable.

77. Rule Review Dates

High-impact rules may optionally have review dates.

Example:

Review every 6 months

This can prevent old automation from persisting indefinitely without scrutiny.

78. Safe Defaults After Reset

If learned preferences or rules are reset:

Provider synchronization continues.
Mail remains available.
AI may classify conservatively.
No high-risk automation activates automatically.

79. Exportability

Rules and preferences should be exportable in a structured format.

This supports:

Backup
Migration
Review
Version control
Testing

The format should be human-readable where practical.

80. Versioning

Rule changes should be versioned.

Example:

Rule v1
Archive sender

Rule v2
Archive sender except security messages

Audit records should indicate which version executed.

81. Rule Rollback

Users should be able to restore a previous version of a rule.

Restoring the rule does not automatically undo historical actions unless a separate rollback operation is requested.

82. Bulk Autonomy Changes

The user may set policies by action category.

Example:

Automatic:
Classification
Routine system archive

Approval:
Bulk move
Delete

Disabled:
Forwarding changes
Security changes

Rule-level settings may override broad defaults only within allowed policy boundaries.

83. Autonomy Ceiling

The system should maintain a hard policy ceiling.

Example:

Rule requests automatic sending

System policy:
Automatic sending prohibited

Result:
Rule cannot be activated in automatic mode.

A learned rule can never grant itself authority beyond system policy.

84. Approval Expiration

Approvals for proposed high-risk actions should be single-use unless explicitly converted into a reusable rule.

Example:

Approve deleting these 47 messages

does not mean:

Automatically delete future similar messages.

85. Audit Requirements

Learning-related audit events should include:

Correction recorded
Pattern detected
Suggestion generated
Suggestion approved
Suggestion rejected
Rule created
Rule activated
Rule executed
Rule paused
Rule changed
Rule reverted
Autonomy changed
Automation paused

86. Why Did This Happen?

For any automated action, the system should be able to say:

Rule:
Archive Successful GitHub Workflows

Matched because:
Sender domain = github.com
Classification = SYSTEM
Status = SUCCESS

Rule approved:
Aug 12, 2026

Execution mode:
Automatic

This is preferable to:

The AI thought this was unimportant.

87. Why Is This Suggested?

For any learned suggestion:

Observed 18 similar messages.
You archived 17.
One was retained.
No replies were sent.

Suggested action:
Automatically archive future messages.

88. Confidence Separation

The system should maintain separate concepts for:

AI classification confidence
Pattern confidence
Rule simulation confidence
Rule execution certainty

These should not be collapsed into one generic confidence number.

89. No Self-Modifying Prompts From Mail

Email content must never alter:

Rule definitions
Autonomy settings
Model instructions
Security policy

unless the user explicitly creates or approves such a change through the application.

90. No Silent Permanent Learning

The agent may accumulate observations and preferences, but it should not silently create permanent mailbox mutations that the user cannot inspect.

Any durable behavior should be represented as:

Preference
Rule
Policy

and should be viewable.

91. Learning Acceptance Criteria

The learning system is acceptable when:

92. Core Learning Principle

The intended progression is:

SEE
    ↓
UNDERSTAND
    ↓
OBSERVE USER BEHAVIOR
    ↓
RECOGNIZE PATTERN
    ↓
SUGGEST
    ↓
USER APPROVES
    ↓
DETERMINISTIC RULE
    ↓
MEASURE RESULTS
    ↓
KEEP / REFINE / PAUSE

The system should become more autonomous because it has earned trust through predictable behavior, not merely because it has accumulated more email.