DEV Community: Davincc77

x.klickd v4.1: Portable, Encrypted, Human-Governed Memory for AI Workflows That Don’t Reset

Davincc77 — Sun, 31 May 2026 00:00:32 +0000

While everyone celebrates the collapse of token costs, we are still measuring the wrong thing.
The real problem is not only the price of the token anymore. It is that memory remains disposable.

AI does not just need better models. It needs memory that travels with you: portable, bounded, inspectable, encrypted, governed by humans, and able to survive beyond a single session.
That is exactly what .klickd has been building from day one.

Today I am releasing x.klickd v4.1, with its full DOI evidence pack, npm and PyPI packages:
• DOI: https://doi.org/10.5281/zenodo.20459934
• GitHub: https://github.com/Davincc77/klickdskill
• npm: @klickd/core@4.1.0
• PyPI: klickd==4.1.0
The problem: AI memory is still too disposable.
Most long AI workflows still rebuild context inside prompts. At first, this feels harmless. A few reminders, a few project notes, a few constraints. But as the workflow grows, prompt-history memory grows with it.
Token consumption rises. Latency can increase. Context gets noisier. Contradictions accumulate. The model may still answer, but continuity becomes harder to trust.
That matters for coding, education, research, governance, security reviews, agent workflows, gaming, robotics, drones and mission-heavy systems. In those environments, memory is not decoration. It is operational infrastructure.
What .klickd proposes
.klickd explores a different architecture: a portable, encrypted memory file that can carry structured skills, preferences, constraints, evidence, policies and optional compressed memory across sessions, models, agents and devices.
The AI model does not decrypt the .klickd file. A trusted runtime does. The model only receives the safe, relevant, sanitized context selected for the task.
The goal is not to make prompts longer. The goal is to make memory more responsible.
When it all .klickd

The turning point came when the skill catalogue stopped being a catalogue at all. It became an architecture: a shared competency backbone, domain-specific layers, governance rules, evidence policies, human-veto mechanisms and optional compressed memory.
That was the moment it all .klickd .
The benchmark did not invent the idea. It stress-tested it. And under that pressure, the architecture began to reveal its core promise: AI memory does not have to grow noisier as projects grow longer. With the right structure, it can become more portable, more bounded, more governed, and more useful.
In v4.1, .klickd is not presented as a universal standard. It is not claiming native support across all AI systems. It is a working open format and reference architecture showing how portable AI memory can function in practice.
What v4.1 includes
v4.1 turns .klickd from a promising format into a more serious architecture. It includes:
• a mapped x.klickd competency matrix;
• structured Lite and Pro skill packs;
• governance rules;
• evidence policies;
• human-veto mechanisms;
• optional compressed_memory for longer workflows;
• npm and PyPI packages;
• a DOI evidence pack with benchmark reports, scripts, metadata and limitations.
Compression is not the whole story. The first efficiency layer comes from structure: deciding what should be remembered, how it should be organized, what can be safely injected, and what must remain governed. Optional compressed memory is the second layer, especially useful when projects become long enough that repeated context becomes structurally expensive.
The principle is simple:
Maximal quality input for minimal token size

Benchmark result: repeated context overhead
The v4.1 benchmark tests the kind of workflow .klickd was designed for: long-running, multi-session, multi-condition AI projects.
It compares multiple conditions: no memory, prompt-history memory, manual context repetition, project-docs-only context, static .klickd , compressed .klickd , cross-session resume, cross-language continuity, cross-agent continuity, human-veto behavior, contradiction handling and CI-weakening resistance.
The completed benchmark aggregate covers four complete bundles:
• 7,200 expected outputs;
• 7,189 valid outputs;
• 11 errors;
• 99.85% completion rate.
Compared with prompt-history memory:
• static x.klickd bundles reduced repeated input-token overhead by approximately 76.49%;
• optional compressed_memory reduced repeated input-token overhead by approximately 93.34%;
• governance conditions such as cross-session resume, cross-language continuity, cross-agent handoff, human-veto, contradiction handling and CI-weakening resistance remained in the same efficiency band, around 92.3-92.9% reduction.

