Akf

_akf: '{"v":"1.0","claims":[{"c":"Trust metadata for README.md","t":0.7,"id":"1979cbeb","src":"unspecified","tier":5,"ver":false,"ai":true,"evidence":[{"type":"other","detail":"updated certify and github action references","at":"2026-03-18T04:21:48.869226+00:00"}]}],"id":"akf-c33254656fc5","agent":"claude-code","at":"2026-03-18T04:21:48.870623+00:00","label":"public","inherit":true,"ext":false,"sv":"1.1"}'

Paste this to your agent

Don't install AKF yourself — let your agent do it. Paste this into Claude Code, Cursor, OpenClaw, or any coding agent:

Install AKF (pip install akf, or pipx install akf) and set it up: run `akf init --git-hooks`.
From now on:
- After you create or modify a file, stamp it:
    akf stamp <file> --agent <your-id> --evidence "<what you verified, e.g. 42/42 tests passed>"
- Before building on any existing file, check it first:
    akf check <file>
  OK = fresh stamp with verified evidence, skip re-verification. STALE/LOW/UNSTAMPED = verify before trusting.
If you support MCP, also register the server: {"mcpServers":{"akf":{"command":"python","args":["-m","mcp_server_akf"]}}}

Your agent installs its own provenance layer — and every file it touches carries trust metadata from then on.

Why agents need this

Agents redo work constantly: re-read files, re-run tests, re-derive conclusions — because nothing tells them what was already verified. A stamp is cached verification state:

# Session 1 — agent fixes auth, tests pass
$ akf stamp auth.py --agent claude-code --evidence "42/42 tests passed"

# Session 2 — tomorrow, any agent, any tool
$ akf check auth.py
OK trust=0.65 agent=claude-code evidence=test_pass age=1d claims=1
# → build on it, skip re-verification

# Someone edits auth.py without re-testing
$ akf check auth.py
STALE trust=0.65 agent=claude-code evidence=test_pass age=1d claims=1 reason=modified_after_stamp
# → re-verify before trusting (exit code 1 — gate CI or hooks on it)

Stamps are trail markers agents leave for other agents — across sessions, across tools (Claude Code → Cursor → Copilot), across teams. Humans get the same trail: who made this file, AI or human, was it tested, can we trust it.

Don't trust the stamp — re-run it

A signature proves who said it; a replay proves it could have been true. A stamp can carry a falsifiable probe recipe, so the next agent re-verifies the claim instead of trusting the label:

# Stamp with a recipe that can be re-run
$ akf stamp auth.py --agent claude-code --evidence "42/42 tests passed" --replay "pytest -q"

# Later — re-run the probe instead of trusting the stamp
$ akf replay auth.py --run
CONFIRMED inputs=intact

# A dependency moved since the stamp was written
$ akf replay auth.py --run
CONFIRMED_DRIFTED inputs=drifted   # probe still passes, but against a changed world — re-check

REFUTED when the probe fails, UNREPLAYABLE when there's no recipe. This is the answer to "a trusted source can still be wrong": trust stops depending on who signed it, for any claim with a runnable check.

Quickstart

pip install akf    # Python
npm install akf-format    # TypeScript / Node.js

akf doctor         # Check your install — detects PATH issues and guides setup

akf command not found? Run akf doctor to auto-detect your setup, or use python3 -m akf (always works).

• Install with pipx: pipx install akf (recommended — auto-handles PATH)
• Windows: use python3 -m akf or install via pipx

# The core loop — stamp what you verified, check before you trust
akf stamp auth.py --agent claude-code --evidence "42/42 tests passed"
akf check auth.py        # OK trust=0.65 agent=claude-code evidence=test_pass age=0d

import akf

# Same loop from Python
akf.stamp_file("auth.py", agent="claude-code", evidence=["42/42 tests passed"])
result = akf.check_file("auth.py")
print(result.summary_line())   # OK trust=0.65 agent=claude-code evidence=test_pass age=0d claims=1

