CLI Reference

Every npx vektor command — from first-run setup to the interactive memory browser, REM cycle, and morning briefing.

All Commands

`npx vektor setup`	First-run wizard. Walks through licence activation, memory test, and integration configuration. Run this once on a new machine.
`npx vektor activate`	Activate your Polar licence key on this machine. Caches the result to `~/.vektor/licence.json` — you won't be prompted again.
`npx vektor deactivate`	Free up this machine's activation slot. Use this before moving to a new machine if you've hit the 3-machine limit.
`npx vektor status`	Full system health check — Node version, licence cache, DB path, Playwright, ONNX runtime, Cloak vault.
`npx vektor test`	Quick smoke test. Boots the memory engine, stores a test memory, recalls it, runs briefing, and cleans up. Confirms everything is working.
`npx vektor mcp`	Start the Claude MCP server. Exposes `vektor_recall`, `vektor_store`, `vektor_graph`, `vektor_delta` tools to Claude Desktop.
`npx vektor tui`	Launch the interactive terminal memory browser. Navigate, search, add, delete, and inspect memories. Requires a TTY — run in a real terminal.
`npx vektor rem`	Run the REM dream cycle on your memory database. Compresses up to 50 fragments into 3 core insights. Safe to run while your agent is idle.
`npx vektor briefing`	Generate a morning briefing from the last 24 hours of memory. Outputs a structured summary to stdout — inject into your agent's system prompt.
`npx vektor help`	Print the command reference with examples.

setup

Runs the full first-time configuration wizard. Activates your licence, tests the memory engine, and optionally configures Claude Desktop MCP integration.

bash

npx vektor setup

Run this once on each new machine. If you skip it, you can run individual commands manually (activate, test) instead.

activate · deactivate

Activates your Polar licence key on this machine. Once activated, the key is cached for 30 days at ~/.vektor/licence.json — no internet required for subsequent runs within that window.

bash

npx vektor activate

To activate non-interactively, set VEKTOR_LICENCE_KEY before running:

bash

# Windows PowerShell
$env:VEKTOR_LICENCE_KEY="YOUR-LICENCE-KEY-HERE"
npx vektor activate

# Unix / macOS
export VEKTOR_LICENCE_KEY="YOUR-LICENCE-KEY-HERE"
npx vektor activate

Each licence supports 3 machine activations. Free up a slot before switching machines:

bash

npx vektor deactivate

Hit the 3-machine limit? Manage your activations directly at polar.sh → your customer portal. Enterprise licences (10 seats) available at hello@vektormemory.com.

status

Prints a full system health report. Run this first when troubleshooting.

bash

npx vektor status

output

  SYSTEM STATUS

  Node.js       ✓ v20.20.1
  Licence cache ✓ found  (~/.vektor/licence.json)
  Licence env   ✓ VEKTOR_LICENCE_KEY set
  Memory DB     ✓ ~/vektor-slipstream-memory.db
  Cloak vault   ✓ found
  Playwright    ✓ installed
  ONNX runtime  ✓ installed

  vektor-slipstream v1.5.0

test

Runs a quick end-to-end smoke test. Confirms the engine boots, stores a memory, recalls it correctly, generates a briefing, and cleans up after itself.

bash

npx vektor test

