Developer docs.

Install

One command. Detects your installed editors, registers the MCP server, and sets up session hooks. Runs entirely on your machine — no signup, no cloud account, no telemetry.

# macOS · Linux
curl -fsSL https://kernora.ai/install | bash

First run

kernora install is a one-time, machine-level setup: it creates the local venv, registers MCP tools with any detected editor, and installs session hooks. Run it once, then run kernora generate any time you want to (re)emit AI-context files for the current repo from your factbook.

kernora install
→ Detected: Claude Code, Cursor, Kiro.
→ MCP registered for Claude Code CLI (~/.claude.json) and Claude Desktop.
→ Hooks installed to ~/.claude/hooks, ~/.cursor/hooks, ~/.kiro/hooks.

cd ~/code/payments-api
kernora generate
→ Emitted AI context files
✓ new   CLAUDE.md
✓ new   .cursorrules
✓ new   .kiro/steering/nora-project.md
✓ new   .github/copilot-instructions.md

Editor integrations

The factbook itself is identical everywhere — one YAML file. What differs is how each editor gets it: some are wired automatically by kernora install, some need one manual step.

Editor	Integration	Status
Claude Code (CLI)	MCP + hooks auto-registered by kernora install (~/.claude.json)	Live
Claude Desktop	MCP auto-registered by kernora install	Live
Cursor	Hooks auto-installed; add the MCP server manually in Settings → MCP Servers, or side-load the VS Code extension	Live
VS Code	Extension marketplace ↗	Live
Kiro	Hooks auto-installed; side-load the same VS Code extension for the dashboard/chat UI	Live

Planned, no shipping code yet: JetBrains, Zed.

Entry shape

The factbook is a git-tracked YAML file — .nora/<project>-factbook.yaml — sitting next to your code. Each fact is one entry in its content: list.

- id: f234
  statement: Stripe webhook handler must be idempotent via the event id.
  sources:
    - docs/adr/018-webhook-idempotency.md
  confidence: 0.94
  review_status: verified
  project: payments-api
  superseded_by: null

Trust ladder

A fact's review_status is one of three states. Coverage stays full at every state — a candidate fact still grounds the AI, just at a lower trust weight than a verified one.

State	Promotion rule	Grounds the AI?
candidate	Just extracted (session analysis) or added manually — awaiting reinforcement	Yes, at candidate trust weight
verified	Auto: reinforced ≥3× without contradiction, or reassessed by nora_factbook_verify. Human: confirmed via the kernora verify wizard (highest trust weight)	Yes
deprecated	Superseded or retired — superseded_by preserves the chain	No (chain visible via nora_provenance)

Emit formats

Same factbook, multiple surfaces. One command writes four of them at once; a fifth is a separate call for Claude's native Memory feature.

# writes CLAUDE.md, .cursorrules, .kiro/steering/*, .github/copilot-instructions.md
kernora generate
# or, in a Claude Code / Cursor / Kiro chat panel:
nora generate

# separate surface: export to Claude's native Memory feature
nora_claude_memory(write=true)

Run kernora hook-install to regenerate automatically on every commit instead of calling generate by hand.

Inspector — verify after it writes

Grounding gets the right facts into the model. Inspector checks what comes back out: it reads the agent's output against the factlets that apply and returns a verdict — so "looks right" becomes "provably conforms, or here's exactly what broke."

The evaluation engine (conformance_verifier.py) is deterministic wherever a factlet carries a verify block. Dispatch is by verify.kind:

verify.kind	How it decides
assertion	A pure expression evaluated against the artifact — no eval/exec, just a sandboxed AST walk.
examples	given → expect cases; an uncovered boundary returns NEEDS_REVIEW, never a pass.
test_ref	Runs a referenced test through a caller-provided runner; flake or timeout → NEEDS_REVIEW.

Every run resolves to a closed verdict — PASS, FAIL, NEEDS_REVIEW, or NOT_APPLICABLE — and a FAIL carries a machine-readable rejection code plus the factlet it broke.

No synthetic passes. Where no deterministic oracle covers the artifact, Inspector returns NEEDS_REVIEW — it never fabricates a PASS from a model guess. Honesty over a green checkmark.