# Embed into Office docs, PDFs, images — any format
akf.embed("report.docx", claims=[...], classification="confidential")

# Audit for compliance (EU AI Act, HIPAA, SOX, GDPR, NIST AI, ISO 42001)
result = akf.audit("report.akf", regulation="eu_ai_act")
print(f"Compliant: {result.compliant}")

TypeScript / Node.js (akf-format):

import { create, validate, effectiveTrust, stampFile } from 'akf-format';

// Create a trust-stamped unit from any AI output
const unit = create('Revenue was $4.2B, up 12% YoY', 0.98, {
  source: 'SEC 10-Q',
  agent: 'claude-code',
});

// Validate against the AKF schema
const { valid } = validate(unit);

// Compute effective trust for a claim
const trust = effectiveTrust(unit.claims[0]);
console.log(`valid: ${valid}, score: ${trust.score}, decision: ${trust.decision}`);

// Stamp trust metadata directly into a file (markdown, json, code, …)
stampFile('report.md', { agent: 'claude-code', evidence: 'tests pass' });

Full TypeScript API and more examples: typescript/README.md.

For AI Agents

AKF is designed agent-first. One-line APIs for checking, stamping, streaming, and auditing.

import akf

# Check before you trust — can I build on this file without re-verifying?
result = akf.check_file("auth.py")
if result.status == "OK":      # fresh stamp, verified evidence
    ...                        # skip re-verification, save the tokens
# LOW / STALE / UNSTAMPED → verify before trusting

# Stamp with evidence (auto-detected: test_pass, type_check, human_review, etc.)
akf.stamp("Fixed auth bypass", kind="code_change",
          evidence=["42/42 tests passed", "mypy: 0 errors"],
          agent="claude-code", model="claude-sonnet-4-20250514")

# Stream trust metadata in real-time
with akf.stream("output.md", model="gpt-4o") as s:
    for chunk in llm_response:
        s.write(chunk)

# Trust-annotated git commits (uses git notes)
akf.stamp_commit(content="Refactored auth module", kind="code_change",
                 evidence=["all tests pass"], agent="claude-code")
print(akf.trust_log(n=10))  # + ACCEPT  ~ LOW  - REJECT  ? none

Multi-Agent Teams

AKF supports multi-agent orchestration — Claude Agent Teams, Copilot Cowork, Codex multi-agent, and any A2A-compatible platform.

import akf

# Agent-to-agent delegation with trust ceiling
policy = akf.DelegationPolicy(
    delegator="lead-agent", delegate="research-bot",
    trust_ceiling=0.7, allowed_actions=["search", "summarize"]
)
result = akf.delegate(parent_unit, policy)

# Multi-agent streaming session
with akf.TeamStream(["research", "writer", "reviewer"]) as ts:
    ts.write("research", "Found 3 sources", confidence=0.8)
    ts.write("writer", "Drafted summary", confidence=0.75)
    ts.write("reviewer", "Approved with edits", confidence=0.9)
    scores = ts.aggregate()  # per-agent + team trust

# Cross-platform agent identity
card = akf.create_agent_card(name="Research Bot", platform="claude-code",
                             capabilities=["search", "summarize"])
akf.verify_agent_card(card)  # SHA-256 hash verification

# Team certification (per-agent breakdown)
report = akf.certify_team("src/", min_trust=0.7)
# report.all_agents_certified — each agent must individually pass

CLI:

akf agent create --name "Bot" --platform claude-code --capabilities search,summarize
akf agent list
akf agent verify <id>
akf agent export-a2a <id> --output card.json   # A2A protocol bridge
akf agent import-a2a card.json
akf certify src/ --team                         # Per-agent breakdown

MCP Server

AKF ships an MCP server so any AI agent can create, validate, scan, and audit trust metadata.

# Install from the repo
pip install ./packages/mcp-server-akf

{
  "mcpServers": {
    "akf": {
      "command": "python",
      "args": ["-m", "mcp_server_akf"]
    }
  }
}

