Every wiki starts the same way and ends the same way. Someone sets up a clean structure, a few people write good pages, and for about two quarters it is genuinely the best thing in the company. Then the product changes, three of the authors leave, four pages get written that cover the same ground slightly differently, and a new hire follows an onboarding page that has been wrong since March. Nobody decided to let this happen. Maintenance is simply the work nobody has time for, and it is exactly the shape of work an agent is good at.
Why Notion Wikis Rot
Worth naming the mechanism, because it explains why the fix has to be recurring rather than a one-off cleanup weekend.
A wiki page is written once, at the moment somebody knows something. It is correct on the day it is published. Everything after that is decay, and the decay is invisible: the page does not change, the world does. There is no notification when the pricing tier a page describes gets retired, or when the tool named in an onboarding checklist gets replaced, or when the person listed as the owner leaves.
The second mechanism is duplication. Search does not surface a page someone half-remembers, so they write a new one. Now two pages disagree, and the one that ranks higher in Notion search wins arguments regardless of which is right. This compounds: the more pages cover a topic, the harder each is to find, and the more likely the next person is to write a third.
Neither problem announces itself. Both are cheap to detect if something reads the whole wiki at once, which no human does and no human should.
What an Agent Can and Cannot See
Being precise about this matters, because the most intuitive maintenance signal is the one you cannot have.
| Signal | Available through the API? | What it tells you |
|---|---|---|
| Last edited time | Yes, on pages, databases and blocks, and you can filter database queries by it | What nobody has touched. A decent proxy for neglect, a poor one for wrongness |
| Created time | Yes | How old the page is, useful for separating "written last week and already stale" from ordinary age |
| Full page content | Yes, via the blocks in each page | Everything the useful checks depend on: what the page claims, and whether the claim expires |
| Links between pages | Yes, they are in the content | Which pages nothing points at, and which are load-bearing |
| Page owner or last editor | Yes, as a user reference | Who to ask, and whether that person still works here |
| Page views and unique viewers | No. Page analytics are a Notion interface feature | The signal everyone wants and nobody gets programmatically |
That last row is the constraint that shapes the whole design. You cannot ask an agent to find the pages nobody reads. You can ask it to find pages nothing links to, which is a decent structural stand-in, and you can ask it to find pages that make expiring claims, which is a better signal than either. If you genuinely need view data, it is visible in Notion's own page analytics and you can read it there for the handful of pages the report flags, rather than for all four hundred.
If you have not connected an agent to a Notion workspace before, connecting an agent to Notion covers the integration and, more importantly, how to share only the pages you intend rather than the whole workspace.
The Six Checks Worth Running
"Tidy up our wiki" produces a confident mess. Six specific checks produce a report you can act on in an hour.
- Expiring claims. Flag any page naming a price, a date, a headcount, a named tool, a policy, a version number or a person. These expire whether or not anyone edits them, and this check finds more real problems than every other check combined.
- Duplicate coverage. Group pages by what they actually say rather than by title, and report clusters that overlap. Report the cluster; do not ask the agent to pick a survivor.
- Orphans. Pages nothing else links to. Some are fine, most are either abandoned or impossible to find, and both are worth knowing.
- Dead-end hubs. The inverse, and the one people miss: index pages that everything links to but that link nowhere useful themselves. A hub that does not route onward is a dead end wearing a table of contents.
- Absent owners. Pages whose last editor or listed owner is no longer in the workspace. These are not wrong, they are unmaintained, which is different and worth separating.
- Contradictions. Where two pages state incompatible things about the same subject. Rarer than duplication and considerably more expensive when a new hire finds the wrong one.
Notice what is not on that list: anything requiring the agent to judge whether a claim is true. It cannot know whether your return window is still fourteen days. It can only notice that a page asserts one, which is the useful half.
What to Hand the Agent
| Element | What to specify |
|---|---|
| Scope | The specific pages or teamspaces shared with the integration. Not the whole workspace by default |
| Permissions | Read only. It reports, it does not edit, archive, move or delete |
| Staleness rule | Flag rather than recommend deletion, and always show the last edited date next to the flag so a human can judge |
| Expiry check | The explicit list of claim types that expire: prices, dates, headcounts, tool names, policies, versions, people |
| Duplicate handling | Report the cluster with a one-line summary of how the pages differ. Never merge |
| Escalation | Where it cannot tell whether something is stale, say so plainly rather than guessing confidently |
| Output | One document, grouped by check, ordered by how much a wrong page would cost. Onboarding and customer-facing pages first |
The permissions row is where to hold the line. Scoping an integration to read-only takes a minute in Notion's own settings and removes every failure mode where an agent quietly rewrites institutional knowledge. AI agent security best practices covers the general principle, which applies well beyond Notion.
A Working Monthly Job
Once a month the agent reads the shared pages, runs the six checks, and writes one review document into a maintenance page in the wiki itself. Someone owns working through it in a single sitting: accept, dismiss, or assign. Edits happen in Notion, by people.
Monthly rather than weekly is deliberate. Wiki drift is slow, and a weekly report is mostly empty, which teaches people to stop opening it. The exception is a change you already know about. If pricing changed, or a tool was swapped out, or a team reorganised, run the job the week after rather than waiting for the calendar, because you already know a specific class of page just went stale.
For the mechanics of a job that fires on its own rather than one somebody remembers, writing a prompt for a recurring agent covers phrasing a recurring instruction so it does not go stale itself. The same maintenance shape works on other documentation tools: Confluence stale page cleanup is the equivalent job in an Atlassian workspace, and the checks transfer almost unchanged.
This also sits alongside the other Notion work worth handing over. A Notion daily rollup agent handles the reporting direction, pulling scattered updates into one place, and Notion project tracking covers keeping project databases current. Maintenance is the one that runs least often and prevents the most quiet damage.
What We Saw Running This
We ran the six checks against our own internal wiki, a few hundred pages built up over about a year, and the results reordered our priorities.
The expiring-claims check was far and away the most productive, and it caught things staleness dates could not. Several pages edited within the previous two months named a pricing structure we had changed, so a last-edited filter would have marked them fresh. Conversely, a set of pages untouched for over a year turned out to be completely fine, because they explained concepts that do not move. If we had started with a "flag anything older than ninety days" rule, which is the obvious first instinct, we would have generated a long list of false positives and missed the pages that were actually wrong.
The duplicate check found fewer clusters than expected but the ones it found were worse than expected. The pattern was consistent: two pages written eight months apart by people who did not know the other existed, both reasonable, quietly contradicting each other on one detail. Nobody had noticed because each was individually correct-looking.
The orphan check produced the most noise. Plenty of pages are legitimately unlinked, including meeting notes and personal scratch pages, and reporting them all buried the real finds. Narrowing it to unlinked pages that also read as reference material, rather than as notes, made it useful.
The honest limit: the report told us what to look at, not what was true. Every genuinely wrong page still needed a human who knew the answer. What it removed was the part where somebody has to read four hundred pages to find the eleven that matter.
What Goes Wrong
Treating last-edited as a truth signal. It is a neglect signal. Anchoring the whole job to a date threshold generates confident lists of the wrong pages, and it is the single most common way this project fails.
Sharing the whole workspace. Notion integrations see what you share with them. It is tempting to share everything so the agent has full context, and that is how a maintenance job ends up reading HR pages. Share the teamspaces you actually want maintained.
Letting the agent merge duplicates. Two pages that overlap usually differ on the one line that matters, and the line that matters is often the newer, less polished one. Report the cluster and let a human choose.
Running it and not staffing it. A maintenance report nobody works through is worse than no report, because it creates the feeling that the problem is handled. If there is no named owner for the hour, do not start the job.
Expecting it to know your business. An agent can see that a page names a fourteen-day return window. Only a person knows whether that is still the policy. A report that says "confirm this is current" is doing its job; one that quietly changes the number is a liability.
If the wider question is what else in a workspace is worth handing to an agent, what an AI agent can actually do is a broader survey, and the cheapest AI agent platforms in 2026 compares what the free tiers cover if you want to try this without a budget conversation first.
Frequently Asked Questions
Can an AI agent clean up a Notion knowledge base automatically?
It can find what needs cleaning up, which is the hard part. Give it read access and it can flag stale pages, duplicate coverage, pages nothing links to, and pages making claims that have probably expired. Let it write and you have an agent that can silently change what your company believes. The pattern that works is a monthly report a human works through in one sitting, with the edits made by people.
Does the Notion API tell you which pages nobody reads?
No. Notion's page analytics, which show views and unique viewers, are a feature of the Notion interface rather than something the API exposes. What the API does give you is last_edited_time on pages, databases and blocks, and you can filter database queries by that timestamp. So an agent can tell you what has not been touched, not what has not been read. Those are different signals and it is worth being clear which one you are acting on.
How do you find stale pages in Notion?
Combine two signals rather than trusting either alone. The first is the last edited timestamp, available through the API. The second is content-based: pages that name a date, a price, a headcount, a tool, a policy or a person are pages that expire, whether or not anyone has edited them. A page last edited fourteen months ago that only explains a stable concept is fine. A page edited last month that names a pricing tier may already be wrong.
Should the agent be allowed to edit or archive Notion pages?
No, or at least not at the start. A wiki is what your team believes about how things work, and an agent with write access can quietly change that. Read and propose only. The cost is a click per accepted change and it removes the entire category of failure where nobody notices an edit until a new hire follows the wrong instructions.
How often should a knowledge base maintenance agent run?
Monthly for most teams. Wiki drift is slow, and a weekly run produces a mostly empty report, which trains people to stop opening it. Quarterly is too slow for a fast-changing product because a full quarter of wrong onboarding documentation costs more than the review. If your product or pricing changed in the last month, run it after the change rather than waiting for the calendar.
What does it cost to run a Notion maintenance agent?
On Gravity the free tier covers one agent at $0 a month, which is enough for a monthly maintenance pass on a single workspace. Paid plans start at $20 a month including $20 of usage, with extra usage available beyond the plan if you are maintaining several workspaces or running the job more often.
Is this different from Notion AI?
Different job. Notion AI is built to help you write and find things inside a page or workspace, and it is good at that. Maintenance is the opposite direction: looking across the whole wiki at once and asking which parts have quietly stopped being true. Nothing stops you using both, and most teams that do the maintenance pass find it makes search better anyway, because there is less contradictory material to surface.
Sources
- Notion. "Page analytics in Notion," notion.com/help, checked 26 August 2026. Source for page analytics being an interface feature showing views and unique viewers.
- Notion. Developer changelog, "Query a database endpoint supports filtering by timestamp," developers.notion.com, checked 26 August 2026. Source for filtering database queries by last edited timestamp even where the database has no timestamp property.
- Notion. Developer changelog, "Last edited and created time properties are now rounded to the nearest minute," developers.notion.com, checked 26 August 2026. Source for last edited and created time being available properties, and for their precision.
- Gravity pricing: free tier with one agent at $0 per month; paid plans from $20 per month including $20 of usage, with extra usage available beyond the plan. Checked 26 August 2026.
- Related reading: connecting an agent to Notion, Confluence stale page cleanup, Notion daily rollup agent, what an AI agent is.