PRE-ALPHA · SOURCE CHECKOUT

Give agents the memory they need.

Nonstop keeps a project archive on disk and selects the bounded working set that belongs in context now. Ranking is deterministic, explainable, and makes zero model calls.

NonstopLOCAL MEMORY

Build Nonstop into a coding workflow without sending project memory to a remote memory service.

$ npm run build$ cd /path/to/your-project$ node /path/to/nonstop/packages/cli/dist/bin.js init✓ initialised .nonstop

QuickstartBuild the source checkout and recall your first memory.Engine conceptsUnderstand ranks, grades, budgets, and score terms.Agent surfacesUse the local CLI, MCP server, or Claude Code hooks.

Start hereRun it locallyBuild, initialise a deck, remember one decision, and recall it.Read guide UnderstandInspect every scoreSee exactly why a memory entered the working set.Read guide IntegrateConnect an agentExpose the four shipped tools over the local MCP server.Read guide

Get started

Quickstart

The registry package is not published yet. Today, the supported route is an authorised source checkout on Node 22.13.0 or newer.

Use the source checkout.

npx -y @nonstop/cli init is not available during pre-alpha. The commands below run the built entry directly.

1. Build and initialise

Install the locked dependencies and build in the Nonstop checkout. Then change into the target project and invoke the built CLI through its absolute path so the deck is created in the right place.

# first, from the authorised Nonstop source checkout
npm ci
npm run build

# then initialise the project whose memory Nonstop should own
cd /absolute/path/to/your-project
node /absolute/path/to/nonstop/packages/cli/dist/bin.js init

2. Remember and recall

Memories are content-addressed and local. An identical remember command is idempotent; recall fills the requested token budget using the rank cascade.

node /absolute/path/to/nonstop/packages/cli/dist/bin.js remember   "Auth tokens are always verified server-side."   --label "auth: server-side verification"   --path src/auth/verify.ts   --subsystem auth

node /absolute/path/to/nonstop/packages/cli/dist/bin.js recall   "how do we verify auth tokens"   --budget 2000

No account or remote service is required.

Nonstop opens no product socket and makes no model call in the ranking path.

Core concepts

An unbounded archive. A bounded working set.

Nonstop does not enlarge a model's context window. It changes which project tokens occupy the window you already have.

Archive sizeUnbounded on diskPortable markdown is the cold-content authority.

Working setO(B) tokensB is the caller-provided context budget.

SelectionO(N) arithmeticEvery non-superseded node is scored today.

Ranking callsZero modelsSelection is reproducible and inspectable.

Cold content lives in memory/, which is designed to open in Obsidian and be committed to Git. The derived index and learned hot state live under .nonstop/ and stay local to each checkout.

Core concepts

Authority and loudness are separate.

Rank says what kind of memory a node is. Grade says how loudly that node should speak right now.

Ranks reserve the budget

Rank	Holds	Share	Cap
`JOKER`	Project constitution	4%	≤ 7
`ACE`	Subsystem charter	10%	≤ 24
`FACE`	Consolidated concept	26%	Uncapped
`SET`	Raw chunk	60%	Uncapped

Unused capacity cascades downward only: JOKER to ACE to FACE to SET. Rank is monotonic, so a node is never demoted out of authority.

Grades control voice

Grade	Meaning	γ
`RED`	Invariant or architecture rule	1.0
`YELLOW`	Active work and live context	0.7
`GREY`	Settled reference	0.4
`BLUE`	Cold or superseded history	0.1

Core concepts

Recall you can replay and explain.

Each memory receives one composite score from five bounded terms. Identical input at an identical tick produces identical output.

S = 0.30·voice + 0.25·elo + 0.15·decay + 0.10·grade + 0.20·match

Voice

A fast and slow EMA pair detects whether relevance is rising or cooling.

Elo

Outcome feedback separates memories that help from memories that merely look recent.

Decay

A fixed half-life rewards recent touches without erasing durable authority.

Grade

A deterministic classifier and lifecycle rules set current loudness.

Match

BM25-lite over labels and paths supplies lexical query relevance.

Run nonstop explain through the built CLI to print every weighted term. The five displayed values sum to the score, which makes regressions bisectable and retrieval decisions auditable.