11 MCP tools: check_file · replay_file · create_claim · validate_file · scan_file · trust_score · stamp_file · audit_file · embed_file · extract_file · detect_threats

Ambient Trust

AKF works where AI agents work. Drop a config file, and every AI-generated file carries trust metadata automatically.

The trust pipeline:

Agent writes code → Git commit stamped → CI runs akf certify → Team reviews with context

Set up in 60 seconds:

# 1. Agent stamps its own work (already in this repo)
cat CLAUDE.md        # or .cursorrules / .windsurfrules / AGENTS.md / .github/copilot-instructions.md

# 2. Git hooks stamp every commit
akf init --git-hooks

# 3. CI certifies trust on every PR
#    uses: HMAKT99/AKF/extensions/github-action@main

# 4. Shell hook intercepts AI CLI tools
eval "$(akf shell-hook)"

Skills

AKF ships as a self-contained agent skill (skills/akf/): the check-before-you-trust procedure, an evidence reference, and a read-only check script.

npx skills add HMAKT99/AKF          # Claude Code, Cursor, Copilot, Cline and 18+ agents
clawhub install akf                 # OpenClaw
hermes skills tap add HMAKT99/AKF   # Hermes Agent

Format at a Glance

Compact (~15 tokens — optimized for AI):

{"v":"1.0","claims":[{"c":"Revenue was $4.2B","t":0.98,"src":"SEC 10-Q"}]}

Descriptive (human-readable — same data):

{"version":"1.0","claims":[{"content":"Revenue was $4.2B","confidence":0.98,"source":"SEC 10-Q"}]}

Full (with provenance, decay, AI flags, security):

{"v":"1.0","by":"[email protected]","label":"confidential","inherit":true,
 "claims":[
   {"c":"Revenue $4.2B","t":0.98,"src":"SEC 10-Q","tier":1,"ver":true,"decay":90},
   {"c":"H2 will accelerate","t":0.63,"tier":5,"ai":true,"risk":"AI inference"}
 ],
 "prov":[
   {"hop":0,"by":"[email protected]","do":"created","at":"2025-07-15T09:30:00Z"},
   {"hop":1,"by":"copilot-agent","do":"enriched","at":"2025-07-15T10:15:00Z"}
 ]}

Works With Every Format

AKF embeds natively — no sidecars needed for most formats:

# One API for all formats
akf.embed("report.docx", claims=[...], classification="confidential")
meta = akf.extract("report.docx")
akf.scan("report.docx")

Zero-Touch Auto-Stamping

AKF can automatically stamp every file AI touches — no manual intervention needed.

# Install the background watcher
akf install

# Or run in foreground
akf watch ~/Downloads ~/Desktop ~/Documents

The background watcher monitors directories for new and modified files and stamps them with trust metadata. Smart context detection automatically infers:

• Git author — from git log history
• Download source — from macOS extended attributes
• Classification — from project .akf/config.json rules
• AI-generated flag — from LLM tracking timestamps + content heuristics
• Confidence score — dynamically adjusted based on available evidence

Shell Hook (intercept AI CLI tools)

# Add to ~/.zshrc or ~/.bashrc
eval "$(akf shell-hook)"

Automatically detects when you run claude, chatgpt, aider, openclaw, ollama, or other AI CLI tools, and stamps any files they create or modify. Also pre-stamps files before upload to content platforms (gws, box, m365, dbxcli, rclone) so trust metadata travels with the file. Use --no-upload-hooks to disable.

Project Rules

Create .akf/config.json in your project root:

{
  "rules": [
    {"pattern": "*/finance/*", "classification": "confidential", "tier": 2},
    {"pattern": "*/public/*", "classification": "public", "tier": 3}
  ]
}

Files matching these patterns are automatically classified when stamped.

CLI

# ── Quick start ──
akf                          # Welcome + quick start
akf quickstart               # Interactive demo
akf doctor                   # Check installation health

# ── Stamp & create ──
akf create report.akf \
  --claim "Revenue $4.2B" --trust 0.98 --src "SEC 10-Q" \
  --by [email protected] --label confidential

