Notion as agent memory for Claude Code — hybrid retrieval over your pages, no vector database

README.md

Notion as agent memory for Claude Code — hybrid retrieval over your pages, no vector database

You already have a Notion connector. This adds the semantic layer: retrieval ranked by meaning, so the agent pulls the right page on the first try.

Last tested: 2026-06-19 — @reneza/ats-mcp + @reneza/ats-adapter-notion, Notion API 2022-06-28. See Changelog at the bottom.

If this saves you setup time, follow @renezander030 — practical AI / coding-agent infrastructure notes.

Full repo with the MCP server + adapter source: github.com/renezander030/agentic-task-system

TL;DR cheat sheet

Goal	Use
Notion in Claude Code	claude mcp add ats -e ATS_ADAPTER=@reneza/ats-adapter-notion -- ats-mcp
Auth	internal integration token (ntn_…), then share the database with the integration
Could not find database	you forgot to share the DB with the integration — see Common failures
Search that ranks by meaning	hybrid dense + sparse + keyword, fused with RRF — not Notion's substring search
Mapping	database = project, page = task, block tree → markdown body

A connector gives access. This gives retrieval.

The official Notion MCP server connects your agent to Notion — fetch this page, create that one. It can't answer "what do we know about the auth migration?" ranked by relevance. That's a search problem. ATS adds hybrid retrieval (keyword + dense + sparse, fused with RRF) over your Notion pages, so the first result is the relevant one instead of whatever the model guessed to query.

ATS is task-first: your task manager is the agent's memory; Notion pages come in as the supporting docs and specs behind the task it's working on — not a separate knowledge base to babysit.

Recommended setup

npm install -g @reneza/ats-cli @reneza/ats-mcp @reneza/ats-adapter-notion
export ATS_NOTION_TOKEN=ntn_xxxxxxxx          # internal integration token
ats config use @reneza/ats-adapter-notion
ats find "auth migration runbook"             # verify from the CLI first
claude mcp add ats -e ATS_ADAPTER=@reneza/ats-adapter-notion -- ats-mcp

Create the token at https://www.notion.so/my-integrations (an internal integration), then in each database click ••• → Connections → add your integration. That per-database share is the security boundary: the integration sees only what you share with it, nothing else in the workspace.

Optional dense/hybrid branch (local, no cloud, no hosted vector DB):

docker run -d --name qdrant -p 6333:6333 qdrant/qdrant:latest
docker run -d --name ollama -p 11434:11434 ollama/ollama:latest
docker exec ollama ollama pull nomic-embed-text
ats sync vector

Common failures

Could not find database with ID: <id>. Make sure the relevant pages and databases are shared with your integration.

The #1 Notion gotcha. The token is valid but you never shared the database with the integration. Open the database → ••• → Connections → add your integration. Re-run ats doctor.

API token is invalid. (HTTP 401)

Wrong or expired token, or you pasted a public OAuth token where an internal integration token (ntn_…) is expected. Re-copy from my-integrations.

rate_limited (HTTP 429)

Notion throttles ~3 requests/sec per integration. A cold find walks every shared database. The adapter backs off on Retry-After; keep the corpus cache on (default) so warm queries don't re-fetch.

body failed validation: body.Notion-Version should be defined

Only happens if you call the API by hand — the adapter always sends Notion-Version: 2022-06-28. Listed here because it's the string people paste into Google.

Smoke test

ats doctor                                        # adapter notion, auth ok, N databases
ats find "something you know is in a Notion page" --limit 3 --json | jq '.tasks[].title'
claude mcp list                                   # ats listed as connected

Then in Claude Code: "use ats find to look up the spec in Notion." Pass criteria: it cites the actual page and returns a sources provenance array, without you pasting the page in.

Series

Same six-method adapter contract, different backend:

• GitHub issues as agent memory for Claude Code
• TickTick MCP server for Claude Code & Claude Desktop
• Obsidian vault as agent memory for Claude Code
• Agent memory without a vector database — RRF over data you already curate

To query Notion and GitHub and your task app in one ranked result, use the composite adapter.

Sources

• ATS repo + adapter source: https://github.com/renezander030/agentic-task-system
• npm: https://www.npmjs.com/package/@reneza/ats-adapter-notion
• Notion API reference: https://developers.notion.com/

Comment with your setup

If you wire Notion into Claude Code another way, comment with: integration type (internal vs OAuth), how many databases you shared, corpus size, and any error strings not listed here.

Changelog

2026-06-19

• Initial publication. Deliberate skips: no hardware matrix (not hardware-bound); no companion repo (the agentic-task-system repo already holds the source).