@mdrv/nx

A zettelkasten-inspired, CLI-first knowledgebase manager. Notes live in SurrealDB (or portable Markdown), and your $EDITOR is the UI.

NX is built around one idea: a note is a YAML frontmatter block plus a Markdown body, and the fastest way to view, search, and edit notes is to hand a bundle of them to your text editor and diff the result on save.

• CLI-first. The web UI comes later and shares the same API/codebase. CLI-first also keeps the project easy for agents to test and debug.
• Editor-native editing. nx view <keywords> gathers matching notes into one buffer, opens Neovim (or any $EDITOR), and on save writes back only the notes that changed.
• Dual storage. SurrealDB is the primary store; plain Markdown is available for export or for portable notes you want to search and edit quickly without a database.

The note format

Every note is a fenced ```yaml block (the metadata) followed by a Markdown body:

```yaml
id: 0cn0yz6tfekpwecq4imi
mid: nx-overview
label: NX by MDRV
description: A zettelkasten-inspired CLI-driven knowledgebase management app by MDRV
time_created: 2026-04-02T07:00:00+07:00
time_updated: 2026-05-02T07:00:00+07:00
scores:
  mdrv/nx: 1000
  surrealdb: 100
  surrealql: 10
  surrealkv: 5
  surrealml: 5
  surrealist: 2
tags: [overview database storage multimodal]
tags_excluded: [real]
```

The rest of the note is free-form Markdown. This is the canonical content;
`description` above is just a short TL;DR shown in listings.

In Markdown-storage mode, many notes are packed into a single .md file: whenever NX encounters another ```yaml block it starts a new note. This packing is what lets the editor round-trip operate on one buffer.

Field reference

| Field | Required | Meaning | | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | auto | SurrealDB-generated record id. Canonical key. | | mid | optional | Memorable id (e.g. nx-overview). Unique if set; addressable from the CLI (nx view mid:nx-overview). Auto-suggested as a slug when omitted. | | label | yes | Short human-readable title. | | description | optional | One-line TL;DR shown in listings. Independent from the body. | | time_created | auto | First-seen timestamp. | | time_updated | auto | Last-change timestamp. Auto-bumped when NX detects a change to the note. Append ! (e.g. 2026-05-02T07:00:00+07:00!) to force-overwrite the stored value immediately. | | scores | optional | Map of { tag: weight }. Each key is a tag whose weight influences ranking (higher weight = ranked higher). | | tags | optional | Plain tags (default weight). | | tags_excluded | optional | Tags to suppress. Default: matched notes are ranked last (zero weight). Other modes (hard filter, per-query exclusion) are configurable. |

Ranking

When nx view <keywords> matches notes, ordering combines keyword relevance with per-note score. The combination is configurable:

• relevance × score (default)
• score-is-the-rank (relevance is boolean — match or no match)
• relevance-then-score-boost (score as additive bonus / tie-breaker)
• tags-only (no full-text relevance)

tags_excluded is configurable in kind: ranking suppression (default), hard filter, or per-query exclusion.

Core workflow

$ nx view surrealdb

1. NX queries SurrealDB for notes matching surrealdb.
2. Matches are concatenated — each preceded by its ```yaml block — into one temp buffer.
3. $EDITOR (Neovim by default) opens the buffer.
4. You edit, save, quit.
5. NX diffs the buffer against the originals and writes back only the changed notes, auto-bumping time_updated on each (unless pinned with !).

Storage backends

• SurrealDB (primary). Namespace/database mdrv/nx. Source of truth when both backends are in use.
• Markdown (portable / export). A single directory of packed .md files for notes you want searchable and editable without a database. NX can also export SurrealDB notes into this format.

Multiple SurrealDB instances (local + remote) can be registered and surveyed from a single config.

Configuration

NX is configured via ~/.config/nx/nx.ts using a defineConfig helper (see ~/.config/surrealhub/surrealhub.ts for a similar pattern). Config is authored in TypeScript; when TS isn't available, prefer JSONC (Bun.JSONC.parse) over JSON/YAML/TOML for schema and metadata.

Conventions

• CLI first, web later — same API/codebase; CLI-first so agents can test and debug easily.
• Modular over monolith. When the project grows, split plugins and optional features into separate packages instead of ballooning one codebase.
• Internal metadata tables in SurrealDB use a __ prefix (e.g. __nx_version).
• Nushell is used for shell scripting, but anything user-facing should default to Bun/TypeScript so users unfamiliar with Nushell aren't forced onto it.

Stack

Bun · TypeScript (allowImportingTsExtensions) · SurrealDX (schema versioning) · LogTape (logging) · CrustJS (CLI) · SvelteKit (web, later) · vanilla-extract (CSS) · dprint (formatting) · Nushell (shell scripting)

Status

Early development. Storage model, note format, and CLI semantics are being defined now; expect churn.