---
title: Data Models
description: Core data model reference for Beever Atlas
---

# Data Models Reference

## Overview

Beever Atlas uses a hierarchical knowledge model with three tiers:

- **Tier 0**: Channel Summary - Overall channel narrative
- **Tier 1**: Topic Clusters - Grouped related facts
- **Tier 2**: Atomic Facts - Individual extracted knowledge units
- **Graph**: Entities and Relationships - Knowledge graph

---

## AtomicFact

A single extracted fact stored in Weaviate (Tier 2).

### Fields

<TypeTable
  type={{
    id: {
      type: 'string',
      description: 'Unique fact identifier (UUID v5)',
    },
    memory_text: {
      type: 'string',
      description: 'The extracted fact text',
    },
    quality_score: {
      type: 'float',
      description: 'Quality score 0.0-1.0',
    },
    tier: {
      type: 'string',
      description: 'Always "atomic" for facts',
    },
    cluster_id: {
      type: 'string | null',
      description: 'Parent topic cluster ID',
    },
    channel_id: {
      type: 'string',
      description: 'Source channel identifier',
    },
    platform: {
      type: 'string',
      description: 'Platform name (e.g., "slack")',
    },
    author_id: {
      type: 'string',
      description: "Author's platform user ID",
    },
    author_name: {
      type: 'string',
      description: "Author's display name",
    },
    message_ts: {
      type: 'string',
      description: 'Message timestamp',
    },
    thread_ts: {
      type: 'string | null',
      description: 'Thread root timestamp',
    },
    source_message_id: {
      type: 'string',
      description: 'Platform message ID',
    },
    topic_tags: {
      type: 'string[]',
      description: 'Topic category tags',
    },
    entity_tags: {
      type: 'string[]',
      description: 'Mentioned entity names',
    },
    action_tags: {
      type: 'string[]',
      description: 'Action item keywords',
    },
    importance: {
      type: 'string',
      description: '"low" | "medium" | "high"',
    },
    graph_entity_ids: {
      type: 'string[]',
      description: 'Linked graph entity IDs',
    },
    source_media_urls: {
      type: 'string[]',
      description: 'URLs of attached media',
    },
    source_media_names: {
      type: 'string[]',
      description: 'Filenames of attached media',
    },
    source_link_urls: {
      type: 'string[]',
      description: 'URLs of linked resources',
    },
    source_link_titles: {
      type: 'string[]',
      description: 'Titles of linked resources',
    },
    source_link_descriptions: {
      type: 'string[]',
      description: 'Descriptions of linked resources',
    },
    valid_at: {
      type: 'datetime | null',
      description: 'When fact became valid',
    },
    invalid_at: {
      type: 'datetime | null',
      description: 'When fact became invalid',
    },
    superseded_by: {
      type: 'string | null',
      description: 'ID of fact that replaced this',
    },
    supersedes: {
      type: 'string | null',
      description: 'ID of fact this replaced',
    },
    potential_contradiction: {
      type: 'boolean',
      description: 'Flagged for conflict review',
    },
    text_vector: {
      type: 'float[] | null',
      description: 'Embedding vector',
    },
    fact_type: {
      type: 'string',
      description: '"decision" | "opinion" | "observation" | "action_item" | "question"',
    },
    thread_context_summary: {
      type: 'string',
      description: 'Thread deliberation summary',
    },
    source_lang: {
      type: 'string',
      description: 'BCP-47 language tag (e.g., "en", "zh-HK")',
    },
  }}
/>

