Hats

An agentic programming language.

A step from Artificial Intelligence to Autonomous Intelligence: a model that predicts, then an agent that walks a skill you own, against memory you own, under limits you set.

You write a skill as a -graphnosis.md file: a short Graphnosis header, then the contract and numbered steps. This repository ships the language, a codec, and a compiler.

A skill is a small program: a header that says when to run and what “done” means, then numbered steps the agent must follow. You do not need to be a programmer to write one. The full grammar is in SPEC.md. That file is not GRAPHNOSIS.md (the standing-instructions file in a project).

This repo is github.com/nehloo/hats.

Language version: 0.1

Agentic programming language

Write a skill. Compile it. Walk it.

1. Write a skill as ship-app-graphnosis.md — YAML header, then contract and steps.
2. Compile it to an unsigned .gsk (hats compile ship-app-graphnosis.md → ship-app-graphnosis.gsk). Import that file in the Graphnosis app. The agent walks the steps there. Memory tools come from the @nehloo/graphnosis SDK.
3. Convert peels a .gsk back to -graphnosis.md, or adds a header if you started from a header-free note.

convert never writes a .gsk. compile never writes Markdown. Several skills in one pack need --out name.gsk — that name is the suggested import engram.

# from this repo until npm publish
node bin/hats.mjs compile examples/ship-app.md
node bin/hats.mjs convert examples/ship-app.md
node bin/hats.mjs compile examples/ship-app.md examples/rollback-deploy.md --out /tmp/graphnosis-crew.gsk

hats compile ship-app-graphnosis.md   →  ship-app-graphnosis.gsk
hats convert ship-app-graphnosis.gsk  →  ship-app-graphnosis.md
hats convert ship-app.md              →  ship-app-graphnosis.md   (adds the header)
hats compile a-graphnosis.md b-graphnosis.md
                                      →  error — a pack needs a name
hats compile a-graphnosis.md b-graphnosis.md --out graphnosis-crew.gsk
                                      →  graphnosis-crew.gsk

The npm package is @nehloo/hats. It is not published until we ship it on purpose. Compiles are unsigned community packs (unverified in the app). Official verified ✓ packs are signed separately. Every -graphnosis.md program carries useWith: Graphnosis and a one-line description. The compiled .gsk does too. Hats is the language; Graphnosis is the walker.

Anatomy of a skill

Every Hats program has two parts, in this order:

| Part | In plain language | In the file | |---|---|---| | Contract | The cover page: when this skill applies, what it needs, what success looks like | Title + the eight fields | | Walk | The program: numbered steps the agent executes | 1. 2. 3. … |

Names that start with $ are variables — labeled boxes the agent fills as it goes.

The compiler requires at least Trigger, Success, and one numbered step. Fields, types, and step tokens are in the spec.

Example

skill ship-app

[dispatch-safe: partial]
Trigger: "ship", "release"
Prerequisites: cortex unlocked; branch exists
Requires: $branch:string
Produces: $receipt:attested
Success: smoke green; rollback exists. [verify: tool]
Out of scope: tag or publish
On failure: @skill: rollback-deploy
On completion: $receipt is in the caller's bindings

1. Call recall("last ship $branch") -> $prior
   only_engrams=["coding"]
   cite $prior
   @needs: extraction
2. @skill: validate-env(branch=$branch) -> $env
3. @parallel: [migrate(branch=$branch), smoke(branch=$branch)] -> [$mig, $smoke]
4. @loop: 2 max=5 unless $smoke
5. emit $receipt from $prior, $env, $mig, $smoke
   @needs: structured-output

In English: when someone says “ship,” take the branch name, look up the last ship for that branch (and cite that memory), check the environment, migrate and smoke in parallel, retry the check up to five times if smoke is not green, then hand back a receipt built from those results.

A header-free teaching copy lives in examples/ship-app.md (hats convert adds the Graphnosis header). Same for examples/rollback-deploy.md. Published skills in this repo are -graphnosis.md only.

Nelu's Digital Hats Agentic Skills

Nelu trained a kit of skills and is sharing it here: skills/. @nehloo. Import the pack (graphnosis-trained-skills.gsk), a single .gsk, or read the -graphnosis.md programs in that folder. Per-skill triggers and outputs: SKILLS.md.

Runtime

Compile here. Walk in Graphnosis.

