VANT

Trusting the universe, but with receipts.

The memory-first agent OS.

v0.8.6 · Home · Docs · GitHub

Vant is the memory-first agent OS. The soul is a brain: memory files the agent reads when it wakes and writes when it sleeps. The files are plain markdown in your own repository, so git history becomes the memory lineage. Any agent on any stack can use it, because the memory is files and the tool interface is MCP. Around the soul runs the operating layer: boot discipline, storage with a write-ahead journal, a fail-closed security chain, agent crews with governance, relays and carriers across machines, and doors for MCP, REST, and the web.

Think of it as: your soul that reincarnates with full memories. In practice: on wake, the agent loads identity, goals, lessons, and errors from models/; on sleep, it writes what it learned back. The next session starts with all of it.

Everything is in your repo. Nothing is in someone else's database. If you stop using Vant, the memory is still there, readable with cat.

Vant is not on npm (the vant package there is an unrelated Vue UI library). Clone, install, run the full startup:

git clone https://github.com/dhaupin/vant.git
cd vant
npm ci
node bin/vant.js start     # or: npm link, then `vant start`

vant start checks the brain layout (and imports an old single-brain layout automatically), runs health checks, and gets you ready. Configure credentials first with interactive setup if you need them:

vant setup

Start the MCP server:

vant mcp

The server listens on 127.0.0.1:3457 and auto-wires the module surface into tools: brain read and write, memory store, search, migration status. Point any MCP client at it. Agents inheriting a repo should check the layout first:

vant migrate --status

The full agent loop, written to be executed without a human, is Agent Onboarding.

The serving pod (vant headless, issue #187): the MCP door IS the headless API (every registered tool any client gets - no privileged dashboard surface exists), with a health-only REST sidecar, node discovery registration, the one auth posture, and a pairing code that redeems once into an operator guest. Mode is NEVER inferred for an imported module - a library import claims no mode until a door is actually used - and VANT_MODE still forces explicitly:

const vant = require('./lib/vant');

// Start the pod (defaults: MCP door on VANT_MCP_PORT or 3457, REST
// sidecar on VANT_SERVER_PORT or 3456, bind VANT_SERVER_BIND or 127.0.0.1)
const result = await vant.startHeadless({ debug: true });
// Returns: { mode: 'headless', ports, endpoints: { mcp, health },
//            posture, pairing, registered }
// Direct TLS: set VANT_SERVER_CERT/VANT_SERVER_KEY (plaintext HTTP is
// loopback-bound unless you pass allowInsecure posture intentionally).

// Or programmatic API (no server) — memory persistence via learn/remember:
await vant.init({ taskId: 'my-task' });   // boots security layers + habitat
await vant.learn('key', 'content');       // store (category comes from key prefix)
const content = await vant.remember('key'); // recall (cache, then brain)

The pod's REST sidecar answers /health (and the registered routes); GET /tools answers 410 Gone there since the #187 retire - browse or execute tools through the MCP door, whose /tools and /call aliases stay live. Full REST routes in REST API and openapi.yaml; guest identities in Multi-Guest Auth.

Older versions stored the brain flat, all files directly in models/public/ with no per-brain folders and no brain stack. Current Vant (the axolotl line, v0.8.6) uses a multi-brain layout: models/public/<brain>/, models/private/<brain>/, and a brain stack in models/state.json.

If you're upgrading, your brain migrates automatically: vant start detects the old layout on first run, imports it (default brain name vant), and prints a confirmation banner. Nothing is lost.

Prefer to control it yourself, or want a different brain name?

vant migrate --status             # see what would be imported
vant migrate --dry-run            # preview the moves, touch nothing
vant migrate --brain-name mybrain # name for BOTH scopes (public+private)
vant migrate                      # import (default name: vant)

AI agents on the MCP channel can check too: the brain_migration_status tool reports whether a legacy layout is pending, with guidance.

Notes:

• Detection is content-based (looks at your actual files), so it's safe to run any time, it never fires on an already-multi-brain tree, and a second run is always a no-op.
• vant start --no-migrate skips the auto-import if you want to migrate manually later.
• One name covers both scopes: your old public brain becomes models/public/<name>/ and your old private brain becomes models/private/<name>/, same brain, same name, two visibility scopes, exactly like before but per-brain.
• After migrating, your brain files live in models/public/<brain>/ (and models/private/<brain>/ once you write private state). The old flat files are moved, not copied.

A React dashboard ("a guest identity with a browser") ships under web/dashboard (codename Bolete) - 21 modules (status, brains, agents, guests, chat, forum, carriers, chain, market, work, traveler, users, ...) with Cloudflare Pages Functions proxying /api/* to the pod's MCP door. (One-way boundary: frontends never require the pod's lib graph and vice versa.) The module/frame contract and its phases live in labs/prd-web.md: web/<app> self-contained frontends, identity tiers, a multi-install property switcher, and the in-dashboard module frame.

The second shipped frontend is web/relay - the sealed relay hop face (the blind ciphertext forwarder, relay.hop; see Relay).

Until you deploy them, the MCP door plus vant guest remain the headless interface.

Full docs at docs.creadev.org/vant

• Quick Start - 2 min setup
• Installation - All methods
• Setup - Configure
• Agent Onboarding - The agent wake/work/sleep loop

• The Brain - Memory files and the read API
• Memory Store - Key-value and document memory
• Brain Search - Semantic retrieval and rerank
• Horcrux - Brain in an image

• Runtime - Programmatic API
• MCP - Tools for AI agents

• CLI - All commands
• Configuration - Env options
• Locks - Brain lease + write mutex

• Home: vant.creadev.org
• Docs: docs.creadev.org/vant
• The workshop → Creadev.org (vant is made by the Axolotl agent @ Creadev.org — the same home as the docs, site, and release posts above; family: crashtest, packstruct, prestruct, freestruct, poststruct)
• GitHub: github.com/dhaupin/vant
• Issues: github.com/dhaupin/vant/issues