Hjarni Notes

Dismiss a nudge served in the `me` payload, on the user's behalf, so it stops appearing on every surface (including the web app). Call this ONLY when the user has actually declined the suggestion or asked not to be reminded — never on mere silence; ignored nudges are already frequency-capped server-side. Required: key (string, the `nudge.key` from `me`). Idempotent.

nudges-dismiss

Get a single container by ID, including notes_count, children_count, description, negative_space (what does NOT belong in the folder), and LLM instructions if set. Optional: include_tree (boolean) to also get ancestor chain and children. Required: id (integer). A row flagged root: true is the space's root (the notes filed outside any folder), which containers-update refuses; set that space's instructions with instructions-update instead.

containers-get

Get an overview of the Second Brain: counts of notes, containers, tags, and inbox items, plus recent_notes (the 5 most recently created personal notes) and recent_changes (the 5 most recently edited notes across ALL spaces — personal, teams, and shared containers — newest edit first). Use recent_changes to orient at the start of a conversation on what changed lately everywhere. If everything is empty because the user hasn't saved anything yet, do not just report that: call `me` and follow onboarding.next_action to run their 60-second setup. No parameters required.

dashboard-get

Get a time-limited download URL for a file attached to a note. Share the URL with the user to download in their browser. The URL expires 15 minutes after it is issued (see download_url_expires_at in the response); request a fresh one rather than reusing an old URL. It requires no login while valid, so treat it as a credential. Required: note_id (integer), file_id (integer, from notes-get response).

files-get_download_url

Get LLM instructions at the specified level. Call with level 'brain' early in conversations to learn user preferences. Optional: level ('brain'|'personal_root'|'container'|'team'), defaults to 'brain' if omitted or blank; the response echoes resolved_level and defaulted_level (true when the level was defaulted). Optional: id (integer, required for 'container' and 'team' levels). 'container' level takes a personal (or shared) container id and returns the full inheritance chain, outermost first; each entry carries a `level` field ('brain'|'personal_root'|'team'|'container'). Team container ids are not addressable here — read a team note's chain from notes-get, or the team's own instructions with level 'team'.

instructions-get

Get a single note by ID, including its full Markdown body, tags, container path, linked notes (outgoing), backlinks (incoming links from other notes), file attachments, and inherited_instructions — every user-written LLM instruction layer that applies to the note, outermost first (an inbox note still carries brain plus its space root), so no separate instructions lookup is needed before editing. A missing brain entry means the user has no custom brain instructions; the defaults come from instructions-get with level 'brain'. A note in Trash returns a status: 'trashed' summary (id, title, purge deadline, how to restore) instead of its content — restore it with notes-restore to read or edit it. Required: id (integer).

notes-get

Get team details including the 10 most recent notes. Required: id (integer).

teams-get

Get the connected user's profile, plan, onboarding state, team memberships, and note quota in a single call. Call this once at the start of a conversation so you can greet the user by first name, run the onboarding script only when needed, route notes to the right team space, and avoid suggesting Pro features to free users. Returns onboarding.completed (boolean) and onboarding.missing_steps (array of 'connect_mcp' | 'first_note'), which together tell you what, if any, setup is left. May include a `nudge` (key, message, url) — one frequency-capped suggestion; see the NUDGES section of the server instructions for how to handle it. Exposes the user's email address and plan — same data the user sees in account settings, but never billing or token metadata. No parameters required.

me

Invite a teammate to a team by email (team owner only). Required: team_id (integer, from teams-list), email (string). Emails an invite; they must accept from that exact address, and a per-seat charge is added only when they accept.

teams-invite

List containers (folders) for organizing notes. Each container includes notes_count and children_count. Returns a JSON array, followed by a line stating the total for the folders it pages through and whether more pages remain; folders shared WITH you are appended in full on the first page and counted separately in that line. Optional: team_id (integer) for team containers, scope ('roots' default|'all'|'archived'), page, per_page. Shared containers are automatically included when listing root-level personal containers. The space's root (the personal root, or a team's root folder) is not a folder: it holds the notes filed outside any folder and cannot be renamed, moved, archived or deleted. It is left out of the default 'roots' scope and appears under 'all' flagged root: true.

containers-list

List the user's email capture addresses (Pro only). Mail sent to one of these becomes a note in the folder it is bound to. Each entry has id, label, address, destination (folder name, or 'Inbox'), container_id, team_id, tags, notes_count and last_received_at. Returns an empty array for a Free account. Treat every address as a secret: it is a write credential for that folder, so never put one in a note, a summary, or anything shared.

email-addresses-list

