[ferhimedamine]

Summary

dk 0.8.2 for Dakera server v0.12.3 (engine PR Dakera-AI/dakera#922: #917 recall correctness, #920 security hardening, #923 document import).

• dk memory recall now prints at most --top-k ranked rows, followed by a separate Context section.
• New dk document command.
• Recall results that are document chunks get a citation.
• Config and key handling are hardened.

Merge order: merge engine Dakera-AI/dakera#922 first (its merge tags v0.12.3 and publishes the images), then this PR. helm and deploy go after the clients. This PR does not depend on the 0.12.3 SDK PRs: it stays on dakera-client 0.12.2 and uses raw requests for the 0.12.3 routes and fields.

Changes

• Breaking (approved by the owner). dk --format json|compact memory recall now prints one object, {"memories": [...], "context_memories": [...]}, instead of an array of rows. Read the results from .memories. The old output could not be parsed anyway: an info line was printed before the JSON on stdout.
• dk memory recall
  • Sends neighborhood_mode through --neighborhood <separate|inline|off> (default separate).
  • Sends include_summaries only when --include-summaries[=false] is given.
  • Prints at most --top-k ranked rows, then the Context section, where each row names the result it belongs to (#2 <id>).
  • Adds a MATCHED_TEXT column when results were collapsed.
  • Adds a SOURCE column for results that are document chunks (Field Manual, p. 39-40 › Install). In JSON this is document: document_id, title, pages, heading_path, chunk_index.
  • An older server's extra rows past --top-k are left out, with a warning.
• dk document (Dakera-AI/dakera#923). Uses raw requests; dakera-client stays at 0.12.2.
  • import <file|->, routed by format:
    • Text, Markdown and HTML go through POST /v1/memory/documents.
    • PDF, DOCX and non-UTF-8 text are uploaded to the agent's namespace (or --namespace), then imported through POST /v1/namespaces/{ns}/attachments/{ref}/document.
  • The media type comes from the file extension unless --media-type is given; an unknown extension exits 5 before any request.
  • Import options: --title, --document-id, --tag, --session-id, --type, --importance, --lang, --chunk-tokens, --overlap, --strategy, --decompose, --wait/--timeout.
  • With --wait, a failed job exits non-zero with its status and code.
  • Other subcommands: job <id>, list (--limit, --cursor), show <id> (chunks with pages and heading paths), delete <id>. All print as a table or JSON.
  • A server older than v0.12.3 answers 404/405 on these routes; the command reports that it needs v0.12.3.
  • Shell completions (bash, zsh, fish) include the new commands.
• Strict admin routes
  • Every route and method dk calls matches the engine router. The route list now includes the document routes.
  • The bodies sent to the 4 strict routes carry only accepted fields.
  • A 422/400 "unknown field" error now gets a hint naming the field.
  • dk keys errors now carry exit codes and hints.
  • IDs are encoded in URL paths.
  • There is no ops shutdown command.
• Security
  • ~/.dakera/config.toml is written with mode 0600, and its directory with 0700.
  • A warning is printed when the config file is readable by other users.
  • dk config masks the API key and shows the transport.
  • A warning is printed when the key would go over plain http to a non-loopback host.
  • Raw requests time out: 10 s to connect, 330 s between reads.
• Final 0.12.3 API
  • dk memory recall lists the server's rank_score, the score that follows the order of the results. score and smart_score can rise down the list. Older servers send no rank_score; smart_score is listed as before.
  • A 429 exits 6 (server busy) with the Retry-After hint. Since 0.12.3 an overloaded server answers 429 where it answered 503.
  • Recall, search and batch recall of an agent with nothing stored now answer 200 with no memories; dk prints "No memories found" (container test).
  • Route list: the 0.12.3 restorable-dedup routes.
• Dependencies: rustls 0.23.46, quinn-proto 0.11.19, chacha20 0.10.2, rustls-webpki 0.103.16 (RUSTSEC-2026-0382) and webpki-root-certs 1.0.10 (RUSTSEC-2026-0383). cargo audit is clean.
• Release dk 0.8.2: version bumped in Cargo.toml and Cargo.lock; CHANGELOG [0.8.2] has a Breaking section; the README compatibility table now covers v0.12.3; hint text updated. The deb/rpm packages read the version from Cargo.toml, and the snap takes it from the tag.

Testing

• cargo check passes
• cargo clippy -- -D warnings passes (--all-targets)
• cargo fmt --check passes
• cargo test passes: 171 unit, 47 mock integration, 2 route audit, 84 in v012, 26 in v0122, and 18 in v0123 (documents, recall citations and context, config, keys).
• Tested against the final 0.12.3 server (the CI image of dakera#922 at c5b63fa): all 26 container integration tests pass. That includes 4 new 0.12.3 tests: document import, citation and delete; a PDF on a server without attachments (exit 6, names DAKERA_ATTACHMENTS); recall scores that follow the order; and empty agents. These tests skip themselves on an older server.
• Manual smoke test against the same server: dk document import (Markdown, --wait), list, recall with a citation and a context row, and a PDF import refused while attachments are off.
• CI's container is still the released 0.12.0 image, so the 0.12.3 tests skip there. The service health check now works on images without curl. Once 0.12.3 is released, moving CI to it is a one-line change.
• cargo build --release: dk --version prints 0.8.2, and dk document --help runs.

Checklist

• Updated CHANGELOG.md
• Updated documentation (if applicable)
• No breaking changes to existing commands. Exception: the approved memory recall --format json shape (see Breaking).

🤖 Generated with Claude Code

https://claude.ai/code/session_019GcW157E6uJuFrBa2RgZBz