notionmemory 0.1.0__py3-none-any.whl

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/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/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/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.

notionmemory/agent_skills/templates/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: templates
+description: Use to look up, add, update, or author against a registered Notion template/database. If the user mentions their own Notion templates or DBs — like "add this to my reading list", "show application status", "register this template" — run the notionmemory CLI with this skill.
+---
+
+# templates
+
+Register an arbitrary Notion template, then CRUD it according to its schema. Unlike the DBs
+we built ourselves (calendar, second brain), **the code doesn't know the schema** — so every
+time, read the profile first and use the names in it verbatim.
+
+## 3-step protocol — follow the order
+
+```
+1. notionmemory templates list            # which templates are registered
+2. notionmemory templates show <slug>     # DB key · property names · types
+3. add / query / update using the exact names seen in step 2
+```
+
+**Don't skip step 2 and guess property names or options.** The value-enforcement layer
+blocks it anyway, but it costs an extra round trip. The rejection message includes the full
+allow-list, so read it and retry with the correction.
+
+If you also need to see options/relation targets, use `templates show <slug> --full`.
+
+## Query
+
+```
+notionmemory templates query <slug> <db>
+  --where "property operator value"     # multiple = AND
+  --search "free text"        # token AND × text-property OR
+  --sort "property asc|desc"
+  --limit N | --all
+  --fields "A,B,C" | --count | --json
+```
+
+Operators: `=` `!=` `>` `<` `>=` `<=` `contains` `!contains` `starts` `ends` `in` `empty` `!empty`
+
+- **If you use `--limit`, also give `--sort`.** Truncating without sorting gives the first N
+  rows in an arbitrary order — if the user asked for "the last 5", you get any 5. If output
+  was truncated, that fact appears on the last line.
+- **Pass dates as absolute dates, computed by you.** `--where "Due >= 2026-07-22"`. This CLI
+  does not interpret relative expressions.
+- `in` is the only surface for OR: `--where "Status in Todo,Doing"`.
+- Write relations by name: `--where "Company contains Acme"` — no need to look up the id.
+- The real row id in results is always the `id` key. If the target DB has a user-created
+  property literally named `id`/`url`, that value isn't dropped — it's moved to the
+  `"id (property)"` / `"url (property)"` key and preserved — if you requested a property
+  with that name, look for it there in the result.
+
+## Add · update · archive
+
+```
+notionmemory templates add <slug> <db> --set "property=value" [--set ...] [--notes "markdown"]
+notionmemory templates update <slug> <db> <row-id> --set "property=value"
+notionmemory templates archive <slug> <db> <row-id>
+```
+
+- `<row-id>` is the first column of `query` output. Don't try to update without querying first.
+- Values not in the option list are rejected. Attach `--allow-new-option` **only when the
+  user explicitly asked you to create a new option** — attaching it by default lets typo'd
+  options accumulate in the user's workspace.
+- There is no hard delete. `archive` moves to trash, which Notion can restore from within 30 days.
+
+## Register · refresh · remove
+
+```
+notionmemory templates register <page URL | page ID | name>   # re-register with --slug
+notionmemory templates refresh <slug>     # when the user changed the schema in Notion
+notionmemory templates refresh <slug> --refresh-notes  # regenerate schema + usage notes (body) too — slow
+notionmemory templates remove <slug>      # deletes only the profile, doesn't touch Notion
+```
+
+- Before registering, confirm that **the page has been shared with the integration**
+  (the most common failure): page top-right ••• → Connections → notionmemory.
+- If registering by name matches multiple candidates, it exits 2 with a list — ask the user
+  which one they mean.
+- If you hit a "property not found" error, the user renamed it in Notion. Run `refresh` first.
+
+**If you need a new DB** — notionmemory has **no DB-creation command (by design)**. Schema
+authoring is your job: call the Notion API directly via `NotionSession` to create a DB with
+the schema you want, then bring its URL in with `register` to CRUD it. Property types/options
+aren't boxed in by our CLI, so this gives full freedom.
+
+```python
+from notionmemory.core.notion_client import NotionSession
+NotionSession().request("POST", "/databases", json={
+    "parent": {"page_id": "<parent page id>"},
+    "title": [{"type": "text", "text": {"content": "<DB name>"}}],
+    "properties": { "Name": {"title": {}}, "Status": {"select": {"options": [...]}} }})
+# → bring the id/url from the response in with `notionmemory templates register <url>`
+```
+
+## Document editing — working with body content, no DB involved
+
+Templates aren't only databases. Pages whose content is **body text (paragraphs, headings,
+sections)** — CVs, portfolios, paper notes — get registered too. The `Structure:` list in
+`show <slug>` gives each page's heading outline and page-id.
+
+```
+templates read <slug> <page-id>                       # live body → markdown + block-id
+templates block add <page-id> [--after <block-id>] --markdown "..."   # append (free)
+templates page add <parent-page-id> --title "..." [--markdown "..."] # create subpage (free)
+templates block set <block-id> --markdown "..." [--yes]   # replace content (needs confirmation)
+templates block remove <block-id> [--yes]                 # delete = trash (needs confirmation)
+```
+
+If body content contains **backticks (code fences), quotes, or `$()`**, don't pass it via
+`--markdown "..."` straight to the shell — use `--markdown-file <path>` (or
+`--markdown-file -` for stdin) instead, to avoid the shell mistaking backticks for command
+substitution. The same applies to `prompt --set-file` and `new-prompt --prompt-file`
+(prompts commonly contain backticks). Writing the markdown to a file first and passing that
+path is the safe route.
+
+`read` output is `[<block-id>] <markdown>`; `[db: id]` is an embedded DB (→ handle it with
+`query`), `[page: id]` is a subpage (→ `read` it separately).
+
+**A row body is also a document.** Each row in a DB is itself a page. "Add a paper and write
+a summary" means: use `add` to create the row and get **the row id**, then use `block add`
+on that id to fill in the body — a combination of CRUD (row) + document editing (body).
+
+### Three rules
+
+1. **Never guess a block-id without `read`.** Before editing or deleting, always `read` the
+   page first to get live block-ids. The cached outline (`show`) only tells you the
+   structure — editing needs a live id.
+2. **`--yes` is not a shortcut.** Calling `block set`/`remove` without `--yes` returns a
+   preview (before → after) and exits 2. **Show that preview to the user and only re-run
+   with `--yes` after getting their approval.** Don't attach `--yes` on your own to skip
+   confirmation. Adds/creates are free to do without asking.
+3. **New items should imitate an existing sibling.** When creating a new subpage or row
+   body, first `read` an existing sibling to see its section structure, then write in the
+   same shape (Notion database templates can't be triggered via the API).
+
+`read` only the one page you're editing (not the whole tree). You already know the section
+structure from `show`'s cached outline.
+
+## Content authoring — filling in a template
+
+Each template can have an **attached prompt** (`templates show` displays it if present) —
+"fill this template like this, in this tone." Read it and follow it before authoring.
+
+- If you need a new structure, create and register a page with `templates create-page
+  --parent <id> --title <t> --slug <s>`, then attach a prompt with `templates prompt <s>
+  --set "<instructions/tone>"`.
+- Fill in the body with `templates block`/`templates page` (document editing);
+  **insert images with `templates image <page-id> <local-image> [--caption ...]`** (this
+  command handles the Notion upload).
+- Read files (PDF/code/HTML) and crop figures **with your own tools** — notionmemory does
+  not read. Just pass the path of the image file you produced to `templates image`.
+
+### Example — lecture notes / paper notes
+"Organize this folder of lecture material for me": (1) you read the PDFs/images in the
+folder yourself (reading and figure-cropping are your own tools' job — install PyMuPDF/
+poppler etc., or ask the user if missing; notionmemory only handles writing to Notion),
+(2) create a notes page with `templates page add <parent>`, (3) following that template's
+prompt, fill the body with `templates block` and insert cropped figures with `templates
+image`. Paper notes work the same way — structure/tone come from the template/prompt,
+reading/cropping is on you.
+
+`templates create-page` **registers** the page it creates as a template — use it only when
+creating a single, ongoing edit-target page (an instance). Notes stamped repeatedly from a
+blueprint should not be registered (registry pollution) — use `templates page add` for
+those instead.
+
+## Prompt-only templates (blueprints) — repeated generation
+
+A template with a prompt but no `page_id` is a **blueprint** — if `templates show` displays
+it as "prompt-only," that means it isn't one page, it's **a definition that stamps out a
+new page each time**.
+
+- Create: `templates new-prompt <slug> --name "Lecture Notes" --prompt "<instructions/tone>"`
+  (no location fixed yet).
+- **Using it**: "organize this lecture material (as lecture notes)" → read that template's
+  prompt, **agree with the user on a location**, create a new page with `templates page add
+  <parent>`, then fill it per the prompt using `templates block`/`image` (don't register
+  it). Repeat per subject — each note you make exists independently, and finding it later
+  is `library`'s job.
+- **Promoting it**: once it becomes "let's collect these notes into one DB," `templates
+  register` that DB **under the same slug** to turn it into an instance-DB (the prompt is
+  preserved), and from then on add one row per subject to that DB.
+- Prompt-only templates have no `query`/`add`/`refresh` (DB/structure operations) — those
+  commands are blocked with guidance.
+
+### Seed — lecture notes
+The retired note-capture skill is revived as this blueprint. Set it up once and reuse it
+per subject. Create it with `templates new-prompt lecture-notes --name "Lecture Notes"
+--prompt "<prompt below>"`, putting the full text below (distilled from the old
+note-capture rules) into the prompt verbatim. The tone lives inside the prompt too (a
+template = structure + attached prompt, tone included):
+
+```
+Read lecture, paper, or study material (PDF/image/slides) and turn it into a personal
+knowledge note that is still useful when you look at it again months later. Don't pretend
+to know information that isn't in the source. Write the notes in the SAME LANGUAGE as the
+source material.
+
+[authority/evidence] The source material is the only ground truth — don't add background
+knowledge, examples, quotes, numbers, or claims about the author's intent from your own
+memory. Restructure and paraphrase boldly for clarity, but preserve the source's
+conditions, exceptions, uncertainty, formulas, terminology, and comparison direction. If a
+reading is uncertain, don't guess to fill it in — omit it or mark it as uncertain.
+
+[terminology] When the source uses non-English technical vocabulary, annotate the original
+term with a brief gloss on first use — pair the source-language term with a short
+explanatory gloss the first time a key term or definition appears. Preserve casing and math
+notation. Don't invent forced translations — keep the original term/abbreviation if there's
+no natural equivalent.
+
+[structure] Infer the material type from the source and use the matching frame: lecture →
+scope → prerequisite concepts → key concepts and their relations → examples present in the
+source → limitations/points of confusion → synthesis; paper → citation → question →
+motivation → method → setup → results → limitations; experiment/assignment/project → goal
+→ setup → procedure → results → interpretation → next steps. Open with a 2–4 sentence
+overview stating the scope and the key question. Reorganize by concept/argument structure,
+not slide order. Include examples only when they're present in the source.
+
+[style] Describe the subject directly rather than reviewing the material itself — ban
+phrasing like "this lecture..." / "the slide says..." (write "X is defined as..." instead).
+Default to a plain, dispassionate textbook register — no addressing the reader, no
+exclamations. Each paragraph carries one role only — roughly 1–2 sentences and about 220
+characters at most — and breaks with a blank line when moving from definition → implication
+or condition → example.
+
+[format] Keep key definitions/theorems in short paragraphs, bold only the key terms (don't
+overuse a "Definition —" prefix or blockquotes). Use inline LaTeX for short expressions,
+standalone `$$...$$` for long derivations. Use tables for comparisons, numbered lists for
+procedures, bullets for parallel items, language-tagged code blocks for code, and checkboxes
+for to-dos.
+
+[figures] Crop important figures/diagrams and place each right after the paragraph that
+interprets it — don't dump them all at the end. Skip decorative logos, tables of contents,
+and pages that duplicate body text. Fold handwriting into the relevant sentence; omit it if
+illegible.
+
+[Notion syntax] Don't use `[[wikilinks]]` (connect concepts through prose instead). Headings
+go up to three levels (`#`–`###`), list nesting up to one level. No slash commands or HTML
+tags — write tables and code in markdown syntax.
+
+[title] Pull the title from the cover page or first title in the source, not from the
+filename or an invented summary. If a lecture number and topic are visible, use
+`Lecture N — original title`; never invent a missing number or title.
+```
+
+## Relationship to other skills — parallel sources
+
+Built-in skills (calendar / memory / git) and registered templates are **not competitors.**
+Users don't tell you where their data lives.
+
+1. Before answering, check the `notionmemory templates:` list injected at session start.
+2. If a template overlaps the request's domain, **query both and merge with sources
+   attached** — e.g. "2 from calendar · 1 from todo-list".
+3. **Never conclude "nothing" from checking only one source.** A silent omission is the only
+   real failure here.
+4. Narrow down only once the user names a specific template.
+
+**Writing is different.** If something overlaps a built-in like calendar — a schedule/
+deadline — and the user says "add it," you must pick one place. If `notionmemory calendar
+add` exits 2 with a list of candidates, ask the user, and if they say they want this
+template going forward, lock it in with `notionmemory calendar target
+template:<slug>/<db-key>`. To revert, use `notionmemory calendar target calendar`.
+
+## Limits — know these up front
+
+- **Page body is not searchable.** Notion API DB filters only look at properties. Content
+  put into `--notes` cannot be found by any condition. Guide the user to put anything they'll
+  need to search for into a property instead.
+- View/filter/sort settings and automatic creation of the relation's counterpart row are not
+  supported.
+
+## Delegating to a subagent
+
+Delegate **only when all three conditions are true.**
+
+1. **3 or more** sources to sweep
+2. What's needed is **synthesis**, not raw rows
+3. **Read-only**, with no follow-up edit expected
+
+(3) is the key one — a subagent returns only a summary, so **the row ids are lost**, which
+makes any subsequent `update`/`archive` impossible and forces the user to re-query.
+
+- Delegate: "What did I do this quarter?" (git + memory + 2 templates, synthesis, read-only)
+- Inline: "Show application status" (1 source, raw rows needed, likely follow-up edit)
+
+Reduce output first with `--fields`/`--count`/`--limit`. Delegation is a fallback for what's
+left after that — not the first line of defense.

notionmemory/app.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+from flask import Flask
+from notionmemory.core.config import Config
+from notionmemory.core.integrations import build_integrations
+from notionmemory.core.registry import Registry
+from notionmemory.core.skill_base import Skill
+from notionmemory.skills.calendar.skill import CalendarSkill
+from notionmemory.skills.git.skill import GitCaptureSkill
+from notionmemory.skills.library.skill import LibrarySkill
+from notionmemory.skills.memory.skill import MemorySkill
+from notionmemory.skills.templates.skill import TemplatesSkill
+from notionmemory.web.server import create_app
+
+
+def build_registry(config_path: str, skills: list[Skill] | None = None) -> Registry:
+    config = Config.load(config_path)
+    resolved = skills if skills is not None else [
+        MemorySkill(config), GitCaptureSkill(config),
+        CalendarSkill(config), TemplatesSkill(config), LibrarySkill(config)]
+    return Registry(resolved, build_integrations(config), config)
+
+
+def build_app(config_path: str, skills: list[Skill] | None = None) -> Flask:
+    return create_app(build_registry(config_path, skills))