Quality scoring
The benchmark also includes automatic long-project quality scoring across the 12 tested conditions.
Under this benchmark-specific rubric:
• x.klickd condition family mean: 86.24 / 100;
• standard AI usage without x.klickd: 58.51 / 100;
• best x.klickd condition, xklickd_compressed_bundle : 88.79 / 100;
• best non-x.klickd baseline, project_docs_only : 73.62 / 100.

“Standard AI usage without x.klickd” means no portable memory file: prompt-history memory, project documents, or no memory.
This is not a general intelligence score. It is an automatic, benchmark-specific long-project score built from completion, bounded memory, context architecture, early resume, language switch, cross-agent handoff, contradiction handling, human-veto / CI behavior and final delivery persistence.

Why the bundle 5 incident matters
The fifth bundle, b05_drone_mission_ops , was excluded from the aggregate. It passed a 24/24 mini-probe after the Gemini cap was adjusted, but the full run hit provider quota and rate-limit constraints before completion.
That is not a failure of the x.klickd architecture. It is a provider-capacity limitation in a hard stress scenario. It is documented separately in the DOI evidence pack.
The process also improved the benchmark harness itself. PR #91 added request timeouts, wall-clock caps, progress logging and deadlock-resistant execution. PR #92 classified provider spend-cap exhaustion as terminal rather than retrying until the job timed out.
A serious benchmark is not one where nothing goes wrong. A serious benchmark is one where failures are visible, classified, fixed and documented.
Where this fits in the memory landscape
The need for AI memory is not unique to .klickd . Many systems are exploring agent memory, graph memory, project memory, MCP memory and persistent assistant state.
.klickd takes a specific stance inside that landscape:
• memory should be portable;
• memory should be encrypted;
• memory should be user-owned or organization-governed;
• memory should carry skills and responsibility, not only chat history;
• memory should remain bounded rather than becoming an endless prompt-history archive.
Future evaluation should compare .klickd against established long-term memory benchmarks such as LongMemEval and agentic multi-session environments such as MemoryArena. The current v4.1 benchmark focuses on long-project continuity, governance conditions and repeated-context overhead rather than claiming direct superiority on public memory benchmarks.

Beyond chat
If this architecture scales, .klickd is not only relevant to chat assistants.
It becomes relevant to coding projects that last hundreds of sessions, student learning continuity, AI tutors, persistent NPCs in gaming worlds, drones and mission operations, robotics, space missions, agentic workflows and AI-native operating systems.
A drone mission, a long software migration, a student learning path, a persistent game character or a multi-agent research project cannot rely forever on copy-pasted summaries and growing prompt histories. They need structured continuity. They need memory that can be inspected, constrained, transferred and governed.
Limits
.klickd is not yet universal. It does not provide automatic GDPR or EU AI Act compliance. It does not replace spend caps, RBAC, audit logs, provider controls, security reviews or deployment governance.
The current v4.1 release shows that .klickd can work as a portable, encrypted memory format in controlled long-project benchmarks. Broader adoption requires adapters, UX work, independent replication, security validation and integration into real runtimes.
That distinction matters. The ambition is large, but the claim must stay precise.
Try it
npm: Benchmark result: repeated context overhead
The v4.1 benchmark tests the kind of workflow .klickd was designed for: long-running, multi-session, multi-condition AI projects.
It compares multiple conditions: no memory, prompt-history memory, manual context repetition, project-docs-only context, static .klickd , compressed .klickd , cross-session resume, cross-language continuity, cross-agent continuity, human-veto behavior, contradiction handling and CI-weakening resistance.
The completed benchmark aggregate covers four complete bundles:
• 7,200 expected outputs;
• 7,189 valid outputs;
• 11 errors;
• 99.85% completion rate.
Compared with prompt-history memory:
• static x.klickd bundles reduced repeated input-token overhead by approximately 76.49%;
• optional compressed_memory reduced repeated input-token overhead by approximately 93.34%;
• governance conditions such as cross-session resume, cross-language continuity, cross-agent handoff, human-veto, contradiction handling and CI-weakening resistance remained in the same efficiency band, around 92.3-92.9% reduction.

