Every new AI session starts cold. You re-explain who you are, what you're building, what constraints you're working under. If you switch models — GPT-4o to Claude to a local Llama — it's a clean slate again. This isn't a model quality problem. It's an architecture gap: there is no portable, user-owned state layer sitting between the user and the model.

.klickd is an attempt to build that layer as an open format. Today v4.0.0 GA ships — the first production-stable release of the v4 track. Here is exactly what it contains, written for someone who is going to read the code.

All links:

• GitHub Release: https://github.com/Davincc77/klickdskill/releases/tag/v4.0.0
• Zenodo DOI: https://doi.org/10.5281/zenodo.20383133
• PyPI: https://pypi.org/project/klickd/
• npm: https://www.npmjs.com/package/@klickd/core
• Format site: https://klickd.app/klickdskill

What a .klickd file is

A .klickd file is a single JSON document, encrypted client-side. No server required. No account. The user holds the passphrase — it never leaves the device.

When loaded into a compatible client, the decrypted payload is injected as a system prompt (or context prefix) into the AI session. The model receives structured data: identity, preferences, constraints, memory items, verification gates. It resumes rather than restarts.

The crypto envelope — frozen at klickd_version: "3.0"

The wire format does not change in v4. The envelope contract was frozen in the v3.x track and is intentionally unchanged.

The 6-field JCS-canonicalized AAD is the detail most implementations get wrong. It binds the ciphertext to the envelope metadata — if you swap the domain field or alter KDF parameters, the GCM tag won't verify. Both reference implementations apply this on every encrypt and verify on every decrypt.

v4 is signaled inside the payload, not the wire envelope:

{
  "klickd_version": "3.0",
  "created_at": "2026-05-25T00:00:00Z",
  "encrypted": true,
  "kdf": { "id": "argon2id", "m": 65536, "t": 3, "p": 4, "salt": "<base64>" },
  "cipher": { "name": "AES-256-GCM", "iv": "<base64>", "tag_len": 16 },
  "domain": "education",
  "ciphertext": "<base64 AES-256-GCM ciphertext + 16-byte GCM tag>"
}

A v3.x reader can open a v4 file without changes — the crypto is identical. It will see unknown payload fields and is expected to ignore them. This is the explicit versioning contract.

What's new in the v4 payload

v4.0.0 promotes five additive surface areas to GA. No v3.x field is removed, renamed, or repurposed.

1. profile_kind

A top-level enum: learner, professional, agent, family, research. Lets readers surface different UI affordances without inspecting the full payload.

2. verification_gates — the most architecturally interesting addition

A sparse, declarative map from action_class to gate level:

{
  "verification_gates": {
    "version": 1,
    "gates": [
      { "action_class": "public_post",              "level": "confirm" },
      { "action_class": "factual_claim_about_person", "level": "block" },
      { "action_class": "casual_media_generation",  "level": "silent" },
      { "action_class": "consent_change",           "level": "require-owner" }
    ]
  }
}

Gate levels ordered by friction: silent → warn → confirm → block → require-owner.

This is a UX friction signal, not a security boundary. The spec's design principle: verification gates must not push agents toward compliance-form UX for ordinary creative work. Unlisted action classes default to silent. The user sets the friction profile once; it travels with the file.

3. human_veto_policy — the override layer

Any action class in human_veto_policy.applies_to requires a human in the loop regardless of gate level or model confidence. The spec states this is sacred: no automatic mechanism may lower a gate past a human_veto_policy floor.

{
  "human_veto_policy": {
    "applies_to": ["public_post", "consent_change", "identity_assertion"],
    "second_party": null
  }
}

4. claim_sources and verification_artifacts

claim_sources declares where the agent should ground factual claims. verification_artifacts is a pointer ledger — not a payload sink — of outputs already produced by expensive verification commands. The next agent can consult it and skip re-running what was already verified.

5. migration block

Audit-only metadata recording source_version, migrated_at, migration_report_ref, and backup_ref. Points to where migration reports live; does not contain migrated data.

Non-destructive v3.x → v4 migrator

Design invariant: "Never break the soul."

from klickd import migrate_klickd

with open("profile_v3.klickd", "rb") as f:
    v3_bytes = f.read()

v4_bytes = migrate_klickd(v3_bytes, passphrase="my-passphrase")

