HUQAN

Models generate. Agents act. Memory stores. HUQAN judges.

HUQAN is a local-first AI governance, agent-safety, and verification layer for claims, memory writes, and risky actions. It connects AI-assisted work to evidence, provenance, scope, policy, approval, and auditable Trust Receipts.

Quick start · Observability quickstart · Why HUQAN · How it works · Ways to run · Current scope

Canonical repository: https://github.com/ali-ulu/huqan

What is HUQAN?

AI systems can produce useful outputs without showing:

• what source supports a claim,
• which workspace or scope applies,
• whether a risky action was approved,
• what changed later,
• or why a result was allowed, blocked, or escalated.

HUQAN adds a deterministic, auditable trust boundary around those decisions on its tested local paths.

claim or action
      ↓
evidence + provenance + scope + policy
      ↓
verification + contradiction + risk gates
      ↓
ALLOW / BLOCK / ESCALATE
      ↓
Trust Receipt + audit context

HUQAN is not another LLM. Its core local graph, verification, gate, and receipt paths do not require a hosted model or cloud service.

Why HUQAN?

Need	HUQAN provides
Repeatable decisions	Deterministic verification and policy outcomes on tested paths
Evidence traceability	Provenance, graph evidence, reasoning context, and receipt links
Safer AI agents	Explicit review, block, escalation, and dry-run boundaries
Protected memory	Admission and workspace checks before canonical memory writes
Auditability	Trust Receipts and append-oriented audit records
Local operation	CLI, local server, and MCP flows without a required cloud dependency

HUQAN is designed for AI governance, agent safety, LLM-output verification, approval workflows, provenance tracking, MCP integrations, and audit-ready AI-assisted work.

Quick start

Requirements

• Git
• npm
• Node.js 22.13.0 or newer
• Node.js 22 LTS or 24 LTS is recommended
• A compiler toolchain may be required if your platform cannot use a prebuilt better-sqlite3 binary

Node.js 20 reached end-of-life on 2026-04-30 and is no longer supported. It was dropped because pdfjs-dist requires >=22.13.0, so on Node 20 npm silently skipped that optional dependency and the PDF adapter could not load — a runtime this project claimed to support could not run a feature it shipped.

Install

npm install -g huqan

That gives you two commands: huqan (the CLI) and huqan-mcp (the MCP server
over stdio). Neither needs a config file or an API key to start.

For a one-off run without installing anything:

npx -y huqan quickstart

A smaller install

PDF ingest (pdfjs-dist) and PDF receipt export (pdfkit) are optional
dependencies. They install by default; skipping them takes the install from
about 111 MB to about 20 MB, and everything except the two PDF paths still
works:

npm install -g huqan --omit=optional

Reading a PDF or exporting a receipt as PDF then fails with a message naming
the package to install; JSON receipt export and every other adapter are
unaffected.

Publishing a new version of the package is documented in
docs/npm-publish.md.

Install from source

Use this to contribute, or to run a revision that is not published yet.

git clone https://github.com/ali-ulu/huqan.git
cd huqan
npm ci

gh repo clone ali-ulu/huqan works the same way.

Optional Rust graph accelerator

The repository includes an optional huqan-core Rust JSON-IPC accelerator. It is not required for the normal CLI, server, MCP, or canonical kernel.learn() path; when the binary is unavailable, HUQAN keeps its existing JavaScript behavior.

On Linux, macOS, or another native Cargo target, build the release binary from the repository root:

cd huqan-core
cargo build --release
cd ..

On Windows, the existing MinGW cross-build remains available:

cd huqan-core
.\build.ps1 -Toolchain gnu

A Windows host with the MSVC Rust target can use the new build option instead:

.\build.ps1 -Toolchain msvc

The runtime discovers huqan-core/target/release/huqan-core (or .exe on Windows). To select a binary elsewhere, set HUQAN_RUST_BIN before starting Node; the legacy compatible spelling is accepted when the canonical variable is absent. If both compatible names are set to different values, startup fails closed rather than choosing one silently.

