# Company brain: an Omnigraph use case

A company's people, projects, claims, decisions and commitments, each tied to the exact words it rests on, shared by its people and agents.

| | |
|---|---|
| Category | Company |
| Graph ID | company |
| Sample data | Lanternworks, a fictional software company: 55 nodes, 114 edges |
| Schema | 8 node types, 18 edge types |
| Stored queries | 41 reads, 28 writes |
| Source | https://github.com/ModernRelay/omnigraph-cookbooks/tree/main/company-brain |

## Node types

### Person

Someone in the real world: an employee, a customer, a vendor contact. One node per human. Being a Person grants nothing; access to the graph belongs to an Actor.

Instruction for agents: Resolve every handle a source gives with person_by_handle before creating a Person; add_person replaces the whole row of an existing slug. Store handles lowercased and trimmed. Change a name, title or handle with update_person and mark someone who left with deactivate_person.

- `slug: String` (key)
- `name: String`
- `title: String?`
- `active: Bool?` false for someone who left (deactivate_person); they keep their history
- `email: String?`
- `slack: String?` Slack member ID, lowercased: u01alice
- `github: String?`

### Actor

Someone who reads or writes this graph: a person's own login or a software agent. slug is the OmniGraph actor id the bearer token selects, so commit history joins to this node.

Instruction for agents: Register with add_actor, which refuses a slug that already exists; retire with deactivate_actor. Agents write only on the branch they were given; they cannot write main, merge or delete branches. The policy cannot tell one agent's branch from another's, so a person checks each commit's actor before merging.

- `slug: String` (key)
- `kind: enum(human, agent)`
- `name: String`
- `purpose: String?`
- `active: Bool?`

### Team

An organizational unit: a team, squad or department. The company itself is the root team.

- `slug: String` (key)
- `name: String`

### Project

A time-bound effort with an owner and an outcome.

- `slug: String` (key)
- `name: String`
- `status: enum(planned, active, paused, done, cancelled)`
- `target_date: Date?`

### Source

A record the brain learned from: a meeting, chat thread, document, email or ticket. Claims are extracted from Sources; a Source is never edited to say something new.

Instruction for agents: slug is <system>:<native id> (meet:…, slack:<channel>/<ts>, doc:…), so ingesting the same item twice upserts instead of duplicating.

- `slug: String` (key)
- `kind: enum(meeting, thread, document, email, ticket, other)`
- `title: String`
- `url: String?`
- `occurred_at: DateTime` When the meeting happened or the message was sent
- `summary: String?`

### Claim

One statement someone made in a source, as they made it: a fact, a proposal, a commitment or a risk. Extracting a claim does not make it true; it stays unverified until someone verifies or rejects it.

Instruction for agents: Write claims with record_claim. quote is the exact text from the source, never a paraphrase; statement says the same thing in one plain sentence. Extraction leaves status unverified. record_claim refuses a slug that already exists. Never edit a claim's statement or quote; reject it and record a new one.

- `slug: String` (key)
- `statement: String`
- `quote: String` The exact words in the source; search_quotes finds a claim by them
- `locator: String?` Where in the source: a timestamp, a section, a message ts
- `kind: enum(fact, proposal, commitment, risk)`
- `status: enum(unverified, verified, rejected)`
- `recorded_at: DateTime` When the brain learned it

### Decision

A commitment to a course of action, made by named people and resting on claims. Never rewritten: a changed decision is a new Decision that the old one points to with SupersededBy.

Instruction for agents: Write decisions with promote_claim or propose_successor, which rest the decision on a claim in the same commit. Both refuse a slug that already exists. Agents write status proposed on a branch; a person merges it, then verifies the claims and accepts on main, where agents cannot write. Never edit statement; supersede instead. Fill rationale only from what the claims say.

- `slug: String` (key)
- `title: String`
- `statement: String` What was decided, in one or two sentences
- `rationale: String?` Why, as stated in the source: drivers and the options that lost
- `status: enum(proposed, accepted, rejected, deprecated)`
- `decided_at: DateTime?` When it was decided in the world
- `recorded_at: DateTime` When the brain learned it

### ActionItem

Something one person committed to do, usually by a date, promoted from a commitment claim.

