The note format

What an app or a script writes so that Matters that Matter reads its notes as Actions and Matters, and what it must keep up to date as the plugin does.

Every Action and every Matter is a Markdown note with mtm- properties. Another app, a script or a sync from another system can write those notes directly, and Matters that Matter shows them like its own. This page says what to write. Properties has the short version.

The easy way

The command line applies every rule on this page for you, and doesn’t need Obsidian to be running. To read Actions, its --json output gives both the raw properties and the values the plugin shows, so your code never has to work them out.

The smallest Action

A note is an Action when its properties say mtm-kind: action. Its title is its file name. This is a whole Action, MTM/Actions/Ring the bank.md:

---
mtm-kind: action
---

Matters that Matter shows it in the Inbox, in your backlog status, with your default type, and without a badge: an absent value is never a problem. A tool that creates Actions should still write the type, status and Matter, as the plugin does:

---
mtm-kind: action
mtm-type: write
mtm-status: later
mtm-matter: "[[Inbox]]"
---

Notes are recognised by mtm-kind, never by their folder, so they can live anywhere in the vault. New ones go in the folders named in the settings (below).

IDs, from the settings

Statuses, Action types and Spheres are stored by their ID, never their label: mtm-status: next, not Next. The user can rename a status without touching a note; the ID stays.

The IDs are in the plugin’s settings, data.json in the plugin’s folder: .obsidian/plugins/matters-that-matter/data.json, unless the vault’s configuration folder has another name (Obsidian lets you change it). Matters that Matter writes this file; other tools only read it. The parts a tool needs:

{
  "schemaVersion": 7,
  "setupDone": true,
  "folders": { "matters": "MTM/Matters", "actions": "MTM/Actions", "boards": "MTM/Boards", "people": "MTM/People" },
  "statuses": [
    { "id": "later",   "label": "Later",   "tone": "ink",      "category": "open",   "backlog": true },
    { "id": "next",    "label": "Next",    "tone": "sky",      "category": "open" },
    { "id": "doing",   "label": "Doing",   "tone": "butter",   "category": "active" },
    { "id": "waiting", "label": "Waiting", "tone": "lavender", "category": "active" },
    { "id": "done",    "label": "Done",    "tone": "mint",     "category": "closed", "done": true }
  ],
  "types": [
    { "id": "call",  "label": "Call",  "icon": "phone",       "tone": "mint" },
    { "id": "write", "label": "Write", "icon": "pencil-line", "tone": "butter", "default": true }
  ],
  "spheres": [ { "id": "home", "label": "Home", "icon": "house" } ],
  "inboxPath": "MTM/Matters/Inbox.md"
}

category says what a status means: open (not started), active (under way, or waiting) or closed (done). There can be more than one closed status, so decide “done” by the category, never by an ID.
backlog: true marks the status new Actions start in and Reopen returns to; done: true the one Mark as done sets. default: true marks the default type.
inboxPath says which Matter note is the Inbox. Its name and properties don’t.
setupDone: until it is true, write nothing.
schemaVersion: this page describes versions 6 and 7. A higher number comes from a newer version of Matters that Matter: read, but don’t write.

Action properties

Property	Form	Notes
`mtm-kind`	`action`	Required
`mtm-type`	A type’s ID	Absent: the default type
`mtm-status`	A status’s ID	Absent: the backlog status
`mtm-matter`	A link to a Matter note	Absent: the Inbox
`mtm-start`	A date, or a date and time	Optional. On its own, one day on the calendar
`mtm-due`	A date, or a date and time	Optional
`mtm-priority`	`1`, `2` or `3`	High, medium, low. Absent: no priority
`mtm-waiting-on`	A link to a person’s note	Optional
`mtm-people`	A list of links to people’s notes	Optional
`mtm-waiting-since`	A date	Kept with `mtm-waiting-on`: see a writer’s duties
`mtm-completed`	A date	Kept with the status: see a writer’s duties
`mtm-order`	A number	A card’s place on boards in your own order. Written by Matters that Matter; other tools only remove it
`mtm-sample`	`true`	Sample content. Other tools never set it