| Piece | Role | |---|---| | Hats CLI (hats convert / hats compile) | Convert is the codec. Compile writes an unsigned community .gsk. Does not depend on the SDK. Does not sign official packs. | | Graphnosis app | The runtime. Import a .gsk or paste a skill in the Skills trainer. The agent walks it there. | | @nehloo/graphnosis SDK | Local memory (recall, remember, edit). The compiler does not link this package. | | graphnosis-harness | Connects that memory to a model or agent runtime under owner policy. It does not own the skill language or the cortex. |

Also in this neighborhood: graphnosis-secure-sync, graphnosis-obsidian-plugin, graphnosis-hermes, Claude Graphnosis MCP tools, docs.graphnosis.com.

Have GBrain notes? Those .md files are not a Graphnosis repo. hats convert adds the Hats header so you can compile them and walk them here.

The cortex is The Un-Brain. Walkable, borrowable skills are Borrowed Skills (Borrowable Skills as Lean Un-Ganglia Subgraphs, Zenodo, 2026).

The Graphnosis Skills trainer accepts the same tokens in ordinary skill text. It does not use the word Hats.

Same person (agent), different hat (skill)

An agent does not become a new person for every job. It puts on a hat.

You already know this from people. The same colleague wears a different hat for ship day, for the incident, for the board memo. They do not clone themselves. The walk changes; the person does not.

A hat is a skill you own: the practice you wear when that work starts — when to run, what “done” looks like, the numbered steps, and what to do if a step throws. Take it off and the agent is the same agent. Put on another and the walk changes.

That is the step. Artificial Intelligence is the model in the loop. Autonomous Intelligence is the same person wearing a hat: the procedure lives with the memory, Success is checkable, and what proposes an action does not approve its own limits. Hats is the language for that hat. Graphnosis is the walker.

Graphnosis already treats a skill as a lean un-ganglia subgraph in the same owner-held cortex as ordinary memory — The Un-Brain. The procedure is the graph: contract fields plus typed edges (seq, loop, branch, calls, ctx). There is no second store for “how we work.” Digital Hats is the Graphnosis word for a worn skill (Agempi wear them in the room). Hats is the language you write one in.

The paper’s headline property is borrow, don’t spawn. Ask how to turn the tap on and a spawned sub-agent hands you the whole kitchen — a worker stood up when one practice was wanted. A @skill: call just turns the tap: arguments in, answer out, then the hat comes off. Measured against a cold sub-agent, that borrow is tens of times cheaper on the published harness, because you skip the warm-up of a whole person. Portability is the same idea across owners: someone else can wear the practice against their memory at walk time. Training never bakes your private cortex into the skill.

The two papers: The Un-Brain (the cortex — local, indelible memory) and Borrowed Skills (Borrowable Skills as Lean Un-Ganglia Subgraphs — the hats).

Grounded Engineering

Hats is one way to write a skill. The discipline underneath is Grounded Engineering — five checkable requirements, independent of whether the agent is a loop or a graph. Grounding (cite your sources) is only the first of the five.

| Requirement | What it means | How Hats and this kit meet it | |---|---|---| | Provenance | Every fact traces back to where it came from. | recall + cite. Recall Before Coding. A step that emits a receipt names the memories it used. | | Indelibility | Nothing is silently overwritten. Contradictions stay until the owner adjudicates. | edit, not a second remember. Consistency Audit. The Un-Brain does not fade a memory because you did not look at it. | | Determinism | The same question gets the same answer, twice. | Convert and compile are functions of the file. Walk Success is tagged [verify: tool\|state\|human]. Inferred overlay is labeled, never mixed into attested memory. | | Capped authority | What proposes an action never approves its own limits. | [dispatch-safe:]. Autonomous Decision Authority. Hostile Reviewer is a different hat. Crew Orchestrator does not confirm its own claim. | | Co-location | Memory, skills, and agents live in one owned store, as one structure. An agent is a subgraph of its memory. | One cortex. @skill: borrows a hat; it does not spawn a second person. Skill Dispatch picks from that rack. |

The five are product law for Graphnosis. They are not optional flavor text on a skill. They are how the step from Artificial Intelligence to Autonomous Intelligence stays checkable. Article: A Framework for Grounded Engineering: What Loops and Graphs Still Forget (2026).

License

Apache License 2.0 — spec, compiler, and the shared skill pack. Copyright is named in NOTICE. Same family as @nehloo/graphnosis. See CHANGELOG.md for pack versions. Older published snapshots that shipped under CC BY 4.0 remain usable under that license.