### Example

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "memory_text": "The team decided to use JWT tokens for authentication with a 1-hour expiration.",
  "quality_score": 0.85,
  "tier": "atomic",
  "cluster_id": "cluster_123",
  "channel_id": "C12345",
  "platform": "slack",
  "author_id": "U12345",
  "author_name": "Jane Smith",
  "message_ts": "2026-04-13T10:30:00Z",
  "thread_ts": null,
  "source_message_id": "1234567890.123456",
  "topic_tags": ["authentication", "security"],
  "entity_tags": ["JWT", "OAuth"],
  "action_tags": [],
  "importance": "high",
  "graph_entity_ids": ["entity_jwt_decision"],
  "fact_type": "decision",
  "source_lang": "en"
}
```

---

## TopicCluster

A Tier 1 topic cluster grouping related atomic facts.

### Fields

<TypeTable
  type={{
    id: {
      type: 'string',
      description: 'Unique cluster identifier',
    },
    tier: {
      type: 'string',
      description: 'Always "topic"',
    },
    channel_id: {
      type: 'string',
      description: 'Channel identifier',
    },
    title: {
      type: 'string',
      description: 'Short descriptive name (5-10 words)',
    },
    summary: {
      type: 'string',
      description: 'Narrative of what happened (2-3 sentences)',
    },
    current_state: {
      type: 'string',
      description: 'Where things stand now (1-2 sentences)',
    },
    open_questions: {
      type: 'string',
      description: 'Unresolved tensions/debates',
    },
    impact_note: {
      type: 'string',
      description: 'Scope and significance',
    },
    topic_tags: {
      type: 'string[]',
      description: 'Topic category tags',
    },
    member_ids: {
      type: 'string[]',
      description: 'Member fact IDs',
    },
    member_count: {
      type: 'int',
      description: 'Number of member facts',
    },
    centroid_vector: {
      type: 'float[] | null',
      description: 'Cluster center embedding',
    },
    created_at: {
      type: 'datetime',
      description: 'Creation timestamp',
    },
    updated_at: {
      type: 'datetime',
      description: 'Last update timestamp',
    },
    key_entities: {
      type: 'object[]',
      description: 'Related entities [{id, name, type}]',
    },
    key_relationships: {
      type: 'object[]',
      description: 'Key relationships [{source, type, target, confidence}]',
    },
    date_range_start: {
      type: 'string',
      description: 'Earliest fact timestamp',
    },
    date_range_end: {
      type: 'string',
      description: 'Latest fact timestamp',
    },
    authors: {
      type: 'string[]',
      description: 'Contributors to this topic',
    },
    media_refs: {
      type: 'string[]',
      description: 'Referenced media URLs',
    },
    media_names: {
      type: 'string[]',
      description: 'Referenced media filenames',
    },
    link_refs: {
      type: 'string[]',
      description: 'Referenced link URLs',
    },
    high_importance_count: {
      type: 'int',
      description: 'Number of high-importance facts',
    },
    related_cluster_ids: {
      type: 'string[]',
      description: 'Related topic clusters',
    },
    staleness_score: {
      type: 'float',
      description: '0.0=fresh, 1.0=very stale',
    },
    status: {
      type: 'string',
      description: '"active" | "completed" | "stale"',
    },
    fact_type_counts: {
      type: 'object',
      description: 'Counts by fact type {decision: N, ...}',
    },
    key_facts: {
      type: 'object[]',
      description: 'Top facts with metadata',
    },
    decisions: {
      type: 'object[]',
      description: 'Extracted decisions',
    },
    people: {
      type: 'object[]',
      description: 'Involved people [{name, role, entity_id}]',
    },
    technologies: {
      type: 'object[]',
      description: 'Technologies mentioned [{name, category, champion}]',
    },
    projects: {
      type: 'object[]',
      description: 'Projects referenced [{name, status, owner, blockers}]',
    },
    faq_candidates: {
      type: 'object[]',
      description: 'Q&A pairs [{question, answer}]',
    },
  }}
/>

### Example

```json
{
  "id": "topic_123",
  "tier": "topic",
  "channel_id": "C12345",
  "title": "Authentication System Migration to JWT",
  "summary": "The team migrated from session-based auth to JWT tokens. This decision was driven by scalability needs and better mobile support.",
  "current_state": "Migration complete, JWT tokens in production with 1-hour expiration.",
  "open_questions": "Token refresh strategy still under review.",
  "impact_note": "Affects all API clients and requires re-authentication flow updates.",
  "status": "active",
  "member_count": 15,
  "staleness_score": 0.1
}
```

---

## ChannelSummary

A Tier 0 channel-level summary consolidating all topic clusters.

### Fields

<TypeTable
  type={{
    id: {
      type: 'string',
      description: 'Unique summary identifier',
    },
    tier: {
      type: 'string',
      description: 'Always "summary"',
    },
    channel_id: {
      type: 'string',
      description: 'Channel identifier',
    },
    channel_name: {
      type: 'string',
      description: 'Resolved display name',
    },
    text: {
      type: 'string',
      description: 'Overall narrative overview',
    },
    description: {
      type: 'string',
      description: 'One-line channel purpose (max 200 chars)',
    },
    themes: {
      type: 'string',
      description: 'Main knowledge areas and interrelations',
    },
    momentum: {
      type: 'string',
      description: 'Active vs completed vs stale',
    },
    team_dynamics: {
      type: 'string',
      description: 'Decision drivers, collaboration patterns',
    },
    cluster_count: {
      type: 'int',
      description: 'Number of topic clusters',
    },
    fact_count: {
      type: 'int',
      description: 'Total number of facts',
    },
    updated_at: {
      type: 'datetime',
      description: 'Last update timestamp',
    },
    key_decisions: {
      type: 'object[]',
      description: 'Top decisions',
    },
    key_entities: {
      type: 'object[]',
      description: 'Top entities',
    },
    key_topics: {
      type: 'object[]',
      description: 'Top topics with metadata',
    },
    date_range_start: {
      type: 'string',
      description: 'Earliest content',
    },
    date_range_end: {
      type: 'string',
      description: 'Latest content',
    },
    media_count: {
      type: 'int',
      description: 'Total media references',
    },
    author_count: {
      type: 'int',
      description: 'Unique contributors',
    },
    worst_staleness: {
      type: 'float',
      description: 'Highest staleness in clusters',
    },
    top_decisions: {
      type: 'object[]',
      description: 'Key decisions across all topics',
    },
    top_people: {
      type: 'object[]',
      description: 'Key people by expertise',
    },
    tech_stack: {
      type: 'object[]',
      description: 'Technologies referenced',
    },
    active_projects: {
      type: 'object[]',
      description: 'Ongoing projects',
    },
    glossary_terms: {
      type: 'object[]',
      description: 'Domain terminology',
    },
    recent_activity_summary: {
      type: 'object',
      description: 'Activity metrics',
    },
    topic_graph_edges: {
      type: 'object[]',
      description: 'Topic relationships',
    },
  }}
/>

---

## GraphEntity

An entity node in the Neo4j knowledge graph.

### Fields

<TypeTable
  type={{
    id: {
      type: 'string',
      description: 'Unique entity identifier',
    },
    name: {
      type: 'string',
      description: 'Entity name',
    },
    type: {
      type: 'string',
      description: '"Person" | "Decision" | "Project" | "Technology" | "Team" | "Meeting"',
    },
    scope: {
      type: 'string',
      description: '"global" | "channel"',
    },
    channel_id: {
      type: 'string | null',
      description: 'Channel scope (if channel-scoped)',
    },
    properties: {
      type: 'object',
      description: 'Additional entity properties',
    },
    aliases: {
      type: 'string[]',
      description: 'Alternative names',
    },
    status: {
      type: 'string',
      description: '"active" | "pending"',
    },
    pending_since: {
      type: 'datetime | null',
      description: 'When status became pending',
    },
    name_vector: {
      type: 'float[] | null',
      description: 'Name embedding for fuzzy matching',
    },
    source_fact_ids: {
      type: 'string[]',
      description: 'Source facts',
    },
    source_message_id: {
      type: 'string',
      description: 'Originating message',
    },
    message_ts: {
      type: 'string',
      description: 'Message timestamp',
    },
    source_lang: {
      type: 'string',
      description: 'BCP-47 language tag',
    },
    created_at: {
      type: 'datetime',
      description: 'Creation timestamp',
    },
    updated_at: {
      type: 'datetime',
      description: 'Last update timestamp',
    },
  }}
/>

### Entity Types

- **Person**: Team members, stakeholders
- **Decision**: Decisions made, conclusions reached
- **Project**: Projects, initiatives, work streams
- **Technology**: Tools, frameworks, libraries
- **Team**: Teams, groups, departments
- **Meeting**: Meetings, standups, reviews

---

## GraphRelationship

A relationship edge in the Neo4j knowledge graph.

### Fields

<TypeTable
  type={{
    id: {
      type: 'string',
      description: 'Unique relationship identifier',
    },
    type: {
      type: 'string',
      description: 'Relationship type (see below)',
    },
    source: {
      type: 'string',
      description: 'Source entity name',
    },
    target: {
      type: 'string',
      description: 'Target entity name',
    },
    confidence: {
      type: 'float',
      description: 'Confidence score 0.0-1.0',
    },
    valid_from: {
      type: 'string | null',
      description: 'When relationship became valid',
    },
    valid_until: {
      type: 'string | null',
      description: 'When relationship became invalid',
    },
    context: {
      type: 'string',
      description: 'Relationship context',
    },
    source_message_id: {
      type: 'string',
      description: 'Originating message',
    },
    source_fact_id: {
      type: 'string',
      description: 'Source fact',
    },
    created_at: {
      type: 'datetime',
      description: 'Creation timestamp',
    },
  }}
/>

### Relationship Types

- **DECIDED_BY**: Person decided Decision
- **PARTICIPATED_IN**: Person participated in Meeting
- **WORKS_ON**: Person works on Project
- **USES**: Project uses Technology
- **MEMBER_OF**: Person member of Team
- **RELATED_TO**: General relationship

---

## WikiPage

A generated wiki page with enhanced Markdown content.

### Fields

<TypeTable
  type={{
    id: {
      type: 'string',
      description: 'Page ID ("overview", "people", "topic-xyz")',
    },
    slug: {
      type: 'string',
      description: 'URL slug',
    },
    title: {
      type: 'string',
      description: 'Page title',
    },
    page_type: {
      type: 'string',
      description: '"fixed" | "topic" | "sub-topic"',
    },
    parent_id: {
      type: 'string | null',
      description: 'Parent page ID',
    },
    section_number: {
      type: 'string',
      description: 'Section number ("1", "2.1", "2.1.1")',
    },
    content: {
      type: 'string',
      description: 'Enhanced Markdown content',
    },
    summary: {
      type: 'string',
      description: '1-2 sentence summary',
    },
    memory_count: {
      type: 'int',
      description: 'Number of source facts',
    },
    last_updated: {
      type: 'datetime',
      description: 'Last update timestamp',
    },
    citations: {
      type: 'WikiCitation[]',
      description: 'Source citations',
    },
    children: {
      type: 'WikiPageRef[]',
      description: 'Child pages',
    },
  }}
/>

### WikiPage Types

- **fixed**: Standard pages (overview, people, decisions, etc.)
- **topic**: Pages generated from topic clusters
- **sub-topic**: Nested topic pages

---

## WikiCitation

A source citation for wiki page content.

### Fields

<TypeTable
  type={{
    id: {
      type: 'string',
      description: 'Citation reference ("[1]", "[2]")',
    },
    author: {
      type: 'string',
      description: 'Message author',
    },
    channel: {
      type: 'string',
      description: 'Channel name',
    },
    timestamp: {
      type: 'string',
      description: 'Message timestamp',
    },
    text_excerpt: {
      type: 'string',
      description: 'First 100 characters',
    },
    permalink: {
      type: 'string',
      description: 'URL to original message',
    },
    media_type: {
      type: 'string | null',
      description: '"pdf" | "image" | "link" | "video" | "audio"',
    },
    media_name: {
      type: 'string | null',
      description: 'Filename or domain',
    },
  }}
/>

---

## EntityKnowledgeCard

Cross-channel aggregation of all knowledge about a single graph entity.

### Fields

<TypeTable
  type={{
    id: {
      type: 'string',
      description: 'Unique card identifier',
    },
    tier: {
      type: 'string',
      description: 'Always "entity_card"',
    },
    entity_id: {
      type: 'string',
      description: 'Graph entity ID',
    },
    entity_name: {
      type: 'string',
      description: 'Entity name',
    },
    entity_type: {
      type: 'string',
      description: 'Entity type',
    },
    channel_ids: {
      type: 'string[]',
      description: 'Channels where entity appears',
    },
    cluster_ids: {
      type: 'string[]',
      description: 'Related topic clusters',
    },
    fact_count: {
      type: 'int',
      description: 'Number of related facts',
    },
    fact_type_breakdown: {
      type: 'object',
      description: 'Fact counts by type',
    },
    key_facts: {
      type: 'string[]',
      description: 'Most important facts',
    },
    related_entities: {
      type: 'object[]',
      description: 'Related entities',
    },
    last_mentioned_at: {
      type: 'string',
      description: 'Latest mention timestamp',
    },
    staleness_score: {
      type: 'float',
      description: '0.0=fresh, 1.0=stale',
    },
    summary: {
      type: 'string',
      description: 'Entity summary',
    },
    updated_at: {
      type: 'datetime',
      description: 'Last update timestamp',
    },
  }}
/>

---

## Model Relationships

```
ChannelSummary (Tier 0)
    ├─> TopicCluster[] (Tier 1)
    │       └─> AtomicFact[] (Tier 2)
    │               └─> GraphEntity (via graph_entity_ids)
    │                       └─> GraphRelationship
    └─> WikiPage
            └─> WikiCitation (cites AtomicFact)
```

---

## Storage

- **Weaviate**: AtomicFact, TopicCluster (Tier 1-2)
- **MongoDB**: WikiPage, WikiMetadata, ChannelSummary
- **Neo4j**: GraphEntity, GraphRelationship (knowledge graph)
