Open Kioku

Open Kioku is a local repository evidence and change-safety layer for coding agents.

It builds a local evidence model of a repository, compiles the smallest useful context for a task, produces bounded change plans before edits begin, and verifies the resulting change against what the agent intended to modify.

CODE + SYMBOLS + RELATIONSHIPS + TESTS + HISTORY + RUNTIME + DOCS + ARCHITECTURE + LOCAL SEMANTICS │ ▼ EVIDENCE MODEL │ ▼ CONTEXT COMPILER │ ▼ PLAN → EDIT → VERIFY → PROVE

No hosted code index. No source upload. Read-only MCP tools by default. Optional semantic retrieval runs locally.

npm install -g open-kioku ok setup agent cursor --repo . --apply

The setup command indexes the repository, installs repository-scoped guidance and MCP configuration, and checks that the local MCP server responds. Run it without--applyfirst to inspect the exact changes.

Then ask the agent for the change you need. Open Kioku gives it a pre-edit evidence routine instead of making it rediscover the repository from scratch for every task.

Open Kioku combines multiple evidence streams instead of treating repository understanding as a single search problem:

Exact evidence remains authoritative over heuristic evidence. Ambiguity is represented as ambiguity rather than silently promoted to a fact.

A coding task is routed through independent candidate streams and compiled into a boundedContextPack:

TASK │ ├─ lexical / BM25 ├─ exact symbol + reference evidence ├─ graph + impact evidence ├─ tests + coverage ├─ history ├─ runtime ├─ docs ├─ architecture + contracts └─ optional local semantic retrieval │ ▼ authority-aware fusion diversity / redundancy control token-budget optimization │ ▼ CONTEXTPACK + omissions + provenance + quality

Task-family routing, evidence provenance, blocker handling, token budgets, and retrieval quality are benchmarked through the real routed path rather than only through isolated search functions.

Explore → plan_change → edit → verify_change

ok plan "change token expiration"

- primary context with source identity and evidence provenance
- impact candidates
- likely validation targets
- edit boundaries
- explicit missing-evidence caveats
- confidence and quality signals

After the edit, verification checks the actual change against the plan rather than treating a successful command exit as proof that the right files changed.

The homepage includes proof artifacts produced from a pinnedmainbuild at commitacbc5bcb387551501b3bc350247d25c133116d75.

A synthetic offline repository produced:

- 51,349 semantic vectors
- 25,673 symbols
- 25,676 chunks
- persistent local HNSW selected automatically above the crossover
- 21.70sfresh semantic build
- about554 MBpeak RSS during that build
- 0 stale / 0 failedvectors
- successful fresh-process reopen of the persisted ANN index

The same pinned build was exercised through a real sandbox workflow. Open Kioku rancargo testthrough its policy-gated validation runner, recorded the validation attestation, observed2 tests passed / 0 failed, and found0 boundary violations. The final verdict still remainedwarnbecause stronger supporting evidence was absent.

That behavior is intentional: passing tests do not manufacture certainty that the available evidence does not support.

Seedemo/proof/verification-dogfood.json.

A separate public-repository audit indexed 4,600+ files, 46,000+ symbols, and 8,900+ tests locally in 33.1s. Methodology, revisions, caveats, and language limitations are recorded indocs/large-repo-proof.md.

ok --repo . semantic status ok --repo . semantic index ok --repo . search "authorization expiry" --hybrid

Seedocs/semantic-search.md,docs/vector-index.md, anddocs/embedding-providers.md.

ok prove . --task "the feature you're working on" ok prove . --task "the feature you're working on" --html

For pull requests, the opt-inopen-kioku-actioncan attach a privacy-safe preflight artifact:

permissions: contents: read steps: - uses: actions/checkout@v4 - uses: shivyadavus/open-kioku-action@v1 with: task: "change token expiration" verify: true

git clone https://github.com/shivyadavus/open-kioku.git cd open-kioku cargo install --path crates/open-kioku-cli

ok init /absolute/path/to/repo ok index /absolute/path/to/repo ok doctor /absolute/path/to/repo ok status /absolute/path/to/repo --markdown --write ok-status.md

ok setup agent claude --repo /absolute/path/to/repo --apply ok setup agent cursor --repo /absolute/path/to/repo --apply

ok mcp install cursor --repo /absolute/path/to/repo ok mcp install claude --repo /absolute/path/to/repo ok mcp install codex --repo /absolute/path/to/repo ok mcp install gemini --repo /absolute/path/to/repo ok mcp install windsurf --repo /absolute/path/to/repo ok mcp install trae --repo /absolute/path/to/repo ok mcp install opencode --repo /absolute/path/to/repo ok mcp install zed --repo /absolute/path/to/repo

Agent setup guides:Claude·Cursor·Codex·Gemini CLI.

[workspace] projects = [ { name = "service-a", repo = "../service-a" }, { name = "service-b", repo = "../service-b" }, ]

ok index --mode cross-project --workspace /absolute/path/to/workspace ok architecture fleet --workspace /absolute/path/to/workspace

Known-good indexes can be exported/imported for local team and CI reuse:

ok --repo . snapshot export --quality best ok --repo . snapshot doctor ok --repo . snapshot import ok --repo . index --from-snapshot auto

Personal memory and compressed-context state are excluded from the shared index snapshot by default.

History, Runtime, and Validation Evidence

Git history is local and enabled by default with a bounded window. It contributes typed commit metadata, file touches and renames, co-change, churn, provenance, ownership, reviewer, and similar-change signals.

Runtime evidence is opt-in: local JSONL traces/logs/incidents/errors can be placed under.ok/runtime/or.ok/analysis/runtime/and re-indexed.

…