List and browse the user's saved notes — their stored knowledge and memories (preferences, workflows, projects, meeting notes, references, and the rest) — with optional filtering, sorting, and pagination. Use search instead when hunting for a topic or keyword; use this to enumerate a folder, tag, or scope. Returns paginated results as a JSON array, followed by a line stating how many notes matched in total and whether more pages remain — read it to know if you have the whole folder before acting on it. Optional: team_id (integer) to list team notes, scope ('active'|'archived'|'inbox'|'favorited'|'trashed'), container_id (integer) with include_nested (boolean), tags (array of strings, AND logic), tag_ids (array of integers, AND logic), summary_stale (boolean, filter to notes with outdated summaries), stale (boolean, filter to notes whose freshness is stale — past their review_after date or unverified for a while), sort ('recent'|'oldest'|'title'), page (integer, default 1), per_page (integer, max 100, default 25), include_body (boolean, default false — include each note's full body, so a scoped/paginated listing can retrieve complete contents without a notes-get call per note; withheld for trashed notes, same as notes-get), include_instructions (boolean, defaults to include_body — include each note's inherited_instructions, the same chain notes-get returns, so a full-body listing also carries the rules governing those notes; withheld for trashed notes). container_id can be combined with team_id to list a specific team container. Example: list ruby-tagged notes in a container: {container_id: 5, tags: ['ruby']}. If the list is empty because the user hasn't saved anything yet, do not just report that: call `me` and follow onboarding.next_action to run their 60-second setup.

notes-list

List all tags with their notes_count. Returns a JSON array, followed by a line stating the total and whether more pages remain. Optional: page (integer), per_page (integer).

tags-list

List all teams the user is a member of, including members_count, notes_count, and containers_count for each team. No parameters required.

teams-list

Create or remove a bidirectional link between two notes. Required: action ('link'|'unlink'), source_note_id (integer), target_note_id (integer). Prefer wiki-link syntax [[id:Title]] in note bodies for inline linking — use this tool for programmatic links without modifying body text. Unlinking is destructive and cannot be undone.

links-manage

Rename, merge, or delete a tag — the cleanup tools for the tag list (this operates on the tag itself, unlike notes-update which only edits one note's tags). Required: action ('rename'|'merge'|'delete') and the tag to act on via name (string, case-insensitive) or tag_id (integer). For 'rename' also pass new_name. For 'merge' also pass the destination via target_name or target_id: every note on the source tag is moved onto the destination and the source tag is deleted — ideal for collapsing duplicates like 'machine learning' into 'machine-learning'. If target_name names a tag that doesn't exist yet, it's created, so you can merge straight into a clean canonical name without creating it first. 'delete' removes the tag from all its notes and deletes it; deleting a name that doesn't exist succeeds as a no-op (already_absent: true), so it's safe to retry. Merge and delete are destructive and cannot be undone; check tags-list first.

tags-manage

Read a note's revision history and provenance: who wrote each version (you, the user, or which AI client), when, and what changed. Use it to attribute facts to their source and to see recent edits before making your own. Read-only. Required: id (integer). Optional: limit (default 20, max 100), before_seq (paginate to older revisions), include_body (boolean — reconstruct each version's full text), seq (integer — return only that revision, with its full reconstructed body).

notes-history

Permanently remove a file attachment from one of your personal notes (personal notes only). This action is irreversible. Required: note_id (integer), file_id (integer, from notes-get response).

files-remove

Restore a deleted folder from the Trash, bringing back everything its delete took -- sub-folders and notes return together, exactly as they were. Find restorable folders with containers-list scope 'trashed'. A note that was deleted TOGETHER with a folder can only come back this way (notes-restore refuses it and names the folder). Required: id (integer, the deleted folder's id).

containers-restore

Restore a note that notes-delete moved to Trash, bringing back its body, tags, attachments, and history. Only works before the note's purge date. Required: id (integer) — the same note id you deleted.

notes-restore

Revert a note's body to an earlier revision (find the seq via notes-history). This does NOT erase history — it appends a NEW revision whose body equals the chosen earlier one, attributed to you, so the revert can itself be undone. Use only when the user explicitly asks to undo a change. Optional expected_lock_version (from notes-get) rejects the revert if the note changed since you read it, instead of clobbering that change. Required: id (integer), seq (integer).

notes-revert

Search across notes, containers, and tags in one call — the retrieval tool for ANYTHING the user has saved in their second brain: preferences, workflows, routines, projects, decisions, meeting notes, research, people, how-tos, code snippets, references, journal entries, and any other saved knowledge or memories. When a task needs something the user previously stored, this is the tool that finds it. Returns results grouped by type with pagination metadata (total_count, page, per_page, total_pages). Required: query (string). Optional: types (array, default all three), search_scope ('all'|'personal'|'team:<id>'), scope ('active'|'archived'), container_id (integer, ignored when search_scope is 'all'), tags (array, AND logic), tag_ids (array, AND logic), include_nested (boolean), include_body (boolean, default false — when true each note includes its full body), include_instructions (boolean, defaults to include_body — when true each note carries inherited_instructions, the same user-written instruction chain notes-get returns, so a full-body search hit arrives with the rules that govern it and needs no follow-up notes-get; pass false to omit the chain from a body-only page), created_after / created_before / updated_after / updated_before (ISO 8601 datetime filters on note timestamps), page (integer, default 1), per_page (integer, default 25, max 100). Note results include a snippet of the matching portion. If results are empty because the user hasn't saved anything yet, do not just report that: call `me` and follow onboarding.next_action to run their 60-second setup.

search

Set or clear a team member's role on a team container. Roles cascade to descendants unless a child has its own role. Caller must have admin role on the target container. Required: container_id (integer, must be a team container), user_id (integer, must be a member of the same team), role ('viewer' | 'editor' | 'admin' | 'inherit'). Use 'inherit' to delete an explicit role and fall back to the role inherited from an ancestor (or from team membership). Team owners are always admin and cannot be downgraded. Returns the user's resulting effective_role on that container.

containers-permissions

Submit feedback about Hjarni itself — confusing tool descriptions, missing capabilities, unexpected errors, friction, or praise. Use this when something about the MCP server, a tool, or the product behavior is worth flagging to the maintainers. Do NOT use this for the user's own notes or knowledge — those belong in notes-create. Required: category ('bug'|'confusing'|'missing_feature'|'friction'|'praise'|'other'), message (string, what's wrong and ideally what you'd expect instead). Optional: severity ('low'|'medium'|'high', default 'medium'), tool_name (the MCP tool the feedback is about, e.g. 'notes-update'), context (JSON-encoded string with any extra structured data — error excerpts, the arguments you tried, the workflow that broke).

feedback-submit

Update an existing container — rename, change description or negative_space (what does NOT belong here), move to a different parent, or set display position. Works for both personal and team containers the current user can edit (team containers require the editor role). Required: id (integer). Optional: name, description, negative_space (pass null to clear it), parent_id (null for root, must be in the same scope), position (integer, lower = first).

containers-update

Update LLM instructions at the specified level. Required: level ('brain'|'personal_root'|'container'|'team'), instructions (string). Optional: id (integer, required for 'container' and 'team'), mode ('replace' default|'append'). The 'container' level updates personal containers only; to set instructions for a team, use level 'team' (team owners only). In 'replace' mode (default), the provided text overwrites existing instructions. In 'append' mode, the text is appended to existing instructions with a newline separator. Always read current instructions first before replacing to avoid losing existing content.

instructions-update

Update a note: edit its content, move it to a different folder (set container_id, or null for the inbox), archive/favorite it, or change its tags. This is the tool for moving notes between folders; there is no separate move tool. Required: id (integer). Optional content (exactly one body-mutation mode at a time): title, body (full replace), append_body (appends to existing body), insert_after + insert_body (insert text immediately after a unique anchor snippet from the existing body), insert_before + insert_body (insert before a unique anchor), replace_find (+ optional replace_with) (replace a unique snippet; omit replace_with entirely to delete the snippet). Markdown-structure ops (heading/section/checklist aware — safer than eyeballing a unique snippet on long notes): replace_section + section_body (replace everything UNDER a heading, keeping the heading line); append_to_section + section_body (add content at the END of a section — the safe 'insert under heading' when you don't know its last line); rename_heading + new_heading (rename a heading in place, preserving its level unless new_heading carries its own '#'); check_item / uncheck_item (tick/untick a checklist item by its text, e.g. '- [ ] ship it'). Headings and checklist items must each match exactly one line. Anchor and find snippets must match exactly once; include enough surrounding context to disambiguate. Also optional: summary, source_url. Freshness: verified (boolean — pass true to mark the note re-confirmed as still true right now; only send this after the user has actually confirmed it), review_after (ISO 8601 datetime to time-box the note, or null to clear it). Organization: container_id (move note), archived (boolean — works on your own personal notes and on team notes where you have the editor role; notes in shared containers are owner-only), favorited (boolean). Tags: tag_list (full replace, comma-separated), add_tags, remove_tags. tag_list takes precedence over add_tags/remove_tags. Concurrent edit safety: pass expected_lock_version (the lock_version you saw when you last read the note via notes-get / notes-list / search) whenever you want a stale-write guard. If it doesn't match the current version, the update is rejected with the current state included so you can re-read and re-apply (append_body-only calls are exempt; see expected_lock_version). Surgical edits (append_body / insert_after / insert_before / replace_find) are anchor-based and so don't *need* expected_lock_version for their body change — but if you also change title / summary / container_id alongside, those fields can still silently overwrite a newer save unless you supply expected_lock_version. Examples: insert under a heading {id: 42, append_to_section: 'Open Questions', section_body: '- Should we ship Friday?'}; replace a section {id: 42, replace_section: '## Status', section_body: 'Shipped 🎉'}; rename a heading {id: 42, rename_heading: 'TODO', new_heading: 'Done'}; tick a checklist item {id: 42, check_item: 'ship it'}; fix a typo {id: 42, replace_find: 'recieved', replace_with: 'received'}; safe full rewrite {id: 42, body: '...', expected_lock_version: 5}. Every edit is recorded as a named, revertable revision attributed to you — use notes-history to see who changed what, and notes-revert to undo a change.

notes-update