notionmemory 1.0.0

English | 한국어

Why · Install · Quick start · Agents · How it works · Uninstall

notionmemory turns your own Notion workspace into a shared, long-term brain for coding agents (Claude Code, Codex). It ships a set of installable skills — long-term memory, calendar, templates, and content search — plus session hooks that surface the right context automatically. Everything lives in your Notion; there's no separate database or server.

You don't run its commands by hand. You talk to your agent in plain language — "remember that", "where did I file this?", "add this to my calendar", "register this page as a template" — and the agent runs notionmemory for you under the hood.

Why notionmemory

I built this for myself. Tools like agentmemory and claude-mem keep memories in a local vector database — fast and private, but two things kept getting in my way:

• I couldn't see what was stored. A vector DB is a black box — I couldn't open it, read what the agent "remembered," or fix a wrong entry. In Notion it's just pages, so I read and edit the memory myself.
• It didn't follow me. I develop across a server and a laptop, and memory that lives on one machine doesn't sync to the other. Notion is already cloud — the same brain everywhere.

I also wanted my agent beyond code: my study notes and schedule already live in Notion. Keeping memory there too gives my agent (and me) one place to reach from anywhere, instead of a hidden sidecar database. So notionmemory uses Notion as the cloud — visible, editable, shared, and already where the rest of my life is.

Install

1. Install the backend (user scope)

Install into your user scope — never sudo / system-wide. notionmemory places skills, session hooks, and local state under your home (~/.claude, ~/.codex, ~/.config/notionmemory, ~/.local/state/notionmemory), so it must run as your own user.

pipx install notionmemory        # recommended — isolated, on your PATH, user-scoped
# or: uv tool install notionmemory
# or: pip install --user notionmemory

2. Add it to your agent

Installing for both agents is supported — that's the point: Claude Code and Codex share the same brain. Just use one install method per agent (plugin or notionmemory install); doing both on the same agent installs its skills twice.

Claude Code (plugin)

/plugin marketplace add legojeon/notionmemory
/plugin install notionmemory@notionmemory

⚠️ The plugin installs the skills and the session hooks. Do not also run notionmemory install --claude — that double-installs them.

Codex (plugin + hooks)

codex plugin marketplace add legojeon/notionmemory
codex plugin add notionmemory@notionmemory
notionmemory install --codex --skip-skills --trust-codex-hooks

⚠️ --trust-codex-hooks is required — without it Codex silently never fires the hooks.

No plugin (one command, both agents)

pipx install notionmemory && notionmemory install

Codex users still need notionmemory install --codex --trust-codex-hooks before Codex hooks fire.

3. Run onboarding

Once installed, just ask your agent to onboard you — it runs the notionmemory:onboard skill (and offers it automatically on your first session). It walks you through connecting Notion — including sharing your pages with the integration — and setting up memory, calendar, and search as guided choices, skipping anything already done. The only thing it hands to you is pasting the Notion token, because a secret must never go through chat — so mind these when you create it at app.notion.com/developers/tokens:

• Workspace (most important): choose the workspace that holds your pages — the token is locked to that one workspace.
• Capability: keep Notion API checked (read/write content); "Workers" isn't needed.
• Expiration: pick the longest window offered — when it lapses the token stops working and you'll have to create a new one and reconnect.

Quick start

After onboarding you never type notionmemory commands — you just talk to your agent and it runs the right skill. For example:

Remember & recall

"Remember that we moved auth to JWT refresh-token rotation." "Did we ever decide how to handle rate limiting?" "What do you already know about this project?"

Calendar

"Add a design review tomorrow 3–4pm." "What's on my calendar this week?"

Search your Notion

"Where did I write the deployment runbook?" "Find my notes on the Postgres migration."

Templates

"Register this Notion page as my weekly-report template." (paste the URL) "Draft this week's report from what we did."

You never see the CLI. And at session start the agent is already primed with this project's brief and your most important memories — so it can pick up where you left off.

Agents

notionmemory is agent-driven — the CLI is only the mechanism the agent calls. You interact in natural language; the agent picks the right skill and runs it.

Skills the agent can reach:

• onboard — first-time guided setup (Notion + memory + calendar + search)
• memory — save/recall long-term decisions & patterns in a Notion Second Brain
• calendar — read/create/move events in a Notion calendar database
• templates — register Notion pages/DBs and author content into them
• library — content search across your Notion pages
• settings — a local web dashboard for connections & configuration
• git — optional post-commit capture of your commits into memory

