Quick start

You need Node.js 20 or newer and a folder of Markdown notes (an Obsidian vault, or an empty folder).

1. Start the engine

npx -y datanotes serve --vault /path/to/vault

It serves the HTTP API on http://127.0.0.1:27150. The settings and the owner’s token are in <vault>/.datanotes/service.json.

2. Make a table and add a row

From code, with the client that comes with the package (npm install datanotes):

import fs from "node:fs";
import { DatanotesClient } from "datanotes/client";

const { httpServerToken } = JSON.parse(fs.readFileSync("/path/to/vault/.datanotes/service.json", "utf8"));
const db = new DatanotesClient({ url: "http://127.0.0.1:27150", token: httpServerToken });

await db.call("create_table", {
  name: "book",
  options: { filename: "{title}" },
  columns: [
    { name: "title", type: "string", required: true },
    { name: "pages", type: "integer", min: 1 },
    { name: "status", type: "enum", values: ["to read", "reading", "read"] },
  ],
});
const r = await db.call("insert_row", { table: "book", values: { title: "Dune", pages: 412, status: "read" } });
console.log(r.ok ? r.value.plannedCreates : r.value); // the new note, or why nothing was written

The table definition goes into Database/database.yaml, and the book becomes a note in Database/main/public/book/:

---
table: main.public.book
id: 0199b6a2-7c1e-7d40-9a51-3f0c2b8e4d11
title: Dune
pages: 412
status: read
---

Edit the note by hand whenever you like: the engine follows the change. If a value breaks the table, check_table reports it.

3. Let agents use it

Agents connect through the MCP server, a separate package: see Connect agents.

Next

• How it works: tables, rows, the journal.
• Operations: everything the API can do.
• JavaScript client and HTTP API.
• Security: what each token can do.