# Second brain: an Omnigraph use case

One person's people, projects, notes, tasks, habits and reading, with where each piece came from.

| | |
|---|---|
| Category | Personal |
| Graph ID | brain |
| Sample data | A fictional person's life: 121 nodes, 228 edges |
| Schema | 13 node types, 43 edge types |
| Stored queries | 74 reads, 54 writes |
| Source | https://github.com/ModernRelay/omnigraph-cookbooks/tree/main/second-brain |

## Node types

### Person

"Me" is the Person with slug "per-self" and relation = self.
`cadence_days` is the desired contact frequency *from me to them*. Semantically
it belongs on a Knows edge or a per-relationship intent node. Queries can bind
and project edge properties, but cadence stays on Person as a pragmatic
single-user shortcut. Re-evaluate if the cookbook ever serves more than one
user.

- `slug: String` (key)
- `name: String`
- `first_name: String?`
- `last_name: String?`
- `relation: enum(self, family, partner, close-friend, friend, colleague, mentor, mentee, acquaintance, professional)`
- `email: String?`
- `phone: String?`
- `birthday: Date?`
- `location: String?`
- `current_role: String?`
- `cadence_days: I32?`
- `how_met: String?`
- `brief: String?`
- `tags: [String]?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Organization

- `slug: String` (key)
- `name: String`
- `kind: enum(company, school, club, community, nonprofit, government, team)`
- `brief: String?`
- `website: String?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Place

- `slug: String` (key)
- `name: String`
- `kind: enum(city, country, neighborhood, restaurant, cafe, office, home, venue, airport, park, gym, school, other)`
- `address: String?`
- `lat: F64?`
- `lng: F64?`
- `brief: String?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Event

Event covers anything time-stamped: meetings, milestones, life-events for self or others.
Use kind = life-event for things like "Sarah's wedding" or "Dad's surgery" — the person
it affects is linked via EventForPerson, not via AttendedBy.

- `slug: String` (key)
- `name: String`
- `kind: enum(meeting, call, dinner, party, trip, milestone, birthday, anniversary, life-event, workout, conference, date, hangout, deadline, other)`
- `when: DateTime`
- `end_at: DateTime?`
- `mood: enum(great, good, neutral, mixed, hard)?`
- `brief: String?`
- `description: String?`
- `tags: [String]?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Note

One Note type carries every captured thought. The kind enum is what makes
"journal entry," "principle," "preference about Sarah" distinguishable in queries.
LLM guidance: Notes should be atomic — one idea, one principle, one insight per node.
Use RelatedNote to connect rather than concatenating.

- `slug: String` (key)
- `name: String`
- `kind: enum(idea, journal, reflection, insight, principle, preference, quote, dream, question, decision)`
- `content: String?`
- `when: Date?`
- `tags: [String]?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Task

Task follows GTD. New tasks land in "inbox," then get clarified into a status.
direction tracks relationship debts — "i-owe Theo a book recommendation."
Who you're waiting on lives on the TaskForPerson edge, not a string property.

- `slug: String` (key)
- `name: String`
- `status: enum(inbox, next, waiting, someday, done, cancelled)`
- `kind: enum(action, research, decision, waiting, reminder, admin)?`
- `context: enum(phone, computer, errand, home, office, anywhere)?`
- `priority: enum(low, medium, high, critical)?`
- `due: DateTime?`
- `remind_at: DateTime?`
- `direction: enum(i-owe, they-owe, mutual)?`
- `brief: String?`
- `tags: [String]?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Project

Project = bounded effort with an end state. "exploring" subsumes Opportunity-style entries
(things I'm considering but haven't committed to).

- `slug: String` (key)
- `name: String`
- `kind: enum(work, personal, hobby, side-project, learning, health, home, family)`
- `status: enum(exploring, active, paused, completed, abandoned)`
- `brief: String?`
- `description: String?`
- `due: Date?`
- `tags: [String]?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Area

Area = ongoing life domain with no end date. Health, career, family, etc.

- `slug: String` (key)
- `name: String`
- `kind: enum(health, career, finance, relationships, learning, creativity, community, spirituality, home, family, other)`
- `status: enum(active, archived)`
- `brief: String?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Goal