Quality scoring
The benchmark also includes automatic long-project quality scoring across the 12 tested conditions.
Under this benchmark-specific rubric:
• x.klickd condition family mean: 86.24 / 100;
• standard AI usage without x.klickd: 58.51 / 100;
• best x.klickd condition, xklickd_compressed_bundle : 88.79 / 100;
• best non-x.klickd baseline, project_docs_only : 73.62 / 100.
“Standard AI usage without x.klickd” means no portable memory file: prompt-history memory, project documents, or no memory.
This is not a general intelligence score. It is an automatic, benchmark-specific long-project score built from completion, bounded memory, context architecture, early resume, language switch, cross-agent handoff, contradiction handling, human-veto / CI behavior and final delivery persistence.
[x.klickd v4.1 quality score: ./xklickd_v41_quality_score_final.png]
Why the bundle 5 incident matters
The fifth bundle, b05_drone_mission_ops , was excluded from the aggregate. It passed a 24/24 mini-probe after the Gemini cap was adjusted, but the full run hit provider quota and rate-limit constraints before completion.
That is not a failure of the x.klickd architecture. It is a provider-capacity limitation in a hard stress scenario. It is documented separately in the DOI evidence pack.
The process also improved the benchmark harness itself. PR #91 added request timeouts, wall-clock caps, progress logging and deadlock-resistant execution. PR #92 classified provider spend-cap exhaustion as terminal rather than retrying until the job timed out.
A serious benchmark is not one where nothing goes wrong. A serious benchmark is one where failures are visible, classified, fixed and documented.
Where this fits in the memory landscape
The need for AI memory is not unique to .klickd . Many systems are exploring agent memory, graph memory, project memory, MCP memory and persistent assistant state.
.klickd takes a specific stance inside that landscape:
• memory should be portable;
• memory should be encrypted;
• memory should be user-owned or organization-governed;
• memory should carry skills and responsibility, not only chat history;
• memory should remain bounded rather than becoming an endless prompt-history archive.
Future evaluation should compare .klickd against established long-term memory benchmarks such as LongMemEval and agentic multi-session environments such as MemoryArena. The current v4.1 benchmark focuses on long-project continuity, governance conditions and repeated-context overhead rather than claiming direct superiority on public memory benchmarks.
Beyond chat
If this architecture scales, .klickd is not only relevant to chat assistants.
It becomes relevant to coding projects that last hundreds of sessions, student learning continuity, AI tutors, persistent NPCs in gaming worlds, drones and mission operations, robotics, space missions, agentic workflows and AI-native operating systems.
A drone mission, a long software migration, a student learning path, a persistent game character or a multi-agent research project cannot rely forever on copy-pasted summaries and growing prompt histories. They need structured continuity. They need memory that can be inspected, constrained, transferred and governed.
Limits
.klickd is not yet universal. It does not provide automatic GDPR or EU AI Act compliance. It does not replace spend caps, RBAC, audit logs, provider controls, security reviews or deployment governance.
The current v4.1 release shows that .klickd can work as a portable, encrypted memory format in controlled long-project benchmarks. Broader adoption requires adapters, UX work, independent replication, security validation and integration into real runtimes.
That distinction matters. The ambition is large, but the claim must stay precise.
Try it
npm: npm install @klickd/core
python: pip install klickd
Evidence pack:
https://doi.org/10.5281/zenodo.20459934
GitHub:
https://github.com/Davincc77/klickdskill
Conclusion
The broader question is no longer only which model is most capable. It is how memory, authority, continuity and trust should be carried across the systems that increasingly mediate human work.
If AI becomes infrastructure, memory cannot remain trapped inside disposable sessions. It needs to become portable, inspectable and governed by the people and organizations it serves.
That is the direction .klickd is designed to explore.

