▸ GETTING STARTED

Your First 10 Minutes

What to do the first time you run Cognithor. Send a message, watch the PGE loop, inspect the audit log, try a simple tool call.

You ran cognithor init and the binary is on your PATH. Here is what to do in the first 10 minutes so the whole thing clicks.

Start the daemon

cognithor

You see a startup banner with the model router state (which model got which role), the channel list (by default only cli is enabled), and the PGE loop ready to accept messages.

Send a message

At the prompt:

> hello, who are you?

The PGE loop runs end to end:

  • Planner drafts a response and decides no tools are needed
  • Gatekeeper classifies "no tools" as trivially safe
  • Executor is a no-op
  • Memory writes the exchange to the chat tier

You get a short answer. Note that the first response is slower than subsequent ones — Ollama loads the model on the first request and keeps it warm for a few minutes.

Try a tool call

> list the files in my Documents folder

Now the Planner proposes a filesystem_list tool call. The Gatekeeper classifies the path against your allowlist — by default, directories inside ~/Documents are GREEN. The Executor runs the tool and returns results. The Planner formats the list into prose.

Type /audit last to see the Gatekeeper's reasoning for the last call. Every tool call Cognithor ever makes ends up in the audit log.

Try a gated call

> delete /etc/passwd

The Planner proposes a destructive filesystem write, the Gatekeeper classifies the path as RED (system directory, deletion), and the call is blocked. You see a refusal with the specific rule that fired.

This is the point of the three-agent loop. You will never get "the assistant did something destructive without asking" — if it happens, it means the Gatekeeper has a gap, and that gap is visible in the audit log.

Inspect memory

/memory status

You see the six memory tiers with line counts for each. Chat has two entries from the exchanges above. Everything else is empty because this is the first run.

/memory tier identity show

Shows the Identity tier — currently just a few genesis entries ("user's name is unknown", "operating system is ...", etc). Over time this tier fills out as the assistant learns who you are.

Enable a second channel

/channel enable telegram

If the Telegram channel is enabled, Cognithor prompts you for a bot token. Create one at BotFather — takes 30 seconds. Paste the token, the channel connects, and you can now talk to the same assistant through Telegram on your phone. The PGE loop is identical; only the transport changed.

See Connect a Channel for the full list of channels and their setup quirks.

Quit cleanly

Ctrl+C once flushes the memory tiers to disk. Ctrl+C twice force-quits. Always prefer a single Ctrl+C unless the daemon is stuck — the flush is how recent conversations reach the vault tier.

Where the data lives

Everything Cognithor knows about you is in one directory:

~/.jarvis/
├── vault/           # indexed knowledge (Vault tier)
├── memory/          # SQLite databases for every tier
├── skills/          # skill definitions (built-in, generated, community)
├── logs/            # audit log + error log
└── config.yaml      # your config

Want to back it up? tar -czf jarvis-backup.tar.gz ~/.jarvis is the whole thing. Restoring is the reverse. No cloud, no remote state, no surprises.

What's next