# ── Check before you trust ──
akf check auth.py            # One line: OK / LOW / STALE / UNSTAMPED
akf check auth.py --json     # Structured output; exit codes 0/1/2 for gating
akf replay auth.py           # Inspect the stamp's falsifiable probe recipe
akf replay auth.py --run     # Re-run it: CONFIRMED / CONFIRMED_DRIFTED / REFUTED

# ── Validate & inspect ──
akf validate report.akf
akf inspect report.akf
akf trust report.akf

# ── Certify (aggregate pass/fail gate) ──
akf certify report.akf                        # Trust + detection + compliance
akf certify src/ --min-trust 0.8              # Custom threshold
akf certify . --evidence-file results.xml     # Attach test evidence
akf certify . --format json --fail-on-untrusted  # CI-friendly output
akf certify src/ --team                       # Per-agent trust breakdown

# ── Compliance ──
akf audit report.akf                          # Compliance readiness check
akf audit report.akf --regulation eu_ai_act   # EU AI Act
akf audit report.akf --trail                  # Audit trail

# ── Universal format commands ──
akf embed report.docx --classification confidential \
  --claim "Revenue $4.2B" --trust 0.98
akf extract report.docx
akf scan report.docx
akf scan ./docs/ --recursive
akf scan . --badge badge.json     # shields.io endpoint: "14% stamped · trust 0.76"

# ── Auto-stamping ──
akf install                                   # Install background watcher
akf watch ~/Downloads ~/Documents             # Watch directories
akf shell-hook                                # Print shell hook code
akf shell-hook --no-upload-hooks              # Without content platform hooks
akf uploads                                   # View upload stamp log

# ── Git integration ──
akf stamp <file> --agent claude-code --evidence "tests pass"

# ── Agent identity & teams ──
akf agent create --name "Bot" --platform claude-code
akf agent list
akf agent verify <agent_id>
akf agent export-a2a <id> --output card.json  # A2A protocol bridge
akf agent import-a2a card.json

# ── Knowledge Base ──
akf kb stats ./kb
akf kb query ./kb --topic finance

Security Detections

10 built-in detection classes: AI content without review, trust below threshold, hallucination risk, knowledge laundering, classification downgrade, stale claims, ungrounded AI claims, trust degradation chain, excessive AI concentration, provenance gap.

from akf import run_all_detections
report = run_all_detections(unit)
for finding in report.findings:
    print(f"[{finding.severity}] {finding.detection}: {finding.message}")

Trust Computation

effective_trust = confidence × authority_weight × temporal_decay × (1 + penalty)

Decision: score ≥ 0.7 → ACCEPT · ≥ 0.4 → LOW · < 0.4 → REJECT

Delegation ceiling: When an agent delegates to another, the delegate's output trust is capped at min(score, delegation_ceiling). This prevents trust inflation in multi-agent chains.

Integrations & Extensions

Framework integrations (install from repo via pip install ./packages/<name>):

Editor & CI extensions (source in repo):

For LLMs

Prompt with one example and LLMs produce valid AKF 95%+ of the time:

Output knowledge as AKF:
{"v":"1.0","claims":[{"c":"<claim>","t":<0-1>,"src":"<source>","tier":<1-5>,"ai":true}]}

See LLM-PROMPT.md for a full system prompt.

Documentation

vs Alternatives

Compliance

EU AI Act Article 50 takes effect August 2, 2026 — AI-generated content must carry transparency metadata (penalties up to EUR 35M / 7% of global turnover). Files stamped with AKF already carry it:

akf audit report.docx --regulation eu_ai_act

Mappings for EU AI Act and NIST AI RMF.

Contributing

See CONTRIBUTING.md for development setup, testing, and PR process.

Free and Open — Forever

AKF is free and open source under the MIT license. The format specification will always be free. No feature will ever be gated behind a paid tier. AKF is a standard, and standards must be free to be universal.

License

MIT — use it everywhere, embed it in everything.