.klickd v4.0.0 — Portable AI memory with constraints, strict schemas, and test vectors

Davincc77 — Mon, 25 May 2026 19:45:56 +0000

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.

Parameter	Value
KDF	Argon2id — m=65536, t=3, p=4
Legacy KDF	PBKDF2-SHA256 / 600,000 iterations (v2.x backward compat)
Cipher	AES-256-GCM
IV	12 bytes, CSPRNG
Salt	16 bytes, CSPRNG
AAD	RFC 8785 JCS-canonicalized over 6 envelope fields
Base64	RFC 4648 §4, standard padded
GCM tag	16 bytes, appended to ciphertext before base64

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:

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 or invalid `payload_schema_version`

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

Resource	URL
GitHub Release v4.0.0	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
Spec (SPEC.md)	https://github.com/Davincc77/klickdskill/blob/main/SPEC.md
v4 Payload Schema	https://github.com/Davincc77/klickdskill/blob/main/schemas/klickd-payload-v4.schema.json
Migration guide v3→v4	https://github.com/Davincc77/klickdskill/blob/main/docs/spec/MIGRATION_V3_TO_V4.md
Playground	https://klickd.app/klickdskill/playground
Benchmark DOI	https://doi.org/10.5281/zenodo.20320480

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

One Soul, Any Model: Portable Memory for Open-Source Agents with .klickd

Davincc77 — Sat, 23 May 2026 01:18:46 +0000

This is a submission for the Hermes Agent Challenge: Build With Hermes Agent

What I Built

I built a prototype integration between Hermes Agent and .klickd, an open portable memory format for AI agents.

The problem I wanted to explore is simple:

Every new agent session often pays again to rediscover context that already exists.

That repeated context cost shows up as:

re-explaining project state;
reloading constraints;
rediscovering previous decisions;
rebuilding handoff notes;
rerunning tests just to find the same failure;
losing track of which actions require human approval.

.klickd is designed to turn that repeated context into a portable, encrypted, versioned file that an agent can load before work starts.

Hermes Agent is a good fit for testing this because it is an open-source, self-hosted agent runtime with skills, plugins, hooks, approvals, local execution, and agentic workflow orchestration.

In this project:

Hermes runs the workflow. .klickd carries the state.

The prototype focuses on a benchmark called Context Cost Benchmark, which compares two modes:

Baseline cold start

The full context is pasted into the prompt every time.
.klickd-loaded mode

Structured context is loaded from a .klickd fixture and injected into the agent workflow.

The benchmark is designed to measure:

repeated input tokens;
output tokens;
estimated cost;
latency;
continuity errors;
violations of locked decisions;
violations of tool permissions;
handoff quality;
unnecessary reruns of expensive commands.

The goal is not to claim a magic percentage improvement. The goal is to measure, reproducibly:

How many tokens and errors are we paying for simply because the agent has to rediscover state we already produced?

Demo

For the Hermes Agent Challenge, I created an experimental Hermes integration inside the klickdskill repository.

The demo uses Hermes Agent to drive the local .klickd Context Cost Benchmark.

hermes_klickd_agent_session_messages_json

If the embedded agent session does not render correctly, here is the relevant Hermes output:

session_id: 20260523_004058_85115c

Existing artifacts from 2026-05-23 were used. No rerun was needed.

Token-proxy totals:
- Cold: 310
- Paste: 6570
- Klickd: 5270

Verified artifacts:
- report.md
- summary.csv
- raw_runs.jsonl
- artifacts/sample_test.log

No publishes, git pushes, or external tool calls were performed.

The live Hermes run used:

Hermes Agent v0.14.0
OpenRouter free model route
capped API key with no paid budget
local dry-run benchmark
no production deployment
no package publishing
no external posting

Hermes session:

20260523_004058_85115c

Hermes was asked to use the klickd-context-cost skill, inspect the benchmark outputs, and avoid rerunning work if durable artifacts already existed.

The key result:

Existing artifacts from 2026-05-23 were used. No rerun was needed.

