Follow it start to finish on a scratch checkout. It teaches the shape of the tool by doing; it is
not a complete reference. When you need to look something up, see Reference; when you
have a specific task in mind, see How-to guides.
By the end you will have installed neurokeeper, listed its engines, and run a read-only engine that
produces a JSON report - without touching any of your files.
Prerequisites
Python 3.9+ (the engines are plain Python; they run on Linux, macOS, and Windows).
A terminal. That is all you need for the CLI path.
(Optional)Claude Code, if you want to try the plugin adapter in the last step.
Step 1 - Get the code
Either install the published package, or work from a checkout:
# from a checkout (editable, with test/lint deps):git clone <neurokeeper-repo-url>cd neurokeeperpip install -e ".[dev]"# or, once published:pipx install neurokeeper # or: uv tool install neurokeeper
This puts a single console command, neurokeeper, on your PATH. That command is a dispatcher: it
runs the same engine files the plugin and CI use - one codebase, no fork.
Step 2 - List the engines
neurokeeper --list
You should see the available engines (for example taxonomy-inventory, frontmatter-lint,
memory-consolidate, registry-generate). Each name maps to one deterministic script. Full descriptions
live in the Reference engine catalog.
Step 3 - Run your first engine (read-only)
Every engine defaults to report-only: it never writes anything unless you explicitly pass --apply.
Run the capability registry generator, which just prints the catalog of engines as markdown:
neurokeeper registry-generate
Now ask an engine for machine-readable output - the --json flag is part of every engine’s contract:
neurokeeper registry-generate --json
You just exercised the core contract: a deterministic engine, a --json output, and zero side effects.
Step 4 - Point an engine at some content
Engines that work over a notes vault read their target from the environment, so the same binary works
against any vault:
export VAULT_ROOT="/path/to/your/notes" # Windows PowerShell: $env:VAULT_ROOT = "C:\path\to\notes"neurokeeper taxonomy-inventory --json
This produces a read-only inventory of naming / tags / frontmatter. Still nothing is written - inventory
is a read-only capability. (For the env vars each engine reads, see the
Reference: environment configuration.)
The frontmatter engines also need a schema
frontmatter-lint and frontmatter-fix validate notes against your schema-as-code, so they read a
second variable, FRONTMATTER_SCHEMA. Copy the shipped example and point at it:
cp config.example/frontmatter-schema.example.yaml my-frontmatter-schema.yaml # then editexport FRONTMATTER_SCHEMA="$PWD/my-frontmatter-schema.yaml"
If it is unset and no schema is found, those engines print a one-line message telling you how to set
it (instead of a traceback). The taxonomy-inventory engine you ran above needs no schema.
Step 5 - Let init do the configuring
Steps 3 and 4 showed the engines one at a time, which is how you learn what they are. init is how
you set one up for real: it looks at your collection, offers the engines with the config each one
costs, and writes that config.
The first line of output is the number of notes it can see. Check it. If that number is wrong,
the root is wrong, and every “clean” report you get afterwards would be a report about the wrong
place. Then run it for real:
Answer three questions and it writes into <collection>/.neurokeeper/, prints every file it wrote,
tells you which variables to export, and finishes by running doctor --check in front of you.
--schema derive reads your collection instead of asking you to describe it
It drafts a schema from the frontmatter you already use: fields with a handful of values become
enumerated axes, free-text fields become open. The draft is written provenance: harvested and
says so in the file, because it describes what your collection contains, not what it should.
Read it and delete the axes that are accidents before treating it as canon.
It configures; it never writes content
No notes, no folders, no naming convention. A tool that invents a structure on day one has chosen
your collection’s shape before you have.
Step 6 - Try the Claude Code adapter (optional)
The CLI you just used is one face of the core. The Claude Code plugin is another - the same engines,
exposed as skills and hooks:
Inside Claude Code you can then invoke the bundled capability (for example the memory-audit skill), which
runs the identical engine and adds an LLM-judgment step on top of the engine’s output.
What you learned
neurokeeper installs as one dispatcher CLI that runs deterministic engines.
Every engine speaks the same contract: --json output, exit codes, report-by-default.
The same engines back the CLI, CI, and the Claude Code plugin - different adapters, one core.
Next steps
Do a real task: How-to guides (reconcile tags, run the memory-audit, add an engine).