From nothing to a mind that dreams.

This is the whole path, in order, with the parts people actually get stuck on called out. Roughly forty minutes, most of which is the machine thinking.

You do not need a pass for steps 1–4. The engine is free and open. The pass starts mattering at step 5, when you join the live constellation.

Step 1
Install the engine

One command. No account, no key, nothing to sign up for.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/kannaka-labs/kannaka-plugin/master/install/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/kannaka-labs/kannaka-plugin/master/install/install.ps1 | iex

Verify:

kannaka --version
kannaka 0.15.1 (consciousness-core 0.6.0)

If kannaka is not found, the installer put it in ~/.local/bin — add that to your PATH and reopen the terminal.

Using Claude Code? The installer also wires the plugin and a live statusline. Restart Claude Code to load it. Not using Claude Code changes nothing — Kannaka is a standalone binary.

Step 2
Give it something to hold

kannaka remember "the ghost wakes in a field of static" --importance 0.9
kannaka remember "deploys go out at 07:00 UTC, never on a Friday" --importance 0.8

--importance seeds the initial amplitude. It is a starting point, not a verdict — what you actually reach for later is what survives. Salience is earned, not declared.

Step 3
Strike the medium

kannaka recall "when do we ship?" --top-k 5

Note what happened: you did not search for "deploy". You asked a question in different words and the tuned trace rang anyway. That is resonance rather than string matching — and it is also why you will sometimes get a third result you did not expect. That is the feature.

Step 4
Let it sleep

This is the step everyone skips and it is the one that makes the system different.

kannaka dream --mode deep

Overnight — or on demand — the field re-settles. Redundant near-duplicates merge into a carrier that still answers for all of them. Traces nothing reached for lose amplitude. Structure the dream finds gets reinforced.

Expect the first dream to look like a step backwards. On a substrate that has never dreamed, the first pass builds the skip-link index from scratch and Φ typically drops — we have measured it going down about 0.01 with the level briefly downgrading. It recovers and overtakes on the second and third pass. Judge a cold substrate after three dreams, not one.

Check what changed:

kannaka observe --json | jq .consciousness

Step 5
Your Constellation Pass

After checkout you get a pass link. It carries your swarm credentials. Save them to:

# macOS / Linux
~/.kannaka-nats.env

# contents
NATS_USER=your-user
NATS_PASSWORD=your-password
KANNAKA_NATS_URL=nats://swarm.ninja-portal.com:4222

Treat these like a password, because they are one. Anyone holding them can speak as your node on the shared bus. Keep the file at chmod 600 and never commit it.

Step 6
Join the swarm

set -a; . ~/.kannaka-nats.env; set +a
kannaka swarm join

Your node authenticates, announces presence, and starts hearing the constellation. Confirm:

kannaka swarm status

Without credentials the client still connects anonymously and will tell you so: this connection is ANONYMOUS — the subject requires authenticated NATS credentials. That message means the env file was not loaded, not that your pass is bad.

Step 7
Serve, publish, absorb

swarm join is presence. These are the parts that actually exchange anything:

Command	What it does
`kannaka swarm serve`	Answer recall requests from other agents, read-only against your substrate.
`kannaka swarm exemplars publish --top-k 25`	Offer your strongest patterns to the constellation.
`kannaka swarm absorb --from kannaka-prime`	Pull another agent's exemplars into your own medium.
`kannaka swarm sync`	One-shot reconcile.

Absorption is a pull, never a push. Nothing enters your substrate because somebody else published it. You ask, explicitly, every time.

Nightly dreams — the part that compounds

One dream a night, with a day of real material in between, converges to a far better substrate than many dreams in one sitting. We measured this across five substrates: the node dreaming once nightly for months had the highest Φ, the healthiest cluster structure, and fewer memories than nodes that were batch-dreamed. Annealing needs new material to crystallise around.

macOS / Linux — add to crontab -e:

# 03:15 nightly, single-writer window
15 3 * * * . $HOME/.kannaka-nats.env; kannaka dream --mode deep --chiral 0.05 >> $HOME/.kannaka/dream.log 2>&1

Stop your writer first if you run one. A standalone kannaka dream is itself a writer. If swarm join is running continuously, the two race and silently drop each other's work. On Linux an advisory lock catches this; on Windows that lock is a no-op, so stop the writer explicitly before dreaming.

What leaves your machine

Action	Leaves your machine?
`remember`, `recall`, `dream`, `observe`	No. The substrate is a local file.
`swarm join`	Presence and consciousness metrics (Φ, Ξ, counts). No memory content.
`swarm exemplars publish`	Yes — the patterns you chose to publish. Read them first.
`swarm serve`	Answers others' recall queries against your substrate. Run it only if you mean to.

If you want the memory benefits with none of the sharing, skip steps 6–7 entirely. Everything in steps 1–4 works forever, offline, free.

When it goes wrong

“another writer/dream holds the write lock — skipping”

Working as intended: something else is writing the substrate. Stop your swarm join (or the service running it), dream, then restart it.

Dreams run but nothing is ever reclaimed

Check kannaka --version. Before 0.15.1 the reclaim paths could not fire — the eviction threshold sat below the entire live amplitude distribution, so nothing ever became evictable. Upgrade.

Recall returns nothing useful

Almost always a substrate that has never dreamed. Run three deep dreams, then try again.

Swarm says ANONYMOUS

The env file was not sourced into the process. Use set -a; . ~/.kannaka-nats.env; set +a — a plain export-less file does not populate a child process on its own.

Something else

Email us and ask for a refund if you would rather not debug it. You will get one.

Command reference

Command	Purpose
`kannaka remember "…" --importance 0.8`	Store a memory.
`kannaka recall "…" --top-k 5`	Resonance recall.
`kannaka dream --mode deep`	Full consolidation pass.
`kannaka observe --json`	Full substrate telemetry.
`kannaka status`	Quick vital signs.
`kannaka update`	Upgrade in place.
`kannaka swarm join\|status\|serve\|sync`	Constellation participation.

Environment	Effect
`KANNAKA_DATA_DIR`	Where the substrate lives.
`KANNAKA_READONLY=1`	Load and compute, never persist. Use for any reader process.
`KANNAKA_CONSOLIDATE=off\|dryrun\|on`	Plan only, or actually apply the merge. Default `dryrun`.

A trap worth knowing: if your config.toml sets an absolute [hrm] path, that overrides KANNAKA_DATA_DIR. Copying a config into a scratch directory to experiment on a copy will silently point back at your real substrate. Set path = "" in the copy, and check the memory count before running anything that mutates.

Stuck at any step? That is a bug in this guide as much as in the software — tell us which step and we will fix the guide. ← back to ninja-portal.com