Semantic Layer

One shared notebook, one dictionary, one name list — so your AI stops guessing and your projects stop living on islands.

A typed claim store + measurement contracts + automatic session injection, in one stdlib-only Python file. Built and battle-tested inside the 19Keys empire; take the code, build your own.

The problem, in plain terms

Imagine your projects are classrooms in one school. Every classroom keeps its own private notebook and makes up its own words. Ask the school "how much money did we make?" and every room answers differently — because every room counts differently, and nobody reads anybody else's notebook. Worse: every morning, every room starts from zero trying to remember what it figured out yesterday.

That's what working across many projects with an AI feels like. The AI guesses what your words mean and which numbers are true — and guessing is where wrong answers come from.

Here's a trick question that shows the disease: how much money did you make? One project counts money people promised. Another counts money that arrived. Both say "revenue." Both are sure they're right. That's how a team lies to itself without anyone lying.

The fix, in four moves

1. One notebook. A single shared fact store. Every fact says who it's about, what it claims, where it was proven, and when. A fact without a receipt literally cannot be saved.
2. One dictionary. Every important word gets one official meaning: "revenue" means money actually received, counted this exact way, from this exact place. And the definition prints under every fact you look up — the rule travels with the number, so nobody can count their own way. The way to count is written on the measuring cup.
3. One name list. "Ask Keys", "askkeys", and "ask.19keys.com" are the same kid — facts never scatter across nicknames.
4. Everybody reads it and writes in it. Every work session starts by reading the notebook (start smart, not blind). Everything proven gets written back (never figure the same thing out twice).

Data-science teams that put this kind of governed layer between an AI and their data report large accuracy jumps on data questions — not because the model got smarter, but because guessing got removed.

What's in the box

Quickstart

# 1) put `cg` on your PATH
mkdir -p ~/.local/bin
printf '#!/bin/sh\nexec python3 %s/scripts/cg.py "$@"\n' "$(pwd)" > ~/.local/bin/cg
chmod +x ~/.local/bin/cg

# 2) freeze your dictionary (edit meanings first!)
sh scripts/seed_contracts.sh

# 3) register what you own
cg entity add "My App" --type project --desc "what it is, one line, no numbers"
cg entity alias "My App" "my-app"

# 4) store your first fact — the receipt is mandatory
cg add "My App" has_status live --source "curl 200 OK https://myapp.com, 2026-07-28"

# 5) never guess again
cg check "My App" has_status     # -> CONFIRMED, with the receipt
cg dict generates_revenue        # -> the frozen definition of revenue
cg context "My App"              # -> everything known, with contracts

The three rules that make it work

1. Check before you quote. cg check or don't say the number.
2. Record what you prove. cg add --source the moment a fact is verified — the source is a file, command, or URL, not a vibe.
3. The dictionary governs. Measure the way the contract says, or change the contract deliberately. Never bend a measurement silently.

The one-liner

Our AI helpers used to wake up with amnesia, count money differently in every room, and sometimes just make things up. Now the whole school shares one book of receipts with one dictionary and one name list — it opens itself when you walk in, no fact enters without proof, and if it's not in the book, nobody's allowed to say it.

License

MIT. Take it, rename it, make it yours.