dakera-cli MCP server

⚡ dakera-cli

Command-line interface for Dakera AI — inspect and manage a Dakera memory instance from the terminal.

The Dakera memory engine scores 88.2% Recall@20 on LoCoMo (1,536 evaluated questions · LLM-judged retrieval recall) — benchmark details

---

Run Dakera

You need a running Dakera server to connect to. The fastest way:

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

For persistent storage (recommended):

curl -sSfL https://raw.githubusercontent.com/Dakera-AI/dakera-deploy/main/docker-compose.yml \
  -o docker-compose.yml
DAKERA_ROOT_API_KEY=dk-mykey docker compose up -d

curl http://localhost:3000/health  # → {"status":"ok"}

Full deployment guide (Docker Compose, Kubernetes, Helm): dakera-deploy

---

Install

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

# From crates.io (compiles from source)
cargo install dakera-cli

# Pre-built binary via cargo-binstall (faster)
cargo binstall dakera-cli

Binary download

Pre-built binaries for macOS (arm64/x64), Linux (x64/arm64), and Windows are available on the releases page.

Platform	File
macOS (Apple Silicon)	dakera-cli-aarch64-apple-darwin.tar.gz
macOS (Intel)	dakera-cli-x86_64-apple-darwin.tar.gz
Linux x64	dakera-cli-x86_64-unknown-linux-musl.tar.gz
Linux arm64	dakera-cli-aarch64-unknown-linux-musl.tar.gz
Windows x64	dakera-cli-x86_64-pc-windows-msvc.zip

---

Quick Start

# 1. Configure the CLI (server URL + API key)
dk init

# 2. Verify connectivity
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
dk text search "user preferences" --namespace default

---

Configuration

Environment variables

Variable	Description	Default
DAKERA_URL	Server base URL	http://localhost:3000
DAKERA_API_KEY	API key for authentication	—
DAKERA_PROFILE	Named profile to use	active profile in config

Config file

dk init creates ~/.dakera/config.toml (one profile per server):

active_profile = "default"

[profiles.default]
url = "http://localhost:3000"
default_namespace = "default"

The API key is never stored in it: dk reads it from DAKERA_API_KEY only. dk writes the file readable by its owner only (0600, in a 0700 directory) and warns on stderr when it finds the file readable by other users. dk config shows the key masked (dk_…9876), never in full, and whether the server URL uses TLS; a key sent over plain http:// to a host other than the loopback interface gets a warning on stderr. TLS certificates are always verified (system trust store).

Named profiles

dk config profile add staging --url https://staging.example.com:3000
dk config profile use staging
dk --profile staging namespace list

Precedence

Environment variables > CLI flags > config file > defaults.

---

Global Flags

Flag	Short	Default	Description
--url	-u	http://localhost:3000	Server URL
--format	-f	table	Output format: table, json, compact
--verbose	-v	false	Log HTTP requests and response timing
--profile	-p	—	Named server profile

dk --format json memory recall my-agent "recent tasks"
dk --format compact namespace list | jq '.[].name'
dk --verbose memory store my-agent "new memory"

---

Commands

dk health

Check server health and connectivity. Reads the server's JSON directly, so a v0.12 server that is still loading its models (/health answers 503 with a Retry-After header) is reported as such, with exit code 6 — never as healthy.

dk health                  # status; lists degraded components, config warnings, embed migration
dk health --detailed       # + live / ready probes, version, build, uptime, diagnostics
dk health ready            # GET /health/ready  (exit 6 and the reason/downloads while starting)
dk health live             # GET /health/live

---

dk capabilities

What the connected server supports (GET /v1/capabilities, Dakera v0.12+): the active embedding model, search mode, scoring strategy, query languages (lang) and which opt-in features are on (attachments, speech to text, image indexing, records). A v0.11 server has no such route: the command exits 3 and says so.

dk capabilities
dk --format json capabilities

---

dk whoami

The API key this CLI authenticates with, as the server reads it (GET /v1/auth/whoami, Dakera v0.12.2): scope, namespace grants, whether it is unrestricted, its grant syntax version and the grants that match nothing (inert: a pre-v0.12.2 foo*, or _dakera_sessions).

