The missing half of your semantic layer
Semantic layers tell your agents that revenue = SUM(price) —
they don't tell them whether 100 is good or bad.
ochakai is a context provider for data agents: metric
definitions, verified golden queries, and the interpretation knowledge that
today travels by Slack — curated by humans and agents together, served to
every data agent over MCP, REST, and a CLI.
$ ochakai context "why is revenue down?" # metric/revenue · verified · by human:ayako revenue = SUM(orders.price) — excludes refunds and internal test orders # insight/revenue-reading · verified · used 41× Weekly baseline ¥12–14M. Dips every Golden Week — compare YoY, not WoW. # query/sales/revenue-by-week · verified · canary passing SELECT date_trunc('week', created_at) AS week, SUM(price) …
Definitions and how to read them, in the same search
Five knowledge types with server behavior attached — and any slug you invent
works as a type of your own. One get_context call returns the
relevant entries in full, links expanded. No LLM involved.
metricSemantic definition (Apache Ossie), compiled to SQL deterministically
queryGolden query: a question plus its human-verified SQL, verbatim
insightBaselines, seasonality, caveats — how to read a metric
termGlossary: what words mean in your company
tableCatalog notes: sources, column caveats, known issues
What semantic layers and memory layers still don't do
Interpretation knowledge is first-class
An insight records the baseline, the seasonality, the
threshold — tribal knowledge that never fits a semantic-model YAML. Your
agent gets it in the same search that returns the metric definition.
A write-back loop with a memory
Agents write learnings back as drafts; a human promotes them to
verified, with provenance on every entry. Rejected proposals
are kept with the reason — a memory of no — and outcome reports
flag verified entries that stopped working.
Curated, not auto-extracted
Memory layers remember what happened, unaudited; ochakai curates what's true, through human review. They compose: preferences in your memory layer, verified data knowledge here.
Any client, and an exit
The same verified knowledge serves Claude Code, hosted MCP agents, and CI jobs — not one vendor's chat. The whole base round-trips through OKF bundles: plain markdown + YAML that lives happily in git. MIT-licensed, self-hostable.
It stays small by refusing things
- No LLM
- SQL is compiled deterministically or returned verbatim from verified queries. Interpretation is your agent's job.
- No SQL execution
- It holds no warehouse credentials. It compiles; your agent executes.
- No connectors
- Knowledge is curated by humans and agents, not harvested by pipelines. Trust density over volume.
- No chat UI
- It feeds your agents; it doesn't compete with them. The bundled web UI is a curation surface, not a BI tool.
- No secrets
- Cloud Run IAM decides who reaches it; callers are identified by their Google identity. Nothing to issue or rotate.
One Go binary and Postgres
1Run it locally
git clone https://github.com/na0fu3y/ochakai && cd ochakai docker compose -f deploy/compose.yaml up
2Import a semantic model, search it
curl -X POST --data-binary @examples/semantic-model.yaml \ http://localhost:8080/api/v1/import/ossie curl 'http://localhost:8080/api/v1/knowledge?q=revenue'
3Connect your agent
# Claude Code and anything with a shell: the CLI go install github.com/na0fu3y/ochakai/cmd/ochakai@latest ochakai use http://localhost:8080 # hosted agents (claude.ai, Claude Desktop): MCP claude mcp add --transport http ochakai http://localhost:8080/mcp