notionmemory 0.1.0__tar.gz

notionmemory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaewoo Jeon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

notionmemory-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: notionmemory
+Version: 0.1.0
+Summary: Notion as a second-brain hub for coding agents: memory, calendar, templates, and library skills.
+Author-email: Jaewoo Jeon <learnsteam.kr@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/legojeon/notionmemory
+Project-URL: Repository, https://github.com/legojeon/notionmemory
+Project-URL: Issues, https://github.com/legojeon/notionmemory/issues
+Keywords: notion,second-brain,claude-code,codex,agent-memory,skills
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: Flask>=3.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: keyring>=25
+Dynamic: license-file
+
+# notionmemory
+
+Turn Notion into a second-brain hub for coding agents (Claude Code, Codex).
+notionmemory ships a set of installable **skills** — long-term memory, calendar,
+templates, and library recall — plus session hooks that surface the right context
+automatically.
+
+> Skills and CLI onboarding output are available in English (default) and Korean
+> (`config language: en|ko`). A longer Korean guide is at [`docs/README.ko.md`](docs/README.ko.md).
+
+## Install
+
+1) Backend (required, both harnesses):
+
+```bash
+pipx install notionmemory      # or: uv tool install notionmemory / pip install --user notionmemory
+```
+
+2a) Claude Code (plugin):
+
+```bash
+/plugin marketplace add legojeon/notionmemory
+/plugin install notionmemory@notionmemory
+# skills appear as notionmemory:calendar, notionmemory:memory, …
+# Do NOT also run `notionmemory install --claude` (the plugin already installs skills + hooks).
+```
+
+2b) Codex (plugin + hooks):
+
+```bash
+codex plugin marketplace add legojeon/notionmemory
+codex plugin add notionmemory@notionmemory
+notionmemory install --codex --skip-skills --trust-codex-hooks   # hooks + trust (plugin owns the skills)
+# --skip-skills: don't mirror skills, the plugin already provides them
+# --trust-codex-hooks: required or Codex will silently not fire the installed hooks
+```
+
+Prefer no plugin? One uniform command sets up both harnesses (skills unnamespaced):
+
+```bash
+pipx install notionmemory && notionmemory install
+```
+
+Codex users: `notionmemory install` will tell you to also run `notionmemory install --codex --trust-codex-hooks` before Codex hooks fire.
+
+The marketplace source is this repository. If you're working from a local clone
+before it's reachable as `legojeon/notionmemory`, add it by path instead:
+`codex plugin marketplace add "$(pwd)"` / `claude plugin marketplace add "$(pwd)"`.
+
+Run `notionmemory serve` to open the settings dashboard and connect your Notion
+token (stored in your OS keyring, never in config).
+
+## Skills
+
+- **memory** — save/recall long-term decisions & patterns in a Notion Second Brain
+- **calendar** — read/create/move events in a Notion calendar DB
+- **templates** — CRUD over your registered Notion templates & databases
+- **library** — content search across your Notion pages
+- **settings** — local web dashboard for connections & configuration
+
+## Upgrade
+
+notionmemory installs files on your system (skill mirrors, session/git hooks,
+state). To upgrade cleanly — including removing skills that a new version has
+retired — run `notionmemory teardown` then reinstall. `teardown` removes only what
+it installed; your Notion pages, config, and keyring token are preserved by
+default (see `notionmemory teardown --dry-run`).
+
+## Uninstall
+
+```bash
+notionmemory teardown              # removes skills, hooks, local state
+notionmemory teardown --purge-config --purge-secrets   # also config + token
+```
+
+Notion databases and pages are never deleted.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

notionmemory-0.1.0/README.md

