Skip to content

Atom Schema

Full field reference for Lattice atoms. See Concepts: Atoms for usage context.

Example

---
id: a1b2c3d4e5f6
kind: preference
subject: coffee preference
content: Prefers Ethiopian dark roast coffee.
observed_at: 2025-11-14T09:12:00Z
source_id: telegram
session_id: sess_20251114_0912
segment_id: seg_0
quality_score: 1.3
recall_count: 4
last_recalled_at: 2025-12-01T14:30:00Z
tier: semantic
episode_id: 2025-11-14:sess_20251114_0912
is_superseded: false
superseded_by: null
supersedes: []
---
Prefers Ethiopian dark roast coffee.

Fields

id

  • Type: string
  • Format: 12-character hex (UUID-derived)
  • Unique: yes, across entire store
  • Set by: ingest pipeline on creation

kind

  • Type: string (enum)
  • Values: fact | preference | goal | decision | event | question | insight | synthesis
  • Set by: LLM extraction during ingest

subject

  • Type: string
  • Description: Normalized topic label. Primary join key for graph edges and supersession lookup. Example: "coffee preference", "database choice".
  • Set by: LLM extraction during ingest

content

  • Type: string
  • Description: The atom's fact as a complete, self-contained sentence.
  • Set by: LLM extraction during ingest

observed_at

  • Type: ISO 8601 datetime string
  • Description: When the fact was observed (not when ingested). For real-time captures, this equals ingest time. For historical documents, can be set via metadata.observed_at.
  • Required: yes

source_id

  • Type: string
  • Description: Channel or document that produced this atom. Common values: telegram, lc-cli, mcp, web, inbox, claude-code. For file ingests: the filename.
  • Set by: caller via metadata.source_id

session_id

  • Type: string | null
  • Description: Session or document grouping identifier. Links atoms from the same conversation or document.
  • Set by: caller or parser

segment_id

  • Type: string | null
  • Description: Sub-segment within a source document. Set by the parser (chat turn ID, heading slug, etc.).
  • Set by: parser

quality_score

  • Type: float
  • Range: 0.1 – 2.0
  • Default: 1.0
  • Description: Relevance signal updated by the feedback loop. Applied as a multiplier to BM25 seed scores.

recall_count

  • Type: int
  • Default: 0
  • Description: Number of times this atom appeared in a cited answer.

last_recalled_at

  • Type: ISO 8601 datetime string | null
  • Description: Timestamp of the most recent recall.

tier

  • Type: string (enum)
  • Values: stm | episodic | semantic
  • Default: stm for new atoms; promoted by consolidation pipeline
  • Description: Memory tier. Affects seed multiplier in selection. See Memory Tiers.

episode_id

  • Type: string | null
  • Format: "<date>:<session_id>" e.g. "2025-11-14:sess_abc"
  • Description: Episode group this atom belongs to. Links to the episode:<date>:<session_id> graph node.

is_superseded

  • Type: bool
  • Default: false
  • Description: True when a newer atom on the same subject has replaced this one. Superseded atoms are filtered from selection results — synthesis never sees them.

superseded_by

  • Type: string | null
  • Description: ID of the atom that superseded this one. Set automatically by the supersession pipeline.

supersedes

  • Type: list[string]
  • Default: []
  • Description: IDs of older atoms this atom replaced.

valid_from

  • Type: ISO 8601 datetime string | null
  • Description: When this fact became true. Optional; for time-bounded facts.

valid_until

  • Type: ISO 8601 datetime string | null
  • Description: When this fact stopped being true. Optional; for time-bounded facts.

Atom kinds in detail

Kind When assigned Example content
fact General statement about the world or a person "Lives in San Francisco."
preference A stated preference or taste "Prefers dark roast coffee."
goal Something the user wants to do "Wants to read Thinking Fast and Slow."
decision A choice made, with context "Decided to use PostgreSQL for the project."
event A timestamped occurrence "Ran a half-marathon on 2025-10-05."
question An open question or uncertainty "Not sure whether to use TypeScript or Python."
insight Serendipitous connection (generated by serendipity agent) "Sleep tracking and productivity atoms share timing patterns."
synthesis Consolidation summary from multiple atoms "Consistently prefers dark roast, especially Ethiopian. Switched from light roast in 2024."