Skip to content

core

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

core

README.md

@klickd/core

Official JavaScript/TypeScript library for reading and writing .klickd portable AI context files.

One soul. Any model. Any agent. — open-source security and continuity layer for every actor in AI.

Official page for the open .klickd format → klickd.app/klickdskill

npm version License: CC0-1.0 DOI (v4.0.0)

Install

npm install @klickd/core

Argon2id dependency

The v3 format uses Argon2id for key derivation. Install the appropriate package for your environment:

  • Node.js: npm install argon2
  • Browser / bundler: npm install argon2-browser

Quick start

Load (decrypt) a .klickd file

import { loadKlickd } from '@klickd/core';
import { readFileSync } from 'node:fs';

const fileBytes = readFileSync('context.klickd');
const payload = await loadKlickd(fileBytes, { passphrase: 'my-passphrase' });

console.log(payload.identity?.name);
console.log(payload.memory);

Save (encrypt) a .klickd file

import { saveKlickd } from '@klickd/core';
import { writeFileSync } from 'node:fs';
import type { KlickdPayload } from '@klickd/core';

const payload: KlickdPayload = {
  payload_schema_version: '3.0.0',
  domain_schema_version: '1.0.0',
  identity: { name: 'Alice', language: 'en', timezone: 'Europe/Luxembourg' },
  agent_instructions: 'Be concise.',
  memory: [],
};

const envelope = await saveKlickd(payload, {
  passphrase: 'my-passphrase',
  domain: 'education',
});

writeFileSync('context.klickd', envelope, 'utf8');

Legacy v2.x files (PBKDF2)

To read files created with the v2.x PBKDF2-SHA256/600k KDF, pass legacy: true:

const payload = await loadKlickd(fileBytes, {
  passphrase: 'my-passphrase',
  legacy: true,
});

.klickd v4 preview fields (additive, non-GA)

This library currently targets the v3 envelope and is stable at v3.5.1. The v4 preview track (v4.0.0-preview.1, NOT GA) introduces additive payload fields such as profile_kind, media_profile, verification_gates, claim_sources, verification_artifacts, migration, and context_cost.

These fields are preserved verbatim on round-trip — loadKlickd returns the raw decrypted JSON object and saveKlickd re-encrypts it without filtering unknown keys. The KlickdPayload type carries an open [key: string]: unknown index signature so v4 preview fields type-check as additive properties. Strict v4 validation, migrations, and business-logic helpers are intentionally not implemented yet.

const v4PreviewPayload: KlickdPayload = {
  payload_schema_version: '4.0.0-preview.1',
  domain_schema_version: '1.0.0',
  profile_kind: 'learner',
  verification_gates: { public_post: 'confirm' },
  // ... any additional v4 preview fields are preserved on save/load
};

const recovered = await loadKlickd(
  await saveKlickd(v4PreviewPayload, { passphrase: 'my-passphrase' }),
  { passphrase: 'my-passphrase' },
);
// recovered deep-equals v4PreviewPayload

See SPEC.md §33 and examples/v4-preview/ for preview-track details.

Starter .klickd skills (v4.0 envelope — non-normative)

Four real, structured, downloadable starter .klickd skills ship under examples/v4/starter-skills/:

Each skill carries base_transversal_core, framework-anchored competencies[] (ESCO / DigComp / LifeComp / EQF / CEFR / SFIA), levels[], mastery[] (pointer-only), source_policy, evidence_policy, verification_gates, human_authority, and a structured_memory slice scoped to memory.x_klickd.<pack>. They are non-normative and trigger no release. SHA-256 manifest in manifest.json; offline verifier scripts/verify_starter_skills.py.

Bundled in @klickd/core 4.0.1

Starting with @klickd/core 4.0.1 (a packaging-only patch — the stable spec release remains v4.0.0), these four starter .klickd skills are shipped inside the npm tarball under starter-skills/ and exposed through a small helper API. The on-the-wire .klickd format, the bundled JSON schemas, and the spec are unchanged from v4.0.0. This patch ships only the starter skill packaging fix; no new schema material is introduced.

import {
  listStarterSkills,
  getStarterSkillBytes,
  getStarterSkillsManifest,
  getStarterSkillsDir,
} from '@klickd/core';

listStarterSkills();
// → ['coding.klickd', 'research.klickd', 'student.klickd', 'user.klickd']

const bytes = getStarterSkillBytes('user.klickd');
const manifest = getStarterSkillsManifest();
const dir = getStarterSkillsDir(); // absolute path to bundled starter-skills/

x.klickd v4.1 skill packs (42 candidate packs — non-normative)

The 42 x.klickd v4.1 candidate skill packs (8 Lite + 34 Pro) ship inside the npm tarball under x-klickd-skills/ alongside the aggregated download index manifest.json. They are NON-NORMATIVE and NOT a v4.1 GA release, and they are JSON artifacts — not native skills in any assistant. A pack is only "used" once artifact_loaded and sha256_matches_manifest are both true.

import {
  listXKlickdSkillPacks,
  loadXKlickdSkillPack,
  getXKlickdSkillPackBytes,
  getXKlickdSkillsManifest,
} from '@klickd/core';

listXKlickdSkillPacks().length; // → 42

const skill = loadXKlickdSkillPack('x.klickd/llm_agent_engineering');
// skill.artifact_loaded === true, skill.sha256_matches_manifest === true
// skill.tier, skill.competency_ids, skill.gates, skill.evidence_policy, ...

const bytes = getXKlickdSkillPackBytes('work-assistant.klickd'); // by file, pack id, or bare id

Full protocol and truth boundary: docs/integrations/skill-loader-protocol.md.

Cryptographic specification (v3.0)

Parameter Value
KDF (default) Argon2id — m=65536, t=3, p=1
KDF (legacy) PBKDF2-SHA256 / 600 000 iterations
Cipher AES-256-GCM
AAD RFC 8785 JCS over 6 canonical fields
Base64 RFC 4648 §4 standard padded
Salt 16 bytes (CSPRNG)
IV 12 bytes (CSPRNG)

Error codes

Code HTTP Meaning
KLICKD_E_AUTH 401 Wrong passphrase / GCM tag mismatch
KLICKD_E_VERSION 400 Unsupported klickd_version major
KLICKD_E_FORMAT 400 Malformed JSON envelope / missing fields
KLICKD_E_KDF 400 Unknown or unavailable KDF
KLICKD_E_WEAK_PASS 422 Passphrase shorter than 8 characters
KLICKD_E_SCHEMA 400 Missing payload_schema_version

Links

License

CC0 1.0 Universal — Public Domain Dedication.
Author: Vincenzo Cirilli (.klickd / klickd.app, Luxembourg)