@@ -0,0 +1,80 @@
+# notionmemory
+
+Turn Notion into a second-brain hub for coding agents (Claude Code, Codex).
+notionmemory ships a set of installable **skills** — long-term memory, calendar,
+templates, and library recall — plus session hooks that surface the right context
+automatically.
+
+> Skills and CLI onboarding output are available in English (default) and Korean
+> (`config language: en|ko`). A longer Korean guide is at [`docs/README.ko.md`](docs/README.ko.md).
+
+## Install
+
+1) Backend (required, both harnesses):
+
+```bash
+pipx install notionmemory      # or: uv tool install notionmemory / pip install --user notionmemory
+```
+
+2a) Claude Code (plugin):
+
+```bash
+/plugin marketplace add legojeon/notionmemory
+/plugin install notionmemory@notionmemory
+# skills appear as notionmemory:calendar, notionmemory:memory, …
+# Do NOT also run `notionmemory install --claude` (the plugin already installs skills + hooks).
+```
+
+2b) Codex (plugin + hooks):
+
+```bash
+codex plugin marketplace add legojeon/notionmemory
+codex plugin add notionmemory@notionmemory
+notionmemory install --codex --skip-skills --trust-codex-hooks   # hooks + trust (plugin owns the skills)
+# --skip-skills: don't mirror skills, the plugin already provides them
+# --trust-codex-hooks: required or Codex will silently not fire the installed hooks
+```
+
+Prefer no plugin? One uniform command sets up both harnesses (skills unnamespaced):
+
+```bash
+pipx install notionmemory && notionmemory install
+```
+
+Codex users: `notionmemory install` will tell you to also run `notionmemory install --codex --trust-codex-hooks` before Codex hooks fire.
+
+The marketplace source is this repository. If you're working from a local clone
+before it's reachable as `legojeon/notionmemory`, add it by path instead:
+`codex plugin marketplace add "$(pwd)"` / `claude plugin marketplace add "$(pwd)"`.
+
+Run `notionmemory serve` to open the settings dashboard and connect your Notion
+token (stored in your OS keyring, never in config).
+
+## Skills
+
+- **memory** — save/recall long-term decisions & patterns in a Notion Second Brain
+- **calendar** — read/create/move events in a Notion calendar DB
+- **templates** — CRUD over your registered Notion templates & databases
+- **library** — content search across your Notion pages
+- **settings** — local web dashboard for connections & configuration
+
+## Upgrade
+
+notionmemory installs files on your system (skill mirrors, session/git hooks,
+state). To upgrade cleanly — including removing skills that a new version has
+retired — run `notionmemory teardown` then reinstall. `teardown` removes only what
+it installed; your Notion pages, config, and keyring token are preserved by
+default (see `notionmemory teardown --dry-run`).
+
+## Uninstall
+
+```bash
+notionmemory teardown              # removes skills, hooks, local state
+notionmemory teardown --purge-config --purge-secrets   # also config + token
+```
+
+Notion databases and pages are never deleted.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