How it works

Your agent talks to your Notion through the notionmemory CLI, which calls the Notion REST API. There's no separate database and no long-running server. What makes it a memory rather than a dumb store is the lifecycle — capture cheaply, consolidate with importance scoring, then recall the important things at the right moment:

What gets stored, and how

• Memory is a Notion "Second Brain" database. When you explicitly say "remember this" it lands Active right away. When the agent decides on its own to save something, it lands as a Draft — recallable, but not yet promoted.
• Every memory carries a Strength (1–10) — an importance score used to rank recall and to decide what's worth surfacing at session start.
• A later consolidation pass (notionmemory memory consolidate, which you run in your own terminal) has an agent review the Drafts: summarize and refine them, assign a real Strength, drop noise (→ Forgotten), merge duplicates (→ Superseded), and maintain a rolled-up per-project brief. So the database stays curated instead of a raw dump.

When it reads

• At session start, the agent is fed this project's brief plus its top high-Strength memories — gated by importance, not a raw recency dump.
• Per message, a zero-network local index may add a one-line "relevant memory" hint; the agent deep-reads it with recall only if it's actually relevant, and ignores it otherwise.
• On demand, library search finds pointers by title/heading across your whole Notion, and the agent live-reads the winners — content is always read fresh, never cached.

Search without embeddings

There is no vector database and no embedding model. Matching is lexical — word-boundary matching for English, substring for Korean — over titles, headings, and each memory's concept tags, weighted by Strength. Deliberately simpler than even BM25: no corpus statistics, no ranking model. That's enough because the search only has to produce candidates: the agent itself supplies the semantics. It reads the top hits live and judges what's actually relevant — the judgment a vector similarity score approximates, an LLM does directly. The upshot: nothing to embed, sync, or go stale, and the per-message hint runs with zero network from a tiny local index.

How memory updates

• New information supersedes the old (--supersedes) — the original is kept as Superseded, not deleted. forget sets Status=Forgotten; nothing is ever hard-deleted.
• Consolidation re-scores and merges over time, so importance and the project brief stay current.
• Pages you delete in Notion self-heal out of the local search index the moment they're read (a live 404 prunes the stale pointer), with an occasional full prune to sweep the rest.

Why a CLI + API, not an MCP server

• The session hooks (SessionStart / Stop / UserPromptSubmit) run as plain shell commands — they need a CLI, not a live MCP connection held open inside an agent session.
• The same CLI runs headless and in cron (e.g. consolidation), not only inside an MCP-capable chat.
• One skill set + CLI behaves identically across Claude Code and Codex; MCP support and semantics vary by agent.
• Fewer moving parts: no server process to run, your token stays in the OS keyring, and the only local state is a thin search index.

The settings dashboard stores your Notion connection and skill options — just ask your agent to "open notionmemory settings" (the settings skill), or run notionmemory serve yourself. The token lives in your OS keyring, never in a file.

Uninstall

Full removal is a few steps because different tools own different pieces. Run notionmemory teardown first (while the CLI still exists) and remove the backend last (a running pipx uninstall of itself is unreliable). teardown removes only what notionmemory installed — skills, session/git hooks, local state — and never touches your Notion pages; it keeps your config and keyring token unless you add --purge-config --purge-secrets.

Claude Code (plugin):

notionmemory teardown --purge-config --purge-secrets   # config, keyring token, local state
claude plugin uninstall notionmemory@notionmemory      # skills + hooks
claude plugin marketplace remove notionmemory          # marketplace source
pipx uninstall notionmemory                            # backend — run last

Codex (plugin):

notionmemory teardown --purge-config --purge-secrets
codex plugin remove notionmemory@notionmemory          # or uninstall it from `codex /plugins`
codex plugin marketplace remove notionmemory
pipx uninstall notionmemory

No-plugin install (you set it up with notionmemory install) — teardown already removes the skills and hooks:

notionmemory teardown --purge-config --purge-secrets
pipx uninstall notionmemory

Drop --purge-config --purge-secrets to keep your config and saved token for a later reinstall. If you installed the backend with uv/pip instead of pipx, uninstall it with uv tool uninstall notionmemory / pip uninstall notionmemory. Notion databases and pages are never deleted.

License

MIT — see LICENSE.