Notion as the Third Tier: Teaching an AI Assistant Where Things Go

Give an AI agent a Notion connection and it will cheerfully dump everything into it.

That is the failure mode nobody warns you about. A code repo, a Google Drive, and a Notion workspace all look identical to a fresh agent: three places that accept text. So it scatters. Canonical config lands in a Notion page where no other tool can read it. A finished PDF gets pasted as a wall of text. A durable behavioral rule ends up as a comment on a database row. Six weeks later your workspace is a junk drawer and you cannot tell which copy of anything is the real one.

I hit this building my own personal-assistant project. The interesting part of wiring Notion into it turned out not to be the connection. Connecting Notion is ten minutes of OAuth. The work is teaching the assistant that Notion is the third tier of a deliberate hierarchy, then giving it a rule for when to write there instead of the other two.

This post is the pattern. By the end you should be able to set up the same thing for your own assistant: a connection, a routing rule, a map, conventions, and a worked example of the agent operating inside all of that.

Three tiers, not one bucket

Start with the thing that makes the whole setup work, which is admitting that not all data is the same kind of data.

My assistant has three storage destinations, and each one is good at something the others are bad at:

• The repo is for code, configuration, and canonical text the agents read at session start. Version-controlled, diffable, multi-agent-readable, low-volume. This is where the agent definitions, the skills, the specs, and the personal-context files live.
• Google Drive is for deliverables, binaries, and sensitive PII that should not be in git. Finished resume PDFs, per-trip planning folders with booking details, anything a human opens on a phone.
• Notion is for relational structure, comments, and mobile-first human editing. The stuff that wants a database schema, or that I want to flip through and edit from the couch, or that a non-technical reader should be able to skim.

Notion is genuinely the best of the three at its job. It is also the worst possible home for canonical config, because it is too easy to edit away the structure that durable knowledge depends on. The whole game is keeping each kind of data in the tier that is good at it.

The routing rule is the heart of it

Here is the rule the agents actually follow. It lives in a spec file the agents read, and it is three questions answered in order:

Route any artifact by answering in order:

1. Code, configuration, or canonical text agents read at session start? → Repo
2. Deliverable, binary, or sensitive PII that doesn't belong in git?    → Drive
3. Relational structure, comments, or mobile-first edit by a human?     → Notion

When two destinations apply, separate canonical (single source of truth)
from mirror (read-only copy). The canonical wins; the others get a pointer.

That last sentence is what keeps Notion honest. Plenty of things could live in two places. A research brief is canonical markdown in the repo, but I also want to skim it from my phone, which is a Notion job. The rule does not let me keep two editable copies. One destination is canonical; the other is an explicit, labeled mirror that points back. When the two drift, the canonical wins. No ambiguity, no guessing which copy is real.

Notion is question three on purpose. An agent only reaches it after confirming the artifact is not config the agents read at boot, and not a deliverable or PII bound for Drive. By the time you get to Notion you have already ruled out the two ways data most commonly ends up in the wrong place. The ordering does the discipline for you.

This same block is duplicated, deliberately, in the agent-facing integration docs, so an agent that only loads the Notion section still sees the full rule. The rule is load-bearing enough to repeat.

Connect the server

Now the easy part. My assistant talks to Notion through Notion's hosted remote MCP server. The entire connection is one line in my integration notes:

Notion is connected via MCP server https://mcp.notion.com/mcp
(OAuth-authenticated, hosted by Notion).

Remote and OAuth-authenticated are the two phrases that matter. You are not running a server, managing a Notion API token, or rotating a secret in a .env file. You authorize once in the browser, the host holds the credential, and the agent gets a set of namespaced tools. In Claude Code those arrive as mcp__notion__*: notion-create-pages, notion-fetch, notion-search, notion-update-page, notion-move-pages. That is the whole surface.

Connecting it is where most write-ups stop. It is also where the junk drawer begins, because a connected agent with no map will write wherever it lands.

Give the agent a map

An agent that can create Notion pages but does not know where will create them anywhere. So the next move is to hand it a registry: a known root, and a table of the pages and databases it is allowed to reach, with what each one is for.

Every page my assistant creates is a child of one root page. The registry that records it looks like this, with the real IDs genericized to show the shape:

| Page             | ID                                 | Purpose                            |
|------------------|------------------------------------|------------------------------------|
| atelier (root)   | <your-root-page-id>  (32-char hex) | Parent for all assistant content   |
| career-path      | <career-path-page-id>              | Career domain hub; mirrors repo    |
| AI Briefs        | <ai-briefs-page-id>                | Research hub; parent for the DB    |
| Intake: Mobile   | <intake-page-id>                   | Landing zone for mobile capture    |