notionmemory-0.1.0/notionmemory/agent_skills/calendar/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: calendar
+description: List, add, update, and cancel my events in the Notion Calendar DB. Use when the user says things like "what's on tomorrow/this week", "schedule a meeting/add an event", or "move/cancel an event". Searching past decisions or memories is the memory skill.
+---
+
+# calendar — list / add / update / cancel
+
+Command to run (the `notionmemory` command is registered on PATH at install time — run it as-is from any project):
+
+```bash
+notionmemory calendar list [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--days N]
+notionmemory calendar add "<title>" --start "YYYY-MM-DD HH:MM" [--end "YYYY-MM-DD HH:MM"] [--location "<location>"] [--link <url>] [--notes "<notes>"] [--source claude|codex]
+notionmemory calendar update <event_id> [--title "..."] [--start "..."] [--end "..."] [--location "..."] [--link <url>] [--status Scheduled|Done|Canceled]
+notionmemory calendar cancel <event_id>
+notionmemory calendar setup
+```
+
+## Conventions
+
+1. Relative time expressions ("tomorrow at 3pm", "next Monday") must be **converted by the agent to `YYYY-MM-DD HH:MM` based on the current date** before being passed in. A date with no time produces an all-day event.
+2. Before update/cancel, always run `list` first to find the target, show it to the user, and get **explicit confirmation**.
+3. After add/update, echo the printed event_id back to the user.
+4. Indicate the saving actor: `--source claude` for a Claude Code session, `--source codex` for Codex.
+5. **Do not copy event text verbatim into the Second Brain.** Only save decisions or facts that arose from an event via the memory skill, linking the Notion page URL that `add` printed via memory's `--link`.
+6. `cancel` records Status=Canceled and then sends the page to the Notion trash (it also disappears from the calendar app, recoverable within 30 days) — tell the user this happened.
+7. If the CLI prints Notion Calendar app connection instructions (on first DB creation), relay them to the user verbatim. If the user asks "it's not showing up in the app / how do I connect it", run `calendar setup` to show the instructions — app setup has no API, so it can't be applied automatically.
+
+## Where to write — different from reading
+
+Reading can merge multiple sources, but writing must **pick exactly one**. When
+`notionmemory calendar add` returns exit 2 with a list of candidates, that means "where to
+write hasn't been decided." **Don't pick arbitrarily — ask the user.**
+
+```
+Where should I add this?
+  1. Calendar DB (built-in)
+  2. Tasks DB in the my-planner template
+→ just this time / going forward
+```
+
+Translate the answer into a command:
+
+| User's answer | What to run |
+|---|---|
+| Just this time · Calendar DB | `notionmemory calendar add ... --here` |
+| Just this time · template | Check properties with `notionmemory templates show <slug>` → `notionmemory templates add <slug> <db-key> --set ...` |
+| Going forward · Calendar DB | `notionmemory calendar target calendar`, then `calendar add` again |
+| Going forward · template | `notionmemory calendar target template:<slug>/<db-key>` |
+
+**Only use `calendar target` when the user explicitly says "going forward."** Promoting a
+one-off answer to a permanent default means the user won't be able to trace "why does this
+go here?" weeks later.
+
+If the write target is set to a template, `calendar add` will tell you which command to run
+and refuse — calendar does **not** write to another template's database. Follow the guidance
+it gives and use the `templates` commands instead. Always confirm property names with
+`templates show <slug>` — never guess them.
+
+## Find content with library
+
+Finding things **by content** — "where did I file this / how did I do X before" — is not
+this skill's job but `library`'s: `notionmemory library search "<query>"`. It searches
+across your Second Brain, registered templates, and general documents, attaching the
+source to every hit. Don't conclude "nothing here" from a single source.
+(Date/status **filter** queries are still this skill's job — library only searches text content.)

notionmemory-0.1.0/notionmemory/agent_skills/library/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: library
+description: Use this to find where something is organized in my Notion. When the user's own Notion content (pages, documents, Second Brain) needs to be found by content — "where did I organize this", "how did I handle X before", "let's reuse that paper summary elsewhere" — run the notionmemory CLI with this skill.
+---
+
+# library
+
+Finds **"what something is about"** across my entire Notion. Whether it's a page, a document,
+or a Second Brain entry, and regardless of whether it's a template or a plain document, it finds
+it by content in one shot.
+
+```
+notionmemory library search "<query>" [--limit N]   # ranked pointers (source · title · section · id)
+notionmemory library read <page-id>                 # live-read the found page's body (block ids inline)
+notionmemory library refresh [--full]                # refresh the index (--full for a full crawl)
+notionmemory library status                          # index age · count
+```
+
+`search` returns **pointers, not body content** — `content · [page-id] title > section`,
+`memory · [mem-id] title`. Each pointer carries its source.
+
+## Three usage modes
+
+- **locate** — Just show the pointers from `search`. Do not read the body.
+- **pull** — Live-read only the top 1–2 candidates with `library read <page-id>` and use that.
+  The read output has block ids inline, so if you need to revisit a specific part, use those.
+  Do not bulk-read every candidate (delegate below if 3+ sources).
+- **sweep** — When you need to sweep 3+ sources and synthesize, **delegate to a subagent**.
+  Have the subagent read the candidates and return **only the answer + sources (ids)**, so the
+  raw body content doesn't flood the main context. (Delegation conditions: 3+ sources, synthesis
+  needed, read-only. Source pointers must always be returned.)
+
+## If the index is empty or stale
+
+If session start injects "library index: none" or a stale age, the index doesn't exist yet or is
+out of date. **Tell the user you're building the search index**, then run `library refresh --full`
+before searching (this crawls the whole workspace and takes time, so don't do it silently). For
+queries where recency matters, like "what did I write today," also `refresh` first.
+
+## Limits
+
+- **The index only knows titles and headings.** A page whose relevant content lives only in the
+  body, not in the title or headings, may not be found — try broadening the query with synonyms
+  (e.g., "container orchestration" → "Kubernetes"), or ask the user which page they mean.
+- Search reflects the current index, so **a page you just created may not show up until you
+  refresh.**
+- **Date/status filters** ("tomorrow's schedule", "incomplete todos") belong to calendar/templates'
+  structured queries, not library. library only finds things by "what they're about" (text).

notionmemory-0.1.0/notionmemory/agent_skills/memory/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: memory
+description: Saves, searches, and deletes long-term memories in a Notion Second Brain. Use when the user says "remember this / save this / note that", when you've learned a decision, pattern, or preference with lasting value, or when past context would help ("did we ever" do this before).
+---
+
+# memory — remember / recall / forget
+
+Executable commands (the `notionmemory` command is registered on PATH at install time — run it as-is from any project):
+
+```bash
+notionmemory remember "<content>" --type <t> --concepts "a,b,c" [--files "x.py,y.ts"] [--project <p>] [--source claude|codex] [--related <mem_id>] [--link <notion_page_url>] [--supersedes <mem_id>] [--auto]
+notionmemory recall "<query>" [--type <t>] [--project <p>] [--top N]
+notionmemory recall --get <mem_id>
+notionmemory forget <mem_id>
+```
+
+## remember conventions
+
+1. Preserve the user's own wording in content — no reinterpreting or over-summarizing.
+2. concepts should be **2-5 items, lowercase, specific**: `jwt-refresh-rotation` correct / `auth` wrong.
+3. If there are referenced file paths, record them in `--files` (real paths only, never guess).
+4. Choose `--type`: pattern (a recurring code pattern) / preference (a user preference) / architecture (a structural decision) / bug (a bug and its fix) / workflow (a work procedure) / fact (anything else).
+5. Indicate who is saving: `--source claude` for a Claude Code session, `--source codex` for Codex.
+6. **When the agent decides on its own to save something, always attach `--auto`.** Saves the user explicitly requested go without `--auto`. If it exits 2 ("auto-save is off"), give up on saving and move on quietly.
+7. When replacing an existing memory, use `--supersedes <mem_id>` (the original is preserved as Superseded); use `--related <mem_id>` for related memories and `--link <url>` for a related Notion page.
+8. After saving, echo the printed mem_id and concepts back to the user verbatim — those are the future search terms.
+
+## recall conventions
+
+- Use the user's own wording as the query as-is. Narrow with `--project`/`--type` when a project or topic is mentioned.
+- **Never fabricate results**: report exactly what comes back, and if it falls back to "no results," say so plainly and suggest 2-3 alternative search terms. Never make things up.
+- Use `recall --get <mem_id>` when the full content is needed.
+
+## forget conventions
+
+- Before deleting, always use recall to find the target, show it to the user, and get **explicit confirmation**.
+- Tell the user this sets Status=Forgotten (not a hard delete).
+
+## Anti-patterns
+
+WRONG: `--concepts "stuff, code, notes"` — unfindable later.
+RIGHT: `--concepts "jwt-refresh-rotation, token-revocation"` — specific and searchable.
+
+WRONG: recall returns nothing, so you answer with a guess like "it was probably discussed last week."
+RIGHT: "No matching memories. Should I try searching for `refresh token` or `session expiry` instead?"
+
+## Checklist
+
+- content preserves the user's own wording.
+- concepts: 2-5 items, lowercase, specific.
+- `--auto` is attached when the agent decided to save on its own.
+- recall results were reported exactly as returned.
+
+## Find content with library
+
+Finding things **by content** — "where did I file this / how did I do X before" — is not
+this skill's job but `library`'s: `notionmemory library search "<query>"`. It searches
+across your Second Brain, registered templates, and general documents, attaching the
+source to every hit. Don't conclude "nothing here" from a single source.
+(Date/status **filter** queries are still this skill's job — library only searches text content.)

notionmemory-0.1.0/notionmemory/agent_skills/settings/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: settings
+description: Opens the notionmemory web settings dashboard. Use this skill when the user says something like "open notionmemory settings" or "show me the connections/settings screen" — it (re)starts the local settings server if needed and opens the browser.
+---
+
+# settings
+
+When the user wants to open notionmemory's settings screen (connections, skill options), follow the steps below in order.
+
+## 1. Check if it's already running
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8765/api/skills
+```
+
+- If the response is `200`, the server is already running — don't start a new one, skip ahead to step 3.
+
+## 2. If it's not running, start it in the background
+
+Use the `notionmemory` command (registered on PATH at install time).
+
+```bash
+nohup notionmemory serve >/tmp/notionmemory-serve.log 2>&1 &
+```
+
+- Wait about 1 second, then re-run the `curl` from step 1 to confirm you get `200`. If it doesn't come up, check `/tmp/notionmemory-serve.log` and report the cause to the user.
+
+## 3. Open the browser
+
+```bash
+open http://localhost:8765
+```
+
+## 4. Tell the user
+
+- URL: `http://localhost:8765`
+- This screen is **settings-only** — it stores connections (Notion PAT, etc.), skill option defaults, and **per-template prompts** (how and in what tone to fill each template). The actual work of reading material and authoring/organizing it into Notion is done by the `templates` skill (`templates create-page` to create the structure → `templates block`/`templates image` to author content).
+- To stop the server: `pkill -f "notionmemory serve"`
+
+## Notes
+
+- The port is fixed at `8765`. The server keeps running in the background, so let the user know to stop it with the `pkill` command above once they're done.