with open("profile_v4.klickd", "wb") as f:
    f.write(v4_bytes)

import { migrateKlickd } from "@klickd/core";
import { readFileSync, writeFileSync } from "fs";

const v3Bytes = readFileSync("profile_v3.klickd");
const v4Bytes = await migrateKlickd(v3Bytes, { passphrase: "my-passphrase" });
writeFileSync("profile_v4.klickd", Buffer.from(v4Bytes));

The migrator writes a new file. The original is never overwritten. Unknown v3.x fields are preserved verbatim — v4 readers must carry unknown fields through on round-trip, not strip them. The migrator refuses to write if the output would be lossy.

Strict JSON Schemas (Draft 2020-12)

Two schemas ship:

• schemas/klickd-payload-v4.schema.json — validates the decrypted payload only
• schema/klickd-v4.schema.json — unified envelope + payload

Both set additionalProperties: false on controlled sub-objects. payload_schema_version is required and enumerated.

Python validation:

from klickd import validate, validate_iter_errors, KlickdError

# Raises KlickdError(KLICKD_E_SCHEMA) on failure
validate(payload, strict=True)

# Non-raising: yields every (path, message) pair
for path, message in validate_iter_errors(payload, strict=True):
    print(f"  {path}: {message}")

pip install "klickd[validate]"
npm install @klickd/core ajv

Cross-implementation test vectors

v4.0.0 ships tests/verify_vectors.py and tests/verify_vectors.ts. Each vector specifies: passphrase, KDF parameters (Argon2id: m, t, p, exact salt in hex), plaintext payload (UTF-8 JSON), and expected decrypted output. Both suites run against the same vectors in CI on every push.

If you're implementing .klickd in another language, fork these and run your implementation against them. If you pass, the crypto contract is correct.

Quick start

Python:

from klickd import load_klickd, save_klickd

# Load
with open("profile.klickd", "rb") as f:
    payload = load_klickd(f.read(), passphrase="my-passphrase")

print(payload["identity"]["name"])
print(payload["memory"])

# Save
payload = {
    "payload_schema_version": "4.0",
    "identity": {"name": "Alice", "language": "en", "timezone": "Europe/Luxembourg"},
    "agent_instructions": "Be concise. Resume as if you have been here from the start.",
    "memory": [],
    "verification_gates": {
        "version": 1,
        "gates": [{"action_class": "public_post", "level": "confirm"}]
    }
}
klickd_bytes = save_klickd(payload, passphrase="my-passphrase", domain="work")

TypeScript (Node.js >= 18):

import { loadKlickd, saveKlickd } from "@klickd/core";
import { readFileSync, writeFileSync } from "fs";

const payload = await loadKlickd(readFileSync("profile.klickd"), {
  passphrase: "my-passphrase"
});

const bytes = await saveKlickd(
  {
    payload_schema_version: "4.0",
    identity: { name: "Alice", language: "en" },
    agent_instructions: "Resume as if you have been here from the start.",
    verification_gates: {
      version: 1,
      gates: [{ action_class: "public_post", level: "confirm" }]
    }
  },
  { passphrase: "my-passphrase", domain: "work" }
);
writeFileSync("profile.klickd", Buffer.from(bytes));

Error codes:

About the benchmark numbers

The benchmark section shows +13.9 average score improvement (across 115 profiles) when a .klickd context file is present vs. absent, scored by qwen3-32b via Groq. Here's what that actually measures: how much better an AI's response aligns with a user's stated context when given structured context, as judged by another AI. It does not measure user outcomes, learning efficacy, or real task performance. The sample is 115 profiles across 23 subjects — directional signal, not a peer-reviewed controlled study. The methodology is published at DOI 10.5281/zenodo.20320480 for independent replication.

What .klickd is not

Taken directly from the Zenodo record and the GitHub release:

• Not an industry standard. No standards body has ratified .klickd. It is CC0.
• Not universally compatible. Portability depends on whether a specific AI tool accepts the system prompt injection. Known-good integrations are listed in docs/integrations/.
• Not a security boundary. Encryption protects the file at rest and in transit. It does not replace provider-side security, model alignment, or application-level access control.

Links

License: CC0 — public domain. No permission required to implement, fork, or build on top of this format.