> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Using Notes
> Jot down card notes right inside the Chatbot window. Each one is a local Markdown file — searchable, readable and writable by AI, and openable in any editor.
## What Notes Are
**Notes** in Linkly AI are a stream of small cards ordered by time: type a line into the box at the bottom whenever something occurs to you, hit save, and it becomes a card on the timeline.
The biggest difference from other note apps is this — **each card is a plain `.md` file on disk**. No proprietary database, no export feature (because none is needed): you can open them in Obsidian or VS Code any time, or just `grep` them. At the same time Linkly AI indexes them, so they turn up in search and your AI assistant can read and write them.
The input box is always there at the bottom. Write, press ⌘/Ctrl+Enter — no new file, no title
Standard Markdown with a YAML header; any editor can read and edit them, and they survive the app
### What They're Good For
Notes are built to be **short, fast, and findable later** — not for long-form writing:
* **Things that just occurred to you**: a one-line to-do, a product idea out of nowhere
* **Annotations while reading**: have the AI dig through material and write down the conclusions as you go
* **Conclusions for the AI to record**: have the Chatbot read a batch of material and turn the key points straight into a note
* **A landing spot for stray facts**: a number you heard in a meeting, a book someone recommended
If what you're writing is a proper document, creating a Markdown file directly in `~/LinklyAI` is a better fit — it gets indexed just the same.
***
## Opening Notes
Notes are **not a separate window**; they're a view inside the Chatbot window, alongside chat:
* Click **Note** in the Chatbot sidebar
* Or press **⌘⇧N** (Windows / Linux: **Ctrl+Shift+N**)
**⌘⇧N is not a global shortcut** — the Chatbot window has to be in the foreground and focused for it to do anything. The one global shortcut in the entire app is **⌘⇧L / Ctrl+Shift+L**, which summons the [search launcher](/docs/en/use-launcher).
***
## Writing Your First Note
The notes view has a permanent input box at the bottom, with the placeholder **Write a note… Use #tag to tag it**.
When the text runs long, click the expand button in the top-right corner and the box **grows upward in place** (up to 60% of the window). No new window opens, and neither your draft nor your cursor position is disturbed.
Press **⌘/Ctrl+Enter**, or click the send button in the bottom-right. The card appears at the bottom of the timeline immediately.
Plain Enter inserts a line break and does not save — deliberately, since notes often run to several lines.
Click **Edit** on a card and it **becomes editable in place**, with no dialog. Only one card can be edited at a time.
When you're done you have to click **Save** or press ⌘/Ctrl+Enter.
The `⋯` menu in the card's top-right corner → **Delete** → confirm.
**Deleting permanently removes that file from disk.** It doesn't go to the trash, and there's no undo in the app. The confirmation dialog is explicit about it: **This permanently deletes the note file from disk. This cannot be undone.**
### What the Editor Can Do
The note editor is a **plain Markdown text box**, not a rich text editor — what you see is the source. The toolbar has just 5 buttons:
| Button | What it does |
| ------------- | ---------------------------------------------------- |
| Bold | Wraps the selection in `**` |
| Strikethrough | Wraps the selection in `~~` |
| Bulleted list | Turns the selected lines into a `-` list |
| Numbered list | Turns the selected lines into a `1.` list |
| Insert tag | Inserts `#` at the cursor and opens tag autocomplete |
There is **no** button for italics, headings, links, or code blocks — a deliberate narrowing, because notes are meant to stay short. Pressing Enter inside a list continues it with the next item.
Once saved, the card switches to reading mode and renders the Markdown normally.
**There is no autosave.** Whatever is in the input box or the editor lives in memory only: switch to the chat view and back and your draft is still there, but **quit the app and it's gone**. Press ⌘/Ctrl+Enter when you're done.
In reading mode, **images are never loaded from the network** — you get a placeholder block with the alt text instead. This is a privacy decision: rendering a remote image tells that server you read this particular note at this particular moment.
There's no character limit in the interface; the backend caps a single note at 10 MiB, which day-to-day writing won't come close to.
***
## Tags
Writing `#tag` in the body is how you tag a note. Typing `#` pops up a candidate list (up to 8), which you navigate with ↑↓ and confirm with Enter.
After saving, tags are lifted out of the body and shown on the tag strip at the bottom of the card — click any of them to filter down to every note carrying that tag.
Tags can be nested with `/`, for example `projects/client-a` or `reading/tech`. A single note can carry up to 50 tags, and each tag is 1–64 characters.
**There is no separate tag input in the interface; tags can only be written in the body.** Which also means: to remove a tag, delete that `#tag` from the body — the body is the single source of truth.
***
## Finding a Note
### The Timeline
The notes view is a **flat stream of cards with no date grouping**. The order is always **oldest at the top, newest at the bottom**, the same way a chat log reads — so the most recent note is always right in front of you. It loads 20 at a time, and scrolling up offers **Load earlier**.
### Sorting
The sort menu at the top has three options:
| Sort | Meaning |
| ------------------- | ------------------------------------------ |
| **Newest created** | The default. By creation time, newest last |
| **Oldest created** | The reverse |
| **Recently edited** | By last modification time |
Sorting is **session-scoped** — it isn't persisted when you quit, and the next launch starts back at **Newest created**.
### Search
Click the magnifying glass at the top, or press **⌘/Ctrl+F**.
Search isn't a simple substring match; it runs through Linkly AI's full-text retrieval (a keyword + semantic hybrid once the semantic index is built, keyword-only otherwise). So searching for "launch plan" can also surface a note that says "release schedule".
Search **returns at most 20 results and has no pagination**. To narrow things down, click a tag to filter first and then search. Input is debounced by about 0.3 seconds, so the query only fires once you stop typing.
### Why a Note You Just Wrote Isn't Searchable Yet
This is the most confusing part. The three things you see in the notes view come down **three different data paths**, with different latencies:
| What you're looking at | Where the data comes from | After writing a note |
| ----------------------------- | --------------------------------------------- | --------------------- |
| Timeline, tag filtering | Scans the file system directly | **Visible instantly** |
| Full-text search results | Depends on the index | Delayed |
| Autocomplete after typing `#` | Depends on a tag table derived from the index | Delayed |
So "the note I just wrote shows up on the timeline, but search can't find it and `#` autocomplete doesn't know it" is **normal** — it sorts itself out once indexing catches up. Conversely, the timeline is always current: it never consults the index at all.
***
## Where Notes Are Stored
Every note lives under `Notes/` inside your library root (`~/LinklyAI` by default), filed by month:
```
~/LinklyAI/Notes/
├── 2026-06/
│ └── Weekly syn-3ea26713.md
└── 2026-07/
├── Launch che-91805137.md
└── 2026-07-28-080741-ca478cef.md
```
Month folders are computed in **UTC**, so a note written at the very start or end of a month may land in a folder a day off from your local time zone.
### Filename Rules
The filename is `-.md`:
* The 10 characters are counted as **Unicode characters** — one CJK character counts as one
* Runs of whitespace collapse to a single space, and that space counts toward the 10
* Characters illegal in filenames (`/ \ : * ? " < > |`) are stripped and **do not count**
A real example: a note whose first line is `**Launch checklist**`. The `*` characters are stripped without counting, leaving `Launch che` as the first 10 characters, so the file is named **`Launch che-91805137.md`**.
If the body is all punctuation or whitespace (no usable stem), or the stem happens to collide with a reserved Windows device name (`CON`, `NUL`, and friends), the name falls back to a timestamp: `YYYY-MM-DD-HHMMSS-<8-char id>.md`.
**The filename is fixed at creation and editing the body never renames the file.** That keeps a file's identity stable, so the index and any external references don't all break because you fixed a typo.
### File Format
Each file is standard Markdown with a block of YAML front matter at the top:
```markdown theme={null}
---
note_id: 91805137-c3f8-4bc9-8db4-e7e8d99409bc
created_at: 2026-07-28T08:02:21.095Z
updated_at: 2026-07-28T08:05:33.709Z
source: user
updated_by: user
tags:
- test
---
**Launch checklist**
To confirm before we ship:
- Website copy finalized
- Changelog translated into all three languages
- Submitted to the download sites
#test
```
What the fields mean:
| Field | Description |
| --------------------------------- | --------------------------------------------------------------------------------------- |
| `note_id` | The note's unique ID (a UUID); the 8 characters at the end of the filename come from it |
| `created_at` / `updated_at` | Creation and last-modified time, ISO 8601, millisecond precision, UTC |
| `source` | Who created the note: `user` (you) or `agent` (AI) |
| `agent` | Present only for AI-created notes, naming which agent it was |
| `updated_by` / `updated_by_agent` | Who made the last edit, with the same possible values |
| `tags` | The array of tags |
The field order is fixed. **Unknown fields you add by hand are preserved verbatim** — the app won't strip them, so tucking your own metadata in there is safe.
A note written by AI looks like this, and carries an `Agent` badge in the interface:
```yaml theme={null}
source: agent
agent: linkly-chatbot # the app's built-in Chatbot; external agents write external-mcp
updated_by: agent
updated_by_agent: linkly-chatbot
```
***
## Opening Notes in Another Editor
There's an **Open notes folder** button at the top, which opens the `Notes/` directory directly in your system file manager.
Because it's all standard Markdown, Obsidian, VS Code, and Typora can read and write it as-is. The `tags:` field happens to be one Obsidian recognizes natively, so opening `Notes/` as a vault gets you its tag panel for free.
External changes are picked up on the app's next scan. If you happen to be **editing the same note in the app at that moment**, a conflict prompt appears asking you to choose **Reload latest** or **Copy my text** — **neither side is ever silently overwritten**.
You're also free to rename files; the app won't rename them back.
Two things will make a note seem to disappear. Watch out for them:
1. **The timeline only scans `.md` files in the two-level `Notes/YYYY-MM/` structure.** Files sitting in the `Notes/` root, or in some other subfolder like `Notes/archive/`, **won't appear on the timeline** (though they're still full-text indexed and still searchable).
2. **Delete the YAML header** and the note drops off the timeline — the file is still on disk and still searchable, the app just no longer treats it as a note.
***
## Letting AI Write Notes for You
Notes can be read and written by an AI assistant. Two tools cover it, exposed both by the local MCP server and, remotely, by the cloud gateway:
| Capability | MCP tool | CLI command |
| ------------ | ----------- | --------------------------- |
| Write a note | `note_save` | `linkly note-save` |
| List notes | `list` | `linkly list --scope notes` |
Full parameters are in [Using the CLI](/docs/en/use-cli). For MCP setup, see [Connecting AI Tools](/docs/en/use-mcp).
Plain language is enough to drive it:
"Save that conclusion as a note and tag it product and todo"
"Read the material on attention in my ml-papers library and write the key points up as a note"
"List my notes tagged ops"
A few differences worth knowing:
* **Edits carry a version for concurrency checking.** When the AI edits a note it must send back the `version` it read; if the note changed in the meantime, the write is rejected (`NOTE_VERSION_CONFLICT`) rather than blindly overwriting.
* **Note bodies written by AI are format-restricted**: only paragraphs, bold, strikethrough, ordered and unordered lists, and plain text are allowed — matching what the interface toolbar can produce. Headings, italics, code blocks, links, images, and tables are rejected. **What you type by hand in the interface is not subject to this restriction.**
* **MCP has no delete tool.** Deleting a note can only be done in the app.
* **Remote access still lands on your own computer.** Both tools also work over the cloud gateway (`linkly --remote`, or the cloud connector in your AI client), but the gateway only forwards to your Desktop — notes are never stored in the cloud. So working with notes remotely needs that computer online and a Pro plan, and when it isn't reachable there's no cloud copy to fall back on.
* **Tag handling differs**: this path **does not extract `#tag` markers from the body**, only the tags passed explicitly as a parameter — and on edit, tags are **replaced wholesale**, so anything you leave out is removed.
After an AI writes a note over MCP, if it doesn't show up in the interface right away, switch to the chat view and back to the notes view and it will be there.
***
## FAQ
Notes currently have **no dedicated cloud sync**; they're kept as local files in your library folder.
One thing to watch: if you add the `Notes/` folder to a library, and that library is bound and pushed to a [cloud library](/docs/en/use-cloud-library), your notes get uploaded like any other Markdown document. To keep them strictly local, don't put `Notes/` in a library you push.
This shortcut only works **while the Chatbot window is focused** — it isn't a global shortcut. Click the Chatbot window first, then press it. The only genuinely global one is ⌘⇧L / Ctrl+Shift+L, which summons the search launcher.
It isn't. The timeline scans the file system directly, so it's visible immediately; full-text search goes through the index, which lags. It'll be searchable once indexing catches up. New tags likewise take a moment to appear in the `#` autocomplete.
None of those exist today. Pinning, favoriting, and archiving aren't features yet; exporting isn't needed — a note is already a `.md` file on disk, so just copy it. If you need something like archiving, move the file elsewhere in an external editor, but be aware that it will disappear from the timeline (see [Opening Notes in Another Editor](#opening-notes-in-another-editor)).
The MCP / CLI path **doesn't extract `#tag` markers from the body**, only the tags passed
explicitly — so the tags end up in the YAML with no matching `#tag` in the body, and since the
interface edits tags by editing the body, there's nothing for it to change.
Two ways around it: edit the file's `tags:` field directly in an external editor, or add the matching `#tag` markers to the body and save once from the interface.
No. Deleting removes the file from disk directly; it doesn't go to the system trash, and there's no undo in the app. Be sure before you delete, or back the file up in an external editor first.
Yes. Notes are ordinary Markdown files under `~/LinklyAI`, scanned, indexed, and retrieved exactly like any other document — which is also why you can find them in the [search launcher](/docs/en/use-launcher), and why an AI assistant's `search` will hit them.
***
## Further reading
* [Using the Launcher](/docs/en/use-launcher) — global search finds notes too
* [Using the CLI](/docs/en/use-cli) — full parameters for `note-save` and `list --scope notes`
* [Connecting AI Tools](/docs/en/use-mcp) — let an external AI assistant read and write your notes
* [Tools Introduction](/docs/en/tools-intro) — the complete MCP tool reference
* [Using the Chatbot](/docs/en/use-chatbot) — what else the window holding your notes can do
* [Linkly AI Space](/docs/en/linkly-space) — where `Notes/` lives, and how to move it