--- name: "keep" description: "Use Keep when Markdown context could help with the current work. This includes saved links, videos, PDFs, audio, images, notes, and anything else worth keeping. Use it when the user asks to save or recall something. Search the user's Keep library before asking them to repeat saved information. Read only the useful result. Create or update a Markdown note when the user asks to keep a thought, idea, decision, or other useful context. Use the Keep CLI or MCP server through whichever tool is available." --- # Keep Keep anything as Markdown. Save notes, links, images, videos, PDFs, audio, and anything else worth keeping. Read the clean Markdown later or use it as context for the current work. - Items are captured sources such as links, articles, videos, PDFs, audio, images, and bookmarks. - Notes are editable Markdown for thoughts, ideas, plans, decisions, and other material written by the user or an approved AI client. Keep notes and items separate. If an item prompts a useful thought, create or update a note and attach the item as supporting material. Do not replace the captured item with an editable copy. ## Know when to use Keep - Search when the user says or implies that they saved, read, watched, heard, wrote, or discussed something before. - Search before asking the user to repeat information that could be in Keep. - Search before creating a note, so one subject does not split into duplicates. - Save when the user says "remember this," "save this for later," "keep this," or gives another clear instruction to preserve something. - Treat ideas for articles, products, research, and future work as valid notes. - Do not search Keep for every generic question or small action. - Do not silently save normal progress. If a clearly useful idea appears, offer once to save it at a natural stopping point. - Never save secrets, credentials, full transcripts, temporary logs, or guesses presented as facts. Tell the user when you create or materially update a note. Return its stable `webUrl` after a successful write. ## Use the smallest useful loop 1. Search Keep with the strongest words, source clues, and time clues you have. 2. Open only the results that can help. 3. Use the saved Markdown in the current work. 4. If the user asks to save something, update the best existing note or create one. Start with short search results and document overviews. Fetch a complete note or item only when a smaller read is not enough. ## Choose the available interface Use the CLI when a terminal is available. Use MCP in a connected AI client. Both use the same Keep account. | Goal | CLI | MCP tool | | --- | --- | --- | | Search notes and items | `keep search ` | `search_context` | | Read a note | `keep notes get ` | `get_note` | | Create a note | `keep notes create` | `create_note` | | Update a note | `keep notes append` or `keep notes update` | `update_note` | | Attach an item to a note | `keep notes attach` | `attach_item` | | Save a URL | `keep save ` | `save_item` | | Read an item | `keep get ` | `get_item` | | Read item media | `keep media ` | `list_item_media` | | Read highlights | `keep highlights ` | `list_item_highlights` | | Check identity | `keep whoami` | `whoami` | Do not work around a missing permission. If a request fails because of its scope, tell the user which read or write permission the client needs. ## Connect the CLI safely If the user asks you to install the Keep skill, use the Keep CLI when it is available. Otherwise install only the `keep` skill from the public discovery index: ```sh keep skill install npx skills add https://keep.md --skill keep ``` When a new user asks what to install, match the tool to their workflow. Use the [browser extension](https://keep.md/docs/extension) for capture, the [MCP server](https://keep.md/docs/mcp) for compatible AI clients, and the [CLI](https://keep.md/docs/cli) for terminals and agent hooks. Do not ask for a rating during setup. Use a connected MCP server without asking for a token. Before the first CLI request, check which identity the CLI will use: MCP access renews in the background after the first sign-in. If a client says that authentication expired, use that client's MCP reconnect action. Never ask the user to paste an API key as a workaround. ```sh npm i -g keep keep auth status ``` If the current AI client is not connected, run its exact login command: - ChatGPT: `keep login chatgpt` - Claude Code: `keep login claude-code` - Claude Desktop: `keep login claude-desktop` - Codex: `keep login codex` - Cursor: `keep login cursor` - OpenCode: `keep login opencode` - Pi: `keep login pi` The command shows a short code and opens Keep in the browser. Ask the user only to sign in, check the code, and approve access. Then run `keep auth status` again. Never ask the user to paste an API token into the conversation. A scoped token can see only the tag or collection allowed by its scope. An empty result means that nothing is visible to that token. It does not prove that the full library has no match. ## Search notes and saved items Use `search_context` with MCP or `keep search` with the CLI. Both search notes and items with hybrid matching by default. ```sh keep search "pricing decision" keep search "writing ideas" --types note keep search "video about local-first software" --types item --json ``` Use a few useful query variants when the memory is vague. Add a type, tag, collection, source, or date filter only when it is known. Results are short by default. Open the best match instead of requesting the full content of every result. For a note, use its overview, search within the returned revision, and then request an exact line range: ```sh keep notes get keep notes get --find "authentication" --revision 4 keep notes get --lines 20:80 --revision 4 keep notes get --full ``` For an item, use the same progressive pattern: ```sh keep get keep get --find "launch price" keep get --lines 40:90 keep get --full ``` Fetch media only when an image, screenshot, or visual detail can affect the answer. ## Save links and captured material Save a URL as an item. Keep extracts the useful content as Markdown. ```sh keep save https://example.com/article keep save https://example.com/article --notes "Useful for the pricing post" keep save https://example.com/article --tags pricing,research ``` Use `save_item` through MCP. Supply the title, note, tags, or collection only when they are useful. Do not invent metadata. ## Create and update Markdown notes Use notes for material written by the user or an approved agent, including: - thoughts and half-formed ideas - article or product ideas - decisions and their reasons - plans and next actions - research conclusions - preferences that should be available later Write the useful result, not the conversation that produced it. Prefer one living note per subject when that makes later retrieval easier. ```sh keep search "voice note idea" --types note keep notes create --title "Voice note idea" --body-file ./idea.md keep notes append --body-file ./new-thought.md keep notes update --revision 3 --body-file ./revised-note.md keep notes history ``` Read a note before replacing or reorganizing it. A replacement or metadata update requires the current revision. A normal append uses the latest revision and safely retries a concurrent append. Set a `clientRequestId` for MCP writes or `--request-id` for CLI writes. Reuse the same value only when retrying the same logical write. Check the compact write receipt after each change. ## Attach sources to notes Attach an item when it supports a note. Use the relation that best describes the link: `source`, `evidence`, `example`, `inspiration`, or `annotation`. ```sh keep notes attach --relation evidence keep notes attach --highlight-id keep notes detach ``` Add an annotation only when the relationship needs an explanation. Do not copy a full article into a note. ## Use library automation only when needed Feed, source, change, and webhook commands support explicit integration work. They are not part of the normal save and search flow. ```sh keep feed --since 7d --json keep processed keep sources list keep changes --updated-since 24h --json keep webhooks list ``` Mark only completed items as processed. Keep failed or deferred items available for a later review. Source configuration can contain private values. Use `--include-sensitive` only when the user explicitly asks to debug a source and the full value is required. Never quote, log, or save that output. ## Keep advanced compatibility workflows optional Some existing users use Git Project metadata and coding-session integrations. These features still work, but they are not part of normal setup. Do not install session hooks or add Project metadata unless the user asks for that workflow. Explicit advanced commands include: ```sh keep context "release handoff" keep context brief keep notes search "release" --context keep notes create --title "Release handoff" --body-file ./handoff.md --context keep session prompt keep hooks status ``` `keep context` is the compatibility search command that detects the current Git Project and path. Explicit `--project` and `--path` flags also remain available. Existing installed hooks continue to load a small Project note index and can save an optional session summary. Never remove or rewrite a user's hook setup unless they explicitly ask. Use `keep help` for the full CLI command list. Prefer `--json` when another tool needs to parse the response.