Instruction for agents: Write action items with add_action_item, which sets the owner and rests the item on its claim in the same commit. The owner, not an agent, closes the item.

- `slug: String` (key)
- `title: String`
- `status: enum(open, in_progress, done, cancelled)`
- `due: Date?`
- `completed_at: DateTime?`
- `recorded_at: DateTime`

## Edge types

- `Person -[MemberOf]-> Team` One stint on a team, with an optional role, keyed by the date it started. It is current until a LeftTeam with the same since closes it; a move closes one stint and opens another.
- `Person -[LeftTeam]-> Team` Closes the MemberOf stint that started on since. A separate edge, so recording the stint again cannot reopen it.
- `Team -[PartOf]-> Team` The source team sits inside the target team.
- `Actor -[ActsFor]-> Person` The person behind this actor: their own login, or the person accountable for an agent.
- `Project -[OwnedBy]-> Person` The person accountable for the project.
- `Project -[RunBy]-> Team` The team doing the project.
- `Source -[SourceAbout]-> Project` The source discusses this project.
- `Claim -[ClaimFrom]-> Source` The source the claim was made in. The same statement in two sources is two claims.
- `Claim -[ClaimedBy]-> Person` Who said or wrote it; every claim has one, and record_claim requires it. Whether they had the authority to decide it is a separate question.
- `Claim -[Contradicts]-> Claim` The source claim says the opposite of the target; point the newer claim at the older one. A pair with neither side rejected is contested.
- `Decision -[BasedOn]-> Claim` The claims a decision rests on: the proposal it promotes and the facts behind it.
- `Decision -[DecidedBy]-> Person` A person who made the decision.
- `Decision -[DecisionAbout]-> Project` The project the decision concerns.
- `Decision -[SupersededBy]-> Decision` The source decision was replaced by the target. A decision is superseded at most once, so two competing successors collide at merge. The full why is in the claims: the successor rests on a claim that contradicts one behind the original.
- `ActionItem -[AssignedTo]-> Person` The one person who owns the action item.
- `ActionItem -[ActionFrom]-> Claim` The commitment claim the action item was promoted from.
- `ActionItem -[FollowsFrom]-> Decision` The decision this action item follows from, if any.
- `ActionItem -[ActionAbout]-> Project` The project the action item belongs to.

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

## Questions it answers

### Which decisions are current, project by project?

Accepted decisions that no accepted or deprecated decision has replaced, by project. The decision log as it stands.

```graphql
query current_decisions() @description("Accepted decisions that no accepted or deprecated decision has replaced, by project. The decision log as it stands.") {
    match {
        $d: Decision { status: "accepted" }
        $p: Project
        $d decisionAbout $p
        not { $d supersededBy $n  $n.status in ["accepted", "deprecated"] }
    }
    return { $p.name as project, $d.slug as decision, $d.title as title, $d.decided_at as decided_at }
    order { project asc, decided_at asc }
}
```

### Which decisions rest on a claim that someone has since contradicted?

Current accepted decisions resting on a claim that an unrejected claim contradicts. Run it on an agent's branch to see what its new claims put in question. Once a person rejects the claim itself, the decision moves to current_on_rejected.

```graphql
query decisions_at_risk() @description("Current accepted decisions resting on a claim that an unrejected claim contradicts. Run it on an agent's branch to see what its new claims put in question. Once a person rejects the claim itself, the decision moves to current_on_rejected.") {
    match {
        $d: Decision { status: "accepted" }
        not { $d supersededBy $n  $n.status in ["accepted", "deprecated"] }
        $c: Claim
        $d basedOn $c
        $c.status != "rejected"
        $x: Claim
        $c <contradicts> $x
        $x.status != "rejected"
    }
    return { $d.slug as decision, $c.statement as rests_on, $x.statement as contradicted_by }
    order { decision asc }
}
```

### What does this decision rest on, and in whose words?

What a decision rests on: each claim, who said it, the exact quote and the source it came from, oldest first.

```graphql
query decision_evidence($decision: String) @description("What a decision rests on: each claim, who said it, the exact quote and the source it came from, oldest first.") {
    match {
        $d: Decision { slug: $decision }
        $c: Claim
        $d basedOn $c
        $s: Source
        $c claimFrom $s
        $p: Person
        $c claimedBy $p
    }
    return { $c.slug as claim, $c.status as status, $p.name as said_by, $c.quote as quote, $s.title as source, $s.occurred_at as occurred_at }
    order { occurred_at asc, claim asc }
}
```