output

  [##############################] 100% Done
  ✓ Memory engine booted
  ✓ Stored memory (id: 1)
  ✓ Recalled 1 result(s) — top score: 0.9741
  ✓ Briefing generated
  ✓ Test database cleaned up

  ✓ All tests passed. VEKTOR is working correctly.

If test fails with better-sqlite3 error: run npm rebuild better-sqlite3 in your project directory. This happens when Node.js is updated after installation.

mcp

Starts the Claude MCP server in stdio mode. Used by Claude Desktop to connect to your local memory database. See the DXT guide for the one-click install — use npx vektor mcp only if configuring manually via claude_desktop_config.json.

bash

npx vektor mcp

claude_desktop_config.json

{
  "mcpServers": {
    "vektor": {
      "command": "npx",
      "args": ["vektor", "mcp"],
      "env": {
        "VEKTOR_LICENCE_KEY": "YOUR-KEY-HERE",
        "VEKTOR_DB_PATH": "C:/Users/you/vektor-memory.db"
      }
    }
  }
}

tui

Launches the interactive terminal memory browser. Navigate your MAGMA graph, search memories, add new entries, adjust importance scores, and run briefings — all without writing code.

bash

npx vektor tui

Keyboard shortcuts

`↑ ↓`	Navigate memory list
`e` or `Enter`	Open selected memory detail
`A`	Add a new memory
`D`	Delete selected memory
`E`	Increase importance score
`/`	Search memories
`B`	Generate briefing
`T`	Switch tab
`Q`	Quit

Windows: run in Windows Terminal or PowerShell. If you see garbled characters, run [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 first.

rem

Runs the 7-phase REM dream cycle on your memory database. Compresses up to 50 raw fragments into 3 distilled core insights. Safe to run at any time — designed to run while your agent is idle.

bash

npx vektor rem

Schedule it as a nightly cron job:

cron

# Run REM every night at 3am
0 3 * * * cd /path/to/project && npx vektor rem >> ~/vektor-rem.log 2>&1

Or trigger programmatically:

javascript

const memory = await createMemory({ ... });
const result = await memory.dream();
console.log(result); // { compressed: 47, retained: 3, ratio: '15.7:1' }

briefing

Generates a morning briefing from the last 24 hours of memory. Structured output — inject directly into your agent's system prompt at session start.

bash

npx vektor briefing

output

  ── MEMORY BRIEFING ──────────────────────────────────

  Yesterday: 12 new memories stored across 3 topics.
  Key decisions: TypeScript migration approved, API rate
  limits increased to 1000/min, deploy blocked on staging.
  Active projects: data-pipeline, auth-refactor, docs-v2.
  User preferences updated: prefers async/await over .then()

  ─────────────────────────────────────────────────────

Inject into an agent system prompt:

javascript

const memory = await createMemory({ ... });
const brief = await memory.briefing();

const systemPrompt = `You are a helpful assistant.
${brief ? 'MEMORY BRIEFING:\n' + brief : ''}`;

chat

Persistent memory chat. Every conversation is automatically stored in your MAGMA graph and recalled in future sessions. Works with all major LLM providers — Ollama runs free and local with no API key.

npx vektor chat

# Use a specific provider
npx vektor chat --provider claude
npx vektor chat --provider groq
npx vektor chat --provider openai

# Use a specific model
npx vektor chat --provider ollama --model qwen3.5:4b

In-chat commands

`/recall <query>`	Search your memory mid-conversation
`/stats`	Show memory node count and graph stats
`/briefing`	Generate memory briefing inline
`/exit`	Exit chat (Ctrl+C also works)

remember

Store a fact instantly from your terminal. Importance is auto-scored based on content — override with --importance.

npx vektor remember "I prefer TypeScript over JavaScript"
npx vektor remember "Client deadline is April 20th" --importance 5
npx vektor remember "Server IP is 159.13.45.182" --importance 4

# Pipe support — feed any content into memory
cat README.md | npx vektor remember
git log --oneline -20 | npx vektor remember "recent commits"
echo "Build failed on auth module" | npx vektor remember

ask

One-shot question against your memory graph. Recalls relevant context then generates an answer using your chosen LLM provider.

npx vektor ask "what stack am I using?"
npx vektor ask "what projects am I working on?"
npx vektor ask "what did I decide about authentication?"

# Use a specific provider
npx vektor ask "summarise my recent work" --provider claude

agent

Autonomous goal executor. Give it a goal, it works through it step by step using memory recall, web fetch, and storage tools. Persists between runs — run again on the same goal to continue where it left off.

npx vektor agent "research AI memory tools and summarise findings"
npx vektor agent "what have I been building this week?"
npx vektor agent "summarise everything I know about my projects"

# Control steps and provider
npx vektor agent "research X" --steps 15 --provider groq

Agent state is stored in MAGMA after each run. Running the same goal again picks up prior context automatically.

Environment Variables

`VEKTOR_LICENCE_KEY`	Your Polar licence key. Set this to skip the interactive prompt on first run. Recommended: store in `.env` and load with dotenv.
`VEKTOR_DB_PATH`	Absolute path to your SQLite memory database. Defaults to `~/vektor-slipstream-memory.db`. Use a project-relative path for per-project memory.
`VEKTOR_AGENT_ID`	Agent identifier string. Used to namespace memories when multiple agents share a database. Defaults to `default`.

← Back to Docs DXT — Claude Desktop →