🧬 HCS: AI context files that cite their sources and verify themselves

npm install -g @oufrid/hcs-cli
hcs check project.hcs

The problem

Everyone who works with AI agents writes context files: AGENTS.md, CLAUDE.md, session summaries, project notes. I do it myself for this site and for my Android apps. These files share three blind spots.

1. Nobody knows what the summary lost. A project of tens of thousands of tokens gets summed up in a few hundred lines, and no number says what disappeared.
2. They rot silently. The code changes, the context file does not. The model then believes something false, and nothing flags it.
3. They cannot be traced. When the file asserts something, nothing says where it came from or where to check.

I cover this at length, with the levers that need no tool at all, in the guide Optimising AI context. HCS tackles all three problems at once.

How HCS works

An .hcs file holds short, numbered claims about a project. Each one carries an anchor to its source, with a hash.

#c7 Shipping costs a base fee of 25 plus 4 per kg, and parcels over 30 kg are refused.
  > src/rates.ts::shippingFee #9c1e0f2a3b4d
#c8 Refunds are accepted within 14 days of delivery.
  > docs/policy.md::"Refund policy" #77aa01b2c3d4

Three properties follow.

• Traceable. Every claim cites its source: a function, a class, a document heading or a line range. The model knows where to read instead of guessing, and through MCP it can open that source on demand.
• Verifiable. Every citation carries a hash. hcs check detects stale claims without any model, and runs in continuous integration. It ignores reformatting, follows code that moved (even to another file) and fails when the meaning may have changed.
• Measured. The file ships test questions whose answers appear verbatim in the source. hcs score reports the fidelity of the context for a given model, with a confidence interval, a no-context baseline and how often the context misled the model.

The compiler asks the model for claims, each backed by an exact quote, then discards every claim whose quote is not actually in the source. It is a mechanical guard against invented summaries. Hand-written claims remain possible, and they are often the most valuable: a rule such as "never log a full card number" cannot be inferred from the code.

HCS works with any material (code in any language, documentation, notes, conversations) and any model: OpenAI, Anthropic, Gemini, Groq, OpenRouter, Mistral, or a local model through Ollama.

What the measurements show

I wanted numbers, not an impression. The full protocol and raw results are in the benchmark report. Every context gets the same 2,000-token budget, and the test questions were written separately, by calls that never saw the HCS context.

• On the three new repositories (express, requests, logrus), the protocol and the success criterion were committed before any model call. Gap with the naive summary: +18.9 points, with a 95% confidence interval entirely above zero.
• With a second model from another family (ministral-14b, from Mistral), the gap holds: +18.8 points on the first five repositories, +16.1 points on the three new ones.
• Reading the source matters even more than the shape of the summary. When the model may open the source the claims cite, HCS reaches 58.3% on the first five repositories and 62.8% on the three new ones.

What did not work, or not yet, is in the same report:

• hcs refine, which adds claims to cover failed questions, did not improve fidelity on held-out questions, and made it slightly worse on one repository. It is documented as an experiment.
• Dependency alerts (seal --deps): on the project's own history, 17 of 18 alerts were not needed. Expect mostly false alarms.
• Prompt-injection detection catches 90% of the attacks in the corpus it was tuned on, but only 47% (7 of 15) on a held-out set. It is a filter, not a guarantee.
• Limits of the protocol: one model compiled the files and wrote the questions, a single budget was tested, 24 to 30 questions per repository.

Try it in 5 minutes

You need Node.js 18.17 or later. No runtime dependency.

npm install -g @oufrid/hcs-cli          # installs the hcs command
hcs init                                # creates an empty file for hand-written claims
hcs check project.hcs                   # verifies anchors, no model involved

To compile a context from your project, a free key is enough (Gemini or Groq), or a local model:

export GEMINI_API_KEY=...               # or GROQ_API_KEY, or Ollama locally
hcs models gemini                       # lists the models your key can use
hcs compile --model gemini:<model> --rpm 8 -o project.hcs
hcs render project.hcs --decoder --budget 2000   # paste into any chat