The Rust learn accelerator is batched to amortize JSON-IPC round trips and is used by the isolated reasoning sandbox. The canonical kernel.learn() and learnDocument() methods remain synchronous and admission/durability-governed, so enabling Rust does not bypass provenance, policy, audit, or Trust Receipt semantics. Compare the optional path against the canonical JavaScript path with:

node benchmarks/rust-vs-js-graph.js 2000

When no binary is present, the benchmark reports that fact and keeps the JavaScript result as the reference; it does not claim Rust throughput without a built binary.

Fix an existing clone that still points to an old repository name

git remote set-url origin https://github.com/ali-ulu/huqan.git
git remote -v

The origin fetch and push URLs should both be:

https://github.com/ali-ulu/huqan.git

Your first Trust Receipt

One command, no API key, no config file to edit:

huqan quickstart

From a source checkout, that is npm ci && node cli.js quickstart.

This runs the real pipeline end to end — huqan.learn is proposed, the
mutation gate answers review, an approval is persisted, huqan.approve
performs the canonical write, the claim is verified against the graph, and the
resulting Trust Receipt is printed:

HUQAN quickstart — learn -> review -> approve -> verify -> Trust Receipt
  1. OK   propose: huqan.learn -> review (mutating_requires_review), approval approval-…
  2. OK   approve: huqan.approve -> approved (actor cli-quickstart)
  3. OK   verify: verified (confidence 0.90)
  4. OK   receipt: receiptId … (status canonical)

Quickstart runs in a throwaway store in your temp directory; it does not write
to your own memory, and it does not relax any gate.

For an observability quickstart covering an isolated local server, real run
telemetry, tool usage, alerts, queue state, and dashboard steps, see
Observability Quickstart.

Authenticated observability access is fail-closed behind both the normal API key and an explicit workspace membership policy. Configure the local API-key principal with exact workspaces and roles before using these endpoints:

$env:HUQAN_OBSERVABILITY_AUTHZ_POLICY = '{"memberships":[{"subject":"local-api-key","workspaceId":"demo","role":"admin"}]}'

Authenticated operational probes are available per exact workspace:

GET /api/observability/health?workspaceId=<workspace>  # process liveness; HTTP 200 while the process can answer
GET /api/observability/ready?workspaceId=<workspace>   # DB/schema/required-worker readiness; HTTP 503 when unready

Both responses report only bounded status, queue depth/lag, and the timestamp of the last successful event write. They never include goals, prompts, tool input/output, credentials, or database error messages. A deliberately disabled optional worker is reported as disabled without making synchronous HUQAN usage unready; a worker configured as enabled but not running does fail readiness.

Roles are bounded: viewer can read and stream, operator can also enqueue, and admin can also create or delete alert rules. Wildcard, duplicate, malformed, missing, or cross-workspace membership is rejected. This local-first default has one authenticated API-key principal; multi-user deployments can inject another principal/membership resolver through the same authorization contract without changing observability routes.

Verify the local SQLite dependency and test suite

node -e "const Database=require('better-sqlite3'); const db=new Database(':memory:'); db.close(); console.log('SQLite OK')"
npm test

Start the CLI

npm start

Direct invocation remains available:

node cli.js

Example controlled statements:

Smoking causes lung cancer
Vaccination prevents disease
Authentication enables secure access
Growth depends on investment

HUQAN currently handles explicit supported relation markers. It is not a general-purpose natural-language understanding engine.

How it works

flowchart LR
    A[Agent or user output] --> B[Evidence and provenance]
    B --> C[Verification and contradiction checks]
    C --> D[Scope, policy, and risk gates]
    D -->|approved| E[Trusted state or permitted action]
    D -->|blocked or uncertain| F[Block or escalate]
    E --> G[Trust Receipt]
    F --> G

The main runtime layers are:

CLI / REST / MCP / local UI
            ↓
agent routing and task dispatch
            ↓
safety gates and approval boundaries
            ↓
verification and graph reasoning
            ↓
provenance, receipts, and memory admission
            ↓
SQLite-backed local state and audit records

Ways to run

As a library

const Kernel = require('huqan'); // KernelV2, the canonical runtime
const kernel = new Kernel();

