git:20260810.e4148e0 to git:20260831.67207aa

---

name: alchemy

description: Use when the user mentions Alchemy, their research notebooks, or wants sources (URLs, files, pasted text) collected, searched, or written up in a local notebook. Alchemy is their local-first research notebook app; this Python-backed skill exposes its notebooks, sources, notes, and hybrid search in the kernel.

---

# Alchemy — the user's local research notebook

Alchemy is a local-first NotebookLM-style app. A **notebook** holds **sources**

(fetched URLs, imported files, watched folders, pasted text — auto-chunked and

embedded on device) and **notes** (markdown the user or you write). Sources

can also be living Mac items the user connected (Apple Notes, Reminders

lists, Calendar windows, Stocks watchlists via `cider://` origins) — these

re-sync automatically. Everything runs on the user's machine; nothing you

store or search leaves it.

## Calling from the kernel

This is a Python-backed MCP integration: Alchemy's tools are async methods on

the auto-imported `alchemy` module. Discover before you call — the tool set

comes from the app, not this file:

```python

import alchemy

for tool in await alchemy.list_tools():

print(tool["name"], "-", tool["description"])

hits = await alchemy.search(notebookId="…", query="…")

```

Every tool is `async` — always `await`. Results arrive as parsed Python

(dicts/lists), no `json.loads` needed.

macOS app: https://github.com/thrashr888/alchemy/releases — this skill is

useless without it.)

## Workflow

1. `list_notebooks` to find the right notebook; `create_notebook` if the topic

deserves its own. Prefer reusing an existing notebook over creating

near-duplicates.

2. `add_source` for each URL, file path, or block of text worth keeping.

Ingestion extracts, titles, chunks, and embeds automatically.

3. `search` to ground claims before writing — hybrid vector + keyword

retrieval over the notebook's chunks. It runs on a local embedder and is

effectively free; make several small queries rather than one broad one.

When you don't know WHICH notebook holds something ("where did the user

save X?"), use `ask_everything` — the same retrieval across the entire

corpus, each passage tagged with its notebook. It returns raw passages;

synthesize the answer yourself.

4. Write findings with `create_note` (markdown). Cite which sources informed

each claim by title so the user can verify.

5. Mac-item write-back, when the user asks for it: `update_mac_note` replaces

the body of an Apple Notes source (writes to the real note, then

re-syncs); `add_reminder` appends to the Apple Reminders list behind a

Reminders source. Both work only on sources the user already connected —

find them in `list_sources` by a `url` starting with `cider://notes/note/`

or `cider://reminders/list/`.

## Sharp edges

- **Duplicates are rejected, not silently merged.** Adding the same URL or

identical content errors with the existing source's title. Treat that as

success and move on.

- **URL imports can fail soft.** Bot-walled or login-gated pages land as a

source with `status: "error"` and a reason. Report it; don't retry the same

URL blindly — try an alternate URL or paste the content as text instead.

- **`search` returns passages, not documents.** When you need full context,

call `get_source` with the passage's `sourceId`.

- **Notes are shared with the user.** `update_note` replaces the whole note —

`get_note` first, and preserve the user's edits. Never `delete_notebook` or

delete notes/sources the user didn't explicitly ask to remove.

- **Mac write-back edits the user's real Apple Notes/Reminders.**

`update_mac_note` replaces the entire note body — `get_source` first and

preserve their content; the first line is the note's title, keep it there.

Only write when the user asked for the change.

- The user sees changes live in the app as you work — no need to tell them to

refresh.