alchemy git:20260831.67207aaB

Immutable. This exact content is served forever at /api/v1/blob/d4a2f9a7832d5534.

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

A connection error means the Alchemy app isn't running or its private local
credential needs refreshing — its MCP server lives inside the app at
`http://127.0.0.1:41414/mcp`. Ask the user to open Alchemy and use
Settings → Agents → Connect if needed. (No Alchemy at all? It's a free
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.