The tutorial goes from install to a checked, scored context in about ten minutes, on a small example project. A Python version of the deterministic core also exists: pip install hcs-format.

Connect it to Claude Code, Cursor or VS Code

hcs serve project.hcs is an MCP (Model Context Protocol) server. The agent first reads a few hundred tokens of verified claims, then opens the exact source behind a claim only when it needs it. It never has to read the whole repository.

With Claude Code, in the project folder:

claude mcp add hcs -- hcs serve project.hcs

Typical configuration for other clients:

{
  "mcpServers": {
    "hcs": { "command": "hcs", "args": ["serve", "project.hcs"] }
  }
}

Only Claude Code has been tested so far, with a recorded session. Setup for Claude Desktop, Cursor and VS Code is in the MCP documentation. To understand MCP itself, see my guide Connecting AI to your tools.

Security and privacy

• What never leaves your machine: check, seal, render, stats, impact, audit and the MCP server call no model and no network.
• What sends text to the provider you choose: compile, score, curve, compare and snapshot. Some free tiers may use your prompts to improve their products. Do not compile private code with them, or use a local model.
• Sandbox: the MCP server cannot read anything outside the project folder, symlinks included.
• Prompt injection: text that looks like an instruction aimed at an AI is tagged suspect and never rendered by default. As noted above, detection relies on patterns and lets through about half of novel attacks.

The full threat model is in SECURITY.md.

What HCS is not

• Not lossless. No summary is. HCS measures the loss instead of hiding it.
• Not magic compression. Claims are plain sentences. What saves tokens is choosing what to keep.
• Not always smaller. On a tiny project, the context can be longer than the source itself. HCS pays off when the material is larger than what you want to put in a prompt.
• Not a judge-free score. Exact answers are graded mechanically, the rest by a judge model. Use a judge from another model family.
• Not proof of truth. A valid file proves each quote existed in the source and that the source has not changed since. It does not prove the paraphrase is faithful, nor that the source itself is right.

Status and roadmap

• The format is stable: SPEC 1.0, published on 22 October 2026. Files written today stay readable across the whole 1.x series.
• The tool is experimental: version 0.3.0, published on npm (@oufrid/hcs-cli) and PyPI (hcs-format). A second implementation in Python passes the same conformance suite as the TypeScript one.
• The roadmap follows four phases: reliability, standardisation, new capabilities, ecosystem. It is public in ROADMAP.md.

I designed HCS and directed its development, which was carried out with an AI coding agent (Claude Code). The story of the project, the choices and the measurements are told in the article Your AI context files go stale silently.

Contributing

Feedback is welcome, especially:

• benchmark results on real projects and real models;
• symbol-location cases for more languages;
• comments on the specification, which evolves through a short RFC process.

Everything happens on GitHub, with a contribution guide. To report a vulnerability, use GitHub's private vulnerability report button, not a public issue.

Frequently asked questions

Does HCS replace AGENTS.md or CLAUDE.md?

No. HCS can sit next to them. hcs audit AGENTS.md checks an existing file for broken references, and can even measure what it actually conveys to a model, with the same verified questions.

Is my code sent anywhere?

Only if you run a command that calls a model (compile, score, compare, snapshot), and only to the provider you choose. Checking, rendering and the MCP server run entirely locally. With Ollama, nothing leaves your machine.

Do I need to pay for a model?

No. The whole pipeline was tested on the free tiers of Gemini and Groq, and with local models. When a quota runs out, compilation keeps its work and resumes on the next run. Small local models on CPU did give weak results, though.

How much should I trust the fidelity score?

It is a measurement on a small sample, always shown with its 95% confidence interval. With a dozen questions, that interval can span 50 points. The score depends on the answering model, the judge and the questions: use a judge from another family and always compare with no context.

Will the format change again?

The format is frozen at version 1.0: anchor syntax, hashes, verification statuses. Readers also accept every earlier version. Changes go through a public RFC. It is the command-line tool, at version 0.3.0, that remains experimental.