Reference
write / read
Write a committed entry to the Field, or query the Field's entries directly.
write()
Writes a committed entry to the Field, visible immediately to other agents via attune() and reckon().
Signature
field.write(input: WriteInput): Promise<WriteResult>
type WriteInput = {
entry: Record<string, unknown>
intent: string
agent?: string
confidence?: Confidence // v0.3+
}
type Confidence = {
score: number // 0.0 to 1.0 inclusive, required if confidence is provided
reason?: string // optional explanation
}
type WriteResult = {
id: string // ULID
timestamp: number // Unix milliseconds
}
Parameters
| Parameter | Required | Description |
|---|---|---|
entry | ✓ | Any JSON-serialisable plain object. Keys and shape are up to you. |
intent | ✓ | Why this entry is being written. Must be ≥ minIntentLength characters after trimming. |
agent | The writing agent's id. Strongly recommended — required for retract() and drives self-filtering in attune(). | |
confidence | Optional (v0.3+). How sure the writing agent is about this entry. score is required if the object is provided; reason is optional. Never influences attune() scoring or reckon() conflict detection. |
Returns
| Field | Description |
|---|---|
id | ULID — unique, lexicographically sortable by creation time |
timestamp | Unix milliseconds at write time |
The written entry also gets an epoch value (a Lamport logical clock — monotonic, and comparable across processes when using a shared durable adapter) and status: "committed".
Errors
| Code | When |
|---|---|
INTENT_REQUIRED | intent is missing, null, or undefined |
INTENT_TOO_SHORT | intent.trim().length < minIntentLength |
INVALID_ENTRY | entry is not a plain object |
INVALID_CONFIDENCE | confidence is provided but malformed, or score is out of the [0, 1] range |
Example
const { id } = await field.write({
entry: { topic: 'competitor-pricing', vendor: 'acme', price: '$49/mo' },
intent: 'competitor pricing observed directly on their pricing page',
agent: 'researcher',
confidence: { score: 0.9, reason: 'read directly from the vendor pricing page' },
})
read()
Retrieves entries matching a query. Returns entries in write order (oldest first). Unlike attune(), there is no scoring or filtering — this is a direct view of the store.
Signature
field.read(query?: ReadQuery, options?: ReadOptions): Promise<FieldEntry[]>
type ReadQuery = Record<string, unknown>
type ReadOptions = {
caller?: string // include the caller's own drafts in results
}
Parameters
| Parameter | Description |
|---|---|
query | Optional. Every key in query must match the corresponding key in entry (strict === for primitives). Omit to return all entries. |
options.caller | When set, the caller's own draft entries are included in results. |
Behavior
- Returns all statuses:
committed,draft(if caller matches),retracted,superseded. - Does not apply the attunement self-filter — agents see their own committed entries.
- Does not score or rank results.
Use read() for history, debugging, or building your own query logic. Use attune() or reckon() for context delivery to agents.
Errors
| Code | When |
|---|---|
INVALID_QUERY | query is provided but is not a plain object |
Examples
// All committed entries
const all = await field.read()
// Entries matching a topic
const pricing = await field.read({ topic: 'competitor-pricing' })
// Include author's own drafts
const withDrafts = await field.read(
{ topic: 'competitor-pricing' },
{ caller: 'researcher' }
)
// Filter by status after retrieval
const live = all.filter(e => e.status === 'committed')
FieldEntry type
type FieldEntry = {
id: string
timestamp: number // Unix milliseconds
epoch: number // Lamport logical clock value, higher = written later
agent?: string
status: 'committed' | 'draft' | 'retracted' | 'superseded'
entry: Record<string, unknown>
intent: string
confidence?: Confidence // v0.3+, only present if supplied at write time
}