### What did this meeting commit people to?

What a meeting, thread or ticket committed people to.

```graphql
query actions_from_source($source: String) @description("What a meeting, thread or ticket committed people to.") {
    match {
        $s: Source { slug: $source }
        $c: Claim
        $c claimFrom $s
        $a: ActionItem
        $a actionFrom $c
        $p: Person
        $a assignedTo $p
    }
    return { $a.title as action, $p.name as owner, $a.status as status, $a.due as due }
    order { action asc }
}
```

## Stored queries

### queries/actions.gq

- `open_actions`: Open and in-progress action items with their owner and due date, earliest due first.
- `overdue_actions`: Open or in-progress action items due before a date, e.g. 2026-10-14.
- `person_actions`: Everything one person owns that is not done or cancelled.
- `actions_from_source`: What a meeting, thread or ticket committed people to.
- `decision_actions`: The action items that follow from a decision.

### queries/claims.gq

- `claims_from_source`: What a meeting, thread or document claimed: each claim, who said it, where, and the exact quote.
- `contested_claims`: Pairs of claims that contradict each other with neither side rejected: what still has to be settled. The first claim is the newer one.
- `decisions_at_risk`: Current accepted decisions resting on a claim that an unrejected claim contradicts. Run it on an agent's branch to see what its new claims put in question. Once a person rejects the claim itself, the decision moves to current_on_rejected.
- `unverified_claims`: Claims nobody has verified or rejected yet, oldest first: the review queue.
- `search_claims`: Full-text search over claim statements, best match first.
- `search_quotes`: Full-text search over the exact words claims quote, best match first: find the claim behind a sentence someone remembers.

### queries/decisions.gq

- `current_decisions`: Accepted decisions that no accepted or deprecated decision has replaced, by project. The decision log as it stands.
- `project_decisions`: Decisions about one project that no proposed, accepted or deprecated successor has replaced, with their status, so a proposal shows in place of what it would replace until a person accepts or rejects it.
- `decision_evidence`: What a decision rests on: each claim, who said it, the exact quote and the source it came from, oldest first.
- `decision_deciders`: Who made a decision.
- `decision_lineage`: Every earlier decision this one replaced, newest first.
- `why_superseded`: Why a decision was replaced: its successor and the one-line reason on SupersededBy. superseding_contradictions shows the claims behind it, when they contradict.
- `superseding_contradictions`: Each claim behind a decision's successor that contradicts a claim behind the decision itself. Zero rows when the successor was proposed for a reason no claim contradicts; why_superseded still has the reason.
- `decision_successor`: What a decision was replaced by, if anything: the end of its SupersededBy chain, skipping rejected successors.
- `decisions_from_source`: Decisions resting on claims made in a meeting, thread or document, with how many of their claims came from it.
- `proposed_decisions`: Decisions waiting for a person to accept or reject them.
- `unimplemented_decisions`: Current accepted decisions that no action item follows from yet, not counting cancelled items.
- `search_decisions`: Full-text search over decision titles, best match first.

### queries/hygiene.gq

- `unsupported_decisions`: Decisions that rest on no claim. Zero rows on a healthy graph.
- `accepted_on_unverified`: Accepted decisions resting on a claim nobody verified. Verify the claims before accepting. Zero rows on a healthy graph.
- `current_on_rejected`: Current accepted decisions resting on a claim a person rejected: replace them with propose_successor or retire them with deprecate_decision. Zero rows on a healthy graph.
- `decisions_without_project`: Decisions about no project. Zero rows on a healthy graph.
- `claims_without_source`: Claims that cite no source. Zero rows on a healthy graph.
- `claims_without_speaker`: Claims with no ClaimedBy. Every claim has a speaker; record_claim requires one. Zero rows on a healthy graph.
- `unowned_actions`: Open or in-progress action items with no owner. Zero rows on a healthy graph.
- `unsupported_actions`: Action items that rest on no claim. Zero rows on a healthy graph.
- `agents_without_owner`: Agents with no accountable person. Zero rows on a healthy graph.

