iAm's power lies in its sophisticated graph-based data model that captures the complex, interconnected nature of subjective experience. Built on Neo4j, the system models human consciousness through a network of entities and relationships that preserve both the temporal and semantic dimensions of experience reporting.
This document provides a deep dive into the core concepts that form iAm's conceptual foundation, explaining how each entity relates to others and the intuitions behind the data structure design.
Traditional relational databases struggle with the fluid, interconnected nature of subjective experience. iAm uses a graph model because:
- Natural Relationships: Experiences don't exist in isolation—they reference, investigate, and build upon each other
- Temporal Sequences: The flow of consciousness has inherent ordering and causation
- Semantic Networks: Different experience types share conceptual relationships
- Emergent Patterns: Graph traversals reveal patterns impossible to detect in tabular data
- Temporal Precision: Every experience capture includes multiple timestamps reflecting different aspects of the reporting process
- Semantic Versioning: All type definitions are versioned to enable research reproducibility
- Observer Ownership: Clear data ownership and privacy boundaries
- Flexible Schema: Graph structure adapts as understanding of consciousness evolves
User: The account holder who owns data and manages the platform experience
- Handles authentication, preferences, and account management
- Contains metadata like birth date, interests, AI preferences
- Owns multiple Observers for different contexts or research projects
Observer: The entity that actually reports experiences
- Represents a specific "lens" or perspective for data collection
- Multiple Observers per User enable different research contexts
- Has an alias for anonymization and distinct identity within studies
Intuition: This separation allows researchers to participate in studies with different "personas" while maintaining account continuity. A meditation teacher might have separate Observer identities for personal practice vs. research participation.
ExperienceType: Defines categories of subjective phenomena
- Examples: "Verbal Thought", "Emotion", "Visual Imagery", "Bodily Sensation"
- Contains semantic definition and phenomenological descriptions
- Specifies how values should be formatted (text, picklist, markdown)
- Includes valence settings (positive/negative/neutral tracking)
SessionType: Defines the structure and rules for measurement sessions
- Specifies which Experience Types can be reported
- Sets timing constraints (fixed duration, extendable, untimed)
- Defines input methods (keyboard, speech, gamepad, touchscreen)
- Controls measurement behavior (live reporting, moment stamping, investigation)
SequenceType: Defines ordered combinations of Sessions and Surveys
- Creates experimental protocols and structured practices
- Each step can be a SessionTypeVersion or SurveyTypeVersion
- Enables longitudinal studies and complex measurement protocols
SurveyType: Defines questionnaire structures for contextual data
- Traditional survey instruments for pre/post measurements
- Can be embedded within Sequences for comprehensive data collection
- Contains versioned definitions with Questions and QuestionScales
SurveyTypeVersion: Specific version of a survey instrument
- Contains ordered Questions with scales and validation rules
- Immutable once published for research reproducibility
- Defines survey structure that can be rendered by SurveyJS or other form systems
Intuition: These Types form iAm's "ontology"—the shared vocabulary for describing consciousness. Version control ensures research reproducibility as definitions evolve.
Every Type has multiple Versions that track definitional evolution:
ExperienceTypeVersion: Specific iteration of an Experience Type definition
- Immutable once published for research integrity
- Contains precise phenomenological definitions
- Specifies measurement parameters and validation rules
SessionTypeVersion: Specific configuration of a Session Type
- Defines exact experience types included and their roles
- Sets precise timing and interaction rules
- Immutable for experimental validity
SurveyTypeVersion: Specific configuration of a Survey Type
- Contains ordered Questions with QuestionScales for response validation
- Defines survey structure, timing, and response requirements
- Immutable for research reproducibility and citation
Intuition: Just as scientific papers cite specific versions of instruments, iAm research can point to exact definitional versions. This enables meta-analysis and replication studies.
Session: An actual instance of a SessionTypeVersion being executed
- Has start/end times and duration
- Links to the SessionTypeVersion it implements
- Contains pre/post notes and metadata
- Owns all Manifestations and Aggregates reported during the session
Sequence: An actual instance of a SequenceTypeVersion being executed
- Contains ordered list of Sessions and Surveys
- Tracks progress through the sequence steps
- Enables complex experimental protocols
Survey: An actual instance of a SurveyTypeVersion being completed
- Contains individual Response entities for each Question
- Can be embedded in Sequences or standalone
- Links to Observer for ownership and access control
- Tracks completion status and timing metadata
Intuition: These are the "data collection events"—the actual moments when consciousness is being measured and recorded.
iAm uses a sophisticated multi-layer model that combines SurveyJS for UI with graph storage for analytics:
- Purpose: Captures the act of completing a specific survey with SurveyJS integration
- Content: Survey metadata, timing, sequence context, and serialized SurveyJS state
- SurveyJS Integration: Stores
surveyStatefield for SurveyJS persistence and resumption - Timing: Tracks when survey was begun, paused, and completed
- Ownership: Links to Observer who completed the survey
- Purpose: Captures each individual answer as a separate graph entity for rich analytics
- Content: The actual response value (string, number, or structured data) with temporal tracking
- Graph Relationships: Links to both Survey instance and specific Question via
TOrelationship - Analytics: Enables question-level analysis across all survey instances and observers
- Timing: Precise timestamp when specific question was answered
- Purpose: Defines the structure and validation rules for survey questions
- Content: Question prompt, type (Scale, NumericRange, Number), validation rules, ordering
- SurveyJS Mapping: Question structure maps to SurveyJS question definitions
- Relationships: Links to SurveyTypeVersion via
IMPLEMENTSand optional QuestionScale - Ordering: Index, groupIndex, and page for proper question sequencing
- Purpose: Provides the complete survey instrument definition (immutable for research)
- Content: Survey metadata, instructions, and contains ordered Questions array
- SurveyJS Generation: Question definitions generate SurveyJS survey models
- Function: Ensures consistent interpretation across observers and studies
- Purpose: Defines response scales for structured questions (e.g., 1-5 Likert scales)
- Content: Scale values, value definitions, and descriptions for validation
- SurveyJS Integration: Maps to SurveyJS choice definitions and validation rules
- Function: Ensures consistent response interpretation and validation across UI and storage
Intuition: Think of this like a hybrid digital form system that combines modern UI with graph analytics:
- Survey = The specific form submission instance with SurveyJS state management
- Response = Each individual field answer stored as a graph entity for analytics
- Question = The form field definition with validation rules that generates SurveyJS questions
- SurveyTypeVersion = The complete form template that generates SurveyJS survey models
- QuestionScale = Predefined dropdown options or rating scales that map to SurveyJS choices
iAm uses SurveyJS for form rendering and user experience while maintaining graph-based storage:
UI Layer (SurveyJS):
- Modern, accessible survey interface with rich question types
- Client-side state management and validation
- Responsive design with progress tracking and navigation
Data Layer (Neo4j Graph):
- Individual Response entities for each question answer
- Rich relationship tracking between responses, questions, and observers
- Temporal analytics and cross-survey pattern analysis
- Research-grade data integrity and versioning
Integration Flow:
- Survey Creation: SurveyTypeVersion → SurveyJS Model generation
- User Interaction: SurveyJS handles UI, validation, and state management
- Data Persistence: SurveyJS results → Individual Response entities in graph
- State Management: Survey entity stores serialized SurveyJS state for resumption
- Analytics: Graph queries across Response entities for research insights
Observer → Survey → Response → Question → SurveyTypeVersion
Observer completes Survey
↓
For each Question in SurveyTypeVersion
↓
Observer provides Response
↓
Response links to specific Question
↓
Question validates against QuestionScale (if applicable)
This structure enables:
- Individual Response Tracking: Each answer is a separate graph entity
- Question-Level Analytics: Analyze responses across all survey instances
- Scale Validation: Ensure responses conform to predefined scales
- Temporal Analysis: Track response timing at the question level
- Research Reproducibility: Immutable survey definitions with precise question structures
iAm uses a sophisticated three-layer model to capture experience reporting:
- Purpose: Captures exactly what the observer typed/said/input
- Content: The raw value as entered ("I'm thinking about lunch")
- Timing: Multiple timestamps capturing input behavior
- Metadata: Valence, observed cause (willful/automatic), session context
- Purpose: Creates a standardized version of the manifestation
- Content: Processed value following format rules ("i'm thinking about lunch")
- Function: Enables grouping of similar experiences across time
- Processing: Applies trim, lowercase, and other normalization rules
- Purpose: Provides semantic meaning and measurement rules
- Content: Phenomenological definition of what constitutes this experience type
- Function: Ensures consistent interpretation across observers and studies
Intuition: Think of this like a library catalog system:
- Manifestation = The specific book instance you checked out on Tuesday
- Abstract = The canonical book title that groups all copies/editions
- ExperienceTypeVersion = The Dewey Decimal classification that defines what category this book belongs to
Aggregate: Groups multiple Manifestations that occur simultaneously
- Models the reality that multiple types of experience can co-occur
- Example: Simultaneous verbal thought and emotional response
- Preserves the temporal relationship between co-occurring phenomena
Intuition: Consciousness isn't linear—we often experience multiple things at once. Aggregates capture this simultaneity without losing the distinctness of each component.
Every experience report captures three distinct temporal moments:
- beginInputTimestamp: When the observer starts responding to the experience
- endInputTimestamp: When the observer finishes input (stops typing/releases key)
- submitInputTimestamp: When the user submits the manifesation/experience instance (in some cases this can be the same or very close to endInputTimestamp)
Intuition: The lag between experience and reporting is crucial data. These timestamps help researchers understand the temporal dynamics of introspection itself.
Manifestations within a session have:
- index: Order within the session
- followedBy/previous: Explicit linking creating a temporal chain
Sessions within sequences have:
- sequenceIndex: Position within the sequence
- followedBy/previous: Links to next/previous sequence items
Intuition: The flow of consciousness has inherent order. These relationships preserve the narrative structure of experience.
HAS: Ownership relationship
- User HAS Observers
- Observer HAS Sessions, Manifestations, Abstracts
- Intuition: Clear data ownership for privacy and access control
IMPLEMENTS: Type instantiation relationship
- Session IMPLEMENTS SessionTypeVersion
- Survey IMPLEMENTS SurveyTypeVersion
- Manifestation IMPLEMENTS Abstract
- Abstract IMPLEMENTS ExperienceTypeVersion
- Response IMPLEMENTS Question (via TO relationship)
- Question IMPLEMENTS SurveyTypeVersion
- Intuition: Links concrete instances to their abstract definitions
REPORTED: Temporal/contextual containment
- Session REPORTED Manifestations
- Survey REPORTED Responses
- Sequence REPORTED Sessions and Surveys
- Intuition: Captures what was reported within what context
TO: Direct relationship targeting
- Response TO Question
- Intuition: Links responses to the specific questions they answer
INVESTIGATES: Experiential investigation relationship
- Manifestation INVESTIGATES another Manifestation
- Intuition: Models meta-cognitive reflection and therapeutic techniques
FOLLOWED_BY: Temporal sequencing
- Creates ordered chains of experiences
- Intuition: Preserves the narrative flow of consciousness
VERSION/DRAFT: Evolutionary relationships
- ExperienceType has VERSION ExperienceTypeVersions
- ExperienceType has DRAFT ExperienceTypeVersions
- Intuition: Tracks the evolution of definitions over time
CONTRIBUTED_TO: Research contribution relationship
- Person CONTRIBUTED_TO Publication
- Intuition: Tracks authorship and research contributions
PUBLISHED_IN: Publication venue relationship
- Publication PUBLISHED_IN Journal/Conference
- Intuition: Links research papers to their publication venues
CITES: Citation relationship
- Publication CITES another Publication
- Intuition: Creates citation networks for research tracking
AFFILIATED_WITH: Institutional affiliation
- Person AFFILIATED_WITH Institution
- Intuition: Tracks researcher institutional connections
BOOKMARKED: User interest tracking
- Observer BOOKMARKED Sessions/Sequences/Publications
- Intuition: Allows users to save items of interest
LIKES: Appreciation relationship
- Observer LIKES Comments/Sessions/Content
- Intuition: Enables social feedback and content curation
Access Control Levels:
- Private: Only the owner can see
- Public: Visible to all platform users
- Shared: Visible to specific groups/studies
Intuition: Granular privacy controls enable both personal exploration and research participation while protecting sensitive data.
- Observer begins a Session implementing a SessionTypeVersion
- As experiences arise, Manifestations are created with precise timestamps
- Each Manifestation links to an Abstract (creating/finding existing)
- Each Abstract links to the relevant ExperienceTypeVersion
- Aggregates may group simultaneous Manifestations
- Session ends with post-notes and analysis
- Query by Experience Type: Find all Abstracts implementing specific ExperienceTypeVersions
- Temporal Analysis: Follow FOLLOWED_BY chains to analyze experience flow
- Pattern Recognition: Graph traversals reveal recurring sequences and relationships
- Cross-Session Analysis: Compare patterns across multiple Sessions
- Longitudinal Studies: Track changes over time within Sequences
- Phenomenological Studies: Use exact ExperienceTypeVersion citations
- Meditation Research: Track specific practice effects through SessionTypeVersions
- Therapeutic Protocols: Use INVESTIGATES relationships to study therapeutic techniques
- Consciousness Studies: Analyze temporal patterns and simultaneity
iAm also provides a fully functioning research data model management system. Below are the entities and what they do:
A project represents a single atomic research endeavor. It serves as the parent to all data collection related to a research project
A Cohort serves as a means of group participants in a Project. A project and have as many cohorts as it wants. Cohorts are used to group Observers (participants) that will allow follow some particular set of data collection task. For example, if you want to identify a control group and an experimental group, this would be defined at the cohort level.
A CollectionTask Entity is used to define a single Measurement Type Version (EG: Session, Survey, or Sequence Type), that a participant is expected to completely, some number of times. For example, A CollectionTask could be to complete 7 individual verbal thought tracking Sessions.
For each participant that is in a cohort assigned to a particular CollectionTask, this entity is used to track how much the participant has completed from the given CollectionTask. All Observer measurements for a given CollectionTask will be linked to the CollectionTaskState.
Presets: Saved configurations for quick session setup
- Store specific ExperienceType selections
- Save duration preferences and other parameters
- Enable rapid deployment of consistent measurement protocols
Intuition: Like camera presets, these enable quick switching between different "modes" of consciousness exploration.
Projects: Group multiple participants and measurement protocols
- Manage research studies with multiple observers
- Control access to specific ExperienceTypeVersions and SessionTypeVersions
- Aggregate data across participants while preserving privacy
Cohorts: Participant groups within Projects
- Organize observers into research cohorts
- Apply specific protocols to cohort members
- Track cohort-level metrics and patterns
CollectionTasks: Assigned measurement tasks
- Define specific data collection requirements
- Track completion status via CollectionTaskState
- Link to Sessions, Sequences, or Surveys
- Enable systematic data collection protocols
Publications: Link research papers to specific type definitions
- Create citations between academic work and iAm ontology
- Enable evidence-based refinement of experience definitions
ChatConversations: AI-assisted analysis of experience data
- Grounded in observer's personal data for relevant insights
- Respects privacy boundaries and access controls
- Enables natural language exploration of patterns
ChatMessages: Individual messages within conversations
- Track AI and user messages separately
- Maintain conversation context and history
- Enable iterative analysis workflows
Feedback: User feedback system
- Collect feature requests and bug reports
- Track user satisfaction and platform improvements
- Enable community-driven development
Events: System and user events
- Track platform usage patterns
- Monitor system health and performance
- Enable behavioral analytics
UserSubscription: Subscription management
- Track user subscription status and plans
- Manage billing cycles and payments
- Enable feature gating based on subscription level
IntervalBell: Meditation timer functionality
- Configure interval-based meditation timers
- Support various bell patterns and sounds
- Enable structured meditation practices
Problem: Different observers might report the same experience with slight variations Solution: Abstracts create canonical representations while preserving raw input Trade-off: Increased complexity for powerful grouping and analysis capabilities
Problem: The gap between experience and reporting contains valuable data Solution: Capture input behavior as part of the measurement Trade-off: More complex data model for richer temporal understanding
Problem: Definitions of consciousness phenomena evolve with research Solution: Immutable versions with clear evolution tracking Trade-off: More complex type management for research reproducibility
Problem: Consciousness is inherently relational and networked Solution: Graph database naturally models complex relationships Trade-off: Less familiar data model for powerful relationship queries
iAm's graph data model reflects a deep understanding of consciousness as a complex, temporal, relational phenomenon. By modeling experience reporting as a network of typed relationships with precise temporal markers, the system enables both personal exploration and rigorous research.
The architecture balances flexibility with structure, enabling the platform to evolve as our understanding of consciousness deepens while maintaining the precision necessary for scientific research. Every design decision reflects the fundamental insight that consciousness is not just a stream of isolated events, but a rich tapestry of interconnected, temporally-situated, semantically-meaningful experiences.
This foundation enables iAm to serve as both a personal tool for developing meta-cognitive awareness and a research platform for advancing the scientific understanding of consciousness itself.