# ochakai

> ochakai is a context layer for data agents: one knowledge base holding metric definitions, attested computations (sanctioned SQL, including verified golden queries), interpretation knowledge (how to *read* a metric), glossary terms, and table catalog entries — curated by humans and agents together, and served to Claude Code and every other data agent over MCP, REST, a CLI, and a bundled web UI. One Go binary and Postgres, MIT-licensed, self-hosted per tenant on Cloud Run + Cloud SQL for about $10/month.

Semantic layers tell you that revenue = `SUM(price)`; they don't tell you whether 100 is good or bad. ochakai keeps that missing half.

ochakai is **OKF-native**: the [Open Knowledge Format v0.2](https://github.com/GoogleCloudPlatform/open-knowledge-format) — an open, vendor-neutral bundle format of markdown + YAML frontmatter — is its one format for storage, wire and round-trip (condition C3 below), not an export bolted on, and import accepts any producer's bundle. The unit of knowledge is a **concept** — the format's own word, and the product uses it everywhere a reader meets it (the word `entry` was retired).

ochakai is deliberately the smallest product that satisfies **eight conditions**, written down and numbered in `docs/surface.md`: C1 the user's assets stay theirs (whole export, whole import, purge on request; since v0.27.0 `--prefix` takes one directory, which anyone who may read it can take without an administrator); C2 Google Cloud with no secret of its own (Cloud Run IAM and Cloud SQL IAM); C3 one format, Open Knowledge Format v0.2, for storage, wire and round-trip; C4 no forward-deployed engineers — you deploy it yourself and every operation has a command you can type; C5 usable from Claude Code (MCP over HTTP plus an `ochakai mcp-stdio` bridge); C6 a small REST API you can embed in your own web service; C7 a human improvement loop that is measured rather than assumed; C8 a first-class choice for Japanese speakers. A proposal serving none of the eight is refused.

Two things shape everything else. It **executes no SQL, and no LLM rules on anything**: search and reads return human-verified concepts verbatim — the golden query, the definition, and the caveats around it — and interpretation is the calling agent's job; no model writes, rewrites or summarises the knowledge. Since v0.28.7 a deployment may turn on its own data agent (`OCHAKAI_AGENT`, a Gemini model on Vertex AI in the deployment's own project and region; **off by default**, and unset ochakai is byte-for-byte what it was), for people with no agent of their own: it answers through one REST operation (`POST /api/v1/agent`) and the web UI's エージェント tab, reads as the caller, cites whether a person confirmed each concept, writes nothing and rules on nothing. For a question that needs a number it may *propose* SQL; the person who asked runs it as themselves (the server runs nothing), and the asker's 合っている / 違う verdict becomes a `worked` / `failed` report — a verdict verifies nothing (design record 0142, which replaces 0081). With the agent off, the one thing that leaves the process is the embedding call: with semantic search on, concept bodies and end users' search queries are sent to Vertex AI to be vectorized, inside the deployment's own project, by a deterministic encoder that returns vectors and never text — a base created after v0.29.0 embeds in `global` by default and an older one in the deployment's region, and one variable pins either to a region — `OCHAKAI_EMBEDDINGS=off`, or withholding `roles/aiplatform.user`, means it never calls out and search is lexical-only. And it runs a **write-back loop with a memory**: agents create drafts, a human promotes them to `verified`, provenance (who wrote it, who verified it, when) is on every concept, every change is kept as a revision, and a proposal that is turned down is deleted with its reason, which rides the revision that recorded the removal and is published in the bundle's own `log.md` (v0.28.0, design record 0135: a rejection is a deletion, the reason is readable where the next proposer looks, and the address is writable again — a recorded reason is information rather than authority). Since v0.31.0 a verification of a draft also publishes it: the same call rewrites the document's `status` line to `stable`, as the verifier's own edit, before recording the verification, so the verification stands for the content it confirmed; verifying an already-stable or deprecated concept still leaves the document and its ETag untouched (design record 0157). A ruling is a person's, or a confirmation job's that readers see as `machine-confirmed`, and no LLM rules. Only a verification by a person makes a concept `human-reviewed` (a `process:` caller's verification over REST or the CLI stops at `machine-confirmed`, and MCP carries no ruling at all), and since v0.28.3 a verification stands only for the content it confirmed — an edit or move after it returns the concept to `unverified` (design record 0138). An import rules on nothing: since v0.22.0 an imported bundle's `verified:` frontmatter is held apart as a claim (`received`) until somebody on the instance rules on it.

**How a client reads it: search, then get.** `GET /api/v1/search` ranks what bears on a question and `GET /api/v1/bundle/{id}.md` hands one concept over in full — since v0.30.0 a plain GET answers the OKF document itself and `Accept: application/json` asks for the JSON view, and a directory's address (`/api/v1/bundle/`, or any path ending in `/`) answers its `index.md`, so an OKF reader that fetches `.md` files and follows `index.md` reads ochakai the way it reads a static file server (decision 0153; **BREAKING** for a REST reader that parsed JSON without naming it) (MCP: `search_concepts` then `get_concept`; CLI: `ochakai search` then `ochakai get`). A single-concept read carries `linked_from` — rows naming the concepts whose bodies link *at* the one being read, in address order, capped at 20 — which is how the insight that says *how to read* a metric reaches a caller who only asked for the metric (design record 0106). The rows are pointers, not delivery: nothing is recorded as fetched for being named, and the complete pageable reverse lookup stays on `?links_to=`. There is no one-call context pack: `GET /api/v1/context`, the MCP tool `get_context` and `ochakai context` were retired in v0.24.0 (design record 0108), on the grounds that deciding what is worth reading is the calling agent's job and the pack was taking it away.

Access has no secrets and no authorization by default: Cloud Run IAM decides who can reach a deployment, and whoever can reach it reads and writes everything. ochakai identifies the caller, records it as provenance, and stops there. Since v0.24.1 a deployment that needs a boundary inside one bundle can grant read and write **under a directory prefix** (design record 0109) — off until the first grant is written, and still not per-concept permissions or roles: a body you can read may name an id under a directory you cannot list, and that id stays readable. Since v0.27.0 a rule can also carry `may_admin`, handing one directory's rules to that directory's own administrator (0124; refused at the root, which is what `OCHAKAI_ADMINS` answers), the policy replaces only as it was read with `--if-match` (0120), its first rule is an administrator's to write (0122), and `stats` is no longer pooled on the administrator — a caller with grants reads their own numbers and the answer says which subtree it counted (0123). Since v0.27.2 a scoped caller may also `move` a concept, when the concept, the destination and every live concept linking at it are all inside what that caller may write — refused whole rather than narrowed when one of them is not (0129); the whole-base archive, `reembed` and the policy itself stay with `OCHAKAI_ADMINS`. v0.27.3 fixed the grant that names the whole bundle (`{"prefix": "", "principal": "*"}`, how a policy says *everyone reads everything*): it had reached reads addressed by id but not search, browse or the numbers. Google Cloud is recommended, not required: since v0.21.0 a deployment can instead name its own OIDC issuer and ochakai verifies bearer tokens against the issuer's published keys — no secret on that path either, and since v0.27.0 that path reads `Authorization` alone (0121), so it can sit behind Cloud Run IAM rather than instead of it. Since v0.30.0 a deployment with no `OCHAKAI_GCS_BUCKET` keeps file bytes (an attester's `.py`, a diagram, a PDF) in PostgreSQL, up to 5 MiB each, so a bundle that carries files round-trips through a local, CI or off-Google-Cloud deployment too (decision 0156). Embeddings stay Vertex AI, so search off Google Cloud is lexical-only — measured rather than assumed: the CI golden set runs that configuration too and scores recall@10 1.00 and MRR 0.91 on its 29-concept base, which says Japanese search stands up off Google Cloud, not that embeddings are unnecessary.

This site (ochak.ai) is a condensed version of the product README. The **README is the source of truth**; where this site and the repository disagree, believe the repository. Links below point at raw markdown so you can read the actual text. Note that the README describes `main` — check the changelog for what reached a tagged release. The manual is written in Japanese by decision (condition C8, marked below); the CLI reference and `docs/en.md` — the guided way into the Japanese pages — are English. The public demo at <https://demo.ochak.ai> holds a knowledge base written in Japanese for the same reason; the base is 37 concepts over Google's public `bigquery-public-data.thelook_ecommerce` dataset, so every `# Computation` fence in it really runs, laid out as OKF's own sample bundles are (`datasets/`, `tables/` with `# Schema`, `# Joins` and `# Metrics`, `computations/`). It is built around one question: revenue fell — whether that is beyond the usual swing, which of booked items × completion rate × average item price moved, what to do, and where the data runs out. Asked nine questions twice, Claude Code with BigQuery alone answered 9 of 18 right and with the bundle over MCP 18 of 18, at twice the turns and twice the cost; the questions were chosen by the bundle's authors, with one model and a Claude grader (`examples/demo-eval`, limits in `examples/README.md`). What stays English there is what comes from the warehouse (column names, `status = 'Complete'`, the SQL), so an English identifier still finds the Japanese concept that explains it: `ochakai search traffic_source` lands on the computation that splits orders and revenue by traffic source, with the table concepts that carry the column below it.

Last reviewed 2026-09-28, against ochakai v0.31.1. There is no `llms-full.txt` here on purpose: every row below points at raw markdown in the product repository rather than restating it, because a copy of a manual page is a copy that goes stale silently.

## Start here

- [README](https://raw.githubusercontent.com/na0fu3y/ochakai/main/README.md): The full story — quick start, "Why ochakai", connecting an agent, what it refuses, and the requirements. Read this one first
- [The manual, for English speakers](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/en.md): Not a translation — the one page an English speaker needs in order to use the Japanese manual: what each page holds, in what order to read them, and the names to search for. English
- [FAQ](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/faq.md): Whether it runs outside Google Cloud, whether anything leaves your project, how it differs from RAG and from a memory layer, what an agent may do to knowledge a human verified, and what leaving looks like. Japanese
- [Positioning](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/positioning.md): Every "why not just use X?" answered one at a time — warehouse semantic layers, catalogs, memory layers, RAG, verified-query stores inside an AI-analyst product, and a markdown vault with an MCP server — plus a plain statement of where ochakai loses and who should pick something else. Japanese
- [The surface, and the eight conditions](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/surface.md): What ochakai exists to satisfy (C1–C8), and every endpoint, parameter, header, command, flag, environment variable, vocabulary word and manual page counted against a declared ceiling that CI enforces. Japanese
- [Architecture](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/architecture.md): How the pieces fit, the data model, the recommended type vocabulary, and why there is no authorization layer beyond the directory grants. Japanese
- [Landing page](https://ochak.ai): The short pitch. Japanese is the site's default and lives at the root; the English page is at <https://ochak.ai/en/>.
- [Knowledge authoring guide (The first month)](https://ochak.ai/guides/write/): Step-by-step guide to bootstrapping a knowledge base from empty — scoping datasets, seeding schemas as drafts, authoring Golden Queries and Insights, and testing agent retrieval accuracy. Japanese (on-site adaptation of `docs/guides/onboarding.md`).
- [Deployment & operations guide](https://ochak.ai/guides/deploy/): Deploying and operating ochakai on Google Cloud (Cloud Run + Cloud SQL) with Terraform or gcloud, configuration options, access controls, backups, and upgrades. Japanese.
- [Agent connection guide](https://ochak.ai/guides/connect/): Connecting Claude Code, Claude Desktop, the Claude connector, and other MCP clients to ochakai — bridge authentication, `.mcpb` or the Claude connector, automated recall/write-back hooks, and MCP tools. Japanese.
- [Knowledge lifecycle guide (The loop)](https://ochak.ai/guides/loop/): Maintaining knowledge quality — status and trust lifecycle, review feeds, outcome reporting, usage statistics, and running Golden Queries as CI canaries. Japanese.
- [Source repository](https://github.com/na0fu3y/ochakai): MIT-licensed, on GitHub

## Interfaces

- [Open Knowledge Format v0.2 specification](https://github.com/GoogleCloudPlatform/open-knowledge-format): The vendor-neutral markdown + YAML format ochakai stores, serves and round-trips natively — a bundle stays readable without ochakai, and any producer's bundle imports
- [OpenAPI specification](https://raw.githubusercontent.com/na0fu3y/ochakai/main/api/openapi.yaml): The fifteen `/api/v1` operations — the only REST contract. Four of them are frozen: the bundle round trip (`GET`/`PUT`/`DELETE /api/v1/bundle/{path}`) and `GET /api/v1/search`, the OKF core, which can only ever widen. v0.24.0 narrowed the freeze to that core and calls it a retraction rather than a reinterpretation (design record 0107); the ruling, usage, stats, move, reembed and frontmatter operations returned to the same 0.x-unstable regime MCP and the CLI were always under. The thirteenth is `POST /api/v1/frontmatter` (v0.27.2, design record 0130): it reads an OKF document's frontmatter as JSON and writes named keys back into the document, stores nothing, and is deliberately absent from MCP and the CLI, being a tool for drawing a form. The fourteenth and fifteenth (v0.28.7, design record 0142) are the optional data agent: `POST /api/v1/agent` takes a whole conversation (the server keeps none) and returns the reply, the ids it read and a `turn` id, and `POST /api/v1/agent/turns/{id}` takes the asker's verdict once; both answer only where `OCHAKAI_AGENT` is set, and MCP and the CLI do not carry them. MCP, the CLI and the web UI are all clients of it
- [Embedding the REST API](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/guides/rest-integration.md): For an application putting ochakai inside its own web service — minting the identity token, carrying an end user's identity with the delegation headers and the IAM grant that permits it, declaring who wrote with `Ochakai-Producer`, concurrent writes with `ETag`/`If-Match`. Japanese
- [Connecting an MCP client](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/guides/mcp-clients.md): Which of the two forms each client wants — the URL for a local server, `ochakai mcp-stdio` for a client that only launches a command and for any client against Cloud Run — the six tools it will see, and which of Claude's two ways in to choose: the `ochakai_<version>.mcpb` bundle (Claude Desktop, the bridge with its JSON pre-written, the deployment stays private) or the Claude connector (claude.ai, mobile, Cowork and Desktop through a Google Workspace sign-in, on a deployment that verifies tokens itself and is publicly reachable). Other hosted assistants cannot reach an IAM-restricted deployment. Japanese
- [CLI reference](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/cli.md): Every command's synopsis, flags and worked examples, rendered from `ochakai <command> -h` itself. The CLI is the recommended interface for Claude Code and anything else with a shell — its schemas never occupy the agent's context. English
- [Claude Code example](https://github.com/na0fu3y/ochakai/tree/main/examples/claude-code): Bundled hooks and settings that make recall, write-back and outcome reporting automatic, with no LLM involved. Since v0.24.0 the recall hook injects the ranked pointers from `ochakai search --json` rather than a packed context, and the agent fetches what it decides it wants
- [Example hook configuration](https://raw.githubusercontent.com/na0fu3y/ochakai/main/examples/claude-code/README.md): What each bundled hook does and how to install it
- [Example golden query](https://raw.githubusercontent.com/na0fu3y/ochakai/main/examples/golden-query.md): The shape of one concept — markdown body plus YAML frontmatter

## The loop

- [The first month with an empty base](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/guides/onboarding.md): The road from a base with nothing in it to one an agent's search actually finds things in — scope it to two datasets, write down the ten to twenty questions the team asks before seeding anything, project the schema as drafts, then fill it in by type in an order where each kind can cite the one above it (tables, glossary, policies, metrics, golden queries, insights, procedures last). Its third step is the one most onboarding guidance omits: fire those same questions back at `ochakai search` and check that what came out is what you wrote — a search no concept's words matched is already ranked for you in `ochakai stats`'s gap lines, most-asked first — and before writing, it tells a missing concept from one that exists under the warehouse's word and only needs the team's word in its `synonyms`. Japanese
- [The improvement loop](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/loop.md): The whole cycle in four prompts — recall, write back, rule on it, close the loop — plus the four queues a curator can empty (unreviewed drafts, concepts reported `failed`, concepts past their declared expiry, and since v0.28.3 concepts edited or moved after their last verification) and what is measured: usage counts, instance-wide `ochakai stats`, and the searches no concept's words matched — since v0.28.7 counted on embedding deployments too, where the vectors always return something. Japanese
- [Golden query canary guide](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/guides/golden-query-canary.md): Running verified queries from CI so they stay trustworthy without waiting for an agent to trip over them. Japanese

## Deploy and operate

- [Terraform module](https://raw.githubusercontent.com/na0fu3y/ochakai/main/deploy/terraform/README.md): The supported way to stand up Cloud Run + Cloud SQL. Japanese
- [Cloud Run deployment guide](https://raw.githubusercontent.com/na0fu3y/ochakai/main/deploy/cloudrun/README.md): The gcloud walkthrough the Terraform module mirrors, and the reference of record where the two disagree (~$10/month). Japanese
- [Requirements and configuration](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/configuration.md): Every environment variable, and the five deployment postures one `OCHAKAI_MODE` spells (unset / `read-only` / `public` / `dev` / `sandbox`). Japanese
- [Operating](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/guides/operating.md): Private IP, the team web UI, the hardening checklist, and upgrade order. Japanese
- [Local docker compose stack](https://raw.githubusercontent.com/na0fu3y/ochakai/main/deploy/compose.yaml): What the quick start runs; local development needs only Docker, demo import included
- [Troubleshooting](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/guides/troubleshooting.md): Symptoms and causes on the local and client side — an empty search, a skipped import, a 409 or 412, an empty web UI, a server that refuses to start. Japanese

## Project

- [Changelog](https://raw.githubusercontent.com/na0fu3y/ochakai/main/CHANGELOG.md): What changed between releases — the place to check whether a README feature is in your version
- [Compatibility and support](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/compatibility.md): What is frozen, what is still unstable at 0.x, and which versions are supported
- [Roadmap](https://raw.githubusercontent.com/na0fu3y/ochakai/main/ROADMAP.md): What is being worked on, and what is deliberately refused
- [Contributing](https://raw.githubusercontent.com/na0fu3y/ochakai/main/CONTRIBUTING.md): Local setup and the exact checks CI runs
- [Security policy](https://raw.githubusercontent.com/na0fu3y/ochakai/main/SECURITY.md): How to report a vulnerability
- [Support](https://raw.githubusercontent.com/na0fu3y/ochakai/main/SUPPORT.md): Where to ask a question
- [License](https://raw.githubusercontent.com/na0fu3y/ochakai/main/LICENSE): MIT

## Optional

How a design choice is written down changed in v0.30.0: the current state of each area is a spec page rewritten in place (`docs/spec`), the reasons for choices likely to be reopened are short decisions that are never rewritten (`docs/decisions`, numbered from 0153), and the numbered design records 0001–0152 are frozen history. The English summary of the design records is retired; English readers go through `docs/en.md`.

- [Current specification](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/spec/README.md): How each of seventeen areas works today and why, one page per area. Japanese
- [Architecture and the data agent](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/spec/architecture.md): What ochakai is and holds, and the optional agent that reads as the caller, writes only new drafts and rules on nothing. Japanese
- [Identity, authentication and authorization](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/spec/identity.md): Cloud Run IAM and the OIDC-issuer path with no secret, provenance, and the directory grants that are the one boundary inside a bundle. Japanese
- [Search and embeddings](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/spec/search.md): Japanese-first lexical search (two-character windows as lexemes), hybrid ranking, tie-breaking, and which embedding model and location a base uses. Japanese
- [The loop and what measures it](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/spec/loop.md): Drafts, rulings, the four queues, outcome reports, and the searches no concept's words matched. Japanese
- [OKF compatibility and the round trip](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/spec/okf.md): What is stored, how a bundle is received and served, and what provenance travels with it. Japanese
- [The type vocabulary](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/spec/vocabulary.md): The nine recommended types, and why the set is never closed. Japanese
- [REST stability](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/spec/rest-stability.md): What is frozen — the OKF core, the bundle round trip and search — and what still moves at 0.x. Japanese
- [Decision log](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/decisions/README.md): Short, never-rewritten records of choices likely to be reopened — serving the bundle as OKF (0153), a directory saying what it is for (0154), exporting only the verifications that stand (0155), files in PostgreSQL without a bucket (0156). Japanese
- [Design record index (frozen)](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/design/README.md): The numbered records 0001–0152, kept as history and no longer rewritten; cited above where a claim was decided. Japanese
- [Docs index](https://raw.githubusercontent.com/na0fu3y/ochakai/main/docs/README.md): What else is under `docs/`. Japanese