require('huqan') resolves to KernelV2, the same runtime the CLI, REST
server and MCP server build. The older Kernel implementation it wraps is
still reachable as require('huqan').KernelV1, but it is deprecated, is not a
runtime option, and will be removed in the next major release.

The package root also exposes the general Error Prevention core:

const { createErrorPrevention } = require('huqan');
const prevention = createErrorPrevention(kernel.memory, {
  verifyEvidence,
  resolveApproval,
});

This is a package/library surface for verified failure memory, governed rule
lifecycle, and deterministic preflight decisions. It is not one of the fifteen
MCP tools advertised below.

Local CLI

npm start

Local REST server

Mutation endpoints require an API key.

HUQAN_API_KEY=replace-with-a-secret npm run server

HUQAN_API_KEY is the canonical environment-variable name used by the runtime.
See the environment-variable migration guide
before running canonical and legacy names together.

The server starts at http://localhost:3000.

Useful endpoints:

Endpoint	Method	Purpose
/health	GET	Health check
/api?q=...	GET	Allowlisted read-only query surface
/graph-data	GET	Knowledge graph export
/verify	POST	Guarded verification
/v2/verify	POST	Guarded structured verification
/upload	POST	Guarded load alias

Authenticated mutation requests use X-API-Key or Authorization: Bearer <key>.

MCP server for Claude or Cursor

huqan-mcp

Claude Desktop configuration, with nothing installed ahead of time:

{
  "mcpServers": {
    "huqan": {
      "command": "npx",
      "args": ["-y", "--package=huqan", "huqan-mcp"]
    }
  }
}

--package=huqan is required because the bin name differs from the package
name: without it npx would run the huqan CLI instead of the MCP server.

If the package is installed globally, "command": "huqan-mcp" with no args
does the same thing. From a source checkout it is still
"command": "node", "args": ["/absolute/path/to/huqan/mcpServer.js"].

The server advertises fifteen tools to the model:

Tool	What it does	Gate
huqan.learn	Learn a natural-language fact into the local graph	review
huqan.ask	Ask a grounded question against the graph	allow
huqan.verify	Verify a statement and return its evidence trail	allow
huqan.plan	Build a multi-step plan for a goal	allow
huqan.agent	Run the multi-step agent loop	dry-run only
huqan.ingest_preview	Build a read-only ingest source manifest for review	allow
huqan.ingest_execute	Queue a reviewed manual or decision ingest for approval-owned execution	review
huqan.ingest_status	Read the status, progress and final receipt of an ingest run	allow
huqan.policy	Inspect the execution policy for a requested tool	allow
huqan.reason	Return forward and backward reasoning traces	allow
huqan.compare	Compare two concepts across the graph	allow
huqan.dream	Generate ranked hypotheses from the graph	allow
huqan.advocate	Challenge a claim without mutating the graph	allow
huqan.search	Search workspace-scoped memory and return provenance refs	allow
huqan.trust_receipt	Read a workspace-scoped Trust Receipt	allow

Operator tools are not advertised to the model

Three tools are deliberately withheld from tools/list and require the
HUQAN_MCP_OPERATOR_TOKEN environment variable:

Tool	What it does
huqan.approve	Approve or reject a pending approval
huqan.approvals	List pending tool approvals
huqan.agent_resume	Resume a suspended agent run

This is the boundary that makes the review gate mean something: a model that
proposes a mutating action cannot also approve it, because the tool that grants
approval is never in the tool list it can see. Approval is an operator action
taken out of band.

The legacy axiom.* names from before the HUQAN rename are still accepted, so
existing installs keep working; they are no longer advertised, and a call using
one returns a meta.deprecation notice. See
docs/mcp-tool-name-migration.md.

Core capabilities

• Graph-backed claim verification
• Contradiction detection
• Explicit CAUSES, PREVENTS, ENABLES, and DEPENDS_ON relations
• Memory admission and workspace isolation
• Risk classification and safety gates
• Approval flows for guarded actions
• Provenance and audit records
• Canonical Trust Receipts and receipt chains
• Verified failure memory and deterministic Error Prevention preflight
• Portable .huqan package primitives with legacy .axiom.json reader compatibility
• CLI, REST, MCP, and local UI surfaces

Current scope

HUQAN is currently a local-first partial trust layer.