Notion IDs are 32-character hex strings. Mine are real; the ones above are placeholders, because the value to you is the pattern, not my identifiers. Do not publish your own real IDs either, for the same reason you would not publish an API key: they are addressable handles into your workspace. Databases get the same treatment in their own table, each with its data-source ID and the properties the agent writes.

The registry is the agent's mental model of the workspace. It reads the registry at session start, the same way it reads the routing rule. The effect is that "create a page" is never an open question about location. The agent knows the root, knows the hubs that hang off it, and knows that anything new becomes a child of the root, so the Notion tree mirrors the repo's artifacts/<domain>/ layout. Structure stays legible because it is declared, not improvised.

Teach it the house style

A map tells the agent where. Conventions tell it how. These live in a feedback rule the agents read at session start, and it opens with the line that sets the tone:

When creating or updating Notion pages, treat presentation
as part of the deliverable, not an afterthought.

Concretely that means every page the agent creates gets a cover image, an emoji icon that signals its domain, and visual structure instead of a markdown wall: callout blocks for the constraints that matter, dividers between sections, emoji-prefixed headers you can skim. A page without a cover reads as a draft, so the convention forbids shipping one.

One convention is a tell that you are working through an API and not a human in the UI: wide mode. Notion's default page width is too narrow for tables, and the MCP API does not expose the setting. So the rule is explicit that wide mode is a one-click manual toggle, and the agent's job is to remind me to flip it after it creates a page. The agent does what it can and hands off what it cannot. That honesty about the boundary beats pretending the tool can do something it cannot.

Let it operate

Connection, rule, map, conventions. Now watch the agent actually use Notion the way the system intends, with a real example from a skill I use constantly.

My phone is where ideas land. A "capture this" from mobile opens a new child page under an Intake: Mobile hub with a status callout, and it sits there until I triage it from my laptop. That triage skill is a clean illustration of the routing rule in motion, because its whole job is to take something that landed in Notion and move it to the tier where it belongs.

The skill declares its narrow Notion permissions up front, and the workspace's own source registry pins down exactly what the agent may do to that page:

notion_mobile_intake:
  canonical: "notion"
  parent_page_id: "<intake-page-id>"
  read_policy: "scan child pages by status for triage"
  write_policy: >
    agent may append new child page on capture/intake trigger from mobile/web;
    pa-intake-review may update status callout and move processed items

Read that write_policy line as a leash. The agent may append a capture, update a status, and move a processed item. It may not do anything else to that page. The permission is written down where the agent reads it, not implied by the fact that it could call any Notion tool.

The interesting move is what happens during triage. The agent reads the captured item and routes it by the same three questions. An idea worth building becomes an implementation brief committed to the repo. An article to digest becomes a research markdown file in the repo. Something blocked becomes a deferred entry. Almost nothing stays in Notion. Notion was the inbox, not the filing cabinet. The repo is where durable knowledge ends up, because the repo is what the agents read at session start.

Then the agent closes the Notion state cleanly. It updates the status callout in place and appends a footer pointing at wherever the work actually went:

Update status callout in place via notion-update-page
(command: "update_content"). Replace `Status: <old>` with `Status: <new>`.

Append a divider + callout footer:
---
> 🔗 Processed by /pa-intake-review on YYYY-MM-DD → <link to artifact>

That footer is the canonical/mirror rule paying off. The Notion page does not hold the result; it holds a pointer to the result. Open the page later and it tells you where the real thing lives. The junk drawer never forms, because nothing accumulates in the tier that was only ever supposed to be a doorway.

What to actually take from this

The connection is the trivial part. If you want an AI assistant that uses Notion well, the work is everything around the connection:

• Decide what Notion is good at before you connect it. For me that is relational structure, comments, and mobile-first human editing. Everything else has a better home.
• Write the routing rule down as ordered questions and make Notion the last one. By the time the agent reaches Notion it has already ruled out the two ways data lands in the wrong tier.
• Give the agent a registry of pages and IDs it reads at session start. A connected agent with no map writes anywhere.
• Make presentation a convention, not a hope, and be honest about what the API cannot do, like wide mode, by having the agent hand that step back to you.
• Make Notion point to canonical, never hold it. When something durable shows up in Notion, the agent's job is to move it to the tier that owns it and leave a pointer behind.

Do that and Notion becomes what it is actually good at: the living, skimmable, mobile front door to a system whose source of truth lives somewhere more durable. Skip it and you get a connection that works on day one and a junk drawer by week six.