dk whoami
dk --format json whoami

---

dk attachment

Files that agent memories can point at (Dakera v0.12, opt-in: the server answers 501 FEATURE_DISABLED until DAKERA_ATTACHMENTS is set; image indexing also needs DAKERA_VISION). dk capabilities shows what is on.

dk attachment upload _dakera_agent_my-agent note.wav    # media type guessed from the extension
dk attachment list _dakera_agent_my-agent
dk attachment download _dakera_agent_my-agent sha256:<hex> -o note.wav
dk attachment delete _dakera_agent_my-agent sha256:<hex>   # 409 while a memory references it

# Speech to text: a WAV attachment becomes a memory (a background job)
dk attachment transcribe uploads sha256:<hex> --agent-id my-agent --tag voice --wait
# Visual memory from a PNG (needs DAKERA_VISION)
dk attachment index uploads sha256:<hex> --agent-id my-agent --content "page 3" --wait
dk attachment job uploads sha256:<hex> job_1a2b3c4d_0 --kind transcribe

A memory can only reference an attachment stored in its own namespace, _dakera_agent_<agent_id>; transcribe and index copy an attachment from any namespace you can read into the agent's. --wait polls the job (progress goes to stderr) and exits 5 if the job fails with a 400, 6 on a 5xx.

---

dk document

Import a document as chunk memories of an agent (Dakera v0.12.3): each chunk keeps its heading path and page, so dk memory recall can cite it (a SOURCE column, document in JSON). Text, Markdown and HTML are sent as text; PDF and DOCX (and text that is not UTF-8) are uploaded as an attachment to the agent's namespace (--namespace to pick another) and imported from there, which needs DAKERA_ATTACHMENTS on the server. The format comes from the extension (.txt, .md, .html, .pdf, .docx; - reads stdin as text) unless --media-type says otherwise.

dk document import guide.md --agent docs-bot --wait
dk document import manual.pdf --agent docs-bot --document-id manual-v3 --tag manual --wait
dk document import notes.txt --agent docs-bot --chunk-tokens 300 --overlap 30 --strategy fixed
cat page.html | dk document import - --agent docs-bot --media-type text/html --title "Release notes"
dk document job job_17_3 --agent docs-bot      # Pending / Running (progress) / Completed / Failed
dk document list --agent docs-bot --limit 20    # then --cursor <next_cursor>
dk document show manual-v3 --agent docs-bot     # the document and its chunks (pages, headings)
dk document delete manual-v3 --agent docs-bot   # every chunk memory of it

Re-importing the same --document-id replaces the document (unchanged chunks are kept as they are). Other flags: --title, --session-id, --type, --importance, --lang, --decompose (also derive sentence sub-memories per chunk), --timeout (with --wait, default 600 s). A server before v0.12.3 has no document routes: dk says so.

dk namespace

Manage namespaces.

dk namespace list
dk namespace create my-ns
dk namespace policy --namespace my-ns

---

dk memory

Store, recall, search, and manage agent memories. This is the primary interface to Dakera.

# Store a memory
dk memory store my-agent "The user likes dark mode" --importance 0.8 --type semantic

# Recall by semantic query: at most --top-k ranked results, then a separate "Context"
# section with the session neighbours of those results (which result each belongs to).
# A MATCHED_TEXT column appears when the server collapsed sentence sub-memories into a result.
dk memory recall my-agent "UI preferences" --top-k 10
# --neighborhood separate (default) | inline | off; --include-summaries[=false]
dk memory recall my-agent "UI preferences" --neighborhood off --include-summaries=false
# JSON: {"memories": [...], "context_memories": [...]} (matched_text, context_of, context_of_rank)
dk --format json memory recall my-agent "UI preferences" | jq '.memories[].id'

# Full-text search within an agent's memories
dk memory search my-agent "dark mode" --top-k 5

# Get a specific memory by ID
dk memory get my-agent mem-abc123

