thrashr888/alchemy/alchemy-prime

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:

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.

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

Ingestion extracts, titles, chunks, and embeds automatically.

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

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

each claim by title so the user can verify.

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

Filling a notebook from a list

When the user hands you a list of things to cover, the work is finding the right page for each. Prefer each item's official page and check unsure URLs first (a quick search, or a HEAD request) instead of guessing paths. Read every result: a title like "Page Not Found", "Access Denied", or "Attention Required", or a charCount of a few hundred, is not content even when status says ready — delete it and try an alternate page, a support-center article, or a text source you write and label as your own summary. A two-segment path on an unfamiliar host can be mistaken for a git repo; if an add comes back with a clone error, re-add the URL with a #fragment. Add three to five at a time, then finish with an index note mapping each item the user named to its sources and gaps. Covers, tags, and notes on sources are yours to set (set_source_image, set_source_tags, set_source_note).

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.