MD-Memo Comprehensive Guide

• Opening a folder shows "Loaded workspace: N notes found".
• Only .md, .markdown and .txt files are scanned, up to 3 folder levels deep.
• Folders that start with ., plus node_modules, vendor, appdata, $recycle.bin, system volume information and windows, are skipped.
• The scan stops at 300 notes, 1500 files or 2.5 seconds, whichever comes first. In a very large folder, later notes may not be considered, and you are not told.
• For each note, MD-Memo keeps the first heading (or the file name) as the title and the first line as the snippet.
• 1.2 seconds after you stop typing, it takes keywords (2 or more characters, up to 8) from the current line and the 250 characters before the caret.
• It scores every other note and shows the top 2 as pills.

• Install from a zip: Download a zip from the Releases page and unpack it into any folder.
• Universal binary: Starting with the next release, the macOS build is a universal binary and supports both Apple Silicon and Intel Macs.
• No Mac to test on? Every push to the repository builds MD-Memo.app on GitHub's hosted macOS runners. Open the Actions tab (or trigger the CI workflow by hand with Run workflow), open the latest CI run, and download md-memo-macos-<commit-sha> from Artifacts. It is ad-hoc signed the same way, so the same first-launch step applies.
• Update check: Shortly after launch, MD-Memo asks GitHub whether a newer release exists (a single request to api.github.com; no note content is sent). If there is one, a small badge appears on the Help (?) button.