# Update a memory
dk memory update my-agent mem-abc123 --content "Updated content"

# The language of the content or query (server v0.12+; `dk capabilities` lists them)
dk memory store my-agent "Anna kommt morgen nach Berlin" --lang de
dk memory recall my-agent "quand part Anna ?" --lang fr

# Link a memory to an uploaded attachment (server v0.12+, DAKERA_ATTACHMENTS)
dk memory store my-agent "Whiteboard from the planning meeting" --attachment-ref sha256:3f2a...

# Store many memories in one request (up to 1000; --file takes a JSON array, '-' = stdin)
dk memory batch-store my-agent -c "Prefers dark mode" -c "Lives in Berlin" --tag prefs
dk memory batch-store my-agent --file memories.json --lang de

# Extract entities from text without storing it
dk memory extract "Anna met Bob in Paris" --entity-types person,location

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

# Batch delete by filters (dry-run first!)
dk memory batch-forget my-agent --min-importance 0.3 --dry-run
dk memory batch-forget my-agent --min-importance 0.3 --max-age-days 90

# Update importance scores
dk memory importance my-agent --ids mem-1,mem-2 --value 0.9

# Consolidate similar memories into summaries
dk memory consolidate my-agent --dry-run

# Submit recall quality feedback (upvote, downvote, flag)
dk memory feedback my-agent mem-abc123 upvote

---

dk text

Full-text (BM25) search across memories.

# Search one namespace (the server has no cross-namespace full-text route)
dk text search "machine learning" --namespace default

# Search within a specific namespace
dk text search "temporal reasoning" --namespace my-ns --limit 20

---

dk session

Manage agent sessions.

dk session start my-agent
dk session start my-agent --idle-timeout 8h   # v0.12.2: own inactivity timeout (0 = never)
dk session touch sess-abc123                  # v0.12.2: keep a quiet session open
dk session end sess-abc123
dk session list --agent-id my-agent --active-only
dk session get sess-abc123
dk session memories sess-abc123 --preview 200 --limit 20

Since Dakera v0.12.2 the server ends a session after 4 hours without activity (storing, recalling or dk session touch); dk session list shows ended_reason (client or idle). Sessions are authorized by their agent: a key needs Write on the agent to start, touch or end its sessions, and dk session end with a read-only key is refused (403).

---

dk agent

View and manage agents.

dk agent list
dk agent create mlx-dev                        # v0.12.2: create before the first memory (idempotent)
dk agent stats my-agent
dk agent memories my-agent --type episodic --limit 20
dk agent memories my-agent --preview 200       # v0.12.2: content previews (CONTENT_LEN, TRUNCATED columns)
dk agent memories my-agent --include-derived   # v0.12.2: also list the derived sentence sub-memories
dk agent sessions my-agent --active-only

Since Dakera v0.12.2 dk agent memories leaves the derived sentence sub-memories out unless --include-derived is given. With --preview N each memory's content is cut to N characters by the server; dk memory get shows a whole memory.

---

dk knowledge

Knowledge graph management and memory summarization.

# Build a knowledge graph from a memory
dk knowledge graph my-agent --memory-id mem-abc123 --depth 3

# Full knowledge graph for an agent
dk knowledge full-graph my-agent --max-nodes 100 --preview 200

# Summarize a set of memories into a new memory
dk knowledge summarize my-agent --memory-ids m1,m2,m3 --dry-run

# Find and remove duplicate memories
dk knowledge deduplicate my-agent --threshold 0.9 --dry-run

---

dk index

Index management.

dk index stats --namespace my-ns
dk index fulltext-stats --namespace my-ns
dk index rebuild --namespace my-ns --dry-run
dk index rebuild --namespace my-ns --index-type vector --yes

---

dk keys

API key management.

dk keys list
dk keys create my-key --permissions read,write
dk keys delete key-abc123
dk keys usage key-abc123