### queries/mutations.gq

- `record_source` (write): Record a meeting, thread, document, email or ticket. The slug is <system>:<native id>, so recording it again upserts.
- `link_source_project` (write): Say a source is about a project.
- `record_claim` (write): Record one claim made in a source: the exact quote, where it is, and who said it, in one commit. The claim starts unverified. Refused if the slug already exists.
- `mark_contradiction` (write): Record that a claim says the opposite of an earlier one. Both stay; the pair is contested until one is rejected.
- `verify_claim` (write): Mark an unverified claim verified: checked against the source and against what the graph already holds. Affects 0 nodes unless it is unverified.
- `reject_claim` (write): Reject a claim that turned out wrong or was superseded by a contradicting one. Affects 0 nodes if it is already rejected.
- `promote_claim` (write): Propose a decision that rests on a claim, about a project, in one commit. Refused if the slug already exists.
- `propose_successor` (write): Propose a decision that replaces an earlier one: the new decision, the claim it rests on, and SupersededBy with a one-line reason, in one commit. Refused if the slug already exists.
- `add_basis` (write): Rest a decision on another claim.
- `add_decider` (write): Record a person who made a decision.
- `accept_decision` (write): Accept a proposed decision. Affects 0 nodes unless it is proposed.
- `reject_decision` (write): Reject a proposed decision. Affects 0 nodes unless it is proposed.
- `deprecate_decision` (write): Retire an accepted decision that nothing replaced. To change a decision, propose a successor instead.
- `withdraw_successor` (write): Remove the SupersededBy link from a decision to a successor that was rejected, so the decision can be replaced again. A separate commit from reject_decision: one write cannot both update and delete.
- `add_action_item` (write): Promote a commitment claim to an action item with its owner and project, in one commit. Refused if the slug already exists.
- `follows_decision` (write): Say an action item follows from a decision.
- `reschedule_action` (write): Change the due date of an open or in-progress action item.
- `start_action` (write): Mark an open action item in progress.
- `complete_action` (write): Mark an action item done. Affects 0 nodes if it is already done or cancelled.
- `cancel_action` (write): Cancel an action item that will not be done.
- `add_person` (write): Add a new person with whatever handles are known, lowercased. On an existing slug it replaces the whole row, including active.
- `update_person` (write): Set a person's name, title, email, Slack member ID and GitHub login, handles lowercased. Leaves active alone; a null clears that field.
- `deactivate_person` (write): Mark someone who left. They keep their claims, decisions and history. Close their team stints with end_membership.
- `add_member` (write): Open a stint on a team, with an optional role, from the date it started. Recording the same stint again cannot reopen one that LeftTeam closed; rejoining later is a new stint with its own since.
- `end_membership` (write): Close the stint on a team that started on since, as of until.
- `add_actor` (write): Register an actor under its OmniGraph actor id: a person's own login, or an agent with the person accountable for it. Refused if the slug already exists.
- `deactivate_actor` (write): Retire an actor: a person who left, or an agent no longer in use. Revoke its token too; this records the fact, the token grants the access.
- `add_project` (write): Add a project with its owner and team.

### queries/people.gq

- `project_owner`: Who owns a project and which team runs it.
- `team_members`: Current members of a team: stints no LeftTeam has closed, with their role.
- `person_by_handle`: Resolve an email, Slack member ID or GitHub login to a person, lowercased: alice@lanternworks.example, u01alice, apark.
- `person_handles`: A person's title, whether they are active, and their email, Slack member ID and GitHub login. Read these before update_person, which sets them all.
- `actors`: Everyone who reads or writes this graph, people's own logins and agents, with the person behind each and whether the actor is active.
- `active_projects`: Active projects with their owner, team and target date.
- `quiet_projects`: Active or paused projects with no meeting, thread or document about them since a time. Pass a fixed time, e.g. 2026-09-14T00:00:00.000Z.
- `project_sources`: Everything the brain has read about a project, newest first.
- `search_sources`: Full-text search over source titles, best match first.

## Run it

```bash
git clone https://github.com/ModernRelay/omnigraph-cookbooks
cd omnigraph-cookbooks
export COOKBOOK=$PWD/company-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/company-brain
