# VispNote User Guide VispNote is a local-first desktop note app for turning ideas into work. It stores your writing as markdown files in local vaults and gives you a block editor, page properties, connections, wiki links, block refs, embeds, tags, saved views, tasks, reminders, and optional AI. The core loop is deliberately small: 1. **Write** in local markdown with a fast block editor and one-step capture. 2. **Connect** with wiki links, backlinks, unlinked mentions, related notes, and search. 3. **Act** by reviewing focus, open loops, due items, and resurfaced notes in Today. Everything else — agenda boards, spatial thinking, research, long-form fiction, agents, the global graph — lives in optional packs you turn on when your work needs them. Reviewed against VispNote 0.2.6 on September 7, 2026. ## Your first five minutes 1. **Make a note.** Press `Cmd/Ctrl N`. The title is selected so you can name it immediately, then write your first blocks below it. 2. **Add a next step.** Type `/todo` to add a checkbox task. Keep it beside the thought it belongs to. 3. **Connect an idea.** Type `[[` and choose another note. Open Connections to see backlinks and unlinked mentions. 4. **Catch something quickly.** Press `Cmd/Ctrl Shift N`, type your thought, and choose **Save to Today** (or press `Cmd/Ctrl Enter`). More options lets you change the destination or use a template. 5. **Review Today.** Open **Today** in the sidebar. Review open loops and due reminders, then open a task’s source note for context. No optional pack is needed. ## Product Philosophy VispNote is built to reduce friction, not create a system you must maintain. The app is simple on purpose. A fresh install starts with one Personal vault, one welcome note, and no setup questionnaire. You should be able to start writing on day one and know what to do next. As your notes grow, VispNote gives you a small set of powerful structures: blocks, page properties, tags, links, block refs, embeds, and saved views. Use it to declutter thoughts, organize work, and turn notes into something useful without spending more time configuring the tool than doing the work. ## Install and Launch Download the installer for your operating system from the VispNote website or from the public GitHub releases page at `djkeshawa/visp-note`. Supported OS types: - Windows 10/11 x64: use the Windows x64 installer and launch VispNote from the Start menu or desktop shortcut. - macOS Apple Silicon: use the Apple Silicon DMG for M-series Macs. - macOS Intel: use the Intel DMG for older Intel Macs. - Linux AppImage x86_64: use AppImage for most x86_64 distros, including Fedora, Arch, openSUSE, Manjaro, and other non-Debian systems. - Debian-family Linux: use the DEB package for Debian, Ubuntu, Linux Mint, Pop!_OS, Zorin OS, Kali, and related systems. On first launch, VispNote creates one local Personal vault with a single welcome note. Nothing else is configured for you, and short contextual tips point at the next useful step until you dismiss them. ## Updates and Releases The VispNote website includes a Latest Updates section that shows the newest public GitHub release and links to the current installer assets. Use it when you want to confirm the newest version before downloading. The current public release is **VispNote v0.2.6**, published on **September 6, 2026**. It includes desktop builds for Windows x64, macOS Apple Silicon, macOS Intel, Linux AppImage x86_64, and Debian-family Linux through a DEB package. To update VispNote: 1. Open the website Latest Updates or Download section, or open the GitHub releases page. 2. Download the installer or package for your operating system. 3. Install the new version over the existing app when your operating system supports that flow. 4. Launch VispNote and continue using your existing vaults. Settings → About shows the installed version and checks GitHub Releases for updates. Windows builds can download an update in place. macOS builds are unsigned and updates are manual: download the matching DMG from GitHub Releases. Linux DEB installs also update manually. Your notes live in local vault folders as markdown files, so updating the desktop app should not require moving your notes. Keep normal backups of important vault folders before major system changes. ## The Default Workspace The sidebar starts with only what most notes need: - **All notes** — every note in the active vault. - **Pinned** — notes you pinned from the editor toolbar. - **Today** — open tasks, reminders, and notes to revisit; always available. - **Views** — saved views over your notes, tasks, and dates, when the Views pack is enabled. - **More** — destinations from enabled packs, such as Thinking Board and Workflow. Quick capture is also available from the sidebar or its keyboard shortcut. - **Tags** — every tag in the vault with counts. - **Recently deleted** — notes and boards still inside the 30-day recovery window. The footer shows local state at a glance: Saved, Saving, or Conflict, the active vault folder, the last successful backup, and a one-click Vault Health check. The note list sits between the sidebar and the editor. It groups notes by day (Today, Yesterday, Earlier this week), filters as you type, and shows tags and a preview line for each note. ## Optional Packs Specialist capability lives in packs so it never becomes setup work. Turn packs on in **Settings → Advanced → Optional packs**. | Pack | What it adds | |---|---| | Planning | Agenda and Workflow views for dated or structured work. | | Thinking Board | Freeform boards for arranging notes, stickies, sketches, and connections. | | Research | Zotero-assisted source reading and synthesis. | | Writer | Novel structure, scenes, chapters, and long-form planning. | | Agents | MCP and local llm-memory integrations. | | Views | Saved tables, boards, calendars, and lists over your notes. | | Labs | Global graph and experimental specialist tools. | Packs are also revealed by your own notes. If a vault already contains canvases, dated todos, workflow markers, novelist tags, or configured integrations, the matching pack appears without being switched on. Activation never changes note content, and turning a pack off hides its views rather than deleting anything. ## Vaults and Local Data A vault is a local folder containing notes, tags, metadata, boards, workflow settings, writer settings, and indexes. Treat a vault as one focused context. Good vault examples: - Personal: journal, errands, reading, ideas. - Work: projects, meetings, decisions, research. - Research: sources, claims, experiments, summaries. - Novel: acts, chapters, scenes, characters, locations, plot threads, research, revision notes. Use fewer vaults than folders. Split vaults only when the context, privacy, or project lifecycle is different enough that you do not want notes mixed. To create a vault: 1. Open the vault switcher in the sidebar, or open Settings → Data & Privacy. 2. Choose to create a new vault. 3. Enter a name. 4. Choose a normal Notes vault, or a Writer vault when the Writer pack is enabled. You can rename vaults from the vault switcher. Vault deletion is available in Settings under Data & Privacy, but VispNote requires another vault to exist first and asks you to type the current vault name before deleting the folder. With the Writer pack enabled, Settings can also convert the active vault into a long-form writing workspace, which adds the Novelist panel, story structure helpers, and the writing workflow for that vault. VispNote stores notes as markdown files under `~/VispNote`. Older legacy data folders may be used only as compatibility fallbacks when `~/VispNote` does not exist. Attachments live in the vault's `attachments/` folder, boards are stored as JSON files inside `.canvases`, and the search index lives beside the vault data. Your core writing remains readable outside the app. ## Writing Notes VispNote uses a block editor. A note can contain paragraphs, headings, bullets, numbered lists, todos, quotes, code blocks, tables, dividers, page embeds, block embeds, block refs, plot-point blocks, attachments, and embedded boards. A productive writing loop: 1. Start with a quick note and write every idea as a separate block. 2. Use headings only after the note has enough material to need sections. 3. Turn action items into todo blocks or workflow blocks. 4. Use wiki links for ideas that deserve their own page. 5. Use refs and embeds for reusable details that should stay connected to their source. 6. Review connections, search, and Today later to discover related notes. Common writing actions: - Create a note from the sidebar or keyboard shortcut. - Edit the note title at the top. - Add tags and properties from the note header. - Pin important notes so they appear first in supported sort modes. - Duplicate, export, or delete notes from the editor toolbar, or right-click a note in the note list to rename, duplicate, or delete it. - Move, duplicate, indent, outdent, delete, and zoom into blocks with shortcuts. Page properties: - Leading lines in the form `key:: value` become editable page properties. - Use properties for structured metadata such as `status:: DOING`, `type:: meeting`, `source::`, `order:: 120`, `act:: [[Act 1]]`, or `chapter:: [[Chapter 1]]`. - The `status::` property drives the note's workflow status when workflow states are enabled. ## Slash Commands Type `/` in a block to open commands. Useful commands include: - `/h1`, `/h2`, and `/h3` for section titles. - `/paragraph` for plain text. - `/bullet` for list items and `/ordered` for numbered lists. - `/todo` for checkbox tasks. - `/quote` for block quotes. - `/code` for code blocks. - `/table` for markdown tables. - `/divider` for horizontal rules. - `/link` for wiki links. - `/tag` for tags. - `/label` for colored attention labels on a block. - `/date` for today's date. - `/reminder` for an `@remind` directive. - `/canvas` to attach a board, when the Thinking Board pack is on. - Workflow commands such as `/TODO` or `/DOING`, when workflow states are available. - `/plot points` for scene beats and linked context, in a Writer vault. - `/ai improve`, `/ai format`, `/ai summary`, `/ai concise`, `/ai fix`, and `/ai write` when assistance is enabled. The menu only lists what the active vault can actually do, so board, workflow, writer, and AI commands appear once those capabilities are available. Block operations: - Right-click a block or use the grip menu to copy a block ref, copy an embed, copy/cut/paste the block, zoom into it, indent/outdent, move it, duplicate it, add a label, convert it to another block type, assign a workflow marker, or delete it. - Drag-select multiple blocks to copy, cut, delete, or apply AI actions to the selection. - Use `((block-id))` to reference a specific block. - Use `{{embed [[Page Title]]}}` to embed a page preview. - Use `{{embed ((block-id))}}` to embed a block. - Use `{{canvas canvas-id}}` to embed a board in a note. Formatting and tables: - The selection toolbar supports bold, italic, underline, strikethrough, inline code, highlights, text colors, smaller/larger text, delete, undo, redo, and AI actions. - Code blocks include a language selector for plain text, JavaScript, TypeScript, JSX, TSX, HTML, CSS, JSON, Markdown, Bash, Python, and SQL. - Type directly into a rendered table, and use `/table` to insert one you can fill in immediately. - Pasted HTML tables, tab-delimited text, and markdown tables are converted into markdown table blocks when possible. - When spell check is enabled, VispNote underlines possible misspellings in rendered blocks. Open the suggestion menu to replace the word or add it to the local ignore list. ## Attachments and Export Paste or drag files straight into a note. Images render inline; PDFs, text and Markdown files, CSV, RTF, Word, Excel, PowerPoint, OpenDocument files, and common audio formats appear as compact Open chips. Every attachment is copied into the vault's `attachments/` folder, so a note and its files travel together. Export the open note from the editor's More menu or the palette: - **Export as Markdown** for a plain `.md` file. - **Export as HTML** for a self-contained page. - **Export as PDF** for sharing or printing. Each export opens the normal operating-system save dialog, and nothing is uploaded. To bring existing writing in, use **Settings → Data & Privacy → Import Markdown** and choose files or a folder. VispNote previews the notes, title collisions, links, and safe relative attachments before anything is added. ## Tags, Links, Connections, and Search Tags are best used as living contexts, not rigid folders. A note can be both `#research` and `#product`, which lets it appear in both views without duplication. Use tags to self-organize notes: - Start with broad tags such as `#work`, `#journal`, `#research`, `#ideas`, or `#reading`. - Split a tag when it becomes crowded. - Merge a tag back into a broader tag when it has only one or two notes for a long time. - Use default note tags for recurring contexts. - Create tags from the sidebar, from the note header, or while typing in a note. Use tags for categories and wiki links for relationships. For example, tag a note `#reading`, then link it to `[[Product strategy]]` when it changes how you think about that topic. Type `[[` to create a wiki link to another note. VispNote suggests existing notes while you type and can create a linked note when the target does not exist. Renaming a note updates wiki links that point to the old title. The **Connections** rail beside the editor gathers everything that relates to the open note in one place: - **Suggested links** — proposed connections you can Accept or Ignore. Nothing is written until you accept. - **Backlinks** — notes that already link here, with a snippet of the sentence that does it. - **Unlinked mentions** — notes that name this one without linking. Use Link to turn a mention into a real connection. - **Related** — notes that read as relevant without being linked at all. Use the note-list filter to find text across the active vault. Search uses a local SQLite full-text index over note titles, body text, and tags, with search-as-you-type prefix matching. Results show highlighted snippets and respect the active view, tag, workflow, or writer filter. With the Labs pack enabled, Graph view shows clusters, linked notes, isolated notes, and tag-colored groups built from wiki links. It can use force, timeline, or cluster style; show labels; use tag colors; size nodes by content; tune link distance and repulsion; reset the layout; and export the visible graph as SVG. In a Writer vault the graph can use focused filters such as all novelist notes, act structure, characters plus scenes, plot threads plus scenes, or research plus scenes. Suggested review rhythm: - Daily capture: create quick notes without perfect names. - Weekly cleanup: add tags, link important ideas, and pin active notes. - Project review: open the tag, the Connections rail, and Today to see what is connected. - Archive by neglect: do not maintain tags that no longer help retrieval. ## What to Use When VispNote gives you several ways to organize work. Use the lightest structure that helps you act or find something later. - Use tags for broad categories and recurring contexts, such as `#research`, `#journal`, `#product`, or `#reading`. - Use wiki links for relationships between specific ideas, projects, people, sources, or story elements. - Use page properties for structured metadata that should stay visible at the top of a note, such as `status::`, `type::`, `source::`, `order::`, `act::`, or `chapter::`. - Use todo blocks for simple done/not-done tasks. - Use workflow states when an item moves through a lifecycle, such as `TODO` → `DOING` → `DONE` or `DRAFT` → `REVISE` → `FINAL`. - Use reminders only for date-sensitive work. - Use saved views when you want the same question answered every time you open the app. - Use boards when the relationship is spatial, visual, or easier to understand as a diagram. - Use assistance for review, summarizing, formatting, or drafting after you decide what context is safe to send to the selected provider. If two structures feel possible, choose the one that changes what you will do next. A reading note probably needs a tag; a project decision usually deserves a wiki link; a deliverable that must be tracked belongs in a workflow state. ## The Palette The palette is one surface with two entry points: - `Cmd/Ctrl P` opens it notes-first, for jumping to a note by name. - `Cmd/Ctrl K` opens it with notes and actions together, for running something by name. Use Arrow Up / Arrow Down to move through results, Enter to run the highlighted item, and Esc to close it. When nothing matches an existing note, the palette offers to create one with the text you typed. The palette can create a note, open Quick Capture, open or create the daily note, open the reference pane, open Ask AI, navigate to Today / Views / Agenda / Graph / boards, open Settings or Vault Health, export or import a backup, rebuild the search index, export the open note as Markdown, HTML, or PDF, rename, duplicate, tag, link, or delete notes, add a todo or reminder to a note, set a workflow status, switch vaults, restore something from Recently deleted, and run enabled integrations. Two things make it more than a launcher: - **Plain-language requests** are interpreted into one or more real app actions and shown as an interpreted request before they run. - **Previews** appear for anything that writes, deletes, or leaves the app. VispNote states what it will change and which notes are affected, and waits for you to confirm. Only actions the active vault supports are listed, so the palette never offers something a disabled pack cannot do. ## Reference Pane Press `Cmd/Ctrl Shift R`, or run **Open reference pane**, to keep one note visible beside the editor without opening a second window. Use it to draft against a source, copy details from a meeting note, or keep a checklist in view while you work. Press the same shortcut again to close it. ## Views Views are saved questions about your vault. A view keeps its own scope, conditions, sorting, and layout, so a review you set up once is one click away every time. Each view starts from a scope — all notes, particular tags, or one note and its links — then narrows with conditions such as status, dates, or task state. Choose the layout that fits the question: - **List** for a fast reading order. - **Table** for dense scanning, with columns you choose. - **Board** for grouped columns you can drag between. - **Calendar** for dated work, with planning directly in the grid. - **Cards** for a visual set you can arrange by hand. - **Timeline** for date-ordered sequence. Create, rename, duplicate, and delete views from the Views panel; a vault can keep up to 24. New installs keep the Views pack off. Enable it in Settings → Advanced → Optional packs to use the starter views: Recent notes, Open tasks, Deferred tasks, and Due reminders. Existing vaults keep their saved views. ## Today Today is the review surface. Open it directly from the sidebar or the palette, and it adapts to what is actually waiting: - A stat line for open loops, overdue items, and notes written. - **Today actions** for adding a quick task without leaving the review. - **Agenda** for what is scheduled, with Plan to move an item to another day. - **Open loops** for unchecked tasks across the vault. - **Reminders** grouped into overdue and due today. - **Worth revisiting** for notes that deserve another look, which you can dismiss or snooze. - **Notes today** grouped by day, with previews and collapsed older days. Settings → Writing controls the default range, the grouping date source, heading format, previews, whether open loops and reminders appear, and whether older day groups start collapsed. With assistance enabled, Today can also generate an **AI daily recap** that summarizes the day and links the notes it used. ## Todos, Agenda, and Reminders Create todo blocks for simple tasks with `/todo` or markdown checkboxes. Open loops appear in Today and in saved views, and you can toggle them from either place. With the Planning pack enabled, the **Agenda** panel gives dated todos and reminders a calendar. Move through months and days, create a dated item, open its source note, toggle it, snooze it, or plan it onto another day. Use reminders with: ```text @remind YYYY-MM-DD @remind YYYY-MM-DD HH:MM ``` The reminder button near the top right opens the reminder center, where reminders are grouped as due, upcoming, or snoozed. Due reminders can also appear as a card or banner, depending on Settings. Snooze duration, overdue-on-launch behavior, and reminder sound are configurable. Use todos for simple binary tasks. Use workflow states when an item has a lifecycle. Use reminders only for time-sensitive work. ## Workflows and Custom States Workflow states turn notes and blocks into trackable work items. A note can carry a status through the `status::` page property, and individual blocks can carry workflow markers such as `TODO` or `WAIT`. This keeps planning connected to the note that explains the work. Workflow lives in the Planning pack, and also appears on its own in any vault that already has workflow data. The default states are: - `TODO` - `DOING` - `DONE` - `LATER` - `NOW` - `WAIT` - `CANCELLED` States whose next state is empty are treated as closed. You can review workflow items in the Workflow panel as Kanban, Table, or List. How to use the default states: - `TODO`: accepted but not started. - `DOING`: one of the few active items. - `WAIT`: blocked by another person, decision, or external event. - `LATER`: useful but not active. - `DONE`: completed. - `CANCELLED`: intentionally closed without completion. Custom state examples: - Writing: `IDEA` → `OUTLINE` → `DRAFT` → `REVISE` → `FINAL` - Research: `CAPTURE` → `READING` → `EXTRACT` → `SYNTHESIZE` - Product: `TRIAGE` → `DESIGN` → `BUILD` → `VERIFY` → `SHIP` Best practice: keep workflow states few and meaningful. If a state does not change what you do next, it is probably a tag, not a workflow state. Workflow panel: - Use Kanban mode to drag notes or workflow cards across columns. - Use Table mode to scan status, note title, preview text, tags, and the state selector in one dense view. - Use List mode for a simpler grouped reading view. - Archive a note from the workflow without deleting it, then restore it from the Archived view. - In Table mode, add or remove note tags without opening the note. Block workflow markers: - Use slash commands such as `/TODO` or the block context menu to add a marker to a block. - Clicking a workflow pill cycles it to the next state or clears it when the state is closed. ## Writer Pack and Novelist Mode Enable the **Writer** pack, then switch a vault into writing mode, and VispNote becomes a workspace for long-form fiction. It adds starter notes, novel-specific tags, a structured Novelist panel, scene plot-point blocks, writing-focused workflow states, story status analytics, and an optional novelist AI configuration. Existing novelist vaults are detected automatically. Novelist mode adds: - Structure tags: `novel-act`, `novel-chapter`, `novel-scene` - Supporting tags: `novel-character`, `novel-location`, `novel-plot`, `novel-research`, `novel-revision` - Starter notes: Act 1, Chapter 1, Scene 1, Characters, Locations, Plot Threads, Research, Revision Notes - Writing workflow: `IDEA`, `OUTLINE`, `DRAFT`, `REVISE`, `FINAL` - Story properties such as `status::`, `order::`, `act:: [[Act 1]]`, `chapter:: [[Chapter 1]]`, `pov::`, `setting::`, and `purpose::` - Plot Points blocks using `::: plot-points` with beat lines, linked context pages, and AI actions How to write a novel in VispNote: 1. Enable the Writer pack, then create a writing vault or switch an existing one into writing mode. 2. Create acts for large story movements. 3. Create chapters for reading units. 4. Create scenes for draftable moments. 5. Use `order::` to keep acts, chapters, and scenes in a stable sequence. 6. Link chapters to acts and scenes to chapters with properties and section links. 7. Keep characters, locations, plot threads, research, and revision notes as supporting notes. 8. Move each scene through `IDEA`, `OUTLINE`, `DRAFT`, `REVISE`, and `FINAL`. 9. Use a board when the story needs a spatial map, timeline, or relationship diagram. Novelist panel: - The Plan tab shows the story as Acts, Chapters, and Scenes. It can create acts, chapters, scenes, and supporting notes from templates; link existing chapters or scenes; set order values; rename notes; attach unlinked chapters or scenes to a parent; create missing parents; and convert a chapter to a scene when needed. - The Status tab summarizes draft word count, average words per scene, unlinked items, scene completion, word count by act, workflow status counts, and a character appearance heat map. Character aliases can come from `name::` or `names::` properties as well as the note title. - The AI Config tab stores novelist-specific writing preferences for the active vault, including prompt preset, model collection, model override, target word limit, instructions, additional context, included components, system/user message templates, temperature, max tokens, and custom prompts. Plot Points blocks: - Use `/plot points` in a scene to create a beat list. - Add one beat per line, link context pages such as characters or locations, then use the block's AI buttons to summarize the beats, improve the plan, or write scene prose. - AI writing from a Plot Points block previews generated text before it is inserted or appended. Existing manuscripts can be brought in from Settings → Data & Privacy → Import novel files, which analyzes the text and previews the generated notes before applying them. Best practice: draft scenes in scene notes instead of one huge manuscript note. Link them into chapters and acts. This keeps revision manageable and lets the Workflow and Novelist panels show exactly where each part of the story stands. ## Thinking Board Boards are freeform visual spaces in a vault, available with the **Thinking Board** pack. Use them for idea maps, diagrams, project flows, visual research, character relationships, story timelines, and planning that benefits from spatial layout. Board tools include select, pen, text, sticky note, rectangle, ellipse, line, arrow, diamond, triangle, and eraser. Live note cards let you place real notes on the board, arrange and connect them, and double-click to open one. Board actions include: - Create, open, rename, preview, or delete boards from the Thinking Board dashboard. - Attach a board to a note with `/canvas`, then open the embedded board from the note. - Adjust stroke, fill, and stroke width. - Select one or more objects, move them, resize them, copy, cut, paste, delete, align, distribute, zoom, and fit to screen. - Double-click text or sticky objects to edit their text. - Use mouse wheel or toolbar buttons to zoom, middle mouse or space-drag to pan, and undo/redo to step through edits. Deleted boards appear in Recently deleted with deleted notes. Restore them from there if you deleted the wrong board, or delete them permanently when you are sure. Board data is saved inside the active vault as JSON. Keep factual writing in notes and visual relationships on boards. ## Research with Zotero Enable the Research pack in Settings → Advanced → Optional packs, and keep Zotero Desktop open with its local API enabled. When the Zotero reader integration is available, use the palette to **List Zotero papers**, **Search Zotero**, **Read Zotero item**, or **Create Zotero source note**. Source notes keep the paper’s context beside your own writing. With assistance enabled, include “Zotero” or “paper” in your request, such as “Summarize this paper from Zotero” or “Use the Zotero paper to improve this note.” Review proposed note changes before applying them. If full text is unavailable, the summary uses the available metadata and abstract. If Zotero cannot be reached, check that the desktop app is running and local API access is enabled. Local source access and AI processing are separate: a hosted AI provider receives the context used for your request. ## Optional Assistance VispNote works without AI. Assistance is off until you enable it in **Settings → Assistance**, and the everyday decision is only where it runs: - **Local** keeps every request on this machine through Ollama. - **Hosted** uses a provider you configure. Provider URLs, API keys, and model IDs stay under Advanced provider settings. Supported providers are Ollama, OpenRouter, OpenAI, Anthropic, Gemini, and a custom OpenAI-compatible endpoint. Hosted provider API keys are stored locally in VispNote settings. Turn on PII reduction before using hosted or custom providers if you want VispNote to redact common identifiers before requests leave your device. This is a safety aid, not a guarantee; avoid sending sensitive notes to hosted models unless you have reviewed the selected provider's terms and your own risk. Assistance is preview-first: it proposes, you decide. Generated text is shown before it is applied, results are saved as ordinary Markdown, and the notes used as context are listed as clickable sources. Turn the open note into something else without leaving it: - **Brief** — a compact summary of what matters. - **Outline** — a structured map of the note. - **Decisions** — explicit decisions separated from open questions. - **Next actions** — actionable follow-ups as checkboxes. Each result is saved as a new note that links back to its source. Good AI uses: - Improve writing while preserving meaning and structure. - Format a messy page into cleaner markdown. - Summarize a long note before review. - Make a page concise. - Fix spelling. - Draft new text in a section, then review before applying. - Create a new page from an Ask AI request. - Format and add useful wiki links to the current page. - Generate a daily recap in Today. - In a Writer vault, continue a scene or extract character facts. Ask AI can answer questions about the active vault, cite source notes, create pages, link notes, and run page actions such as improve, format, summarize, make concise, or fix spelling. Long-running requests can be stopped or sent to the background. With Ollama and the `nomic-embed-text` embedding model installed, VispNote can use semantic retrieval. If embeddings are unavailable, it falls back to local keyword search and recent-note context. Hosted providers use local keyword and recent-note context; your note index remains local. Configure the provider, API key, host or base URL, chat model, embedding model for Ollama, retrieval behavior, and token limits in Settings. Default chat models include `gemma3` for Ollama, `openai/gpt-4o-mini` for OpenRouter, `gpt-4o-mini` for OpenAI, `claude-sonnet-4-5-20250929` for Anthropic, and `gemini-2.5-flash` for Gemini. If assistance is disabled, all AI features stay unavailable and the rest of the app continues to work normally. ## Agents: MCP and Local Memory The **Agents** pack connects VispNote to tools that run on your own machine. VispNote ships a local MCP (Model Context Protocol) server, so agents such as Claude Code can use your vaults as a knowledge base. It reads the same vaults and index as the app, is read-only by default, and never listens on the network — it speaks MCP over stdio to the process that launched it. ```bash node bin/vispnote-mcp.js # read-only (default) node bin/vispnote-mcp.js --allow-writes # also enables create_note / append_to_note ``` Tools are `list_vaults`, `search_notes`, `get_note`, `get_backlinks`, `get_unlinked_mentions`, `list_notes_by_tag`, and — only with `--allow-writes` — `create_note` and `append_to_note`. If an agent appends to a note you have open with unsaved changes, the next autosave reports a conflict and asks which version to keep, so prefer agent writes to notes you are not actively editing. VispNote can also pair with a local [llm-memory](https://github.com/djkeshawa/llm-memory) server so your notes and your agents share one memory. Configure the server URL, repository id, and API key in Advanced settings, then use the palette to: - **Import memories as notes** — materialize memories as editable notes tagged `#memory` with provenance properties. Imported notes are yours; re-imports never overwrite them. - **Remember this note** — distill the open note back into the memory server so agents can recall it. - **Sync note links to memory graph** — create and update managed relationships as your note graph changes, preserving unmanaged ones. - **Memory graph insights** — review what the memory graph knows. Ask AI can blend relevant recall into its answers, and the note footer shows memories connected to the open note. ## Settings Settings are grouped into six tabs. - **General:** theme, interface density, app font size. - **Writing:** editor width, block font size, indent guides, spell check, auto-link note suggestions, new-section collapse behavior, note sorting, default new-note tags, pinned-first behavior, Today heading format and defaults, reminder notification style, sound, overdue-on-launch behavior, snooze duration, week start, and graph style. - **Data & Privacy:** current vault folder, create a vault, vault mode, auto-save and markdown storage confirmation, local-only sync backend, backup export and import, Markdown import, novel-file import, Vault Health, vault deletion, and the local usage report. - **Assistance:** enable assistance, choose Local or Hosted, PII reduction, API key, host or base URL, chat model, retrieval mode, and provider status. - **Advanced:** optional packs and existing integrations such as Zotero and llm-memory. - **About:** app version, update checks, keyboard shortcuts, platform information, vault statistics, and project links. Usage and privacy: - The local feature report counts feature use on this device — never note text, titles, tags, searches, prompts, filenames, paths, vault IDs, or secrets. - You can preview, export, or clear the exact report at any time, or turn it off. - Anonymous aggregate sharing is separately opt-in and off by default. ## Data, Recovery, and Maintenance VispNote saves notes automatically as markdown files. It also gives you recovery tools for common mistakes and maintenance tools for larger vaults. Version history: - Open a note's Version history from the editor toolbar. - Versions are saved snapshots of the note on disk, shown as a readable diff against the current text. - Restore a previous version when you need to undo changes older than the normal editor undo stack. - Restoring a version replaces the current note content with that saved version. Save conflicts: - If a note changes on disk while you also have local edits open, VispNote shows a save conflict dialog. - Choose Keep editing to leave your local edits unsaved while you decide. - Choose Save local copy to preserve your current edits as a separate copy. - Choose Reload disk version to discard the local edits and load the file currently on disk. Recently deleted: - Deleted notes and boards are listed in the sidebar under Recently deleted. - They are kept for 30 days before cleanup. - Restore an item to bring it back into the active vault. - Delete permanently only when you are sure you do not need it. Backup and restore: - Export backup writes a VispNote backup JSON file containing vault metadata, notes, and boards. - Import backup restores the backup into new vaults and can activate the imported vault. - The sidebar footer shows the last successful backup, so you can tell at a glance how current it is. - Use backups before major upgrades, OS migrations, or large cleanup sessions. Vault Health: - Open Vault Health from the sidebar footer, Settings, or the palette. - It reports note count, tag count, board count, word count, broken wiki links, and orphan notes. - Use Rebuild index when search, connections, or graph results feel stale. These tools do not replace normal system backups. Keep your `~/VispNote` folder backed up with your regular backup tool if the notes matter. ## Shortcuts | Action | Shortcut | | --- | --- | | New note | Cmd/Ctrl N | | Quick capture | Cmd/Ctrl Shift N | | Palette · Notes first | Cmd/Ctrl P | | Palette · Notes and actions | Cmd/Ctrl K | | Toggle reference pane | Cmd/Ctrl Shift R | | Open Ask AI | Cmd/Ctrl Shift K | | Open graph | Cmd/Ctrl G | | Toggle sidebar | Cmd/Ctrl \\ | | Toggle note list | Cmd/Ctrl Shift \\ | | Undo | Cmd/Ctrl Z | | Redo | Cmd/Ctrl Shift Z or Cmd/Ctrl Y | | Select all blocks | Cmd/Ctrl A in the outliner | | Copy selected blocks | Cmd/Ctrl C | | Cut selected blocks | Cmd/Ctrl X | | Paste blocks | Cmd/Ctrl V | | Indent bullet | Tab | | Outdent bullet | Shift Tab | | New sibling bullet | Enter | | Soft line break | Shift Enter | | Delete empty bullet | Backspace | | Zoom into block | Cmd/Ctrl Enter | | Move focused block | Alt Up / Alt Down | | Duplicate focused block | Cmd/Ctrl D | | Delete focused block | Cmd/Ctrl Backspace | | Start wiki-link suggestion | `[[` | | Start tag | `#` | | Schedule reminder | `@remind YYYY-MM-DD` | | Close overlay | Esc | | Navigate slash/wiki/AI menus | Arrow Up / Arrow Down | | Accept highlighted menu item | Enter or Tab | Ask AI and Graph shortcuts work once assistance and the Labs pack are enabled. Settings → About lists the same shortcuts with the modifier keys for your platform, and warns if the system took the global Quick capture shortcut. Board shortcuts include Cmd/Ctrl C, Cmd/Ctrl X, Cmd/Ctrl V, Cmd/Ctrl Z, Cmd/Ctrl Shift Z or Cmd/Ctrl Y, Delete, mouse wheel zoom, and space-drag panning. ## Troubleshooting If you see **Search index unavailable**, VispNote is using a limited fallback over loaded notes. This does not mean your files are gone. Clear the search to browse the vault, then open Vault Health and run Rebuild index. If the download button opens the release page instead of an installer, the latest build may still be uploading assets. If a panel you expect is missing, open Settings → Advanced and check whether its pack is enabled. Agenda, Workflow, Thinking Board, Novelist, Views, and Graph each belong to a pack. Today is always available in the sidebar and does not need a pack. If assistance is unavailable, open Settings → Assistance, confirm it is enabled, and check whether it is set to Local or Hosted. For Local, start Ollama and pull the chat model, for example `ollama pull gemma3`. For semantic retrieval, also pull the embedding model, for example `ollama pull nomic-embed-text`. If Ask AI says keyword mode, the chat model is available but the local embedding model is not. Ask AI still works with local full-text search and recent notes, but semantic retrieval needs the configured Ollama embedding model. If reminders do not show, check the syntax and date format. If a note is missing from a workflow column, check whether the note has a `status::` property that matches an existing workflow state. If the note was archived from the Workflow panel, open Archived and restore it. If search, connections, or graph feel stale, run Rebuild index from Vault Health or the palette. They are built from the active vault's indexed markdown, tags, and wiki links. If a board is not visible in a note, open the Thinking Board dashboard and confirm the board still exists in the active vault. Board embeds point to an id, so deleting the board removes the source for that embed. If you deleted the wrong note or board, open Recently deleted in the sidebar. Restore the item from there before the cleanup window expires. If a wiki link points nowhere, open Vault Health to find broken links. Either create the missing note or update the link target. If you need an older version of a note, open Version history from the editor toolbar and restore the saved version you want. If you are moving computers, export a backup from Settings → Data & Privacy on the old computer, then import it on the new computer. You can also copy the raw `~/VispNote` folder with your normal file tools. To access raw notes, open the vault folder shown in Settings. Notes are markdown files, attachments live in `attachments/`, and boards are JSON files inside the vault's `.canvases` folder.