# Dakera v0.12.2
dk keys edit dk_key_1a2b --name ci                             # rename (alias: dk keys patch)
dk keys edit dk_key_1a2b --namespaces '_dakera_agent_mlx-*,docs'  # replace the grants (p* prefix patterns)
dk keys edit dk_key_1a2b --all-namespaces                      # every namespace (sends null)
dk keys edit dk_key_1a2b --no-namespaces                       # no namespace (sends [])
dk keys edit dk_key_1a2b -n team-a --namespaces 'team-a*'      # as a namespace admin
dk keys rotate dk_key_1a2b --grace 1h                          # the old key keeps working for 1h (at most 7d)

dk keys edit needs an unrestricted super_admin key (or, with -n, an admin of that namespace whose grants contain the new ones). Saving the namespaces of a key created before v0.12.2 activates its foo* entries.

---

dk admin

Cluster administration, caching, backups, and server configuration.

# Cluster overview
dk admin cluster-status
dk admin cluster-nodes

# Namespace index management
dk admin optimize my-ns
dk admin index-stats my-ns
dk admin rebuild-indexes my-ns

# Cache management
dk admin cache-stats
dk admin cache-clear
dk admin cache-clear --namespace my-ns

# Server configuration
dk admin config-get
dk admin config-set --key max_connections --value 100

# Namespace quotas (a hard quota is enforced since v0.12: writes over it get 413)
dk admin quotas-get
dk admin quotas-set --data '{"max_vectors": 100000, "enforcement": "hard"}'              # default quota
dk admin quotas-set -n my-ns --data '{"max_vectors": 10000, "enforcement": "soft"}'      # one namespace

# Performance diagnostics
dk admin slow-queries --limit 10

# After an upgrade to v0.12: the one-time background re-embed (also in `dk health`)
dk admin embed-migration

# Encryption at rest (v0.12 keyring): status, rotation per namespace, re-seal
dk admin encryption-status
dk admin encryption-rotate -n my-ns                      # a new random key for one namespace
dk admin encryption-rotate --new-key-env MY_NEW_KEY      # global, from a passphrase in the environment
dk admin encryption-reseal --wait-secs 30

# Backups
dk admin backup-create --name nightly --type full --wait
dk admin backup-list
dk admin backup-get <backup-id>
dk admin backup-schedule                                 # an enabled schedule runs since v0.12
dk admin backup-download <backup-id> -o nightly.json.gz  # super_admin
dk admin backup-upload nightly.json.gz                   # super_admin
dk admin backup-restore <backup-id> -n my-ns --wait      # super_admin; add --overwrite --yes for a point-in-time restore
dk admin backup-restore-status <restore-id>
dk admin backup-delete <backup-id>

# Dakera v0.12.2
dk admin derivations-status                              # derived data owed (sub-memories, full-text, graph edges)
dk admin derivations-drain --timeout 10m                 # derive everything owed now
dk admin session-idle-timeout                            # show the server-wide session idle timeout
dk admin session-idle-timeout 8h                         # set it (0 = never; at most 30d)

All of these need a global key. A key pinned to namespaces gets 403 on node-wide routes even with the admin scope, and backup download, upload and restore need super_admin (see Permissions). The previous backup-create sent no name, which the server requires, and quotas-set called a route that does not exist; both now work.

---

dk config

Show or manage connection profiles.

dk config
dk config profile add staging --url http://staging:3000
dk config profile use staging
dk config profile list

---

dk completion

Generate shell completion scripts.

dk completion bash --install
dk completion zsh --install
dk completion fish --install
dk completion powershell

---

Dakera v0.12 and compatibility

Breaking in dk 0.8.2: dk --format json|compact memory recall prints one object, {"memories": [...], "context_memories": [...]}, instead of an array of rows: read the ranked results from .memories.

The 0.8.2 additions need a v0.12.3 server; older servers ignore them, as noted:

