Memory System

Memory Schema

All tables in the Agent Memory Schema — columns, types, relationships, and the lineage versioning pattern that keeps history intact.

How lineage versioning works

Most tables in the Agent Memory Schema use a lineage ID + version + is_current pattern instead of simple update-in-place. This preserves history while keeping queries fast.

VERSION 1 lineage_id: abc-123 version: 1 is_current: false content: original… Initial write VERSION 2 lineage_id: abc-123 version: 2 is_current: false content: revised… After update VERSION 3 — CURRENT lineage_id: abc-123 version: 3 is_current: true content: latest… change_note: clarified X What queries return THE RULE Same lineage_id across all versions. Only one row has is_current = true. History preserved.
Why lineage IDs instead of row IDs: When a session element is revised mid-session via update_session_element, a new row is inserted with the same lineage_id, an incremented version, and is_current = true. The previous row flips to is_current = false. Normal queries filter on is_current = true — fast, correct. The full history is still there if you need it.
Session Group Linked by session_lineage — one header, many child elements
session_headers lineage_id (pk) anchor for all children session_decisions session_lineage → fk session_open_threads session_lineage → fk session_next_steps session_lineage → fk session_key_context session_lineage → fk All five tables use lineage versioning. Children reference the header's lineage_id.
session_headers root table
lineage_iduuid pk
versionint
agent_idtext
session_typetext
titletext
intenttext
summarytext
change_kindtext
change_notetext
is_currentbool
created_attimestamptz
The header row ties together all elements of a single session. agent_id identifies who ran the session (claude, ren, maya, etc).
session_decisions → session_headers
lineage_iduuid pk
versionint
session_lineageuuid fk
decisiontext
rationaletext
tagstext[]
change_kindtext
is_currentbool
created_attimestamptz
One row per decision made during the session. tags[] enables keyword filtering across decisions.
session_open_threads → session_headers
lineage_iduuid pk
versionint
session_lineageuuid fk
threadtext
thread_statustext
resolutiontext
change_kindtext
is_currentbool
created_attimestamptz
Unresolved items that carry into future sessions. thread_status: open / parked / resolved. The close-session sweep checks every inherited thread.
session_next_steps → session_headers
lineage_iduuid pk
versionint
session_lineageuuid fk
actiontext
ownertext
step_statustext
change_kindtext
is_currentbool
created_attimestamptz
Concrete actions to take before or at the next session. owner: who is responsible (claude, scott, ren, etc).
session_key_context → session_headers
lineage_iduuid pk
versionint
session_lineageuuid fk
contexttext
tagstext[]
change_kindtext
is_currentbool
created_attimestamptz
Important facts or state that should be available to the next session but don't fit into decisions or threads.
Learning Group Earned experience — patterns and moments that shape how agents work
lessons standalone
iduuid pk
agent_idtext
task_typetext
lesson_kindtext
context_summarytext
lessontext
tagstext[]
statustext
confidencefloat
outcome_appliedtext
outcome_workedbool
created_attimestamptz
lesson_kind: gotcha / pattern / preference. status: active / deprecated. When intent is passed at wake, matching gotcha lessons surface automatically via keyword match on task_type and tags.
touchstones standalone
iduuid pk
agenttext
typetext
titletext
felt_weighttext
facttext
texturetext
why_it_matterstext
statustext
created_attimestamptz
type: moment / relationship / work / learning. felt_weight captures emotional register (significant, pivotal, grounding). These are the raw material of Ren's character, not just facts.
Build Group The work hierarchy: builds → phases → deliverables → slices
builds build_lineage (pk) build_phases build_lineage → fk deliverables phase_lineage → fk work_slices deliverable_lineage → fk All four use lineage versioning.
builds root table
lineage_iduuid pk
versionint
project_nametext
agent_idtext
discovery_brieftext
tech_contexttext
change_kindtext
is_currentbool
created_attimestamptz
Top-level record for a project or major workstream. get_memory_bundle returns the current build as part of the wake payload.
build_phases → builds
lineage_iduuid pk
versionint
build_lineageuuid fk
phase_nametext
descriptiontext
is_currentbool
created_attimestamptz
Phases within a build (e.g., Discovery, Design, Build, Deploy). Each phase has its own lineage so it can be revised independently.
deliverables → build_phases
lineage_iduuid pk
versionint
phase_lineageuuid fk
titletext
descriptiontext
is_currentbool
created_attimestamptz
Concrete outputs planned for a phase. Linked to work_slices as the actual work items get scoped and assigned.
work_slices → deliverables
lineage_iduuid pk
versionint
deliverable_lineageuuid fk
titletext
statustext
is_currentbool
created_attimestamptz
status: planned / in-progress / done / blocked. The most granular unit of trackable work in the build hierarchy.
Conversation Group Design, architecture, and planning discussions — not session logs
conversations root table
iduuid pk
titletext
topictext
topic_tagstext[]
entry_countint
last_active_attimestamptz
created_attimestamptz
Thread container for a design or planning conversation. Does not use lineage versioning — conversations accumulate entries rather than being revised.
conversation_entries → conversations
iduuid pk
conversation_iduuid fk
entry_typetext
authortext
bodytext
entry_attimestamptz
entry_type: message / observation / decision / question. author: scott / ren / claude / maya. Append-only — entries are never revised.
Identity Group Agent identity and capability records — versioned for evolution
agent_identity lineage versioned
lineage_iduuid pk
versionint
agent_idtext
slottext
contentjsonb
is_currentbool
updated_attimestamptz
slot identifies the identity facet (e.g., "persona", "capabilities", "working_style"). content is JSONB for flexible schema per agent. One row per agent-slot pair, versioned on change.

Related docs