What is real today:

• verification, graph, provenance, approval, audit, and receipt primitives,
• verified-failure Error Prevention core exposed through the package root,
• local CLI, REST, MCP, and UI surfaces,
• bounded memory and action gates,
• production-wired Agent Action Firewall for classic agent, workflow/HTTP, and MCP action paths,
• canonical HUQAN package and cryptographic foundations,
• two conformance suites, run from this repository:
  npm run conformance:external (75 cases) and npm run conformance:a2a
  (50 adversarial cases).

A2A routes ship but stay unconfigured

Four A2A routes are on main and mounted through lib/a2a/routes.js:
POST /api/a2a/exchange, GET /.well-known/agent-card.json,
POST /api/a2a/negotiate and GET /api/a2a/tasks/{taskId}.

They are deployment-gated, not disabled: with HUQAN_A2A_AUTHORITY_FILE and
HUQAN_A2A_REPLAY_DIR unset, every one answers 404 rather than 401, so an
unconfigured install does not advertise a surface it cannot serve.

Three of the four turn on from an npm install. POST /api/a2a/exchange does
not: it reaches the V5 cryptographic family, which package.json#files
deliberately keeps out of the published tarball, so the route stays 404 there
no matter how it is configured. Run it from a clone. This is a packaging
decision, not a defect — lib/a2a/exchange-route.js requires those modules
behind a guard precisely so the installed server still boots.

To turn them on, and for the boundary of what turning them on does not claim,
see docs/a2a-deployment.md.

What this repository does not currently claim:

• universal truth or hallucination elimination,
• complete inline enforcement for every connector and mutation path,
• a finished V5 shared-trust ecosystem,
• external interoperability: no third party has spoken to the A2A transport,
  and the conformance suites are self-test plus one cross-implementation
  comparison, not third-party verification,
• a public agent marketplace or certification network,
• Wikipedia-scale graph performance,
• a complete autonomous Self-Healer.

Shipped but not wired

Part of this repository is implemented and unit-tested but is not reached by
the production entry-point graph declared in
lib/module-reachability.js: cli.js,
server.js, mcpServer.js, index.js, kernel.js, and
github-app-server.js (plus dynamically loaded plugin entry points). Green
tests for those unreached modules mean the code behaves as specified in
isolation — they are not evidence that the product runs it.

That set is enumerated with a reason per module in
lib/module-reachability.js and enforced by a
test, so nothing can join it silently. It is now ten modules:

Group	Modules	Why
V5	lib/v5/runtime-reader.js, lib/v5/structural-signing-helper.js, four schemas/v5/agent-identity-*.js	entry is authorized, these five have no production caller yet
Self-Healer	lib/self-healer/index.js, audit-runner.js, finding-classifier.js	library-only by product decision; no autonomous runner
Connector	lib/github-connector.js	library-only connector

The external-client trust boundary and the reviewed external ingest chain have
both left this list: they are reached by server.js and gated by deployment
configuration rather than by reachability. Four A2A modules left it the only way
a module may — POST /api/a2a/exchange gave them a production caller.

The Error Prevention core is not in that unwired set: index.js reaches and
exports it as a package/library surface. No Error Prevention MCP tool is
currently advertised.

For the live execution order and exact limitations, read docs/current-operating-roadmap.md.

Repository map

Path	Purpose
kernel.js, graph.js	Verification and graph reasoning core
lib/	Gates, provenance, memory, receipts, viewers, and supporting modules
cli.js	Local command-line interface
server.js	Local REST server and UI delivery
mcpServer.js	MCP integration
public/	Backend-connected local UI
test/ and *.test.js	Automated test coverage
docs/	Architecture, audits, product boundaries, and roadmap

Development

npm test
npm run bench
npm run bench:verify

Focused test commands are available in package.json.

Documentation and support

• Current operating roadmap
• Product surfaces
• Competitive positioning
• NLP boundary
• Scale truth pack
• Governance
• Agent Action Firewall
• HTTP upload approval contract
• Security policy
• Contributing
• Issues
• Discussions

License

GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE and NOTICE.

---

HUQAN: trust and evidence infrastructure for AI-mediated work.