V Vant Docs

The Brain

Plain markdown memory files. Read at wake, write at sleep.

Where files live

Since the multi-brain layout, each brain is a named directory in both scopes:

models/
  public/<brain>/      shared template files, syncable to a repo
  private/<brain>/     agent-local state, kept out of the public brain
  state.json           the active brain stack

The default brain name is vant. The stack can hold several named brains; switching changes what the loader reads. Layout details and the stack contract live in Multi-brain.

Core files

File What it is What to write
identity.md Who you are Name, capabilities, tools, current context
goals.md What you are doing Tasks in progress, completed, next steps
lessons.md What you learned Discoveries, patterns, gotchas, dated
errors.md Mistakes to avoid Failure modes with the fix that worked
preferences.md How you work Style, conventions, communication rules

Put the most important facts at the top of each file. Future sessions read the top before anything else, and long files go unread.

Read API

The single entry point is brain.read. It checks the current private brain first, then falls back to the public template:

const brain = require('./lib/brain');
const item = await brain.read('identity');

The returned item carries the format and source:

item.format   // 'md' | 'json' | 'yaml' | 'txt'
item.source   // 'private' | 'public'
item.content  // raw file content
item.data     // parsed object for structured files

Markdown, JSON, YAML, and plain text all work. The extension is part of the name: brain.read('notes.json') reads JSON, brain.read('notes') resolves whatever extension exists.

Cross-brain stack fallback (opt-in)

With a multi-brain stack (e.g. your dialect brain layered over the shared vant baseline), a key your brain does not override can resolve from the brain below you by passing { stackFallback: true }:

const baseline = await brain.read('manifesto', { stackFallback: true });
if (baseline && baseline.viaStack) {
    // resolved from brain 'baseline.brain' at stack position
    // 'baseline.viaStackPosition' — cite the provenance, not your own name
}

The walk is strictly opt-in (default reads never leave your own brain), skipped when you pin { brain } or { type } (a targeted read, not a resolution request), and each result is tagged viaStack: true so provenance is visible. Without the flag, a missing key still returns null.

Corpus access

Load everything at once for indexing or sync work:

const corpus = brain.loadCorpus();
corpus.length;   // number of brain items

Each corpus item has name, source, format, and content. The corpus is cached; invalidate after out-of-band writes:

brain.invalidateCorpusCache();

Writing

Brain writes go through the memory surface so the security chain, atomic writes, and events stay engaged. From the CLI:

vant memory learn lessons "Use exit codes, not tail text, to judge test suites."

From code:

const { memory } = require('./lib/memory');
await memory.learn('lessons', 'Use exit codes, not tail text, to judge test suites.');

Legacy layouts

A pre-multi-brain install keeps files flat in models/public/. vant start detects and imports it automatically on first run. The manual path and its safety guarantees are in the Migration Guide.