That matters because one of the core ideas in .klickd v4 is that agents should not spend tokens or compute rediscovering output that already exists.

The dry-run produced these local artifacts:

benchmarks/context_cost/results/2026-05-23/
├── report.md
├── summary.csv
├── raw_runs.jsonl
└── artifacts/
    └── sample_test.log

The benchmark output was explicitly marked as a whitespace token proxy, not a provider-token measurement. This is important: these are not OpenAI, Anthropic, or OpenRouter tokenizer counts. They are deterministic local proxy values for early validation.

Current dry-run totals:

Condition	Token-proxy total
Cold start	310
Full context pasted	6570
`.klickd` structured context	5270

The useful result is not “.klickd reduces cost by X%.” That would be premature.

The useful result is:

The benchmark harness can now compare repeated context strategies, produce raw evidence, persist artifacts, and let Hermes inspect those artifacts instead of rerunning the same work.

Verification artifacts

One lesson from real agent workflows is that agents often rerun expensive commands just to recover output they already produced.

The benchmark therefore includes a verification_artifacts[] pattern inspired by this idea:

command 2>&1 | tee .test-output/<scope>.log

Instead of rerunning the test suite to find a failure, the agent can inspect the persisted artifact:

grep -n FAIL .test-output/full.log

In .klickd v4, that becomes structured state:

{
  "command": "npm test",
  "artifact_path": ".test-output/vitest.log",
  "status": "failed",
  "query_hint": "grep -n FAIL .test-output/vitest.log",
  "checked_at": "2026-05-23T00:00:00Z",
  "retention": "latest",
  "scope": "project"
}

This turns agent memory into something more operational:

what the agent knows;
what the agent must verify;
what the agent is not allowed to do without approval;
where the evidence lives;
what happened last time.

Code

Repository:

https://github.com/Davincc77/klickdskill

Hermes POC integration path:

integrations/hermes/
├── README.md
├── skill/
│   └── SKILL.md
├── plugin/
│   ├── plugin.yaml
│   └── __init__.py
├── scripts/
│   └── run_context_cost_benchmark.py
└── tests/

Context Cost Benchmark path:

benchmarks/context_cost/
├── RFC.md
├── runner.py
├── fixtures/
│   ├── baseline/
│   ├── klickd/
│   ├── prompts/
│   ├── validation/
│   ├── verification_artifacts/
│   └── edge_cases/
├── results/
└── tests/

Current benchmark pieces:

RFC-003: Context Cost Benchmark
local dry-run runner
fixture validation
deterministic token proxy
CSV / JSONL / Markdown reports
edge-case fixtures for:
- migration/version break;
- tool-call failure recovery;
- multi-session handoff.

The Hermes integration currently includes:

a Hermes-facing skill;
an experimental plugin scaffold;
a wrapper script that runs the local benchmark;
tests for the wrapper;
explicit safety constraints:
- no provider calls from the wrapper;
- no paid resources;
- no publishing;
- no production deployment;
- no secrets.

My Tech Stack

Hermes Agent — open-source, self-hosted agent runtime

https://github.com/NousResearch/hermes-agent
Hermes Agent docs

https://hermes-agent.app/en/docs
.klickd / klickdskill — portable encrypted AI context format

https://github.com/Davincc77/klickdskill
.klickd official page

https://klickd.app/klickdskill
Python SDK — local .klickd loading / saving

Current development install, until PyPI is updated:

pip install "git+https://github.com/Davincc77/klickdskill.git@main#subdirectory=packages/pypi/klickd"

Current Python import:

from klickd import load_klickd, save_klickd

GitHub Actions — test vectors and package integrity checks
CSV / JSONL / Markdown — benchmark reports
Local verification artifacts — persisted logs for agent inspection
OpenRouter free model route — used only to run the Hermes agent session for the demo

How I Used Hermes Agent

Hermes Agent is used as the workflow runner for the benchmark.

The .klickd file is not meant to replace Hermes memory or Hermes skills. Instead, it gives Hermes a portable external state artifact it can load before work starts.

