Event Sourcing & Claims
Relevant source files
The following files were used as context for generating this wiki page:
Oboete implements an event-sourcing architecture to manage the memory of coding agents. The system captures raw interactions as events, curates them into claims using LLM-based curation, and maintains a verifiable record of knowledge derivations. This process ensures that agent memory is grounded in specific evidence from the user's work history.
Sources: src/curate.rs:1-12, src/capture.rs:1-7
Architecture Overview
The system operates in three primary phases: Capture, Curation, and Consumption.
- Capture: Agent hooks send payloads that the system transforms into events in
raw.db. - Curation: The curation phase reads a "window" of raw records and calls a curator (LLM) to extract claims.
- Consumption: Consumers read the operation log to update the
knowledge.db, which stores the current state of derivations and claims.
The system uses a curation checkpoint to track progress. Every record in a window's range is covered, curated with its text, or elided if it is too large.
Sources: src/curate.rs:5-12, src/consumer/claims.rs:25-35, src/capture.rs:72-88
Claims Data Model
A Claim represents a piece of knowledge extracted from the event stream. Claims are identified by a UID, which is a SHA256 hex string derived from the claim kind and the sentence where its first quote starts.
Core Structures
| Structure | Description |
|---|---|
ClaimOp | The body of an operation stored in the log. Contains kind, status, speaker, and body. |
Evidence | Traces a claim to its source. Includes device, sequence number, byte offset, and the quote. |
Derivation | A specific version of a claim. One claim UID can have multiple derivations from different providers. |
CorrectionOp | An owner's manual override for a claim's status or body. |
Sources: src/claims.rs:10-53, src/claims.rs:125-132, src/claims.rs:142-151
Claim Kinds and Statuses
Claims are categorized into specific types and follow a status lifecycle.
- Kinds: decision, preference, lesson, fix, open item, repo fact, change.
- Statuses: decided, proposed, retracted, done.
If the system encounters an unknown kind or status, it normalizes it to a "repo fact" with an "unverified" status.
Sources: src/claims.rs:56-78
Curation Logic
Curation identifies the next window of records for a device. Windows are bounded by tokens (interim size of 5,000) and records (max 2,000).
Window Processing Flow
The system fits carried context and repository candidates into the curator's prompt. Carried context includes the session's goal, open items, and previously proposed claims.
Sources: src/curate.rs:40-100, src/curate.rs:430-460, src/gates.rs:104-125
Code Gates
Code gates are programmatic validations that run on a curator's drafts without model calls. They ensure that claims meet specific criteria before being promoted to higher statuses.
- Speaker Validation: Sets the speaker based on the role of the quoted line (e.g., User, Assistant, Tool).
- Decided Status: A claim is only "decided" if it uses the user's own words or follows an acceptance turn.
- Pasted Content: If a proposal's words are shared with a tool line (minimum 40 characters), it is marked as a "paste" and cannot be "decided" without user confirmation.
- Tainting: Proposals derived from tool content are "tainted" and require user words for promotion.
Sources: src/gates.rs:4-100, src/gates.rs:165-190, src/gates.rs:250-265
Consumption and Knowledge.db
The Claims Consumer processes the operation log and updates the knowledge state.
Derivation Activation
Each UID's active derivation is determined by:
- Tier: Higher tiers (Paid > Subscription > Free > Code only) take precedence.
- Time: If tiers are equal, the newest derivation becomes active.
Sources: src/claims.rs:188-195, src/consumer/claims.rs:300-325
Knowledge Schema
The system maintains several tables in knowledge.db:
| Table | Description |
|---|---|
derivations | Stores every version of a claim. |
evidence | Maps derivations to specific raw record offsets. |
edges | Tracks supersedes relationships between claims. |
claims | Indexed view of active derivations by UID. |
claims_fts | Full-text search index for candidate matching. |
corrections | Stores manual overrides from the owner. |
Sources: src/claims.rs:142-185
Digests
Digests provide a high-level summary of a session's current claims in a repository. The curation phase writes a DigestOp once a session's windows are covered.
- Freshness: A digest is only shown if every claim it cites is still current and has not been re-derived or corrected since the digest was written.
- Constraints: Max 6 lines, 2,000 characters total.
Sources: src/digest.rs:1-40, src/digest.rs:320-350
Recuration
oboete recurate allows re-processing spans of records. This is necessary if redaction rules change or if a claim's evidence is removed (tombstoned).
- Queueing: Spans that lose evidence are queued in the
recuratetable. - Retraction: If a recuration no longer produces a previously active unsettled claim, that claim is marked as "retracted".
Sources: src/curate.rs:560-600, src/consumer/claims.rs:230-260
Conclusion
The Event Sourcing and Claims system provides a verifiable and corrigible memory for coding agents. By separating the raw event log from derived knowledge and applying programmatic gates, Oboete ensures that agent memory remains accurate, grounded in user intent, and adaptable to changes in work history or redaction policies.