CLI Reference

dk is the official command-line interface for Dakera AI. Use it to store and recall agent memories, run semantic and full-text search, manage namespaces, inspect knowledge graphs, rotate API keys, and administer your memory server — all from the terminal.

Source: github.com/dakera-ai/dakera-cli  ·  v0.6.0 release notes

Prerequisites — Run a Dakera server

You need a running Dakera server before using the CLI. The fastest way to get one running:

Quick start (Docker)

docker run -d \
  --name dakera \
  -p 3300:3300 \
  -e DAKERA_PORT=3300 \
  -e DAKERA_ROOT_API_KEY=dk-mykey \
  ghcr.io/dakera-ai/dakera:latest

Production (Docker Compose with persistent storage)

git clone https://github.com/Dakera-AI/dakera-deploy.git
cd dakera-deploy/docker
DAKERA_ROOT_API_KEY=dk-mykey DAKERA_PORT=3300 docker compose up -d

# Verify the server is healthy
curl http://localhost:3300/health
# → {"status":"ok"}

For Kubernetes and Helm deployments see dakera-deploy.

Installation

Homebrew (macOS / Linux)

brew install dakera-ai/tap/dk

APT (Debian / Ubuntu)

curl -fsSL https://dakera-ai.github.io/apt-repo/KEY.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/dakera-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/dakera-archive-keyring.gpg] https://dakera-ai.github.io/apt-repo stable main" \
  | sudo tee /etc/apt/sources.list.d/dakera.list
sudo apt-get update && sudo apt-get install -y dk

YUM / DNF (Fedora / RHEL / CentOS)

sudo tee /etc/yum.repos.d/dakera.repo << 'EOF'
[dakera]
name=Dakera AI
baseurl=https://dakera-ai.github.io/rpm-repo/
enabled=1
gpgcheck=0
EOF
sudo dnf install -y dk

Cargo

cargo install dakera-cli        # compiles from source (Rust 1.70+)
cargo binstall dakera-cli       # pre-built binary via cargo-binstall (faster)

Binary download

Pre-built binaries for macOS (arm64/x64), Linux (x64/arm64), and Windows (x64) are on the GitHub Releases page. Extract and place dk in your PATH.

Quick Start

Five commands to go from zero to storing and searching memories:

# 1. Interactive setup — configure server URL and API key
dk init

# 2. Verify connectivity to your Dakera server
dk health

# 3. Store your first memory
dk memory store my-agent "The user prefers concise responses" --importance 0.8

# 4. Recall by semantic query
dk memory recall my-agent "user preferences" --top-k 5

# 5. Full-text BM25 search across all memories
dk text search "user preferences"

dk init writes ~/.dakera/config.toml with your server URL and API key. You will not need to pass --url or set environment variables on every command after that.

Configuration

Environment variables

Config file

dk init creates ~/.dakera/config.toml. You can also edit it manually:

[server]
url = "http://localhost:3300"
api_key = "dk-mykey"

[defaults]
namespace = "default"

Named profiles

Switch between environments without touching environment variables:

# Add a profile for a staging server
dk config profile add staging --url https://staging.example.com --namespace staging

# Switch the active profile
dk config profile use staging

# Or pass --profile per command without switching
dk --profile staging namespace list

# List all saved profiles
dk config profile list

Precedence

Environment variables > CLI flags > config file > built-in defaults.

Global flags

# JSON output for scripting
dk --format json memory recall my-agent "recent tasks"

# Compact output for piping
dk --format compact namespace list | jq '.[].name'

# Verbose: show HTTP request/response details
dk --verbose memory store my-agent "new memory"

Memory

The core feature of Dakera. Memories are stored per-agent and retrieved by semantic similarity. Each memory has a type that controls its lifecycle:

Store

# Store with default type (episodic) and importance (0.5)
dk memory store my-agent "Completed onboarding for user Alice"

# Semantic memory: factual preference, higher importance
dk memory store my-agent "User prefers dark mode" --type semantic --importance 0.8

# Procedural: how-to knowledge
dk memory store my-agent "To restart the service: systemctl restart dakera" --type procedural --importance 0.9

# Working memory: short-term context, attach to a session
dk memory store my-agent "Currently debugging auth issue" --type working --session-id sess-abc123

Importance ranges from 0.0 (low) to 1.0 (critical). Higher-importance memories are preserved longer under TTL decay and ranked first in recall.

Recall (semantic search)

# Recall top 5 memories matching a query
dk memory recall my-agent "user preferences"

# Return more results
dk memory recall my-agent "authentication flow" --top-k 10

# Filter by memory type
dk memory recall my-agent "debugging" --type episodic --top-k 5

Search (agent-scoped text search)

# Full-text search within a single agent's memories
dk memory search my-agent "dark mode" --top-k 10

