# Know

The data behind the agents' knowledge base and agent settings.

- Registry name: `know` (`@candor/know`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/know

## Install

```bash
npx candor-ui add know
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/know`.
It brings in: chat, status.

## Types

### KnowDoor

How knowledge came in: read from the environment's configuration or data, shared as a file or link, answered by a person, or a vendor's release notes.

```ts
"config" | "data" | "file" | "link" | "answer" | "release-notes"
```

### KnowSource

```ts
{ id: string door: KnowDoor label: string /** Who added it, for files, links and answers. */ addedBy?: string | undefined addedAt?: string | undefined /** When it was last read; null if never. */ readAt: string | null /** How often it should be re-read, in hours, when it has a schedule. */ everyHours?: number | undefined status: RunStatus /** "214 objects", "38 pages" — only when counted. */ exten
```

### Confidence

```ts
"high" | "medium" | "low" | "unknown"
```

### RaciRole

```ts
"R" | "A" | "C" | "I"
```

### RaciAssignment

```ts
{ role: RaciRole; who: string }
```

### RetrievedPassage

```ts
{ id: string sourceId: string title: string excerpt: string /** Retrieval score 0–1; null when the retriever didn't score it (e.g. a pinned source). */ score: number | null /** Whether the answer actually cites it. */ cited: boolean /** Why it ranked where it did, when the retriever says. */ why?: string | undefined readAt: string | null }
```

### Claim

A sentence in an answer and the passages it rests on.

```ts
{ id: string; text: string; evidence: string[] }
```

### ModelVendor

```ts
"Anthropic" | "Google" | "OpenAI" | "xAI"
```

### ModelOption

```ts
{ id: string vendor: ModelVendor name: string /** One line on what it's good for. */ note?: string | undefined /** Relative cost, 1 (cheapest) to 4. */ cost: 1 | 2 | 3 | 4 /** The vendor's zero-retention contract has been attested by an operator. */ zdr: "attested" | "not-attested" }
```

### ReasoningEffort

```ts
"low" | "medium" | "high" | "max"
```

### ModelSettingsValue

```ts
{ model: string reasoning: ReasoningEffort /** Most tool-calling steps per run before it stops and asks. */ stepLimit: number /** Used when the primary is unavailable; must also be attested. */ fallback?: string | undefined }
```

### ToolPermission

```ts
"always" | "ask" | "never"
```

### ToolSetting

```ts
{ id: string name: string description: string /** What the tool can do to the environment. */ effect: "read" | "write" | "deploy" | "outside" permission: ToolPermission /** Permissions this tool can't take, with why. */ locked?: Partial<Record<ToolPermission, string | undefined>> | undefined }
```

### AgentConfig

```ts
{ agent: AgentIdentity enabled: boolean status: RunStatus model: string /** Runs per day for the last 14 days, oldest first. */ runs: { ok: number; failed: number }[] lastFailure?: string | undefined }
```

### Memory

```ts
{ id: string text: string /** Who taught it: a person said so, or an agent inferred it. */ from: { person: string } | { agent: AgentIdentity } createdAt: string scope: "account" | "environment" environmentId?: string | undefined }
```

### MemoryModeValue

Whether agents use memory: on, paused (kept and not used for now), or off.

```ts
"on" | "paused" | "off"
```

### Version

```ts
{ id: string label: string state: "live" | "draft" | "past" at: string by: string note?: string | undefined }
```

### ContextSegment

```ts
{ label: string tokens: number kind: "system" | "instructions" | "knowledge" | "thread" | "tools" | "files" }
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.