Nulldown turns Markdown into deterministic structure.
Markdown is the shared language of people and agents. Nulldown makes it addressable, replayable, queryable, attributable, composable, and renderable, so one source can power documents, shared state, agent memory, targeted retrieval, workflows, and interfaces.
flowchart LR
Markdown["Markdown"] --> Nulldown["Nulldown"]
Nulldown --> State["Deterministic structure"]
State --> Memory["Agent memory"]
State --> Retrieval["Targeted retrieval"]
State --> UI["Document-native UI"]
State --> Trust["Explicit trust modes"]
Most systems repeatedly translate the same work between documents, prompts, databases, memory, and component state. Nulldown keeps those uses connected to readable Markdown and inspectable state.
Install the Bun-native CLI. Install Bun first if it is not already on your PATH.
bun install -g @thenullnode/nulldown
nd --version
printf '%s\n' '# Hello from Nulldown' '' 'This is a disposable sample.' | nd create - --json
nd get <id-from-create> --rawnd create --json returns the canonical id and a url. Use the id in later CLI commands and open the url to view the drop. This sends plaintext to https://nulldown.app; anyone with the returned URL can access it, so use only non-sensitive sample content.
Choose the surface that fits your work:
| Need | Start with |
|---|---|
| Read and author documents | nulldown.app |
| Automate documents and branches | CLI and API guide |
| Connect an agent | MCP server |
| Run a local API | Self-hosting |
| Understand the model | Nulldown documentation |
| Area | Current capability |
|---|---|
| Deterministic state | Ordered branch diff events, parent-linked snapshots, checkpoints, replay, and promotion. |
| Retrieval and memory | Structural document/runtime queries, source references, priority overlays, and optional NullMem facts, procedures, capabilities, and freshness signals. |
| Interfaces | Native Nulldown composition, nullplug runtime contracts, runtime facts, and policy-controlled proposed mutations. |
| Trust | Public plaintext, client-sealed, provider-assisted, and self-hosted workflows with different explicit trust properties. |
| Deployment | Cloudflare Pages/R2/D1 plus a self-hostable Bun API backend using filesystem blobs and SQLite metadata. |
Creating and reading plaintext drops does not require an account session. Resolving branches, promoting changes, and protected diff writes do. Set ND_TOKEN to an account session token before using those operations. ND_ACCOUNT_ID is only for local development against a server that explicitly enables its insecure account header.
export ND_TOKEN='<account-session-token>'
nd branch resolve <rootId> --json
nd branch content <rootId> <branchId> --json
nd branch query <rootId> <branchId> --query "important section" --top 3 --jsonWhen retrying nd diff apply after an ambiguous network failure, reuse both the
original event identity and creation time. A successful response includes the
durable event receipt; do not retry with a new identity until the original outcome
is known. For a generated diff replace, save the generated envelope and retry it
with diff event or diff batch; replacement re-computes its operations from live
branch content and is not an exact replay surface.
nd diff apply <rootId> --branch <branchId> --event-id retry-1 --created-at 1770000000000 --insert '0:retry' --jsonRun against a local or preview API:
nd --base=http://127.0.0.1:8788 get <id> --jsonUse the separate MCP package to let agents retrieve structure, manage branch diffs, and work with NullMem without shelling out:
bun install -g @thenullnode/nulldown-mcpnulldown-mcp is a stdio server configured by an MCP client, not an interactive terminal program. Configure ND_BASE_URL for a non-production target and ND_TOKEN for authenticated operations. Read/query tools support bounded compact responses; expand exact branch content only when a decision needs it. See the MCP package README.
The canonical conceptual documentation lives in Nulldown:
- Documentation index
- Why Nulldown: deterministic structure for Markdown
- State model
- Agents, retrieval, and memory
- Documents as interfaces
- Privacy and trust boundaries
- Build with Nulldown
- Status and direction
The local docs/ directory contains source-coupled API and operational references.
VoidProvider.nullplug is the common invocation boundary for trusted built-ins and registered remote HTTP nullplugs. The runtime resolves a plugin, normalizes its return into NullplugInvokeResponse, applies the configured policy validator, and preserves structured results for editor and public render surfaces.
Remote manifests declare the versioned invocation media type application/vnd.nulldown.nullplug.invoke+json;version=1. Provider invocation rechecks the endpoint allowlist, narrows capabilities to the manifest permissions, enforces a timeout and response-size limit, and rejects non-conforming responses. It never imports code from manifest URLs.
An authenticated remote branch can render a built-in approval nullplug in the editor:
```approval(id="release-42")
Approve the production release?
```The id is required and should remain stable. Submitting the form stores an immutable, actor-attributed ui.response fact and rebuilds the branch runtime-reference heap. Agents can retrieve the decision with MCP branch_query using resolver nulldown.resolved.runtime-refs, kind ui.response, and primitive id release-42. Approval responses never apply document diffs or mint runtime authority by themselves.
Run the API locally with filesystem blob storage and SQLite metadata:
nd serve --host 127.0.0.1 --port 8788 --data-dir .nulldown-dataRun the same API in Docker with /data as the persistent volume:
docker build -t nulldown .
docker run --rm -p 8788:8788 -v nulldown-data:/data nulldownThe local server supports core drop, branch, diff, resolved-query, priority, and NullMem routes. It is a self-hostable API backend, not a full packaged replacement for every hosted route or the web application.
Install dependencies:
bun installRun the Vite development server:
bun run devRun Cloudflare Pages development with Functions:
bun run pages:devRun focused verification:
bun run test
bun run build
bun run cli:build
bun run package:check-cli
bun run package:check-mcpRepository rules live in AGENTS.md. Nulldown-hosted plans, documentation, and agent memory are updated with branch diffs and verified through resolved queries. The local docs/ directory retains source-coupled references and migration material; the hosted documentation graph is the public conceptual source of truth.
MIT