• What the AI reads: the selection; with no selection, the current line; on a blank line, the whole note. The chip on the bar tells you which one applies. In an empty note it says "No target text (free question)" and only your instruction is sent.
• Where the answer goes: below the last line of that text, with one blank line before and one after. The selection or line itself is never replaced. On a blank line, the answer takes that line.
• If the LLM is not set up: the bar does not open. A message says "LLM is not configured (Settings -> AI Models)" and the note is untouched. That is the case when the model or the URL is empty, or when a cloud service such as Gemini or OpenAI has no API key (local servers such as Ollama need no key).
• While it works: a placeholder such as [AI Generating: first 20 characters of your instruction...] sits in the note, and the answer replaces it when it arrives.
• If it fails: one line, [LLM error: ...], is left instead (the message is shortened to one line).
• Cancel: the task panel (Alt + T) lists the request. Cancel it there and the placeholder disappears, so the note is back as it was. The request itself is not stopped; an answer that arrives later is discarded.
• Japanese input: pressing Enter to confirm an IME conversion does not send the instruction. Press Enter once more to run it.
• Other ways in: the toolbar AI button, the right-click item "Ask AI..." and the palette item "Ask AI" open the same bar. It uses the built-in text LLM (Settings → AI Models).
• Answer fences: if the model wraps its entire answer in a single ```markdown / ```md fence, MD-Memo removes that fence before inserting. A real code answer (```python and the like), or an answer that merely contains fenced blocks among other text, is inserted exactly as returned.
• Old shortcut: if you had saved Ctrl + K for this bar, MD-Memo moves it to Ctrl + L once and shows a notice; the separate prompt dialog was merged into this bar.

• Suggestions come from a local LLM (Ollama / Gemma 4) or a cloud API. The setting is "Inline Autocomplete (Ghost Text)" in Settings → AI Models.
• The default wait before a suggestion appears is 500 ms. The settings screen allows 200–2000 ms, but the effective minimum is 300 ms.
• Click the "Predict" badge in the status bar to switch it on or off.

• In Settings → AI Models → Image OCR (Vision), set an image model such as Gemini and its API key.
• The switch "Automatically transcribe pasted images (Ctrl+V) using Gemini OCR" must be on (it is on by default).
• It works only when the clipboard holds an image and nothing else. If there is also text, the text is pasted.
• A local vision model (Ollama or LM Studio) can do OCR without an API key.
• To paste the image as an image, without OCR, use special paste (Ctrl + Shift + V), which saves it to assets.

What is converted (a built-in converter with no external dependency)

• Headings (h1 to h6), paragraphs, line breaks and horizontal rules
• Bold, italic, strikethrough, inline code, and fenced code blocks with a language
• Nested blockquotes, nested lists that keep their start number, and task-list checkboxes
• Links (with title) and images
• GFM tables with column alignment (a literal | inside a cell is escaped)
• The wrapper markup that Google Docs adds around copied content

Removed for safety: the contents of <script>, <style>, <iframe> and <svg>, javascript: and data: links, and data: images.

Saved image name: The extension follows the real image type (.png, .jpg, .gif or .webp). A name collision appends -2, -3, and so on.

Where ./assets/ lives: next to the note if it has been saved; otherwise the current workspace folder; and if there is no workspace either, the app data folder. In that last case the inserted link is an absolute file:/// link instead of a relative one.

If no HTML is available: If the paste event itself carries no HTML (some apps offer only plain text), Ctrl + Shift + V falls back to the async clipboard API. The embedded browser may then show its own one-time permission prompt. If that still yields nothing, plain text is pasted.

Toast: "Pasted as Markdown" for a converted paste, or "Image saved to assets" when an image-only clipboard was saved to ./assets/.

Ctrl + Shift + V is a fixed key and cannot be changed in Settings → Shortcuts. It used to open Preview to the Side; that command is now on Ctrl + Alt + V (macOS: Cmd + Option + V).

Each message is shown in the status bar for 6 to 9 seconds.

• Model: The default is gemini-3.5-transcribe (it used to be gemini-2.5-flash). Gemini models only: there is no offline or non-Gemini option.
• How it is called: Google's Gemini 3.5 Transcribe is called through the Interactions API (POST {base}/v1beta/interactions, header x-goog-api-key). Older models such as gemini-2.5-flash run through generateContent with a prompt.
• The live model cannot be used: gemini-3.5-transcribe-live is the streaming (Live API) variant and cannot be used for recorded audio. Choosing it shows an error that says so.
• Privacy: MD-Memo always sends store: false, so Google does not keep the recording or the transcript.
• Keys: If the API key and Base URL are empty, the Image OCR (Vision) settings are used. The config file also has voice.apiKey / voice.baseUrl keys, but the settings screen has no field for them.
• Japanese IME: The shortcut works even while the IME is on.
• Microphone permission: The permission prompt comes from the embedded browser (WebView2), not from the OS, and only the first time you record.
• macOS: A microphone usage description is built in, but behavior on macOS has not been fully verified yet.

• What happens to the result: It is set by "Open CLI execution results in a new tab" under Settings → Agent, in the "Commands (Run)" section. When it is on (the default), the selected text is replaced by the output and the result also opens in a new tab. When it is off, no new tab opens, and with no selection the whole note is replaced by the output.
• Empty output: If a command succeeds but prints nothing, the result tab shows "(no output)".
• Working directory: Commands run in MD-Memo's own working directory.
• The drop-down list: Your recent commands come first, then your own command snippets from agents.yaml, then the fixed filters (sort, sort -u, jq ., tr, wc -l, duckdb -box and more), then the built-in command snippets for your OS: Current date and time, Git status, Git diff summary, Git recent commits, List large files and List files. A snippet whose body has a placeholder such as ${selection} or $0 is left out. The same snippets can be inserted as [[ $ ... ]] tasks (see Auto Selector).

• What counts as a notation: A [[ ... ]] is a task only when it starts with @llm or $, so wiki links such as [[Note name]] are left alone. A {{ @name ... }} is an agent task when name is an agent's key or alias. Otherwise it is a skill, as before.
• One line per task: The whole notation must fit on one line. It may follow a list or quote mark, as in - [[ @llm ... ]] or > {{ @claude ... }}, and a rewrite keeps that mark. Notations inside code blocks or inline code are ignored.
• Agent tasks: The instruction reaches the agent as you wrote it. The standing instruction of the {{ }} notation (code blocks only) is not added. If nothing follows the name and that agent takes an instruction, the task ends with an error line (its text is Japanese in both UI languages).

What the result looks like

[[ @llm Translate this into English ]]
<!-- md-memo:res a1b2 -->
The translated text
<!-- /md-memo:res -->

• Result block: Two HTML comment lines with the answer between them. The short id (a1b2, usually 4 characters) is unique in the note. A run never changes your instruction line. The answer is trimmed, and no blank line is added inside. Nothing inside a result block is ever run, even if the answer contains a {{ }}.
• While it runs: A one-line marker, <!-- md-memo:run a1b2 -->, sits under the line, and the status bar shows the running-task badge.
• Where you see the comment lines: The editor shows them, and MD-Memo's own preview hides them (a viewer that passes HTML through does not display them either). You may delete them by hand. If you delete the marker while a task runs, the answer is added at the end of the note.
• Run again: Press Ctrl + Enter on the instruction line. The old result block (or a marker left behind by a crash) is replaced, so results do not pile up. While a task is running you get "This slot is already running."
• Cancel: Press Cancel on the task in the task panel (Alt + T), which also lists AI and command tasks. The marker disappears and the note is as it was. An AI request cannot be stopped at the provider, so MD-Memo forgets it and drops a late answer. A command or an agent is stopped. If you cancel a re-run, the old result does not come back.
• If it fails: The block holds one line, [LLM error: ...] or [agent name error: ...]. A command's block holds its output, its error output and an exit code N line.
• What the AI receives: Only your instruction. A task recorded through the ask bar sends the instruction and the text it was about. Its opening comment then reads ctx=above n=1 (n is the number of lines of that text), for example <!-- md-memo:res a1b2 ctx=above n=1 -->. On a re-run the same text is sent again: up to n non-blank lines directly above the instruction (looking past other task lines and result blocks; at most 80 lines or 8000 characters). A task you wrote by hand, made from a snippet or made by rewriting a line carries no such mark, so only what is inside its brackets is sent.

The check runs on your PC with fixed rules. It uses no network and calls no model. Each time you press the key, it reads one line, or your selection.

What Ctrl + Enter does, in this order

1. While a Japanese IME is converting text, the key is left alone. A held-down key runs only once.
2. The caret is inside a result block: nothing runs. The status bar shows "This is a result block. Write your instruction outside of it."
3. A task in the new notations is under the caret (with a selection: under the start of the selection, else the first one inside it): only that task runs. Several lines never run at once.
4. The caret is inside a classic {{ }} slot: it runs, and its result replaces it, as before.
5. The Auto selector is off, the line is blank, or the line holds a slot that the caret is not inside: the older rule applies. The next slot after the caret runs, and if there is none, the first slot in the note (with no slot at all, the status bar says so). Inside a fenced code block nothing happens.
6. Otherwise the target is your selection, or the current line. If the selection covers only part of a line or several lines, or the line is not clearly a request, the ask bar opens.
7. If the whole line looks like a request, MD-Memo decides where it goes:

With "Confirm before an auto-detected agent or command runs" switched off, an agent or a command runs right after the rewrite. An AI instruction always runs at once.

What counts as an instruction

• A request: a request phrase (Japanese endings such as ...してください, or English such as "please" and "can you"), a question with a question word or a question mark, or an English command word such as translate, summarize, fix, write or explain.
• Not a request (the ask bar opens): ordinary statements, headings, URLs, code, table rows, and a line longer than 240 characters.
• Where it goes: the AI for wording jobs (translate, summarize, proofread, rephrase, bullet points, tables, ideas, explanations). An agent for code and project jobs (implement, refactor, run the tests, commit, pull request, build, research, fix a bug, read an error log). A command for a line that starts with a known command such as git status, or a pipe such as git log | head. If nothing fits, the AI (a text-only answer is the safe side).
• You can say it yourself: a line that starts with @llm, @agent (a key or an alias) or $ goes where you said.
• Risky commands are never guessed: a line such as rm -rf build (delete, move, copy, sudo and the like) opens the ask bar. To run one, write [[ $ ... ]] yourself; the safety check then decides.

It can be wrong. The rules are fixed, so a polite request to a person, such as "Please share the materials in advance.", also looks like a request to the AI. When the check is not sure, it opens the ask bar and leaves your note alone until you send an instruction. A wrong guess for an agent or a command is easy to undo, because the line is rewritten first and waits (Ctrl + Z).

When something is not set up

Three ways in

• Type {{: The quick selector (the popup under the caret) lists the notations first, then the snippets, with a kind tag, a name and a one-line preview. The first nine rows have a number key. Enter, Tab or a number inserts one in place of the {{, and Esc closes it. Typing [[ opens nothing, so wiki links are not disturbed. The header of this popup is Japanese in every UI language.
• Command palette: Choose "Insert task snippet". It lists only the snippets, at the caret.
• A short word and Tab: At the start of a line or after a space, type an exact short word such as ;sum and press Tab. Any other Tab works as before. Nothing is expanded inside code.

Inserting never runs anything. The caret lands where your text goes; press Ctrl + Enter to run the task.

Built-in snippets

• One version per OS: A command that differs between systems is listed only in the version for yours: PowerShell on Windows, sh on macOS and Linux.
• Placeholders: ${selection} (the selected text), ${line} (the current line), ${date} (today, YYYY-MM-DD), ${agent} (your default agent) and $0 (where the caret lands). Write $$0 or $${ for a literal $0 or ${.
• The selection: ${selection} is filled when you insert from the command palette with text selected. Otherwise it is empty.
• Safe by design: A substituted value becomes one line and cannot break a [[ ]] or {{ }}. In a command, quotes, $, ;, | and other shell characters are removed from it. ${selection} and ${line} are cut at 2000 characters in a task and 300 in a command.

Your own snippets and aliases (in agents.yaml, see Customizing it in agents.yaml)

agents:
  my-agent:
    command: "my-cli"
    args: ["--prompt", "{instruction}"]
    aliases: ["mine", "m"]   # {{ @mine ... }} and {{ @m ... }} call my-agent

snippets:
  - id: "weekly"
    label: "Weekly review"
    kind: "llm"
    trigger: "/weekly"
    body: "Summarize this as a weekly review in 3 points: ${selection}"

• Aliases: aliases gives an agent extra names for {{ @name ... }}. Names are not case-sensitive, and a key wins over another agent's alias. Built in: claude and cc for claude-code, and antigravity and gemini for agy (hermes and codex have none). If your file defines claude-code or agy without an aliases line, these defaults still work, unless another agent already uses the name. A list you write is used as it is.
• Snippet fields: id, label, kind (llm, agent, command or text) and body. Optional: trigger, os (win, unix or any; for commands) and agent (the agent for a kind: agent snippet; the default agent if left out).
• Replace or add: A snippet with the id of a built-in one replaces it, and a new id adds one. A snippet with an unknown kind or an empty body is ignored.
• Trigger: No spaces, 2 to 30 characters. Capitals become lower case and full-width letters become half-width, and the word must match exactly. Built-in words start with ;, and /weekly works as well.
• When it applies: The {{ list, the palette list and short-word expansion read aliases and snippets when MD-Memo starts, so restart it after you edit them. Running {{ @alias ... }} and the command bar's drop-down list use the new file without a restart (the agent is looked up when the task runs, and the bar reads the file each time it opens).
• Command bar: Command snippets that need no placeholder, in the version for your OS, are also offered in the drop-down list of the command bar.

• Which one runs: A slot or task under the caret runs. On a plain line, the Auto selector takes over (it is on by default). When the Auto selector is off, or the line is blank, Ctrl + Enter uses the older rule: it runs the next slot after the caret, and if there is none, the first slot in the note. Inside a code block it does nothing.
• When none is found: The status bar shows "No slot found to run (place the cursor inside a {{ }}-style block)." for a few seconds. This appears only when the older rule applies and the note has no slot at all. Your note is not changed.
• If it is already running: The status bar shows "This slot is already running."
• Run button: A small button with a play icon. It appears next to a complete block that is not running yet, while the caret is inside it (hover text: "Run this slot (Ctrl+Enter)"; on macOS, Cmd+Enter). It also appears at the right end of a task line ([[ @llm ... ]], [[ $ ... ]], {{ @agent ... }}) that is not running. Clicking it does the same as pressing Ctrl + Enter.
• Quick selector: It also disappears on its own as soon as you keep typing normal words.
• Japanese input: If a Japanese IME turns your brackets into full-width characters (｛｛, 【？), they are converted back to half-width automatically.
• No accidental runs: Delimiters inside fenced code blocks, inline code, Markdown links and bare URLs are never treated as slots, so a {{ }} in a code sample does not fire.

When a command cannot be found, the slot is replaced by an error like the one below (the inserted text is Japanese in both UI languages). Fix the cause, put the caret back in that slot and press Ctrl + Enter to run it again.

{{ ⚠ エラー: エージェント起動失敗: ... (再試行: Ctrl+Enter) }}

• Working directory: The project root, found by walking up from the note until a folder that contains .md-memo/, agents.yaml (or agents.yml / agents.json), AGENTS.md, skills/ or .git/. If none is found, it is the note's own folder.
• .env: If the project root has a .env file, its variables are passed to the agent as environment variables (only that file is read).
• Tasks with a result below: The error is one line inside the result block, such as [claude-code error: ...]. Fix the cause and press Ctrl + Enter on the task line to run it again.

version: 2
default_agent: claude-code
timeout_seconds: 180
hover_peek_enabled: true
ghost_diff_duration_ms: 4000

# 1. The CLIs to call. {instruction} becomes your prompt, {file} the note's absolute path.
agents:
  claude-code:
    command: "claude"
    args: ["--file", "{file}", "--prompt", "{instruction}"]
    description: "Claude Code"
  my-agent:
    command: "my-cli"
    args: ["--prompt", "{instruction}"]
    description: "Our in-house agent"
    aliases: ["mine"]   # {{ @mine ... }} calls my-agent

# 2. Notation-to-agent mapping. Only what you list here stays active.
slot_profiles:
  - trigger_open: "{{"
    trigger_close: "}}"
    name: "code"
    agent: "claude-code"
    system_instruction: "Skip any preamble and output only a runnable code block."

  - trigger_open: "<<"
    trigger_close: ">>"
    name: "review"
    agent: "my-agent"
    system_instruction: "Review the changes and report your findings as bullet points."

# 3. Recipes run several steps in sequence.
recipes:
  - trigger_open: "[>>"
    trigger_close: "]"
    name: "deep-research-and-code"
    description: "Research -> risk critique -> implementation"
    steps:
      - "Research the current official specification and best practices"
      - "Point out migration risks and breaking changes"
      - "Generate the implementation based on the above"
    requires_approval_step: 2
    self_refine: true

• Placeholders: {instruction} is replaced by what you wrote in the slot, {file} by the current note's absolute path. If you never mention {instruction}, it is appended as the final argument.
• Choosing delimiters: pick trigger_open / trigger_close pairs that do not collide with ordinary Markdown syntax (#, *, -, and so on).
• How overriding works: writing slot_profiles or recipes replaces the defaults, so copy over any of the four built-in notations you still want. agents behaves differently: built-in agents you don't override are kept.
• self_refine: set it to true and the recipe's first step runs a draft → self-critique → revise loop (up to two passes) before moving on.
• aliases and snippets: aliases gives an agent extra names for {{ @name ... }}, and snippets adds your own ready-made tasks. Both are described under Auto Selector.
• Save the file as UTF-8 without a BOM.

• Hint line: While the panel is open it shows "Ctrl+1..3 Run now / Ctrl+Tab Move → Enter Confirm / Esc Close".
• A bare Enter: If you press Enter without first moving the selection with Ctrl + Tab, it is just a newline. No card runs, and the panel closes.
• It stays out of your typing: Bare digits, a bare Tab and Ctrl + Enter (the Auto selector's key, which also runs slots) are never taken by the panel.
• Auto-suggest: Besides Ctrl + J, the panel can appear on its own after a typing pause (on by default). To stop that, choose "Manual trigger only (suppress auto-popup, press Ctrl+J)" under Settings → Agent, in the "Suggestions (Quick Actions)" section. The delay before it appears is set there too.
• Changing the key: The shortcut itself can be reassigned under Settings → Shortcuts.
• Status bar badge: The "Action" badge shows the current mode, and each click cycles On → Manual → Off → On. It reads "Action: ON", "Action: Ctrl+J" (your configured key; Cmd+J on macOS) or "Action: OFF". It mirrors the two checkboxes under Settings → Agent → Suggestions (Quick Actions). While it is Off, Ctrl + J does nothing.
• Commands with no output: If a Run card (an sh card) command succeeds but prints nothing, > (出力なし) is inserted so you can tell it ran. This applies to Quick Actions only (the command bar shows "(no output)" in its result tab). The inserted text is Japanese in both the English and Japanese builds.
• Working directory: Run-card commands run in MD-Memo's own working directory. For example, git status -s returns the state of the folder where MD-Memo was started.

• By default, suggestions come from the built-in local rules only. Nothing from your note leaves your machine.
• Data is sent only if you enter an API key (it goes to OpenRouter's fixed endpoint) or change the Base URL to something other than the OpenRouter default (it goes to <Base URL>/predict). Then an external inference model (such as Jev) is queried.
• What is sent is an excerpt around the caret: up to 1,500 characters before it and 500 after (about 2,000 in total).
• The Base URL and Model Name fields come pre-filled with https://openrouter.ai/api/v1 and jev-latest, but while the API key is empty, nothing is sent.
• The safety check is the AST guardrail. The glossary explains these internal names.

• Files are copied in: The embedded browser does not expose the original path of a dropped file, so MD-Memo copies the file (up to 25 MB each) into ./assets/ next to the note and links to it relatively. The original location is not recorded.
• Link format: Spaces and parentheses in the link are percent-encoded (%20, %28, %29), so the Markdown stays valid. Ctrl + Click still opens the file normally.
• Links that can be opened: file:// links, absolute paths and note-relative paths. http(s): and mailto: links get their normal handling, and any other scheme is refused.
• Thumbnail: Its position is approximate.

• Choose the model, aspect ratio and resolution under "Image Generation (Mermaid & Infographics)" in Settings → AI Models.
• If the Gemini API key field is empty, the Vision key is used, then the Text key, in that order.
• The image is saved as assets/diagram_<number>.png, and ![Generated Diagram](assets/diagram_...png) is inserted. Save the note first to get a relative link.

It uses all available CPU cores (runtime.NumCPU()) to run a multithreaded, case-insensitive substring search (plain text, not a regular expression) across your historical scraps.

When an item is saved, one of these lines goes into the note, depending on the situation. These inserted lines are Japanese in both UI languages.

• Where it is saved: ./assets/YYYY-MM-DD-HHmmss.<extension>, next to the note. If there is no saved note, the workspace folder; if that is missing too, the app data folder (then the link is a file:// link). A name collision appends -2, -3.
• If saving fails too: Only when saving to assets fails as well, [Mobile Drop: <filename> の処理に失敗しました: <error>] is appended after that item's heading. The remaining items arrive normally.

• Up to 10 photos or files, 60 MB in total.
• Per-item limits: an image 20 MB, an audio file 25 MB, a text file 2 MB. Any other binary file is refused.

• Page layout: From top to bottom: the "Text from PC" card, the "Send tray" (each added item shows its name, size and a ✕ to remove it), camera / file picker (several files) / voice recording, and the text box. There is only one send button.
• "Text from PC": The text selected on the PC (or the clipboard text, if nothing was selected when the dialog opened) is shown with a one-tap copy button. It refreshes every 2 seconds and shows up to 64 KB.
• On the PC: The dialog shows it as "Sharing with phone: ...", truncated to 80 characters.

• It needs cloudflared. MD-Memo never downloads or installs it for you.
• If it is missing, the dialog shows the install command (Windows: winget install --id Cloudflare.cloudflared -e, macOS: brew install cloudflared) with a Copy button. Run it, then press the button again.
• While the tunnel is up, the transferred data passes through Cloudflare's servers.
• About the 90 seconds: The tunnel's 90 seconds is an idle timeout. Activity on the phone re-arms it. It is not a fixed "valid for 90 seconds after it is issued" limit.

• It exists only while the dialog is open. Opening it starts a small server on the PC. It stops after one submission, after 60 seconds without activity, or when you close or cancel the dialog. Opening the page on the phone, and any work on the phone (adding a file, recording, typing), all count as activity and reset that timer. So even a large batch does not trip the 60-second idle timeout.
• One submission per QR code. To send more, open the dialog again. The one-time token is checked before the request body is even read.
• Only someone with the code can send. The address contains a random one-time token, and a request without it is refused before anything is read.
• Photos and cloud models. If your vision model is a cloud service such as Gemini, photos are sent to that provider, exactly as when you paste an image with Ctrl + V. Even with no API key, the photo is not lost: it is saved as an image (see "Not set up, or it fails" above).
• Location is opt-in and tunnel-only. Only when connected through the Cloudflare tunnel (HTTPS), the phone may attach its location once, as a single one-time attempt. Only the first item's heading carries it: ## Mobile Drop [14:20:05] — <filename> (34.693, 135.502). Over plain LAN HTTP, location is never requested or attached.

On a plain LAN connection, recording a voice note opens the phone's own recorder app. To keep the session alive meanwhile, the phone page works as follows.

• Just before handing over to the camera, the file picker or the recorder app, it asks the PC to keep the session open up to 120 seconds longer. The PC session normally ends after 60 seconds without activity, and the server caps such a request at 180 seconds.
• When you come back to the page, it pings the PC.
• A picked file is copied into memory right away, because recorder apps may still be writing to it or may revoke access.
• While files are being read, the Send button waits.
• If sending fails, the page checks whether the PC session is still alive. If it is, the page resends once automatically, and if that fails too it shows "network error - please try again".
• If the PC session has ended, it shows "the connection to the PC is gone (closed or timed out) - reopen Mobile Drop on the PC and scan the QR code again".
• Recording directly in the page, without opening a recorder app, needs the HTTPS Cloudflare tunnel.

• Check that both devices are on the same Wi-Fi. Guest networks and some routers stop devices from talking to each other ("AP isolation"). A VPN on the PC or the phone can also get in the way.
• On Windows you may see a firewall prompt for MD-Memo the first time. Allow it on private networks.
• The QR code uses the address of the network adapter that carries your default route (virtual adapters such as WSL or Docker are skipped). If your phone is not on that network, use the Cloudflare connection above.

• It searches the commands and the notes in the workspace folder you have opened.
• The AI and command entries are "Ask AI", "Command Bar" (opens in the mode you used last), "Command Bar: Run a Command" and "Command Bar: AI Writes the Command". The last two have no key by default.
• "Insert task snippet" opens the list of ready-made LLM, agent and command tasks at the caret. Insert one, then press Ctrl + Enter to run it (see Auto Selector).
• Matching is a plain substring match, not a fuzzy search.
• Settings are not searchable. Open the settings screen with Ctrl + , (macOS: Cmd + ,).

API keys and other secrets

• With "Include API keys" off, the value of every setting whose name contains apikey, api_key, api-key, token, secret, password or passwd is emptied. A Git remote URL loses its user:password@ part.
• In agent definitions, values of the same kind under env: are emptied (comments and layout are kept). If that cannot be done safely, the file is included unchanged and a notice says it may still contain secrets; check before you share it.
• The number of emptied values is shown on the export result screen.

After you import

• Settings are merged into the running app and saved on the spot; theme, language, toolbar and shortcuts switch at once. Sections you did not tick stay as they are.
• Agent definitions and skills are written by MD-Memo itself. A package cannot be imported by editing config.json by hand, because the running app owns that file.
• Targets: the app-wide agent definitions go to %APPDATA%\md-memo\agents.yaml (macOS: ~/Library/Application Support/md-memo/agents.yaml), the project's to <project>/.md-memo/agents.yaml, skills to <project>/<folder>/<name>. An agents file that does not parse is skipped with a reason.
• Whatever would be overwritten is first copied to %APPDATA%\md-memo\pack_backups\<date-time>\ (macOS: ~/Library/Application Support/md-memo/pack_backups/). That folder is outside the project, so skill folders stay clean. The result screen shows the location.
• An older settings JSON (one file with all settings) can be imported too; it covers settings only and may contain API keys. Choosing "JSON (settings only)" as the export format writes the same kind of file.
• Some settings take effect after you restart MD-Memo; the result screen says so.

What "project" means

Starting from the folder of the open note (for an unsaved note: the opened folder, else the scraps folder), MD-Memo walks up to the first folder that contains .md-memo, agents.yaml, AGENTS.md, skills or .git. The home folder is never treated as a project (so global skills are never carried away). If no project is found, project items show "needs a project" and cannot be ticked.

Limits and safety

• A package can be up to 50 MB and 3000 files; one file up to 10 MB, 100 MB in total after unpacking. Settings are limited to 2 MB and one agents file to 1 MB. A skill over the limits is left out of the export with a notice.
• Not packaged from skill folders: .env and .env.* files (templates such as .env.example are included), .git, node_modules and __pycache__ folders, and symbolic links.
• Refused on import: unsafe paths (.., absolute paths, drive letters and the like), encrypted or damaged files, and packages from a newer version. Files not listed in the manifest are ignored.
• Skills are instructions an agent will follow, and agent definitions contain commands MD-Memo will run. Import only from sources you trust.

• jev verify [--mode strict|reviewed|unattended] <cmd> runs the same deterministic, always-on AST analysis that the GUI's run gate uses. It runs entirely locally, and nothing leaves your machine.
• Exit codes: 0 safe, 1 blocked, 2 warning (not known to be destructive, but the guard cannot vouch for it).
• Modes: The mode does not change the rules, only how seriously a finding is weighed, because who is watching differs. strict (the default) is for one-click paths where nobody reviews the command before it runs, reviewed assumes a person confirms before running, and unattended is for hooks.
• A command such as sudo rm -rf / is reported as blocked in every mode.

The agent reads this table from section (e) of skills/md-memo/references/setup-guide.md. You can also use it to check by hand.

• Variables MD-Memo itself reads: TYPESAFE_API_KEY (else JEV_API_KEY), OPENROUTER_API_KEY (CLI only), JEV_MODEL, JEV_API_URL, and PATH and similar.
• Variables it does not read: GEMINI_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, OLLAMA_HOST. MD-Memo's own LLM features read their keys and URLs only from config.json. These variables help only the external agent CLIs that read them.
• GUI apps do not inherit them: An app started from the Start menu or Finder does not inherit shell-profile variables. On macOS, MD-Memo repairs only PATH. For other variables, use the project's .env.
• Saving on Windows: Save a user environment variable with setx NAME "value", fully quit MD-Memo from the tray, and start it again.
• A good split: agent keys in <project root>/.env, MD-Memo's own keys in config.json, and OS environment variables only for additions to PATH and the Jev-related ones.