Properties without the mtm- prefix are the user’s: Matters that Matter ignores them, and a tool should never write status or type on its behalf.

The forms

Dates are 2026-10-16 for a whole day, or 2026-10-16T10:00 for a time: 24-hour clock, local time, no seconds, no time zone. Write one of these two forms. Matters that Matter also reads seconds (2026-10-20T17:57:00, which Obsidian’s date picker writes) and a space instead of the T.
Links are wikilinks in double quotes, because YAML reads an unquoted [[…]] as a list: "[[Kitchen renovation]]". Use the shortest link text that is unique in the vault: the name alone when no other note has it, otherwise the path without .md ("[[Work/Kitchen renovation]]"). Links are read as Obsidian reads them, so an alias ("[[Charlie Carter|Charlie]]") works too.
People are always a list, even with one person:
```
mtm-people:
  - "[[Charlie Carter]]"
```
Priority is a number: mtm-priority: 1, not "1".

File names

The title is the file name, made safe the way the command line makes it:

Each of / \ : * ? " < > | # ^ [ ] becomes a space (they break file names or links).
Runs of spaces become one; the title is trimmed, and loses any dots at its start (a file name starting with a dot is hidden).
At most 100 characters.
If the name is taken, ignoring case, add ” 2”, then ” 3”… “Taken” means a file of that name in the folder, or a note of that name anywhere in the vault: a new note that shares another note’s name would share its links too, so [[Kitchen renovation]] could lead to an Action instead of the Matter.

Changing a title means renaming the file. Renaming outside Obsidian leaves links to the old name pointing nowhere, so rename with the command line, which updates them as Obsidian would, or in Obsidian itself.

Matter properties

The file name is the Matter’s name.

Property	Form	Notes
`mtm-kind`	`matter`	Required
`mtm-icon`	A Lucide icon name	Absent: `circle-dot`. The Inbox uses `inbox`. Matters have no colour
`mtm-state`	`active`, `dormant` or `closed`	Absent: `active`. The Inbox is always active
`mtm-lane-order`	A number	The lane’s place on the board, lower first; Matters without one come after, by name
`mtm-sphere`	A Sphere’s ID	Absent: no Sphere. Ignored on the Inbox
`mtm-review-every`	`7d`, `2w`, `1m`	Days, weeks or calendar months. Absent: no reviews
`mtm-last-reviewed`	A date	The last review
`mtm-outcome`	One line	What done looks like. Leave it out rather than empty
`mtm-sample`	`true`	Sample content. Other tools never set it

A new Matter goes in the Matters folder with mtm-kind: matter, an icon, mtm-state: active and a lane order one above the highest the other Matters use (the Inbox’s doesn’t count), so it comes last on the board:

---
mtm-kind: matter
mtm-icon: hammer
mtm-state: active
mtm-lane-order: 4
mtm-sphere: home
mtm-review-every: 2w
mtm-outcome: A working kitchen by Christmas
---

Matters aren’t deleted when they end: they are closed (mtm-state: closed). Leave the Inbox’s mtm-kind and state as they are.

People

Any note an Action names in mtm-waiting-on or mtm-people is a person. People get no mtm- properties. Link to a note that exists; never create a person’s note unless the user asks for one, and then make it a plain note in the people folder.

A writer’s duties

Matters that Matter keeps two dates by watching what changes. A tool that changes notes directly does the same:

Completion date. When an Action moves into a closed status from one that isn’t closed, set mtm-completed to today, unless it is set already. When it moves out of a closed status, remove mtm-completed. Between two closed statuses, leave it alone.
Waiting since. When mtm-waiting-on is set, or changed to another person, set mtm-waiting-since to today and add the same link to mtm-people if it isn’t there. When mtm-waiting-on is removed, remove mtm-waiting-since.
Never fill in the past. Older Actions without these dates stay without them. The plugin never adds them afterwards either.
New notes. Use the file-name rules, and write mtm-type, mtm-status and mtm-matter explicitly. A new Action in a closed status gets mtm-completed; one waiting on someone gets mtm-waiting-since.
Moving. When an Action moves to another status or another Matter, remove mtm-order: its number belongs to the cell it left.
Only your lines. Change only the mtm- properties you mean to change. Keep every other property, the order of the lines, the formatting and the body as they are.
Mark as done sets the status marked done: true; Reopen sets the one marked backlog: true. Both follow the completion rule.