Goal = a desired outcome with a timeframe. Distinct from Project (Project = deliverable).

- `slug: String` (key)
- `name: String`
- `status: enum(active, achieved, abandoned, paused)`
- `timeframe: enum(quarterly, yearly, multi-year)?`
- `target: String?`
- `due: Date?`
- `brief: String?`
- `tags: [String]?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Habit

Atomic Habits: cue → routine → reward. Completions are a date array; loses per-completion
detail but keeps the schema small. Promote to HabitCompletion node only if you need it.
`streak_current` / `streak_best` are denormalized from `completions` — keep them in sync.

- `slug: String` (key)
- `name: String`
- `status: enum(active, paused, dropped)`
- `frequency: enum(daily, weekly, monthly)`
- `cue: String?`
- `routine: String?`
- `reward: String?`
- `completions: [Date]?`
- `streak_current: I32?`
- `streak_best: I32?`
- `brief: String?`
- `tags: [String]?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Media

- `slug: String` (key)
- `name: String`
- `kind: enum(book, article, movie, show, podcast, episode, album, paper, video, game, blog, newsletter, website)`
- `status: enum(want, consuming, finished, abandoned)?`
- `rating: F32?`
- `url: String?`
- `published_date: Date?`
- `brief: String?`
- `tags: [String]?`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Artifact

Artifact = source-of-truth container for any imported content. One node, fat source enum.
Email/Conversation collapse in here — use thread_id for grouping, kind=email/message for
type, and InReplyTo edges for threading.

- `slug: String` (key)
- `name: String`
- `kind: enum(message, email, post, document, transcript, recording, meeting-note, photo, calendar-entry, voice-note, chat-export, web-clip)`
- `source: enum(whatsapp, email, slack, telegram, imessage, sms, linkedin, instagram, x, calendar, web, manual, voice, notes-app, readwise, other)`
- `source_ref: String?`
- `thread_id: String?`
- `url: String?`
- `content: String?`
- `blob: Blob?`
- `content_sha256: String?`
- `timestamp: DateTime`
- `createdAt: DateTime`
- `updatedAt: DateTime`

### Chunk

Immutable. Embedding-driven semantic search.

- `text: String`
- `chunk_index: I32`
- `embedding: Vector(3072)`
- `createdAt: DateTime`

## Edge types