# Filter by type
dk memory search my-agent "onboarding" --type episodic

Get a memory by ID

dk memory get my-agent mem-abc123

Update

# Update content
dk memory update my-agent mem-abc123 --content "User now prefers light mode"

# Change memory type
dk memory update my-agent mem-abc123 --type semantic

Forget (delete)

# Delete a single memory
dk memory forget my-agent mem-abc123

Batch forget

# Preview what would be deleted (always dry-run first)
dk memory batch-forget my-agent --min-importance 0.3 --dry-run

# Delete low-importance memories older than 90 days
dk memory batch-forget my-agent --min-importance 0.3 --max-age-days 90

# Delete all working memories for a specific agent
dk memory batch-forget my-agent --type working

Update importance scores

# Boost importance for a set of memories
dk memory importance my-agent --ids mem-1,mem-2,mem-3 --value 0.9

Consolidate

# Preview similar memories that would be merged
dk memory consolidate my-agent --dry-run

# Merge with a higher similarity threshold (stricter)
dk memory consolidate my-agent --threshold 0.9

# Consolidate only semantic memories
dk memory consolidate my-agent --type semantic --dry-run

Feedback

# Signal that this memory was highly relevant for a recall
dk memory feedback my-agent mem-abc123 "Very relevant to the query" --score 1.0

# Signal low relevance
dk memory feedback my-agent mem-abc123 "Not relevant" --score 0.1

Feedback signals are used to tune recall quality over time. The --score flag accepts a float from 0.0 to 1.0.

Text Search (BM25)

BM25 full-text search across memories. Complements semantic recall for exact keyword matches.

# Search across all namespaces
dk text search "machine learning"

# Limit to a specific namespace
dk text search "temporal reasoning" --namespace my-ns

# Control result count
dk text search "user preferences" --namespace default --limit 20

# JSON output for scripting
dk --format json text search "API key" --namespace default

Sessions

Sessions group related memories and provide a shared context window for an agent conversation.

# Start a new session
dk session start my-agent

# Start with metadata
dk session start my-agent --metadata '{"task":"onboarding","user":"alice"}'

# End a session with a summary
dk session end sess-abc123 --summary "Completed user onboarding flow"

# Get session details
dk session get sess-abc123

# List sessions (with filters)
dk session list --agent-id my-agent --active-only
dk session list --agent-id my-agent --limit 20

# View all memories associated with a session
dk session memories sess-abc123

Agents

Inspect agents stored in the system — their memories, sessions, and aggregate statistics.

# List all agents
dk agent list

# Memory and session statistics for an agent
dk agent stats my-agent

# List memories for an agent
dk agent memories my-agent
dk agent memories my-agent --type episodic --limit 20

# List sessions for an agent
dk agent sessions my-agent
dk agent sessions my-agent --active-only --limit 10

Namespaces

Namespaces partition memories into isolated vector spaces. Each namespace can have its own dimension, TTL policies, and rate limits.

Basic operations

# List all namespaces
dk namespace list

# Get details for a namespace
dk namespace get my-ns

# Create a namespace (optional: specify vector dimension)
dk namespace create my-ns
dk namespace create my-ns --dimension 1536

# Delete a namespace (preview first)
dk namespace delete my-ns --dry-run
dk namespace delete my-ns --yes

Namespace policy

Control how memories age, decay, deduplicate, and are rate-limited within a namespace. All flags are optional — only supplied flags are changed.

# View current policy
dk namespace policy get my-ns

# Set TTLs (in seconds)
dk namespace policy set my-ns \
  --working-ttl 7200 \
  --episodic-ttl 1296000 \
  --semantic-ttl 31536000 \
  --procedural-ttl 63072000

# Set decay curves per memory type
dk namespace policy set my-ns \
  --working-decay exponential \
  --episodic-decay power_law \
  --semantic-decay logarithmic \
  --procedural-decay flat

# Enable spaced repetition (TTL extends on each recall hit)
dk namespace policy set my-ns --spaced-repetition-factor 1.5 --spaced-repetition-base-interval 86400

# Enable background DBSCAN deduplication
dk namespace policy set my-ns \
  --consolidation-enabled true \
  --consolidation-threshold 0.92 \
  --consolidation-interval-hours 24

# Enable per-namespace rate limiting
dk namespace policy set my-ns \
  --rate-limit-enabled true \
  --rate-limit-stores-per-minute 100 \
  --rate-limit-recalls-per-minute 200

Knowledge Graph

Build and explore semantic relationships between memories, summarize clusters, and deduplicate near-identical content.

Graph from a seed memory

# Build a graph starting from one memory
dk knowledge graph my-agent --memory-id mem-abc123