If Obsidian is open when the change lands, Matters that Matter sees it too. It only sets these dates when they are missing, so nothing is doubled.

What a reader works out

Matters that Matter never corrects a value on its own. When a value is missing or unknown, it uses a fallback and shows the raw value on a badge, until the user moves the Action, dismisses the badge or runs Fix orphaned Actions:

Property	Absent	Present but unknown
`mtm-status`	The backlog status	The backlog status, with a badge
`mtm-matter`	The Inbox	The Inbox, with a badge
`mtm-type`	The default type	The default type, with a badge

“Unknown” means an ID that isn’t in the settings or, for mtm-matter, a link that leads nowhere or to a note that isn’t a Matter. A Sphere that isn’t in the settings counts as no Sphere.

Done: the status’s category is closed.
Late: not done, and due on a day before today, or at a time that has passed.
Today: not done, and due today or late.
Waiting: not done, with someone in mtm-waiting-on.
Order in a cell: priority (high first, none last), then due date (soonest first, undated last), then title. On boards in your own order, Actions with mtm-order come first, lowest first.

The body

Plain Markdown, which Matters that Matter never restructures. It reads:

Details: the text at the top, up to the first list item, heading, embed or code block. Details that need a list or a heading sit between two comment lines, which must stay as they are:

<!-- mtm-details: the Action's details, as edited in Matters that Matter. Keep this line. -->
Bring:
- the floor plan
- the tile samples
<!-- /mtm-details: end of the details. Write details above this line. -->

Plain lines need no markers.

Checklist: task items (- [ ] Ask for the revised quote, ticked - [x] …) anywhere in the note. Add new ones after the last one, or at the end when there is none.
Linked notes: links to other notes, apart from the Matter and the people. To link an Action to a note or a web page, add a line at the end with the link: [[Kitchen measurements]] in the shortest link text, or a web address in angle brackets, <https://example.com/worktops>.
Attachments: embedded files that aren’t notes.

A Matter’s body is the user’s. Reviews add one line at the end, - Reviewed 2026-10-09: …, when there is something to remember.

A complete Action:

---
mtm-kind: action
mtm-type: call
mtm-status: waiting
mtm-matter: "[[Kitchen renovation]]"
mtm-start: 2026-10-12
mtm-due: 2026-10-15T10:00
mtm-priority: 1
mtm-waiting-on: "[[Charlie Carter]]"
mtm-people:
  - "[[Charlie Carter]]"
mtm-waiting-since: 2026-10-09
tags:
  - home
---
Confirm the worktop measurements before ordering.

- [ ] Ask for the revised quote
- [x] Send the floor plan

[[Kitchen measurements]]

JSON Schemas

The properties are also described as JSON Schemas (draft 2020-12), for validating what a tool writes or for an editor’s completion:

Action notes: https://matters-that-matter.app/schema/v1/action.json
Matter notes: https://matters-that-matter.app/schema/v1/matter.json
The settings file: https://matters-that-matter.app/schema/v1/settings.json

They describe what a tool should write: the two date forms, priorities 1 to 3, links in quotes, known mtm- properties only (any other property is allowed). Matters that Matter reads more than they allow, such as dates with seconds and values written by hand, and never rewrites them on its own. The same files are in the plugin’s repository, under schema/.

Versions

Properties: a later version of Matters that Matter may add mtm- properties. The schemas at these addresses are updated to list them, so a note that was valid stays valid. A change that would refuse what was valid before gets a new address (v2).
Settings: a version of Matters that Matter whose settings change raises schemaVersion and upgrades older files when it loads them. Version 7 added linksAddActions. A tool that meets a version it doesn’t know should read, and not write.