Command (0.8.2)	v0.12.2 and older	v0.12.3
dk memory recall (--neighborhood separate, the default)	the server appends its context to the results unmarked: dk shows the first --top-k and warns how many it left out	at most --top-k ranked results, then the Context section with context_of
dk memory recall --include-summaries[=false]	ignored	yes
MATCHED_TEXT column	never shown	when the server collapses derived sentences (DAKERA_RECALL_COLLAPSE_DERIVED)
the unknown-field hint (keys create, admin backup-create, admin encryption-rotate)	not needed: unknown fields are ignored	a misspelled field is a 422, with a hint naming it
dk document ...	no route: dk says it needs v0.12.3	yes (DAKERA_DOCUMENTS, on by default; PDF / DOCX also need DAKERA_ATTACHMENTS)
SOURCE column / document in memory recall	never shown	for results that are document chunks
dk admin / dk keys commands	as before	as before; POST /ops/shutdown (no dk command) needs a super_admin key

dk 0.8.2 works against Dakera v0.11.108 and v0.12.0 – v0.12.3 servers (it uses dakera-client 0.12). The new commands need the server release that has the route or field:

Command	v0.11.108	v0.12.0
everything in 0.7 (memory, namespace, session, keys, ...)	yes	yes
dk health, dk health ready, dk health live	yes	yes (+ degraded, config_warnings, embed_migration)
dk capabilities	exits 3 (no route)	yes
dk memory batch-store, dk memory extract	yes	yes
--lang (`dk memory store	recall	search
dk attachment ...	no	yes, once DAKERA_ATTACHMENTS is on
dk admin embed-migration, encryption-status, encryption-reseal	no	yes
other dk admin commands (encryption-rotate, backup-*, quotas-*, ...)	routes that v0.11.108 already had	same routes; v0.12 changes who may call them and what they do (below)

The 0.8.1 commands need a v0.12.2 server; on v0.12.0 / v0.12.1 they fail (404/405, exit 3 or 1) or are ignored, as noted:

Command (0.8.1)	v0.12.0 / v0.12.1	v0.12.2
dk whoami, dk agent create, dk session touch, dk keys edit, dk admin derivations-*	no route	yes
dk keys rotate --grace	the old key is deactivated at once (dk warns)	yes
dk session start --idle-timeout	ignored (sessions never time out)	yes
dk admin session-idle-timeout	says the server predates it	yes
--preview, --include-derived (agent memories, session memories, knowledge full-graph)	ignored (full content; derived records always listed)	yes

Permissions (v0.12)

• Keys pinned to namespaces get 403 on node-wide routes (/admin/*: backups, encryption, quotas, config, cluster), even with the admin scope.
• Backup download, upload and restore need a global super_admin key: a backup bundle carries every API key hash, so an admin key can no longer take one (or restore an edited one).

dk turns those answers into a message that says what to do, for example:

✗ Permission denied: Request failed (403 Forbidden) [INSUFFICIENT_SCOPE]: Insufficient scope for this operation (required: super_admin, actual: admin)
  hint: this needs a global super_admin key: since v0.12 backup download, upload and restore are refused to admin keys ...

Errors

v0.12 answers every error with a JSON body ({"error", "code", "status", "details"}) and every 503 carries Retry-After. dk keeps those fields: with --format json the error on stderr gains http_status, server_code, details and retry_after_secs. A 413 (a body over a size limit such as DAKERA_ATTACHMENT_MAX_BYTES, or a hard namespace quota) exits 5; a 501 (a feature that is switched off, FEATURE_DISABLED, or a configuration the server cannot serve) and a 503 exit 6. Retry a 503 after the Retry-After seconds.

Server-side commands (not dk commands)

Two operator commands ship in the server binary, not in dk; run them with the server's image, environment and volumes:

# Check a configuration with the new image before upgrading: exits 0 (the server
# would start, warnings included) or 78 (it would refuse). Starts nothing.
docker run --rm <same env and volumes> <v0.12 image> --check-config

# Go back to v0.11.108: run once, after the v0.12 server has stopped. Prints a JSON
# report; exit 0 = the data is v0.11.108's, 1 = something still needs fixing (run it
# again), 78 = it refused and changed nothing.
docker run --rm <same env and volumes> <v0.12 image> downgrade

See the server's docs/v0.12/UPGRADE.md ("Going back to v0.11.108") for what downgrade converts and when it refuses.

---