Quickstart

This workflow creates a throwaway Git repo, initializes repo .memzoi/ memory plus local runtime state, writes the built-in sample memory, recalls it, checks a risky command, exports an agent projection, and prints MCP configuration.

Install Memzoi

Mac or Linux:

curl -fsSL https://raw.githubusercontent.com/Zokiio/Memzoi/main/scripts/install.sh | sh

Windows:

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/Zokiio/Memzoi/main/scripts/install.ps1 | iex"

The install script downloads the latest release binary and does not require Cargo.

Or install from a source checkout:

make install

Then verify the binaries:

memzoi --version
memzoi-mcp --version

Run the first workflow

mkdir -p /tmp/memzoi-demo
cd /tmp/memzoi-demo
git init

Initialize Memzoi memory and try recall, precheck, export, and MCP config:

memzoi init
memzoi doctor
memzoi quickstart --apply-sample
memzoi search quickstart
memzoi context --task "remember quickstart setup"
memzoi handoff --task "switch agents after quickstart"
memzoi precheck --command "rm -rf .memzoi"
memzoi export agents-md
memzoi mcp config --project-root .

memzoi quickstart --apply-sample proposes, approves, and applies one sample repo memory. It is idempotent: running it again should reuse the existing sample record instead of creating duplicates.

Preview the workflow without writing the sample

memzoi quickstart

Use this when you want the command sequence before letting Memzoi write a sample memory.

What init creates

memzoi init creates the canonical memory directory in the discovered project root:

• .memzoi/records/

It also creates local runtime state under ~/.memzoi/projects/<repository-key>/:

• config.toml
• shared.db for local/session memory and DB-local proposals shared by linked worktrees
• worktrees/<worktree-key>/index.db for the active worktree's disposable canonical index
• worktrees/<worktree-key>/exports/

The repository key is derived from Git's canonical common directory and is therefore stable across linked worktrees. Each worktree receives its own index and generated exports. Opening a newly linked worktree builds its index from that checkout's .memzoi/records/; it does not require another memzoi init.

Project root discovery prefers an ancestor with .memzoi/records/, then an ancestor Git root, then the current directory.

Health check

memzoi doctor --json

doctor checks the project root, records directory, shared runtime, current worktree index, exports directory, and whether memzoi-mcp is available on PATH. Missing canonical records and missing shared runtime are reported separately.