# Control traversal depth and similarity cutoff
dk knowledge graph my-agent --memory-id mem-abc123 --depth 3 --min-similarity 0.75

Full knowledge graph

# Full graph for an agent (all memories as nodes)
dk knowledge full-graph my-agent

# Limit graph size
dk knowledge full-graph my-agent --max-nodes 200 --max-edges 50 --min-similarity 0.7

# Adjust cluster grouping threshold
dk knowledge full-graph my-agent --cluster-threshold 0.85

Summarize

# Preview a summarization (does not write)
dk knowledge summarize my-agent --memory-ids mem-1,mem-2,mem-3 --dry-run

# Summarize into a semantic memory
dk knowledge summarize my-agent --memory-ids mem-1,mem-2,mem-3 --target-type semantic

Deduplicate

# Preview duplicates above default threshold
dk knowledge deduplicate my-agent --dry-run

# Set a stricter threshold (higher = more similar required)
dk knowledge deduplicate my-agent --threshold 0.95 --dry-run

# Deduplicate only episodic memories
dk knowledge deduplicate my-agent --type episodic --dry-run

API Keys

Create and manage API keys for authenticating agents and services against your Dakera server.

# Create a key (name is required, other flags are optional)
dk keys create my-service-key --permissions read,write
dk keys create ci-reader --permissions read --expires 90

# List all keys
dk keys list

# Inspect a key
dk keys get key-abc123

# View usage statistics for a key
dk keys usage key-abc123

# Rotate a key — generates a new secret, invalidates the old one
dk keys rotate key-abc123

# Temporarily suspend a key without deleting it
dk keys deactivate key-abc123

# Permanently delete a key
dk keys delete key-abc123

Admin & Operations

Cluster health, index management, cache, server configuration, quotas, performance diagnostics, and backups.

Cluster

dk admin cluster-status
dk admin cluster-nodes

Index management

# Compact indexes and reclaim storage for a namespace
dk admin optimize my-ns

# View index statistics
dk admin index-stats my-ns

# Rebuild indexes (typically after large imports)
dk admin rebuild-indexes my-ns

Cache

# View cache statistics
dk admin cache-stats

# Clear all caches
dk admin cache-clear

# Clear cache for a specific namespace only
dk admin cache-clear --namespace my-ns

Server configuration

# Get current server configuration
dk admin config-get

# Update a configuration value
dk admin config-set --key max_connections --value 200
dk admin config-set --key log_level --value debug

Namespace quotas

# View all namespace quotas
dk admin quotas-get

# Set quotas (JSON object)
dk admin quotas-set --data '{"max_memories":50000,"max_namespaces":20}'

Performance diagnostics

# View the 20 slowest queries
dk admin slow-queries

# Show queries slower than 500ms
dk admin slow-queries --min-duration 500

# Limit output
dk admin slow-queries --limit 10 --min-duration 100

Backups

# Create a full backup (data + schema)
dk admin backup-create

# Create a schema-only backup (no vector data)
dk admin backup-create --no-data

# List all backups
dk admin backup-list

# Restore from a specific backup
dk admin backup-restore bkp-abc123

# Delete an old backup
dk admin backup-delete bkp-abc123

TTL configuration

# Set a namespace-level TTL (seconds)
dk admin configure-ttl my-ns --ttl-seconds 2592000

# Set TTL with a strategy
dk admin configure-ttl my-ns --ttl-seconds 86400 --strategy archive

Index Management

Fine-grained control over vector and full-text indexes for a namespace.

# Vector index statistics
dk index stats --namespace my-ns

# Full-text index statistics
dk index fulltext-stats --namespace my-ns

# Preview a rebuild (does not make changes)
dk index rebuild --namespace my-ns --dry-run

# Rebuild the vector index
dk index rebuild --namespace my-ns --index-type vector --yes

# Rebuild both indexes
dk index rebuild --namespace my-ns --index-type all --yes

Shell Completions

Install shell completions so you get tab-complete for commands, subcommands, and dynamic values like namespace and agent names.

# Install completions automatically
dk completion bash --install
dk completion zsh --install
dk completion fish --install

# Print to stdout (for manual installation)
dk completion bash
dk completion zsh
dk completion fish

Dynamic completion queries your live server to suggest namespace and agent names.

Exit codes

Every dk command exits with a typed code. Use $? in scripts to detect specific failure modes:

With --format json, errors emit a JSON object containing error, code (machine string), exit_code (integer), and message. This makes it easy to handle errors programmatically:

# Check specific exit code in a script
dk memory recall my-agent "recent tasks" --format json
if [ $? -eq 2 ]; then
  echo "Cannot reach Dakera server"
fi

Safety features

The CLI is designed for safe use in production pipelines.

All command groups

Run dk --help for the full command reference. Run dk <group> --help for subcommand details and flag descriptions.