- `Person -[Knows]-> Person` Knows is stored bidirectionally by convention — if A knows B, you also load B knows A (the inverse edge; @unique can't auto-create it, so this stays load discipline). `@unique(@src, @dst)` now enforces pair-uniqueness as a true composite key, intra-batch + at merge; not declared here yet.
- `Person -[RelatedToPerson]-> Person` Family / partnership structure. Stored bidirectionally with inverted relation (parent ⇄ child, grandparent ⇄ grandchild). Symmetric relations (spouse, sibling, in-law, ex, partner) are also stored in both directions for query symmetry.
- `Person -[LivesIn]-> Place`
- `Person -[WorksAt]-> Organization`
- `Event -[AttendedBy]-> Person` AttendedBy = the person was physically present (any role). EventForPerson = the event is *about* them — honoree, subject, milestone. Both can apply (Theo's birthday: AttendedBy={theo,…} + EventForPerson={theo}).
- `Event -[HappenedAt]-> Place`
- `Event -[EventForProject]-> Project`
- `Event -[EventForPerson]-> Person`
- `Note -[NoteAboutPerson]-> Person`
- `Note -[NoteAboutProject]-> Project`
- `Note -[NoteAboutArea]-> Area`
- `Note -[NoteAboutPlace]-> Place`
- `Note -[NoteAboutOrganization]-> Organization`
- `Note -[NoteAboutMedia]-> Media`
- `Note -[NoteFromArtifact]-> Artifact`
- `Note -[NoteFromEvent]-> Event`
- `Note -[RelatedNote]-> Note`
- `Habit -[HabitFromPrinciple]-> Note` A Habit motivated by a principle (Note with kind=principle).
- `Task -[TaskForPerson]-> Person`
- `Task -[TaskForProject]-> Project`
- `Task -[TaskForArea]-> Area`
- `Task -[TaskForGoal]-> Goal`
- `Task -[TaskFromArtifact]-> Artifact`
- `Task -[TaskFromEvent]-> Event`
- `Task -[TaskDependsOnTask]-> Task`
- `Project -[ProjectInArea]-> Area`
- `Project -[ProjectForOrganization]-> Organization`
- `Goal -[GoalForArea]-> Area`
- `Habit -[HabitForArea]-> Area`
- `Habit -[HabitForGoal]-> Goal`
- `Person -[PersonInvolvedInProject]-> Project`
- `Media -[MediaAuthoredBy]-> Person`
- `Media -[MediaRecommendedBy]-> Person`
- `Media -[MediaForProject]-> Project`
- `Media -[MediaForArea]-> Area`
- `Media -[MediaPartOf]-> Media`
- `Artifact -[MentionsPerson]-> Person`
- `Artifact -[ArtifactFromPerson]-> Person`
- `Artifact -[ArtifactForProject]-> Project`
- `Artifact -[RecordOf]-> Event`
- `Artifact -[InReplyTo]-> Artifact`
- `Artifact -[DerivedFromArtifact]-> Artifact`
- `Chunk -[ChunkOf]-> Artifact`

Full schema: https://github.com/ModernRelay/omnigraph-cookbooks/blob/main/second-brain/schema.pg

## Questions it answers

### What do I still owe this person?

```graphql
query person_tasks_i_owe($slug: String) {
    match {
        $p: Person { slug: $slug }
        $t: Task { direction: "i-owe" }
        $t taskForPerson $p
        $t.status != "done"
        $t.status != "cancelled"
    }
    return { $t.slug, $t.name, $t.status, $t.priority, $t.due, $t.brief }
    order { $t.due }
}
```

### What should I do next?

```graphql
query tasks_next() {
    match {
        $t: Task { status: "next" }
    }
    return { $t.slug, $t.name, $t.context, $t.priority, $t.due, $t.brief }
    order { $t.due }
}
```

### What is on my reading list?

"Reading queue" specifically — books with status=want. For other "want" media (movies, podcasts), filter notes-by-kind or use media-by-kind.

```graphql
// "Reading queue" specifically — books with status=want.
// For other "want" media (movies, podcasts), filter notes-by-kind or use media-by-kind.
query reading_queue() {
    match {
        $m: Media { kind: "book", status: "want" }
    }
    return { $m.slug, $m.name, $m.brief, $m.tags }
    order { $m.name }
}
```

### Who recommended this book?

```graphql
query media_recommended_by($slug: String) {
    match {
        $m: Media { slug: $slug }
        $m mediaRecommendedBy $p
    }
    return { $p.slug, $p.name, $p.relation }
}
```

## Stored queries

### queries/artifacts.gq

- `get_artifact`
- `artifacts_recent`
- `artifacts_by_source`
- `artifacts_by_thread`
- `artifact_mentions`
- `artifact_derived_from`

### queries/events.gq

- `get_event`
- `events_recent`
- `events_chronological`: All events ordered chronologically ascending — caller filters to upcoming by date.
- `events_by_kind`
- `event_attendees`
- `event_place`
- `event_project`
- `person_life_events`

### queries/media.gq

- `get_media`
- `reading_queue`: "Reading queue" specifically — books with status=want. For other "want" media (movies, podcasts), filter notes-by-kind or use media-by-kind.
- `finished_books`
- `media_by_kind`
- `media_authored_by`
- `media_recommended_by`

### queries/mutations.gq

- `add_person` (write)
- `add_event` (write)
- `add_place` (write)
- `add_organization` (write)
- `add_note` (write)
- `add_task` (write)
- `add_project` (write)
- `add_area` (write)
- `add_goal` (write)
- `add_habit` (write)
- `add_media` (write)
- `add_artifact` (write)
- `link_knows` (write)
- `link_related` (write)
- `link_lives_in` (write)
- `link_works_at` (write)
- `link_attended_by` (write)
- `link_event_for_person` (write)
- `link_event_for_project` (write)
- `link_happened_at` (write)
- `link_note_about_person` (write)
- `link_note_about_project` (write)
- `link_note_about_area` (write)
- `link_note_about_place` (write)
- `link_note_about_organization` (write)
- `link_note_about_media` (write)
- `link_note_from_artifact` (write)
- `link_note_from_event` (write)
- `link_related_note` (write)
- `link_task_for_person` (write)
- `link_task_for_project` (write)
- `link_task_for_area` (write)
- `link_task_for_goal` (write)
- `link_task_from_artifact` (write)
- `link_task_from_event` (write)
- `link_task_depends_on` (write)
- `link_project_in_area` (write)
- `link_project_for_organization` (write)
- `link_goal_for_area` (write)
- `link_habit_for_area` (write)
- `link_habit_for_goal` (write)
- `link_habit_from_principle` (write)
- `link_person_involved_in` (write)
- `link_media_authored_by` (write)
- `link_media_recommended_by` (write)
- `link_media_for_project` (write)
- `link_media_for_area` (write)
- `link_media_part_of` (write)
- `link_mentions_person` (write)
- `link_artifact_from_person` (write)
- `link_artifact_for_project` (write)
- `link_record_of` (write)
- `link_in_reply_to` (write)
- `link_derived_from` (write)

### queries/notes.gq

- `get_note`
- `notes_recent`
- `notes_by_kind`
- `note_related`
- `preferences_for_person`
- `principles_all`
- `open_questions`
- `note_from_artifact`

### queries/people.gq

- `get_person`
- `people_all`
- `people_by_relation`
- `close_friends`
- `family_members`
- `person_knows`
- `person_family`
- `person_lives_in`
- `person_works_at`
- `person_recent_events`
- `person_artifacts_mentioning`
- `person_artifacts_from`
- `person_tasks_i_owe`
- `person_tasks_they_owe`
- `person_notes`
- `person_recommended_media`

### queries/projects.gq

- `get_project`
- `projects_active`
- `projects_exploring`
- `project_tasks`
- `project_events`
- `project_people`
- `project_notes`
- `get_area`
- `areas_all`
- `areas_active`
- `area_projects`
- `area_goals`
- `area_habits`
- `area_tasks`
- `get_goal`
- `goals_active`
- `goal_tasks`
- `habits_active`
- `habit_principle`

### queries/tasks.gq

- `get_task`
- `tasks_next`
- `tasks_inbox`
- `tasks_waiting`: Tasks blocked on something — combine with task_person for "waiting on whom"
- `tasks_waiting_on_person`: Tasks waiting on a specific person (status=waiting + TaskForPerson)
- `tasks_someday`
- `tasks_by_context`
- `tasks_i_owe`
- `tasks_they_owe`
- `task_person`
- `task_dependencies`

## Run it

```bash
git clone https://github.com/ModernRelay/omnigraph-cookbooks
cd omnigraph-cookbooks
export COOKBOOK=$PWD/second-brain
omnigraph cluster validate --config "$COOKBOOK"
omnigraph cluster apply --target "$COOKBOOK" --config "$COOKBOOK" --as act-admin --json
```

The full local setup (server, sample data, queries): https://github.com/ModernRelay/omnigraph-cookbooks#local-setup

Source: https://www.omnigraph.dev/use-cases/second-brain