Hermes is responsible for:

running the benchmark task;
reading fixture context;
executing local dry-run commands;
inspecting generated artifacts;
summarizing benchmark results;
respecting approval and verification boundaries.

.klickd is responsible for carrying:

project state;
locked decisions;
tool permissions;
handoff notes;
verification gates;
human veto rules;
claim sources;
verification artifacts.

This is useful because multi-agent systems need more than agent-to-agent communication.

If A2A defines how agents talk, .klickd explores what portable state they carry between tasks, tools, models, and sessions.

The Hermes integration is therefore not about making a chatbot remember more. It is about testing whether an open-source agent runtime can operate with structured, portable context instead of repeatedly reconstructing the same state.

The goal is to reduce:

repeated prompt context;
hallucinated continuations;
forgotten decisions;
unsafe actions;
unnecessary reruns;
handoff failures.

The larger idea is that agent memory should become infrastructure:

Portable state, explicit constraints, verification artifacts, and human approval boundaries.

In short:

Hermes runs the workflow. .klickd carries the state.

What I Learned

The first useful result was not a performance number. It was a workflow result.

Hermes correctly used the existing benchmark artifacts instead of rerunning the dry-run unnecessarily.

That matters because a lot of agent waste is not only token waste. It is also repeated execution waste.

Agents often:

rerun tests to rediscover failures;
reread long logs from context;
rebuild state from previous messages;
regenerate summaries that already exist;
ask the model to infer what a file could have told it deterministically.

The benchmark and Hermes POC make that waste visible.

This also clarified the role of .klickd:

.klickd should not only remember preferences. It should help agents know:

what state exists;
what evidence exists;
what claims were executed, inspected, or assumed;
what actions require human approval;
what artifacts should be read before rerunning work.

That is why .klickd v4 is moving beyond portable memory toward a more operational layer:

portable encrypted context
+ project memory
+ verification gates
+ human veto
+ claim sources
+ verification artifacts
+ migration safety

Sources

Hermes Agent Challenge:

https://dev.to/challenges/hermes-agent-2026-05-15

Hermes Agent repository:

https://github.com/NousResearch/hermes-agent

Hermes Agent documentation:

https://hermes-agent.app/en/docs

.klickd / klickdskill repository:

https://github.com/Davincc77/klickdskill

.klickd official page:

https://klickd.app/klickdskill

Related article on preserving command output for agents:

https://dev.to/tacoda/dont-make-the-agent-re-run-the-test-suite-to-find-the-failure-427

Final Note

This is still early.

The benchmark does not yet claim provider-token savings. The current numbers are a deterministic local proxy. The next step is to run the same structure against real provider usage and compare actual input/output tokens, latency, and continuity failures.

But the architecture is now testable:

Hermes can act as the workflow runner.
.klickd can act as the portable state layer.
The benchmark can produce raw evidence.
Verification artifacts can prevent unnecessary reruns.
The system can evolve without breaking older .klickd files.

That is the direction I want to keep exploring.

One soul. Any model. Any agent.

AI agents don't have a memory problem. They have an architecture problem.

Davincc77 — Fri, 22 May 2026 08:06:23 +0000

Every session,
the LLM starts fresh. The user re-explains their role, their constraints, their preferences, what they were doing last time. Then the session ends, and next time: same thing.

The industry has diagnosed this correctly — statelessness is a real limitation. But the solutions being built mostly share the same premise: that memory is a service you connect to. I think that premise is wrong, and it shapes everything downstream.

The actual cost of statelessness

This isn't just a UX annoyance. A 2026 study by Pichay measuring 857 production AI sessions found that 21.8% of input tokens are "structural waste" — context that has to be re-established on every session because nothing persists. Nearly a quarter of your token budget, on every call, going toward re-explaining what should already be known.

For casual chat, that's tolerable. For workflows where context is dense and high-stakes — a lawyer switching between matters, a developer moving between codebases, a clinician picking up a patient thread — the cost compounds. And it's paid on every session, indefinitely.

