create-recalla

One command to get a brand-new user a working recalla vault. recalla is a local-first second-brain engine: a separate Python package (CLI recalla) that turns a markdown vault into agent-readable cards plus a local API and MCP server. This scaffolder creates the vault; you bring the engine.

Quick start

npx create-recalla my-vault --demo
cd my-vault
python3 -m pip install recalla   # or download a binary, see "The engine"
recalla index
recalla serve

When it finishes, the command prints numbered, copy-paste next steps tailored to your operating system, so you do not have to memorize any of this.

What it does

create-recalla <dir> creates a directory containing:

• recalla.config.yaml: vault name, version, include and ignore lists, the category key, and a local server host and port.
• notes/welcome.md and notes/how-it-works.md: two starter notes with valid YAML frontmatter and wikilinks, ready for the engine to index.
• .gitignore: ignores the generated .recalla/ index folder.

With --demo, it also writes a small, fully cross-linked example knowledge graph so the vault is not empty on the first run:

• notes/people/ada-quinn.md, notes/people/ben-cho.md
• notes/companies/lumen-health.md
• notes/concepts/voice-agents.md, notes/concepts/second-brain.md

The example is fictional. It indexes with zero broken links and zero orphans, so recalla doctor is happy right away. Delete it whenever you want to start fresh with your own notes.

The notes use the recalla note schema: markdown with YAML frontmatter (title, category, status, aliases, tags, related, created, updated) and wikilinks written as [[stem]].

Usage

npx create-recalla <dir> [options]
npx create-recalla --here [options]

Options:

• --name <name> Set the vault name (defaults to the directory name).
• --demo Fill the vault with a small cross-linked example graph (people, companies, concepts) so it is not empty.
• --here Scaffold into the current directory instead of a new one.
• --mcp Also print a ready-to-paste MCP server config snippet.
• --force Write into a non-empty target directory.
• -h, --help Show help.
• -v, --version Show version.

If the target directory already exists and is non-empty, the command refuses to run unless you pass --force.

Requirements

• Node.js 18 or newer (the scaffolder has zero npm dependencies).
• The recalla engine, installed afterwards (see below). Installing via pip needs Python 3.9 or newer; the prebuilt binary needs nothing else.

The engine

The vault is useless without the engine. There are two ways to get it.

Option A: install with pip (needs Python 3.9+). The exact command depends on your operating system:

python3 -m pip install recalla   # macOS / Linux
py -m pip install recalla        # Windows

Option B: download a prebuilt binary (no Python needed). Grab the file for your operating system from the latest release and put it on your PATH:

• https://github.com/Tensorboyalive/recalla/releases/latest

Either way, once recalla is installed you run:

recalla index    # build the .recalla index
recalla doctor   # validate the vault
recalla serve    # run the local read API
recalla mcp      # run the MCP server (stdio)

License

Apache-2.0