Agent surfaces

The local CLI

One built entry exposes deck creation, retrieval, feedback, inspection, vault sync, and recovery.

init

Create the local deck and portable markdown vault.

remember

Add a durable decision, invariant, reference, or snippet.

recall

Select a bounded hand for a query and optional token budget.

feedback

Settle a durable retrieval round with a host outcome.

explain

Show the five weighted terms behind one memory’s score.

stats

Inspect ranks, grades, hot bytes, tokens, and the deck clock.

sync

Drain authenticated markdown-vault outbox batches.

reindex

Rebuild and crash-safely install the derived index.

Use node /absolute/path/to/nonstop/packages/cli/dist/bin.js help for the built-in reference. Unknown flags are rejected by strict parsing; there are no aliases or implicit global options.

Agent surfaces

MCP, without a hosted relay.

The built CLI implements JSON-RPC 2.0 over stdin and stdout and reopens the local deck for every tool call.

{
  "mcpServers": {
    "nonstop": {
      "command": "node",
      "args": [
        "/absolute/path/to/packages/cli/dist/bin.js",
        "mcp"
      ],
      "env": {
        "NONSTOP_DECK": "/absolute/path/to/project/.nonstop"
      }
    }
  }
}

nonstop_recall

Select a bounded hand for text, budget, and optional session.

nonstop_remember

Store body, label, path, and subsystem metadata.

nonstop_explain

Inspect one memory's score terms. This tool is read-only.

nonstop_feedback

Settle a durable retrieval round with a validated outcome.

Initialise first.

The MCP server never creates a deck implicitly; run init in the target project.

Agent surfaces

Automatic recall for Claude Code.

Phase 1 ships one host adapter: Claude Code command hooks. Other host adapters remain Phase 4 work.

The hook reads one event from stdin, emits one JSON object on stdout, opens no network connection, and exits zero even if an observer payload is malformed. The next prompt orSessionEnd provides the structural settlement fence.

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "node /absolute/path/to/nonstop/packages/cli/dist/bin.js hook",
        "timeout": 30
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "node /absolute/path/to/nonstop/packages/cli/dist/bin.js hook",
        "timeout": 5
      }]
    }]
  }
}

The excerpt demonstrates the two structural endpoints.

The complete production block also observes tool success and failure. Copy it fromdocs/HOOKS.md in your authorised source checkout before enabling hooks.

Operations

Sync what changed. Rebuild what is derived.

The markdown vault and SQLite index have explicit authority and recovery contracts.

Durable write pathSync the vaultDrain authenticated, ordered outbox batches into memory/.Read guide Recovery pathReindex safelyBuild a verified replacement index, then install it with a retained backup.Read guide

node /absolute/path/to/nonstop/packages/cli/dist/bin.js sync
node /absolute/path/to/nonstop/packages/cli/dist/bin.js reindex

Reindex preserves every cold content field. Hot fields that cannot be reconstructed from markdown reset under the explicit contract: f=0, s=0, r=1200, n=0, with the clock anchored to retained creation time.

Operations

Know which files are authoritative.

Nonstop separates portable content from frequently changing learned state.

memory/Portable cold-content authority

Plain markdown, intended for Git and readable in Obsidian.

.nonstop/Derived local index and hot state

Schema-v4 SQLite plus a compatibility clock mirror; ignored by Git.

.nonstop-vault.lockStable transaction fence

Lives outside replaceable directories so it survives a reindex swap.

Upward discovery stops at the nearest Git or configured project root. SetNONSTOP_DECK or NONSTOP_MEMORY when an explicit location is required.

Operations

Current status and honest boundaries.

Nonstop is pre-alpha. The docs separate verified local behavior from future distribution and host support.

Available now

Node 22 and 24 local build gates
CLI, MCP, and Claude Code hook regression suites
Deterministic ranking and explanation
Markdown outbox, sync, and crash-recoverable reindex

Not available yet

Published npm packages or registry install
Production 1.0 compatibility freeze
Automatic adapters for Codex, Cursor, Gemini, or Windsurf
A hosted account, server, telemetry, or remote memory service