One engine, three cadences — a policy parameter, not three codebases: conformance (per change), compliance (evidence export), sweep (scan a whole repo).

Run it today: the live demo at trace.kernora.ai/inspector runs the engine on a real payload in your browser. Locally, kernora verify-artifact <path> --cadence conformance is the CLI gate (exits 1 on a FAIL) and kernora sweep --target <path> scans a whole repo (Pro tier). A pre-built CI Action and cron-scheduled Sweep (no daemon scheduler yet) are on the roadmap.

Orchestrator runs the whole loop — ground → act → verify — with as much or as little human in it as your verification coverage earns. Today that means human-approves / human-reviews gates; fully unattended operation is on the roadmap.

Factlet protocol

The factbook is built on the open Factlet protocol. Five elements — f:fact, f:lineage, f:consent, f:confidence, f:emit — wired together with W3C PROV-O for lineage.

Your factbook is portable: an open spec, plain YAML on disk, vendor-neutral. Switch tools, switch employers, switch models — the factbook moves with you.

MCP tools

A full Kernora install exposes 60 MCP tools (Lite installs expose a smaller set — call nora_help to see what's active for you). The goal-loop runner tools (nora_run_start, nora_sweep, and similar) require Pro; everything below is available on every tier.

Tool	Purpose
nora_search	Search patterns, decisions, bugs, and insights — BM25-ranked
nora_factbook	Create, update, delete, or check provenance on a named factbook
nora_factbook_add	Add a candidate fact to a factbook's DB-backed store
nora_factbook_verify	Re-assess a fact's factuality and confidence with an AI reasoning pass
nora_factbook_promote	Panel-review pending facts and promote passers into a factbook
nora_factbook_reverse	Retire one decision and write its replacement in one call — resolves, creates, and supersedes atomically, fails closed on any match ambiguity
nora_factbook_inject	Regenerate CLAUDE.md / .cursorrules / .kiro steering files from the factbook right now
nora_factbook_view	Show a factbook's title, layer, and active facts
nora_roi	Return-on-Intelligence report, scored by the current session's LLM
nora_pe_review	Structured 6-lens Principal-Engineer review brief for the IDE's LLM to execute
nora_generate	Emit CLAUDE.md, .cursorrules, .kiro steering, and copilot-instructions from the latest factbook
nora_claude_memory	Export Nora intelligence formatted for Claude's native Memory feature
nora_help	List every Nora MCP tool, skill, and subagent available in this install

nora_provenance

Returns lineage for one fact — statement, sources, supersession history, and how many times it's been cited downstream (decision_traces) — rendered as markdown, ready to relay in chat.

nora_provenance(fact_id="f234")

# Provenance — f234
**Statement:** Stripe webhook handler must be idempotent via the event id.
confidence: 0.94  ·  scope: project:payments-api

## Sources
- docs/adr/018-webhook-idempotency.md

## Decision-trace events (downstream consumption)
**Total events:** 3

Team sync (Pro)

Pro adds encrypted S3 sync via the hosted relay at mcp.kernora.ai. Bring your own bucket; Kernora never holds the key. Per-fact egress consent is the default — you approve which facts cross the wire.

Security

BYOK end to end. On-device factbook. Per-fact egress consent. Audit log of every escalation. Built on the open Factlet protocol so you can verify the wire format yourself.

The install script is plain bash — read it before you pipe it. The MCP server source is on GitHub. Run tcpdump on kernora.ai after install; on Free you'll see zero packets.

Telemetry

None on Free. On Nora Pro and Nora Team, telemetry is opt-in per category — crash reports, usage counts, model-routing stats — and listed in the dashboard with a one-click revoke. Nothing is sent without your consent; nothing identifies you by default.

Uninstall

One command:

bash ~/.kernora/uninstall.sh

This unloads the LaunchAgents, stops the background daemon, and removes the hook file. It does not delete ~/.kernora/ — your config and local DB stay put. To remove everything: rm -rf ~/.kernora.

Your .nora/ folder stays in your git repo either way — that's your data, you keep it. Re-running curl -fsSL https://kernora.ai/install | bash later picks up where you left off.