viking-chat

An interactive CLI chat with persistent memory across sessions, powered by Viking.

Tell it your name, preferences, or ongoing projects — restart it a week later and it still remembers.

Install

npm install -g viking-chat

Requires Node.js >= 20 and a free OpenRouter API key.

Quick Start

viking-chat

On first run, the setup wizard will ask for your OpenRouter API key and save it to ~/.viking-chat/settings.json. After that, just run viking-chat to start chatting.

Commands

viking-chat                    Start interactive chat
viking-chat -n <namespace>     Chat with a specific memory namespace
viking-chat config             Show active configuration and file paths
viking-chat clear              Delete all stored memory data (with confirmation)
viking-chat --help, -h         Print usage
viking-chat --version, -v      Print version

In-session:

/model    Switch the active model without restarting

Configuration

Settings are loaded in order — later overrides earlier:

| Priority | File | Purpose | |---|---|---| | 1 (lowest) | built-in defaults | sensible out-of-the-box values | | 2 | ~/.viking-chat/settings.json | global user preferences | | 3 | <cwd>/.viking-chat/settings.local.json | per-project overrides | | 4 (highest) | OPENROUTER_API_KEY env var | CI / scripting |

Available settings

// ~/.viking-chat/settings.json
{
  "openrouterApiKey": "sk-or-...",
  "chatModel":    "minimax/minimax-m2.5",         // main chat model
  "fastModel":    "google/gemini-2.5-flash-lite", // used for history summarization
  "embedModel":   "openai/text-embedding-3-small",
  "historyWindow": 20,        // messages to keep before compaction
  "topK":          5,         // memories recalled per query
  "scoreThreshold": 0.25,     // minimum similarity score (0–1)
  "namespace":    "default",  // memory namespace
  "dataDir":      "~/.viking-chat/data" // where memory files are stored
}

Memory Namespaces

Namespaces isolate memories — different namespaces never share data.

Auto-detection (no prompt, no flag needed):

1. --namespace / -n flag — highest priority
2. namespace in <cwd>/.viking-chat/settings.local.json
3. namespace in ~/.viking-chat/settings.json
4. "default" — fallback

Per-project memory — drop a file in your project root:

// my-project/.viking-chat/settings.local.json
{ "namespace": "my-project" }

Now viking-chat in that directory automatically uses isolated project memory.

The active namespace and its source are shown on startup:

◆ namespace: my-project  (.viking-chat/settings.local.json)

Data Storage

All memory data lives in ~/.viking-chat/data/ by default (override with dataDir).

• Human-readable JSON files for context records
• SQLite + sqlite-vec for embedding index
• Safe to delete for a clean slate: viking-chat clear

Memory Tools

The agent has access to three memory tools it uses proactively:

| Tool | When it's used | |---|---| | storeMemory | Personal info — preferences, events, projects, patterns | | storeSkill | Procedures — how-to instructions, workflows | | storeResource | Reference material — docs, technical content, knowledge bases |

Memories are recalled automatically at the start of each turn via semantic search.

Recall is cached within a session. Identical user queries skip the embedding call and reuse the previous result (LRU, 64 entries).

File Tools

The agent can read and write files in the current working directory (sandboxed — no access outside cwd). This makes it useful as a project-aware assistant.

License

MIT