What everyone else built

The market's answer has been centralized memory stores. Mem0 just closed $24M in funding (October 2025) to build "the memory layer for AI." Letta/MemGPT persists agent state in a server-side database. Zep builds a temporal knowledge graph of user interactions. SAMEP and MemTrust add encryption layers on top of server-side storage.

These are all genuinely useful tools. They solve the statelessness problem for most use cases. But they share an architecture: your context lives on their infrastructure, retrieval is query-scoped, and access is controlled by the service provider.

Even the solutions that advertise encryption — SAMEP, MemTrust — encrypt server-side. The data leaves the client before any cryptographic protection is applied. You've traded "AI forgets you" for "your memory is a managed cloud service." For many applications that's fine. For sensitive workflows, it's a different risk surface, not a smaller one.

The question that didn't get asked

What if memory is a file, not a service?

Not metaphorically. Literally: a single encrypted file, owned by the user, that travels with them across sessions and across models. The LLM reads it at session start, updates it at session end, and the file lives wherever the user puts it.

{
  "format": "klickd/v1",
  "encrypted_payload": "<AES-256-GCM ciphertext>",
  "kdf": "argon2id",
  "salt": "<per-file salt>",
  "nonce": "<GCM nonce>"
}

The key insight: persistent context doesn't require a server. It requires a standard. A shared format that any model can read and any client can write.

What we built

We built .klickd around this premise. The architecture is deliberately minimal:

AES-256-GCM encryption, Argon2id key derivation. Client-side only. The key is derived from a passphrase that never leaves the device. There is no server that could be subpoenaed, breached, or decommissioned.
Provider-agnostic. The same .klickd file works with GPT-4o, Claude, Gemini, Llama. It's not bound to any model provider's infrastructure or format.
Zero-server. There is no backend storing context. The file is the memory. If the file doesn't exist on your machine, the context doesn't exist anywhere.

On personalization quality: our LLM-judge benchmark (Zenodo, DOI: 10.5281/zenodo.20320480) — run across 23 test lots and 115 profiles, using qwen3-32b as judge — showed an average improvement of +13.9 points over baseline, with a range of +12.8 to +19.2. This is with llama-3.3-70b-versatile as the model under test. Results are published as-is; methodology and raw data are in the report.

For legal and regulated workflows specifically: the file-per-context model makes cross-matter contamination structurally impossible — not enforced by query scoping or ACLs, but by physical separation. Discovery compliance changes shape: you produce the file, or you don't. There's no "server logs" ambiguity.

The honest tradeoffs

This architecture gives up things that matter in other contexts.

You lose:

Centralized governance and server-side revocation
Query analytics and usage telemetry
Multi-tenant management at scale
Cross-device sync without a separate sync layer

You gain:

Zero trust surface: there is nothing to breach on the provider side
GDPR-native by architecture: personal data doesn't leave the client, so data residency and right-to-erasure are trivially satisfied
Portability: the file works with any model, now and in the future

This is not a universal solution. It is the right solution for a specific class of use cases: privacy-sensitive, cross-model, user-owned context. If you're building a consumer product where the vendor needs to manage memory at scale, use Mem0 or Zep — they're well-engineered for that. If you're building for a context where the user owns the data and the service provider should have zero access, the server-side model is architecturally incompatible with that requirement, regardless of how good the encryption story is.

Is this a new standard?

The field probably needs a portable, encrypted, open context format the way it needed JWT for auth tokens or RSS for feed syndication — a shared abstraction that any tool can read and write, owned by no single vendor.

We're not claiming .klickd is that standard. It's a proof of concept that the abstraction is viable. The memory-file spec is open: https://github.com/Davincc77/klickdskill

The question I keep coming back to: if the AI ecosystem converged on server-side memory because that's what was easy to build first, not because it's the right primitive — what does the right primitive actually look like? And is the file abstraction the right level, or is there something better?

Curious what others think, especially those who've hit the limits of query-scoped retrieval in production.