# Introduction

Source: https://known.info/docs

Known is a shared workspace of wikis and structured records for your company. Your team reads it in the browser, and AI assistants and coding agents read and write it for you through MCP and the `known` CLI. Every change is versioned and shows who made it.

To set up an organization and connect your first agent, see [Quick start](https://known.info/docs/quick-start).

---

# Quick start

Source: https://known.info/docs/quick-start

This guide takes about five minutes. You'll create an organization, add a page, and connect an AI assistant to it.

## Sign in

Go to [known.info](https://known.info) and click **Start free**. Sign in with your work account.

## Create an organization

1. Open the organization menu and click **New organization**.
2. Enter your company's name, for example `Acme Robotics`.
3. Check the address, for example `acme`. You'll use it in links and CLI commands, and you can't change it later.
4. Click **Create organization**.

Your organization starts with a wiki called `general`. If someone already invited you to an organization, open the organization menu and accept the invitation instead.

## Add a page

You write pages in Known by asking an agent. The browser is for reading them. Open **Chat** and enter:

```
Write a page in general called "How we work": we ship on Tuesdays,
decisions go in general:decisions, and support questions go to Sam.
```

The assistant creates the page. To open it, go to **Wikis** and select `general`. The page's history shows that the Known assistant wrote it for you.

## Connect an assistant

Add Known to the assistant you already use, such as Claude or ChatGPT. Follow the steps for your tool in [Connect an agent](https://known.info/docs/connect-agent), then ask it:

```
Which wikis can you see in Known? Read the page "How we work".
```

## Next steps

- [Create a wiki](https://known.info/docs/wikis) for a subject that needs its own readers.
- [Add a table](https://known.info/docs/records) to track customers, decisions, or anything else.
- [Invite your team](https://known.info/docs/members).

---

# Connect an agent

Source: https://known.info/docs/connect-agent

You can connect AI assistants and coding agents to Known with MCP (Model Context Protocol). Agents sign in through your browser, so you don't need an API key.

## MCP server address

```
https://api.known.info/mcp
```

## Connect

Select your tool above for step-by-step instructions. For any tool, the steps are:

1. Add Known as a remote MCP server, using the address above.
2. Sign in to Known in your browser. Select the organizations the agent can use, confirm your identity, and click **Allow**. No organizations are selected by default.
3. Ask the agent which wikis it can see, then ask it to read a page you know.

Other tools that support remote MCP servers with browser sign-in should work the same way. If one doesn't, [let us know](mailto:hello@known.info).

## Available tools

Connected agents can use Known's wiki tools to:

| Read | Write |
|---|---|
| List wikis and show a wiki's pages | Create a wiki (admins only) |
| Search and read pages | Write, edit, move, and remove pages |
| Read page history and recent changes | Change a page's metadata |
| Read records and notes | Write and delete records |
| Look up who made a change | Add and resolve notes |

Results include the address of each page and record in Known, so agents can link to their sources.

## Permissions

- An agent has your access, in the organizations you selected. If you leave an organization or lose access to a wiki, the agent does too.
- Changes made by an agent show the agent and your name, for example "ChatGPT for Ada".
- Agents can't delete page history.

For more, see [Agents](https://known.info/docs/agents).

## Use your voice

You can talk to a connected agent instead of typing. See [Use Known by voice](https://known.info/docs/voice).

## Change or disconnect an agent

In Known, go to **Settings → Connections**. In the **Agents** section, you can change the organizations an agent can use, disconnect an agent, or disconnect all your agents. Adding an organization asks you to confirm your identity. Disconnecting takes effect on the agent's next request.

Organization admins can see the agents connected to their organization and remove them.

## Troubleshooting

### ChatGPT uses an old list of tools

ChatGPT keeps the tool list a chat started with. After Known's tools change, refresh the app in ChatGPT's settings and start a new chat.

### The agent can't find a wiki

The agent can only use the organizations you selected. To change them, go to **Settings → Connections**.

### The agent shows a generic icon

Some clients use their own icon for custom connectors instead of the server's.

---

# Use Known in Claude

Source: https://known.info/docs/connect-agent/claude

## Before you start

- A Known account in the organization you want Claude to use.
- A Claude plan. Free plans allow one custom connector.

## Add Known

1. In Claude, open **Customize → Connectors**.
2. Select **+ Add**, then **Add custom connector**.
3. Name it `Known` and paste the address:

   ```
   https://api.known.info/mcp
   ```

4. Select **Add**, then **Connect**.
5. Known opens in your browser. Sign in, choose the organizations Claude may use, confirm it's you, and select **Allow**.

On a Team or Enterprise plan, an owner adds Known once for everyone: **Organization settings → Connectors → Add → Custom → Web**, with the same name and address. Each person then connects with their own Known account.

## Check the connection

Start a chat, select **+ → Connectors**, and turn on **Known**. Then ask:

```
Which wikis can you see in Known?
```

Claude lists your organization's wikis, such as `general`. Ask it to read a page you know, and it answers with a link to that page in Known.

## Troubleshooting

- **Claude can't see a wiki you expected.** It can only use the organizations you selected. To change them, go to **Settings → Connections** in Known.
- **Known shows a generic icon.** Claude uses its own icon for custom connectors. The connector works normally.

## Next steps

- [What Claude can do with Known, and its permissions](https://known.info/docs/connect-agent)
- [Write your first page](https://known.info/docs/quick-start)

---

# Use Known in ChatGPT

Source: https://known.info/docs/connect-agent/chatgpt

## Before you start

- A Known account in the organization you want ChatGPT to use.
- A ChatGPT plan that allows custom apps. In a workspace, an admin may need to allow them first.

## Add Known

1. In ChatGPT, open **Settings → Apps → Advanced settings** and turn on **Developer mode**.
2. Back in **Apps**, select **Create**.
3. Name it `Known`, paste the address, and choose **OAuth** for authentication:

   ```
   https://api.known.info/mcp
   ```

4. Select **Create**. Known opens in your browser: sign in, choose the organizations ChatGPT may use, confirm it's you, and select **Allow**.

## Check the connection

Start a **new chat**, turn on **Known** from the **+** menu, and ask:

```
Which wikis can you see in Known?
```

ChatGPT lists your organization's wikis. Ask it to read a page you know, and it answers with a link to that page in Known.

## Troubleshooting

- **ChatGPT reports a validation error on a tool.** A chat keeps the tools it started with. Refresh Known in **Settings → Apps**, then start a new chat.
- **ChatGPT can't see a wiki you expected.** It can only use the organizations you selected. To change them, go to **Settings → Connections** in Known.

## Next steps

- [What ChatGPT can do with Known, and its permissions](https://known.info/docs/connect-agent)
- [Write your first page](https://known.info/docs/quick-start)

---

# Use Known in Claude Code

Source: https://known.info/docs/connect-agent/claude-code

## Before you start

- A Known account in the organization you want Claude Code to use.
- Claude Code installed.

## Add Known

1. In a terminal, run:

   ```
   claude mcp add --transport http --scope user known https://api.known.info/mcp
   ```

   `--scope user` makes Known available in every project. Leave it out to add Known to the current project only.

2. Start Claude Code, run `/mcp`, select **known**, then **Authenticate**.
3. Known opens in your browser. Sign in, choose the organizations Claude Code may use, confirm it's you, and select **Allow**.

## Check the connection

Ask Claude Code:

```
Which wikis can you see in Known?
```

It lists your organization's wikis. Ask it to read a page you know, and it answers with a link to that page in Known.

## Troubleshooting

- **`/mcp` shows Known as failed.** Run `claude mcp get known` to see the error, then authenticate again from `/mcp`.
- **Claude Code can't see a wiki you expected.** It can only use the organizations you selected. To change them, go to **Settings → Connections** in Known.

## Next steps

- [The known CLI](https://known.info/docs/cli), for scripts and agents that work from the terminal.
- [What Claude Code can do with Known, and its permissions](https://known.info/docs/connect-agent)

---

# Use Known in Codex

Source: https://known.info/docs/connect-agent/codex

## Before you start

- A Known account in the organization you want Codex to use.
- Codex installed.

## Add Known

1. In a terminal, run:

   ```
   codex mcp add known --url https://api.known.info/mcp
   ```

2. Then sign in:

   ```
   codex mcp login known
   ```

3. Known opens in your browser. Sign in, choose the organizations Codex may use, confirm it's you, and select **Allow**.

## Check the connection

Run `codex mcp list` and check `known` is listed. Then ask Codex:

```
Which wikis can you see in Known?
```

It lists your organization's wikis.

## Troubleshooting

- **Codex can't connect.** Run `codex mcp login known` again.
- **Codex can't see a wiki you expected.** It can only use the organizations you selected. To change them, go to **Settings → Connections** in Known.

## Next steps

- [The known CLI](https://known.info/docs/cli)
- [What Codex can do with Known, and its permissions](https://known.info/docs/connect-agent)

---

# Use Known in Cursor

Source: https://known.info/docs/connect-agent/cursor

## Before you start

- A Known account in the organization you want Cursor to use.

## Add Known

1. Open `~/.cursor/mcp.json` (create it if it doesn't exist) and add Known:

   ```json
   {
     "mcpServers": {
       "known": { "url": "https://api.known.info/mcp" }
     }
   }
   ```

   To add Known to one project only, use `.cursor/mcp.json` in that project instead.

2. Open **Cursor Settings → Tools & Integrations**. Known is listed under MCP; select **Connect**.
3. Known opens in your browser. Sign in, choose the organizations Cursor may use, confirm it's you, and select **Allow**.

## Check the connection

In the agent, ask:

```
Which wikis can you see in Known?
```

It lists your organization's wikis.

## Troubleshooting

- **Known shows an error in Cursor Settings.** Select it to see the message, then **Connect** again.
- **Cursor can't see a wiki you expected.** It can only use the organizations you selected. To change them, go to **Settings → Connections** in Known.

## Next steps

- [The known CLI](https://known.info/docs/cli)
- [What Cursor can do with Known, and its permissions](https://known.info/docs/connect-agent)

---

# Use Known in VS Code

Source: https://known.info/docs/connect-agent/vs-code

## Before you start

- A Known account in the organization you want Copilot to use.
- VS Code with GitHub Copilot.

## Add Known

1. Add Known to `.vscode/mcp.json` in your project (or to your user settings for every project):

   ```json
   {
     "servers": {
       "known": { "type": "http", "url": "https://api.known.info/mcp" }
     }
   }
   ```

2. Select **Start** above the `known` entry in the file.
3. Known opens in your browser. Sign in, choose the organizations Copilot may use, confirm it's you, and select **Allow**.

## Check the connection

In Copilot Chat, switch to **Agent** mode and ask:

```
Which wikis can you see in Known?
```

It lists your organization's wikis.

## Troubleshooting

- **The server doesn't start.** Run **MCP: List Servers** from the Command Palette, select `known`, and **Show Output** to see the error.
- **Copilot can't see a wiki you expected.** It can only use the organizations you selected. To change them, go to **Settings → Connections** in Known.

## Next steps

- [The known CLI](https://known.info/docs/cli)
- [What Copilot can do with Known, and its permissions](https://known.info/docs/connect-agent)

---

# Wikis

Source: https://known.info/docs/wikis

A wiki is a collection of pages about one subject. Each organization has a `general` wiki, and you can create more, such as `finance`, `product`, or one for each customer project.

Each wiki has its own access settings, so you can create a wiki for a subject that only some people should read.

## Wiki properties

| Property | Description |
|---|---|
| Name | The wiki's address, used in paths. Lowercase letters, digits, and hyphens, for example `customer-acme`. |
| Title | The display name, for example `Customer: Acme`. |
| Description | What belongs in the wiki and who reads it. Agents use it to decide where to write. |
| Access | Open to the whole organization, or restricted to specific people and teams. |

To change access, see [Access and sharing](https://known.info/docs/access).

A page's path starts with its wiki's name. For example, `finance:budget.2026` is the page `budget.2026` in the `finance` wiki.

## Create a wiki

Only organization admins can create wikis. Ask your agent to create one, or use the CLI:

```
known acme wiki create finance --title "Finance" \
  --description "Budgets, pricing, and the monthly close. Read by founders and finance."
```

To create a restricted wiki, add `--restricted` and at least one grant, for example `--grant team:founders:author`.

## Update a wiki's title or description

Anyone who can write in a wiki can change its title and description:

```
known acme wiki update finance --description "Budgets, pricing, and the monthly close."
```

Write a description that says what the wiki contains and who it's for. Agents read it when deciding where a page belongs.

## Browse wikis

In the browser, click **Wikis** to see your organization's wikis. Inside a wiki, the sidebar shows its pages. The **Notes** and **Changes** tabs show open feedback and recent changes.

From the CLI:

```
known acme wiki wikis
known acme wiki tree finance:
```

`wiki wikis` lists each wiki with its description, who can read it, and what changed since you last looked. `wiki tree` shows a wiki's pages.

## When to create a new wiki

Create a new wiki when a subject needs different readers from the rest of the organization, or when it's large enough that people go to it directly. Otherwise, add a page to an existing wiki. Pages can contain other pages, so a single page like `general:handbook` can hold an entire handbook.

## FAQ

### Can I rename or delete a wiki?

Not yet. You can move and rename pages within a wiki. See [Pages](https://known.info/docs/pages).

### Can the `general` wiki be restricted?

No. Every member of the organization can always read and write `general`.

### Can organization admins read restricted wikis?

Only if they're granted access. Admins can see that a restricted wiki exists and who has access, and they can change access. If an admin grants themselves access, the wiki's owners can see that they did.

---

# Pages

Source: https://known.info/docs/pages

A page is a Markdown document in a wiki. Pages are organized in a tree, and every save creates a new revision. A page can also hold structured data. See [Records](https://known.info/docs/records).

## Page paths

A page's path is its position in the tree, with segments separated by dots. For example, `handbook.onboarding` is the page `onboarding` under `handbook`. Prefix the wiki name to refer to it from anywhere: `general:handbook.onboarding`.

In the browser, the same page is at `known.info/<org>/general/handbook/onboarding`.

Path segments can contain lowercase letters, digits, hyphens, and underscores, and must start with a letter or digit. Any page can have pages under it. When you write to a path whose parent pages don't exist, Known creates them.

## Create and edit pages

You create and edit pages through an agent or the CLI. The browser shows pages and updates them live, but doesn't have an editor.

To write a page with an agent, ask the Known assistant in **Chat** or a [connected agent](https://known.info/docs/connect-agent):

```
Write general:handbook.onboarding with the first week for a new engineer.
```

To write a page with the [CLI](https://known.info/docs/cli), use `wiki write` for the whole page or `wiki edit` to change one passage:

```
known acme wiki write general:handbook.onboarding --title "Onboarding" --file onboarding.md
known acme wiki edit general:handbook.onboarding --old "two weeks" --new "one week"
```

`wiki edit` fails unless the text you pass to `--old` appears exactly once on the page. Use `--all` to replace every occurrence.

## Avoid overwriting changes

If two people or agents edit the same page at once, one can overwrite the other. To prevent this, read the page with `--json`, note its `revisionId`, and pass it when you write:

```
known acme wiki write general:handbook.onboarding --file onboarding.md --if-revision <revisionId>
```

If the page changed since you read it, the write fails. Read the page again, merge the changes, and retry. Connected agents are instructed to do the same.

## Supported Markdown

Known supports headings, paragraphs, bold and italic text, lists, links, block quotes, code, and tables. A single line break is shown as a line break.

Images, task-list checkboxes, horizontal rules, strikethrough, diagrams, and math aren't supported yet.

## Embed a page

To show one page inside another, put `![[path]]` on a line by itself:

```
## This quarter
![[roadmap.q4]]
```

The embedded page shows its content and, if it holds records, its first rows. Embeds can be nested up to three levels deep.

## Move or rename a page

`wiki move` moves a page and all the pages under it, and keeps their history. You can move pages only within the same wiki.

Moving a page doesn't update links to it. Before you move a page, check what links to it:

```
known acme wiki links general:handbook.onboarding
known acme wiki move general:handbook.onboarding general:handbook.engineering-onboarding
```

## Delete a page

Deleting a page requires owner access to its wiki. On a wiki that's open to the whole organization, that means an organization admin.

```
known acme wiki rm general:drafts.old-plan
```

To delete a page that has pages under it, add `--recursive`. The page's history is kept after it's deleted.

## Page metadata

Each page has a JSON metadata object. Known uses these keys:

| Key | Description |
|---|---|
| `key` | Makes the page a table of records, keyed by this field. |
| `schema` | A JSON Schema that every record on the page must match. |
| `retain` | How long the page keeps records or record versions. |
| `description` | On a wiki's root page, the wiki's description. |

You can add other keys for your own use. To change metadata, use `wiki meta`. It merges the keys you pass with the existing ones, and a `null` value removes a key.

## FAQ

### Can I edit pages in the browser?

Not yet. Use Chat, a connected agent, or the CLI. Pages in the browser update as soon as a change is saved.

### Can I restore a deleted page?

Yes. Read the page as it was before you deleted it, then write it back to the same path:

```
known acme wiki read general:drafts.old-plan --at 2026-10-01T00:00:00Z > old-plan.md
known acme wiki write general:drafts.old-plan --file old-plan.md
```

---

# Links

Source: https://known.info/docs/links

You can link to pages and records with double brackets. Known tracks these links, so you can see what links to a page before you move or change it.

## Link to a page

To link to a page in the same wiki, put its path in double brackets. To set the link text, add `|` and the text:

```
See [[handbook.onboarding]] for the first week.
See [[handbook.onboarding|the onboarding guide]] for the first week.
```

Without link text, the link shows the page's path.

Inside a Markdown table, escape the bar as `\|`.

## Link to a record

To link to a row in a [table](https://known.info/docs/records), add `/` and the row's key to the page path:

```
Renewal owner: [[customers/acme|Acme]].
```

Links also work inside records. A string field that contains `[[customers/acme]]` is tracked the same way as a link on a page.

## Link to another wiki

To link to a page in another wiki in your organization, add the wiki's name and a colon:

```
The budget is in [[finance:budget.2026]].
```

Links between wikis work in the browser, but `wiki links` doesn't list them yet.

## See what links to a page

```
known acme wiki links general:handbook.onboarding
known acme wiki links crm:customers/acme
```

The command lists every page and record that links to the page or record. In the browser, a record's page lists them under **Linked from**.

## Broken links

A link to a page that doesn't exist is shown muted, with a dashed underline. Clicking it shows a "not found" page that links to the nearest existing page above that path.

Moving a page doesn't update links to it. Run `wiki links` before you move a page, then update the pages that link to it.

---

# History

Source: https://known.info/docs/history

Known keeps every version of every page and records who made each change. You can see what a page said at any point in the past and what changed in a wiki over time.

## Changes and revisions

Each write to a wiki creates a change. A change has a number, an author, a message, and a time. A single change can affect several pages, for example when you move a page with the pages under it. Each page the change affects gets a new revision.

Records keep a separate history. For tables, Known keeps every version of each row. See [Records](https://known.info/docs/records).

## Authors

Every change records its author:

| Author | Shown as |
|---|---|
| A person | Their name, and where they made the change: the browser, the CLI, or a site. |
| A connected agent | The agent and the person it acted for, for example "Claude for Ana". |
| The Known assistant | The assistant and the person who asked, for example "Known assistant for Ana". |

Page history can't be deleted, by people or by agents.

## View history in the browser

To see a page's revisions, open the page and click **History**. Select a revision to see what it changed. Changed lines are highlighted, along with any changes to the title, path, or metadata.

To see every change in a wiki, click **Changes**.

## View history with the CLI

```
known acme wiki history general:handbook.onboarding
known acme wiki diff general:handbook.onboarding
known acme wiki changes general:
known acme wiki changes general:handbook
```

| Command | Shows |
|---|---|
| `wiki history` | A page's revisions, newest first. |
| `wiki diff` | What the latest revision changed. Add `--change <id>` or `--revision <id>` for an earlier one. |
| `wiki changes` | Every change in a wiki, or under one page, newest first. |

## Read a page as it was

To read a page or a wiki's tree at a point in the past, pass `--at` with a time or `--change` with a change number:

```
known acme wiki read general:handbook.onboarding --at 2026-09-01T00:00:00Z
known acme wiki tree general: --change 3120
```

To read a table as it was, use `wiki records --at <time>`.

## FAQ

### How far back can I see history?

On the Free plan, you can see the last 90 days. Older history is kept and becomes visible when you upgrade. See [Plans and limits](https://known.info/docs/plans).

### Can history be deleted?

Page history can't be deleted. Records can lose old versions if the page sets a retention limit. See [Schemas and retention](https://known.info/docs/schemas).

---

# Notes

Source: https://known.info/docs/notes

A note is feedback on a page, such as a correction or a missing detail. Open notes appear in the wiki's queue until someone updates the page and resolves them.

Notes don't change the page or its history, and adding one never conflicts with someone editing the page. You need write access to the wiki to add or resolve notes.

## Add a note

To add a note in the browser, open the page and type in **Leave a note on this page**.

You can also ask an agent to leave a note, or use the CLI:

```
known acme wiki note general:handbook.onboarding --text "Laptops now ship from the Berlin office."
```

Notes can be up to 10,000 characters.

## Review open notes

To see every open note in a wiki, click the wiki's **Notes** tab. From the CLI:

```
known acme wiki notes general:
known acme wiki notes general:handbook --deep
```

`--deep` includes the notes on every page under the one you name. `--all` includes resolved notes.

## Resolve a note

After you update the page, resolve the note:

```
known acme wiki resolve general:handbook.onboarding <note-id>
```

Resolved notes are kept, with who resolved them. Anyone with write access can resolve any note in the wiki.

To have an agent work through the queue, ask it to read a wiki's open notes, update each page, and resolve each note.

## FAQ

### What happens to notes when a page moves?

They move with the page. Notes on a deleted page are removed from the queue.

---

# Search

Source: https://known.info/docs/search

Search finds pages and table records that contain the words you enter, and ranks them by relevance.

## Search in the browser

Open a wiki and type in the search field. Results include pages and records from the whole wiki.

## Search with an agent or the CLI

Agents search automatically when you ask them about something. To search with the CLI, name a wiki, or a page to search only the pages under it:

```
known acme wiki search "refund policy" general:
known acme wiki search renewal crm:customers
```

Record results are shown as `<page>/<key>`, for example `crm:customers/acme`.

## What search includes

| Included | Not included |
|---|---|
| Page paths, titles, and content | Log entries |
| The text and number fields of table rows | Earlier revisions of pages and rows |

Results contain every word you search for. Search doesn't support operators such as `OR` or exact phrases.

To find entries in a log, read its records with a time filter. See [Records](https://known.info/docs/records).

---

# Records

Source: https://known.info/docs/records

Records are structured data stored on a page. Use them for anything you track, such as customers, decisions, hires, or incidents, so that people and agents can read them as data.

## Tables and logs

A page holds one of two kinds of records:

| Kind | How it works | Use it for |
|---|---|---|
| Table | Each row has a unique key. Writing a row with an existing key replaces that row. | Things that change, such as customers, open roles, or decisions. |
| Log | Each entry is added with a timestamp. Entries are never replaced. | Things that happen, such as deploys, calls, or daily metrics. |

A page is a table if its metadata sets a `key`. A page with records and no `key` is a log.

## Create a table

Ask your agent, for example: "Make a table at crm:customers, keyed by id, with name, stage, and owner."

To create one with the CLI, write the page and then set its key:

```
known acme wiki write crm:customers --title "Customers" --text "Every customer, keyed by id."
known acme wiki meta crm:customers --text '{"key": "id"}'
```

To make sure every row has the fields you expect, add a [schema](https://known.info/docs/schemas).

## Write records

Use `wiki set` to write a row to a table or add an entry to a log:

```
known acme wiki set crm:customers --text '{"id": "acme", "name": "Acme", "stage": "pilot", "owner": "sam"}'
known acme wiki set ops:deploys --text '{"service": "api", "version": "1.42.0"}'
```

On a table, `wiki set` replaces the whole row. Fields you leave out are removed. To update one field, read the row, change the field, and write the full row back.

To make sure nobody changed the row since you read it, pass the row's version with `--if-version <n>`. The version is in the row's `_v` field. If the row has changed, the write fails.

On a log, `wiki set` adds an entry with the current time. To record something that happened earlier, add `--ts <time>`.

To delete a record, use `wiki del`:

```
known acme wiki del crm:customers/acme
```

## Read records

```
known acme wiki records crm:customers
known acme wiki get crm:customers/acme
known acme wiki records ops:deploys --reverse --limit 20
known acme wiki records ops:deploys --since 2026-10-01T00:00:00Z
```

| Command | Returns |
|---|---|
| `wiki records` | All records. Table rows are sorted by key; log entries by time, oldest first. |
| `wiki get` | One record, by its key or, on a log, its `_id`. |
| `--reverse` | Newest first on a log, highest key first on a table. |
| `--since`, `--until` | Log entries in a time range. |

Results are returned in pages of up to 1,000 records. To get the next page, pass the `--cursor` value from the previous result.

## System fields

Known adds these fields to every record:

| Field | Description |
|---|---|
| `_ts` | When the record was written. |
| `_actor` | Who wrote it. |
| `_v` | On a table, the row's version number. |
| `_id` | The record's ID. |

Your own field names can't start with `_`.

## Records in the browser

A page with records opens on its **Data** view, which shows the records in a grid. You can sort and filter the grid. Your sort and filter settings are saved in your browser.

If a table row has a `content` field with text, the row opens as its own page, with `content` shown as Markdown. Search and links use a row's `title` field as its name, or its `name` field if it has no title.

You can't edit records in the browser. Use an agent or the CLI. The grid updates as soon as a record changes.

## Row history

Tables keep every version of every row, including deletions:

```
known acme wiki history crm:customers/acme
known acme wiki diff crm:customers/acme --version 3
```

To read a whole table as it was at a point in time, use `wiki records --at <time>`. Log entries have no versions, because they can't be changed.

## Limits

- A record is a JSON object of up to 16,384 characters.
- A page can hold any number of records.
- Writing records doesn't create page revisions.

## FAQ

### What can agents do with records?

Agents can read, write, and delete table rows. Only people can delete log entries, remove a page that holds records, change a table's key, or lower a retention limit.

### Can I search log entries?

No. Search includes pages and table rows only. To find log entries, use `wiki records` with `--since` and `--until`.

---

# Schemas and retention

Source: https://known.info/docs/schemas

A page's metadata can define a schema for its records and how long its records are kept.

## Schemas

A schema is a [JSON Schema](https://json-schema.org) that every record on the page must match. If a record doesn't match, the write fails and the error says why:

```
record does not match the page's schema: /stage must be equal to one of the allowed values
```

This metadata defines a customers table with a schema:

```json
{
  "key": "id",
  "schema": {
    "type": "object",
    "required": ["id", "name", "stage"],
    "properties": {
      "id": { "type": "string" },
      "name": { "type": "string" },
      "stage": { "enum": ["lead", "pilot", "customer", "churned"] },
      "owner": { "type": ["string", "null"] }
    },
    "additionalProperties": false
  }
}
```

To apply it, save it to a file and run `wiki meta`:

```
known acme wiki meta crm:customers --file customers.json
```

Known validates schemas with JSON Schema draft-07. Keywords such as `type`, `required`, `enum`, `properties`, `items`, `pattern`, and `additionalProperties` are enforced. `format` isn't.

Agents read a page's schema before they write records to it. To tell agents what a field means, add a `description` to the field.

## Change a schema

A new schema applies only to records written after the change. Existing records aren't validated again or modified.

`wiki meta` replaces each top-level key you pass. To change one field in a schema, pass the whole schema. Every metadata change is saved as a page revision, so the page's history shows each schema it has had.

## Retention

By default, Known keeps every record and every row version. To limit this, set `retain` in the page's metadata:

| Setting | Applies to | Effect |
|---|---|---|
| `retain.days` | Logs | Entries are deleted this many days after their timestamp. Applies to entries written after you set it. |
| `retain.versions` | Tables | Each row keeps at most this many past versions. The current row is never deleted. |

```
known acme wiki meta ops:deploys --text '{"retain": {"days": 90}}'
known acme wiki meta crm:customers --text '{"retain": {"versions": 20}}'
```

Agents can set or raise a retention limit. Only people can lower one.

## FAQ

### Do I need a schema?

No. Without a schema, a page accepts any JSON object. We recommend adding one when more than one person or agent writes to the page.

### Can I change a table's key?

People can, but rows that already exist keep their old key, which makes the table hard to read. Instead, create a new page with the new key and copy the rows to it. Agents can't change a table's key.

---

# Agents

Source: https://known.info/docs/agents

An agent is an AI assistant or tool that you connect to Known, such as Claude, ChatGPT, or Claude Code. A connected agent acts on your behalf: it can read and write what you can, in the organizations you choose. Each change it makes shows the agent's name and yours.

## Connect an agent

Known is an MCP server. Add this address to your agent:

```
https://api.known.info/mcp
```

When the agent connects, Known opens in your browser. Sign in, select the organizations the agent can use, and click **Allow**. No organizations are selected by default, and you're asked to confirm your identity before you allow access.

For step-by-step instructions for each tool, see [Connect an agent](https://known.info/docs/connect-agent).

## What agents can do

In the organizations you allow, an agent can:

- List wikis and read, search, and browse pages.
- Read page history and recent changes.
- Write, edit, and move pages.
- Read and write [records](https://known.info/docs/records).
- Add and resolve [notes](https://known.info/docs/notes).

An agent can only reach wikis that you can reach. Some actions are limited to people, even when an agent acts on a person's behalf:

- Deleting log entries
- Removing a page that holds records
- Changing a table's key
- Lowering a retention limit

## How agent changes appear

Every change an agent makes shows the agent and the person it acted for, for example "Claude for Ana". Changes made through **Chat** in the browser show "Known assistant for" the person who asked. Page history can't be deleted by people or agents.

## Manage connected agents

To see your connected agents, go to **Settings → Connections**. The **Agents** section lists each agent and the organizations it can use. From there you can:

- Change which organizations an agent can use.
- Disconnect an agent, or disconnect all of them.

A disconnected agent loses access immediately. Organization admins can also see the agents that members have connected to the organization, and remove them.

## Connection lifetime

An agent's access renews automatically while you use it. A connection expires after 30 days without use, or 90 days after you connected it. After that, the agent asks you to sign in again.

If you leave an organization, your agents lose access to it.

## Rate limits

| Scope | Limit |
|---|---|
| Each connected agent | 60 calls per minute |
| All of one person's agents | 300 calls per minute |
| All agents in an organization | 3,000 calls per minute |

## FAQ

### Do agents count as members?

No. Agents act on behalf of a member and aren't counted on your plan.

### Can an agent see a restricted wiki?

Only if you have access to it, and only in the organizations you allowed for that agent.

---

# The Known assistant

Source: https://known.info/docs/assistant

The Known assistant answers questions about your organization and writes to its wikis for you. It's built into the browser, under **Chat**, so there's nothing to install.

## Ask a question

Open **Chat** and ask about your company, for example:

```
What did we decide about pricing, and when?
What changed in the product wiki this week?
```

The assistant searches and reads the wikis you have access to, and answers from them. It can't see wikis you don't have access to.

## Write to a wiki

Ask the assistant to record a decision or update a page:

```
Add a decision to general:decisions: we're moving billing to monthly only. Ana and Sam decided today.
Update the onboarding page: laptops now ship from Berlin.
```

The assistant reads a page before it edits it and changes only what you asked. Its changes appear in the page's history as "Known assistant for" your name.

## Conversations

Your conversations are listed in **Chat**. You can return to a conversation, rename it, or delete it. Other members can't see your conversations.

## Use your own agent

To use Known from Claude, ChatGPT, or a coding agent instead, [connect it](https://known.info/docs/connect-agent). A connected agent has the same access as the assistant.

## FAQ

### How many questions can I ask?

It depends on your plan. On Free, Chat has a small daily allowance. See [Plans and limits](https://known.info/docs/plans).

---

# Use Known by voice

Source: https://known.info/docs/voice

You can talk to Known through the assistants and coding tools you've connected. Speak a question, or dictate a decision, and the agent reads or writes your wikis as it would for a typed message.

Most tools offer two ways to use your voice:

| Feature | How it works | Works with Known |
|---|---|---|
| Dictation | Your speech is turned into text in the message box. You review it and send it. | Yes, in every tool. The agent receives a normal text message. |
| Voice conversation | You talk and the assistant talks back, without typing. | Depends on the tool. See below. |

Before you start, [connect Known](https://known.info/docs/connect-agent) to the tool you want to use.

## ChatGPT

Use dictation:

1. In a chat, click the microphone icon in the message box.
2. Speak, then stop the recording. ChatGPT turns your speech into text.
3. Check the text and send it.

ChatGPT uses Known the same way as for a typed message.

At the time of writing, ChatGPT voice conversations don't use apps you've added, such as Known. To use Known by voice, use dictation.

## Claude

Claude's voice mode is a spoken conversation on the web, in Claude Desktop, and in the mobile apps. Voice mode can use connected tools. To start it, click the sound wave icon next to the message box.

In the Claude mobile apps, you can also dictate: tap the microphone icon in the message box, speak, and send the text.

On the web and in Claude Desktop, Claude doesn't have dictation. Use voice mode, or your computer's dictation (see below).

## Claude Code

Claude Code has built-in dictation in the terminal and in its VS Code extension.

1. Run `/voice` to turn on dictation.
2. Hold `Space` while you speak. Release it to finish.
3. Press `Enter` to send.

To tap once to start and again to send, run `/voice tap`. Dictation requires signing in to Claude Code with a Claude.ai account. For details, see [Claude Code voice dictation](https://code.claude.com/docs/en/voice-dictation).

## Codex

In the Codex CLI, run `/voice` to start a spoken conversation in the current thread. You talk, Codex answers out loud, and captions of both sides appear in the terminal. Codex can start work, including work that uses Known, from what you say.

In the Codex app, click the microphone icon in the message box to dictate.

## Cursor

Click the microphone icon in the agent's message box, speak, and stop the recording. Review the text and send it.

## VS Code (GitHub Copilot)

1. Install the [VS Code Speech](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-speech) extension.
2. In Copilot Chat, press and hold `Cmd+I` (macOS) or `Ctrl+I` (Windows and Linux) while you speak. When you release the keys, the prompt is sent.

Speech is processed on your computer. To start voice chat by saying "Hey Code", turn on the `accessibility.voice.keywordActivation` setting.

## Your computer's dictation

Every operating system has dictation that works in any text field, including tools without their own voice feature.

| System | Start dictation |
|---|---|
| macOS | Press the dictation key (🎤), or the shortcut set in **System Settings → Keyboard → Dictation**. |
| Windows | Press `Windows+H`. |
| iOS and Android | Tap the microphone on the keyboard. |

## Tips

- Name the wiki or page when you can, for example "in the general wiki" or "on the decisions page". The agent finds it faster.
- Say what you want done: "Record that we're moving billing to monthly only. Ana and Sam decided today."
- Read dictated text before you send it, especially names and numbers.
- Ask the agent to read back what it wrote: "Read me the page you just changed."

## Examples

```
What did we decide about pricing last month?
Add a note to the onboarding page: laptops now ship from Berlin.
Record a decision in general:decisions: we're hiring a second support engineer in Q1.
What changed in the product wiki this week?
```

---

# The known CLI

Source: https://known.info/docs/cli

The `known` CLI lets you and your coding agents read and write Known from the terminal. The CLI is in early access. To try it, [contact us](mailto:hello@known.info).

## Sign in

```
known login
```

`known login` opens your browser, where you sign in and select an organization. Each sign-in creates a session for one organization. To add another organization, run `known login` again.

Commands take the organization as their first argument:

```
known <org> <command> [arguments]
```

To see your sessions, run `known sessions`.

## Set a project's organization

To skip the organization argument in a project, add a `KNOWN_ORG` file to the project's root directory:

```
echo acme > KNOWN_ORG
known wiki read general:handbook
```

Commands run in that directory or any directory below it use the organization in the file. The file contains no secrets, so you can commit it. To check which organization and account a command will use, run `known ping`.

If you use a coding agent in the project, tell it to run `known ping` before it writes.

## Pages

Every path starts with its wiki's name. For example, `general:handbook.onboarding` is the page `handbook.onboarding` in the `general` wiki.

| Command | Description |
|---|---|
| `wiki wikis` | List wikis, with their descriptions and access. |
| `wiki tree <wiki>:[path]` | Show the page tree. |
| `wiki search <query> <wiki>:[path]` | Search pages and records. |
| `wiki read <wiki>:<path>` | Print a page. |
| `wiki write <wiki>:<path>` | Write a whole page, from `--text`, `--file`, or standard input. |
| `wiki edit <wiki>:<path>` | Replace the text in `--old` with `--new`. |
| `wiki move <wiki>:<from> <wiki>:<to>` | Move or rename a page and the pages under it. |
| `wiki history <wiki>:<path>` | Show a page's revisions. |
| `wiki changes <wiki>:` | Show recent changes in a wiki. |

Add `--json` to any command for machine-readable output.

## Edit safely

To change part of a page, use `wiki edit`. It fails unless the text in `--old` appears exactly once, and it leaves the rest of the page unchanged.

To replace a whole page, read it with `--json`, note its `revisionId`, and pass it with `--if-revision`. If someone changed the page since you read it, the write fails. Read the page again, merge the changes, and retry. To see what changed, run `wiki diff`.

To link pages, use `[[path]]`. Before you move a page, run `wiki links <wiki>:<path>` to see what links to it. See [Links](https://known.info/docs/links).

## Records

| Command | Description |
|---|---|
| `wiki records <wiki>:<path>` | Read records. |
| `wiki get <wiki>:<path>/<key>` | Read one record. |
| `wiki set <wiki>:<path>` | Write a record. Use `--if-version` to update a row safely. |
| `wiki del <wiki>:<path>/<key>` | Delete a record. |
| `wiki meta <wiki>:<path>` | Set a page's key, schema, or retention. |

For details, see [Records](https://known.info/docs/records) and [Schemas and retention](https://known.info/docs/schemas).

## Notes

To list a wiki's open notes, run `wiki notes <wiki>:`. After you update a page, resolve the note with `wiki resolve <wiki>:<path> <id>`. See [Notes](https://known.info/docs/notes).

## Errors

When a command fails because of a conflict, a missing page, or a permission, it prints a short message that says what to do next. When a session expires, the message includes the `known login` command to run.

---

# Organizations

Source: https://known.info/docs/organizations

An organization contains your company's wikis, members, and connected agents. You sign in once and can belong to several organizations.

## Create an organization

1. Open the organization menu and click **New organization**.
2. Enter a name, for example `Acme Robotics`.
3. Enter an address, for example `acme`. The address can contain lowercase letters, digits, and hyphens, up to 40 characters.
4. Click **Create organization**.

The address appears in links (`known.info/acme/…`) and CLI commands (`known acme …`). Only Known can change an address after it's created, so choose it carefully. You can change the name and logo at any time in **Settings**.

You're the organization's first admin. The organization starts with a `general` wiki.

## Switch organizations

The organization menu lists every organization you belong to and any pending invitations. The organization's address is in the URL, so you can work in different organizations in different browser tabs.

## Roles

| Role | Can |
|---|---|
| Admin | Invite and remove members, change roles, create wikis, and manage settings, billing, domains, and single sign-on. Admins are owners of every wiki that's open to the whole organization. |
| Member | Read and write every wiki that's open to the whole organization, and any restricted wiki they're granted. |

To invite people, see [Members and teams](https://known.info/docs/members). To control who can read a wiki, see [Access and sharing](https://known.info/docs/access).

## Leave an organization

Go to **Settings** and click **Leave organization**. Agents you connected to the organization lose access to it.

## Delete an organization

Admins can delete an organization in **Settings → Delete organization**. To confirm, type the organization's address.

Deleting an organization permanently deletes its wikis, records, and history. Its address can't be used again.

---

# Members and teams

Source: https://known.info/docs/members

Members are the people in your organization. Teams are named groups of members that you can grant access to a wiki.

## Invite members

Admins can invite people from **Members**:

1. Enter one or more email addresses, separated by commas.
2. Select a role: **Member** or **Admin**.
3. Send the invitation.

Each person gets an email, and the invitation also appears in their organization menu. Pending invitations are listed in **Members**, where admins can withdraw them.

## Let people join with your email domain

Admins can verify your company's email domain in **Settings → Domains** by adding a DNS record. After the domain is verified, people who sign up with an email address at that domain are offered to join your organization.

You can't verify domains of public email providers, such as gmail.com.

## Set up single sign-on

On the Business plan, admins can require sign-in through Okta, Google Workspace, Microsoft Entra ID, or another SAML provider for a verified domain. See [Plans and limits](https://known.info/docs/plans).

## Change a role or remove a member

In **Members**, admins can change a member's role or remove them. A removed member loses access to the browser, the CLI, and their connected agents within a minute.

You can't change your own role or remove yourself. To leave, see [Organizations](https://known.info/docs/organizations).

## Teams

A team is a named group of members, such as `founders` or `finance`. When you grant a team access to a [restricted wiki](https://known.info/docs/access), everyone on the team gets access, and people you add to the team later get it too.

Teams are in **Members → Teams**.

| Who | Can |
|---|---|
| Admins | Create and delete teams. |
| Admins and team maintainers | Rename a team and add or remove its members. |
| Every member | See every team. |

## FAQ

### Who counts as a member on a paid plan?

People who have signed in at least once. Agents aren't counted.

### Can I belong to several organizations?

Yes, with one account. Each organization only sees its own wikis.

---

# Access and sharing

Source: https://known.info/docs/access

Access is set for each wiki. A wiki is either open to everyone in the organization or restricted to the people and teams you grant. Agents have the same access as the person they act for.

## Open and restricted wikis

| Access | Who can read and write |
|---|---|
| Open (default) | Every member can read and write. Admins are owners. |
| Restricted | Only the people and teams granted access. Other members can't see the wiki or its name. |

The `general` wiki is always open.

## Access levels

| Level | Can |
|---|---|
| Reader | Read pages, records, history, and notes. |
| Author | Everything a reader can, plus write pages and records, and add and resolve notes. |
| Owner | Everything an author can, plus delete pages and change access. |

On an open wiki, a grant can raise a member's level. For example, granting a member owner access lets them delete pages.

## Change access

1. Open the wiki menu and click **Admin** on the wiki's row.
2. Choose **open** or **restricted**, and add people and teams with a level.
3. Save your changes.

Changing access requires owner access to the wiki or an admin role.

With the CLI:

```
known acme wiki grant finance team:founders:author
known acme wiki grant finance user:<user-id>:reader
known acme wiki update finance --restricted
known acme wiki revoke finance user:<user-id>
```

A wiki needs at least one grant before you can restrict it, and a restricted wiki must keep at least one grant.

## What admins can see

Admins can see every wiki and who has access to it, and can change access. They can't read a restricted wiki's pages unless they're granted access. If an admin grants themselves access, the wiki's owners can see that they did.

## Share a wiki with another organization

Owners can share a wiki with another organization, such as a customer or an investor:

1. Open the wiki's **Admin** page.
2. Under **Shared with**, enter the other organization's address.
3. Select **Reader** or **Author**, and click **Share**.

An admin of the other organization accepts the invitation from their organization menu and chooses which of their people get access. Their people can't get a higher level than the one you chose.

The wiki and its history stay in your organization. Changes made by the other organization's people show which organization they came from. You can stop sharing at any time, and the other organization can leave the share.

## FAQ

### Can I restrict a single page?

No. Access is set per wiki. To restrict some pages, move them to their own [wiki](https://known.info/docs/wikis).

### What can a connected agent access?

The same wikis as the person who connected it, in the organizations they allowed. See [Agents](https://known.info/docs/agents).

---

# Plans and limits

Source: https://known.info/docs/plans

Every organization starts on the Free plan. For prices, [contact us](mailto:hello@known.info).

## Plans

| Plan | Includes |
|---|---|
| Free | Wikis, pages, records, notes, sharing, connected agents, the CLI, sites, and GitHub, for up to 25 people. 90 days of history, and a small daily Chat allowance. |
| Advanced | Everything in Free, plus Slack and Telegram, full history, and a daily Chat allowance that grows with your team. |
| Business | Everything in Advanced, plus single sign-on with Okta, Google Workspace, Microsoft Entra ID, or another SAML provider, and twice the Advanced Chat allowance. |
| Enterprise | A custom contract for larger companies. [Contact us](mailto:hello@known.info). |

Admins can see and change the plan in **Settings → Billing**. Plans are billed monthly.

## Who counts as a person

Paid plans count the people who have signed in at least once. Agents aren't counted.

## History on the Free plan

On the Free plan, you can see the last 90 days of history. Older history is kept and becomes visible when you upgrade. The current version of every page is always available.

## Limits

| Limit | Value |
|---|---|
| Record size | 16,384 characters of JSON |
| Records per page | No limit |
| Note size | 10,000 characters |
| Records per read | 1,000 by default, up to 10,000 with the CLI; up to 50 for agents |
| Search results | 20 by default, up to 200 |
| Calls per connected agent | 60 per minute |
| Calls per person, across their agents | 300 per minute |
| Calls per organization | 3,000 per minute |
| Organization address | 40 characters |

---

# Sites

Source: https://known.info/docs/sites

A site is an app or website that lets people in your organization sign in with Known and read your wikis. For example, you can build an investor portal from a `fundraising` wiki, or a customer portal from a project wiki. Each person sees only the wikis they have access to.

## How sites work

1. You register the site in Known and attach the wikis it can read.
2. A person opens the site and signs in with Known.
3. The site reads the attached wikis on that person's behalf.

Known checks every request. If you detach a wiki or remove someone from the site, their next request fails.

Sites can read wikis but can't write to them.

## Register a site

In the browser, go to **Sites** and register a new site. Or use the CLI:

```
known acme sites create "Investor portal" --redirect https://portal.acme.com/callback --site https://portal.acme.com
known acme sites attach <client-id> fundraising
```

Admins and wiki owners can register sites. Attaching a wiki requires owner access to it or an admin role.

`--redirect` sets the address Known returns people to after they sign in. It must be an exact `https` address, or an `http` address on `localhost` during development.

By default, every member can use the site. To limit it to specific people and teams, pass `--user user:<id>` or `--user team:<id>`.

## Sign people in

Sites use OAuth 2.0 with the authorization code flow and PKCE (S256), so you can use any standard OAuth library. Sites don't use a client secret. You can find these values in the site's **Develop** tab:

| Value | |
|---|---|
| Authorization URL | `https://known.info/authorize` |
| Token URL | `https://rpc.known.info/oauth/token` |
| Client ID | Your site's client ID, starting with `app_` |
| Scope | `wiki:<name>:read` for each attached wiki, separated by spaces |

Access tokens expire after one hour. Each refresh token can be used once. To sign a person out, call `POST https://rpc.known.info/oauth/revoke`.

## Read wikis

Send JSON-RPC 2.0 requests to the RPC host with the person's access token. Paths start with the wiki's name:

```
curl -s https://rpc.known.info/rpc \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <access_token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"wiki.read","params":{"path":"fundraising.round"}}'
```

| Method | Returns |
|---|---|
| `site.whoami` | Who is signed in, and their access to each wiki. |
| `wiki.read`, `wiki.tree`, `wiki.search` | Pages. |
| `wiki.records`, `wiki.get` | Records. |
| `site.watch` | A live stream of changes. |

For every method and parameter, see the [RPC reference](https://rpc.known.info/rpc). A `GET` request to `https://rpc.known.info/rpc` with a person's access token returns your site's own reference, including its wikis and that person's access.

## FAQ

### Who can use my site?

Members of your organization who are allowed to use the site. By default, that's every member. They can read only the attached wikis they have access to.

### Which plans include sites?

Every plan. `site.watch` requires live updates on your plan. Without them, poll `wiki.changes`.

---

# Docs for agents

Source: https://known.info/docs/for-agents

Every page in these docs is available as Markdown, so you can give it to an AI assistant or a coding agent.

## Markdown pages

To get a page as Markdown, add `.md` to its address:

```
https://known.info/docs/records.md
https://known.info/docs/index.md
```

Each page also has these buttons:

| Button | Does |
|---|---|
| **Copy page** | Copies the page as Markdown. |
| **Markdown** | Opens the Markdown version. |
| **Open in ChatGPT**, **Open in Claude** | Starts a conversation that reads the page. |

## llms.txt

[known.info/llms.txt](https://known.info/llms.txt) lists every page with its Markdown address and a summary, following the [llms.txt](https://llmstxt.org) format. [known.info/llms-full.txt](https://known.info/llms-full.txt) contains every page in a single file.

## Set up a coding agent

To help a coding agent use Known in a project, add a line to its instructions file, such as `CLAUDE.md` or `AGENTS.md`:

```
This company's decisions and docs are in Known. Read https://known.info/llms.txt to learn how to use it.
```

Then connect the agent to your organization. See [Connect an agent](https://known.info/docs/connect-agent).

---

# Guides

Source: https://known.info/docs/guides

How to give your agents your company's context, organised by the problem you have rather than by feature. Each problem has one page that explains it, every way of solving it (Known's and others'), and the guides that go deeper: how-tos, tutorials for each agent, and comparisons.

The problems:

- **Agents don't know your company:** every session starts from zero.
- **Instruction files sprawl:** CLAUDE.md and AGENTS.md grow per repository, go stale and disagree.
- **Agents contradict each other:** each answers from its own memory.
- **Context walks out the door:** when someone leaves or a client is handed over.
- **The reasons get lost:** what was decided survives; why it was decided does not.
- **One model per client:** agencies and fractional execs need each client's context, kept apart.
- **[Work your agents can see](https://known.info/docs/guides/problems/work-with-context):** issues and customers that live with their context. Compare Known with [Linear, Jira, HubSpot and Attio](https://known.info/docs/guides/decisions).

The first two are being written.

---

# Comparisons

Source: https://known.info/docs/guides/decisions

How Known compares with the tools teams use for issues and customer relationships, with facts from each vendor's own documentation, dated, and where each is the better choice.

- [Known vs Linear](https://known.info/docs/guides/decisions/known-vs-linear)
- [Known vs Jira](https://known.info/docs/guides/decisions/known-vs-jira)
- [Known vs HubSpot](https://known.info/docs/guides/decisions/known-vs-hubspot)
- [Known vs Attio](https://known.info/docs/guides/decisions/known-vs-attio)

---

# Known vs Attio

Source: https://known.info/docs/guides/decisions/known-vs-attio

**Attio is a configurable CRM with its own data model, email and calendar sync, enrichment and AI agents. Known is a shared model of your company, where relationships are records next to your issues, decisions and plans.** Choose Attio for a CRM that syncs your inbox and enriches records. Choose Known when your relationships need to live with the rest of your work, for people and agents alike.

Facts about Attio come from Attio's own docs and pricing page, read on 27 October 2026.

## When to choose Attio

- You want email and calendar sync: Attio syncs Gmail, Google Calendar and Outlook, and creates and links people and companies automatically.
- You want enrichment and call recording (call recording on Pro and Enterprise).
- You want a CRM you can shape: custom objects on every plan, lists with their own attributes, table and kanban views.
- You want AI inside the CRM: Ask Attio reads your records, emails and call transcripts, and asks you to approve every write.
- Your work is relationship-heavy and driven by email: fundraising, partnerships, founder-led sales.

## When to choose Known

- Your relationships connect to work outside the CRM: the issues a customer reported, the plan a partner is part of, the round an investor is in. In Known they're one model an agent follows.
- You want one place for every kind of record, not a CRM plus a tracker plus a wiki.
- You want interactions that say what was agreed, written by people and agents, rather than synced email.
- You use your own agents (ChatGPT, Claude, Claude Code) and want them to work your relationships as you, over MCP.

## Side by side

| | Attio | Known |
|---|---|---|
| Records | People, companies, optional deals; custom objects (3 on Free, 5 Plus, 12 Pro) | Tables you define |
| Views | Table, kanban | Table (sort and filter), record pages, backlinks; no board |
| Email and calendar | Sync for Gmail and Outlook; 1–2 accounts per member by plan | None; interactions are written by people and agents |
| Calls and enrichment | Call recorder (Pro and up), enrichment | None |
| AI | Ask Attio, Custom Agents in workflows, Universal Context; billed in credits | Your own agents over MCP |
| MCP | Server at mcp.attio.com; writes ask for confirmation | MCP server for the whole wiki |
| History | Edit history per attribute | Every record versioned with who changed it |
| Pricing | Free (3 seats); Plus $35, Pro $79 per seat/month annual; credits | See [Plans and limits](https://known.info/docs/plans) |
| Export | Views to CSV or Excel; workspace backup as CSVs (emails not included) | Records as JSON over the CLI and API |

## Using both

Keep inbox sync and enrichment in Attio, and the wider context in Known. Connect both MCP servers to your agent; before a call, it reads the person in Attio and their issues, plans and decisions in Known, and afterwards records what was agreed in Known.

## Moving from Attio

Export your people and companies views as CSV. Give the files to an agent connected to Known and ask it to create one contact or organization per row, searching for existing records first. See [Set up a CRM in Known](https://known.info/docs/guides/how-to/crm).

## Sources

Attio: [pricing](https://attio.com/pricing), [objects and lists](https://docs.attio.com/docs/objects-and-lists), [MCP](https://docs.attio.com/mcp/overview), [Ask Attio](https://attio.com/help/reference/attio-ai/ask-attio/chat-with-ask-attio), [email and calendar syncing](https://attio.com/help/reference/email-calendar/email-and-calendar-syncing.md), [call recording](https://attio.com/help/reference/productivity-collaborating/call-intelligence/recording-calls-with-attio), [exporting](https://attio.com/help/reference/imports-exports/exporting-lists-and-views.md), [backups](https://attio.com/help/reference/imports-exports/back-up-your-workspace-data.md). Read 27 October 2026.

---

# Known vs HubSpot

Source: https://known.info/docs/guides/decisions/known-vs-hubspot

**HubSpot is a CRM platform with marketing, sales and service tools on one database, and AI agents billed through credits. Known is a shared model of your company, where contacts and deals are records next to your issues, decisions and plans.** Choose HubSpot for inbox sync, sequences, marketing and built-in agents. Choose Known when your agents need relationships in the same model as the rest of your work, and a small team wants to define that model itself.

Facts about HubSpot come from HubSpot's own pages and docs, read on 27 October 2026.

## When to choose HubSpot

- You want your inbox and calendar synced: HubSpot logs emails from Gmail, Outlook or IMAP and sends sequences.
- You want marketing, service and sales on one vendor, with a large app ecosystem.
- You want built-in agents for prospecting, support and data, billed per outcome in HubSpot credits.
- You want a free start: HubSpot's free CRM has up to two users and 1,000 contacts.
- You want an MCP server with broad coverage: HubSpot's remote MCP server is generally available and writes contacts, companies, deals, tickets and activities.

## When to choose Known

- Your relationships connect to everything else: the customer is linked from the issue they reported, the partner from the plan, the investor from the round. In Known they're records in one model an agent follows; in HubSpot the CRM is its own world.
- You want to define your own objects without an Enterprise plan. HubSpot's custom objects are Enterprise only; in Known every table is your own schema.
- You want interactions that say what was agreed, written by people and agents, rather than logged emails.
- You want every change versioned with who made it, person or agent.

## Side by side

| | HubSpot | Known |
|---|---|---|
| Records | Contacts, companies, deals, tickets and more; custom objects on Enterprise | Tables you define: contacts, organizations, interactions, pipeline, anything else |
| Pipelines | Up to 15 (Starter), 100 (Professional), 350 (Enterprise) | A table with a stage field; as many as you need |
| Email and calendar | Inbox sync, sequences, Chrome and Outlook add-ins | None; interactions are written by people and agents |
| Calls | Recording and transcripts on Professional and up | None |
| AI | Breeze Assistant in the free CRM; Breeze agents billed in credits | Your own agents (ChatGPT, Claude) over MCP |
| MCP | Remote server, generally available since April 2026 | MCP server for the whole wiki |
| Pricing | Free; paid seats from Starter; Professional $90/seat/month annual plus a $1,500 onboarding fee; credits for agents | See [Plans and limits](https://known.info/docs/plans) |
| Export | Per object as CSV or Excel, and the API | Records as JSON over the CLI and API |

## Using both

Keep email sync and sequences in HubSpot, and the context in Known: connect both MCP servers to your agent, and ask it to read the customer's issues, plans and past decisions in Known before a call, and to record what was agreed in Known afterwards.

## Moving from HubSpot

Export contacts and companies as CSV from HubSpot. Give the files to an agent connected to Known and ask it to create one contact or organization per row, searching for existing records first. See [Set up a CRM in Known](https://known.info/docs/guides/how-to/crm) for the tables.

## Sources

HubSpot: [free CRM](https://www.hubspot.com/products/crm), [Sales Hub pricing](https://www.hubspot.com/pricing/sales), [Sales Hub pricing explained](https://blog.hubspot.com/sales/hubspot-sales-hub-pricing), [credits catalog](https://legal.hubspot.com/hubspot-product-and-services-catalog), [remote MCP server](https://developers.hubspot.com/changelog/remote-hubspot-mcp-server-is-now-generally-available), [custom objects](https://knowledge.hubspot.com/object-settings/create-custom-objects), [connect your inbox](https://knowledge.hubspot.com/connected-email/connect-your-inbox-to-hubspot), [export records](https://knowledge.hubspot.com/import-and-export/export-records). Read 27 October 2026.

---

# Known vs Jira

Source: https://known.info/docs/guides/decisions/known-vs-jira

**Jira is Atlassian's configurable tracker for work items, built for teams that need custom workflows, permissions and planning at scale. Known is a shared model of your company, where issues are one kind of record next to your customers, decisions and conversations.** Choose Jira for deep configuration, portfolio planning and the Atlassian suite. Choose Known when a small team and its agents need issues that carry their context.

Facts about Jira come from Atlassian's own docs and pricing page, read on 27 October 2026.

## When to choose Jira

- You need custom workflows, work types and fields per space, with permission schemes and item-level security.
- You plan across teams: Jira's Plans (Premium) adds capacity planning, scenarios and cross-project dependencies.
- You're regulated or large: approvals, sandboxes, uptime SLAs and audit logs.
- You already use Confluence or Jira Service Management.
- You want agents in the tracker: Jira lets you assign work items to Rovo or MCP agents and keeps their changes in the item's history.

## When to choose Known

- Your agents need the context around a work item: the customer, the decision, the last call. In Known these are records linked to the issue; in Jira they're in other tools.
- You're a small team and want a model you define in minutes, not a tracker to administer.
- You track more than software work in one place: sales, a fundraise, hiring, each a table with a schema you write.
- You want every change versioned with who made it, person or agent, on every plan.

## Side by side

| | Jira | Known |
|---|---|---|
| What an issue is | A work item in a space | A record in a table you define |
| Configuration | Workflows, work types, fields, screens, schemes | A JSON Schema per table, and the table's page for rules |
| Views | Backlog, list, board, timeline, calendar, summary | Table (sort and filter), record pages, backlinks; no board |
| Planning | Sprints on boards; Plans on Premium | None built in |
| GitHub and GitLab | Development panel, Smart Commits, automation | None built in; agents add commit and deploy links |
| Notifications | Notification schemes, email, Slack | None |
| Agents | Rovo MCP server (Standard and up; delete and admin tools off until enabled); agents assignable to work items | MCP server for the whole wiki; agents act as the person who connected them |
| History | Work-item history; user-activity audit log on Enterprise | Every record versioned with who changed it, on every plan |
| Export | CSV and Excel up to 10,000 items per export; full site backup | Records as JSON over the CLI and API |

## Using both

Keep sprints and boards in Jira and the context in Known. Connect both MCP servers to your agent; ask it to read the related customer and decision in Known before it works a Jira item, and to record the outcome in Known when it's done.

## Moving from Jira

Export the work items to CSV from a search (up to 10,000 per export; split larger sets with JQL). Give the CSV to an agent connected to Known and ask it to create one record per row in your issues table, following the table's schema. See [Set up issue tracking in Known](https://known.info/docs/guides/how-to/issue-tracking).

## Sources

Atlassian: [Jira pricing and plans](https://www.atlassian.com/software/jira/pricing), [Rovo MCP server](https://developer.atlassian.com/cloud/rovo-mcp/), [supported tools](https://support.atlassian.com/atlassian-rovo-mcp-server/docs/supported-tools/), [agents in Jira](https://www.atlassian.com/blog/rovo/ai-agents-in-jira), [Smart Commits](https://support.atlassian.com/jira-software-cloud/docs/process-issues-with-smart-commits/), [notification schemes](https://support.atlassian.com/jira-cloud-administration/docs/configure-notification-schemes/), [exporting over 10,000 items](https://support.atlassian.com/jira/kb/export-over-10-000-work-items-in-jira-cloud/). Read 27 October 2026.

---

# Known vs Linear

Source: https://known.info/docs/guides/decisions/known-vs-linear

**Linear is a fast, opinionated issue tracker for software teams. Known is a shared model of your company, where issues are one kind of record next to your customers, decisions and conversations.** Choose Linear for a polished board, cycles and GitHub automation. Choose Known when your agents need to see why an issue exists, not just the ticket. Many teams can use both.

Facts about Linear come from Linear's own docs and pricing page, read on 27 October 2026.

## When to choose Linear

- Your engineering team plans in cycles and lives on a board.
- You want pull requests to move issues automatically: Linear links branches, PRs and commits by issue ID and changes status on review and merge.
- You want notifications in an inbox, on mobile, in Slack and by email.
- You want intake from Slack, email, forms, Zendesk or Intercom (Linear's Business plan).
- You want agents in the tracker itself: in Linear you assign or delegate an issue to an agent like a teammate, and agents aren't billed as seats.

## When to choose Known

- Your agents work issues and need the context around them: the customer who reported it, the decision behind it, the last call with that customer. In Known these are linked records an agent follows; in Linear they're in other tools.
- You track more than engineering work in the same place: a sales pipeline, a fundraise, hiring, all as tables with schemas you write.
- You want to define the fields yourself. Known's tables take any [JSON Schema](https://known.info/docs/schemas); Linear's model is fixed by design (statuses in five fixed categories, metadata through labels, priority and estimates).
- You want every change versioned with who made it, person or agent, on every plan.

## Side by side

| | Linear | Known |
|---|---|---|
| What an issue is | A Linear issue in a team, project and cycle | A record in a table you define |
| Fields | Fixed model; labels, priority, estimates | Your schema; any fields, checked on every write |
| Statuses | Custom per team, in five fixed categories | An enum you define |
| Views | List, board, timeline (projects) | Table (sort and filter), record pages, backlinks; no board |
| Links to other work | Projects, initiatives, related issues | Links to any record: customers, meetings, decisions, plans |
| GitHub | Automatic PR and commit linking and status changes | None built in; agents add commit and deploy links |
| Notifications | Inbox, desktop, mobile, Slack, email | None |
| Agents | Official MCP server; agents as assignable teammates; Linear Agent built in | MCP server for the whole wiki; agents act as the person who connected them |
| History | Per-issue activity; audit log on Enterprise | Every record versioned with who changed it, on every plan |
| Export | CSV (without attachments), Markdown, API | Records as JSON over the CLI and API |

## Using both

Keep the board in Linear and the context in Known. Connect both MCP servers to your agent, and ask it to read the customer and the decision in Known before it picks up the Linear issue. When it ships, it updates the Linear issue and records what happened in Known.

## Moving from Linear

Linear exports issues as CSV, up to 250 at a time for members and 2,000 per view for admins; attachments aren't included. To move them, give the CSV to an agent connected to Known and ask it to create one record per row in your issues table, following the table's schema. See [Set up issue tracking in Known](https://known.info/docs/guides/how-to/issue-tracking) for the table.

## Sources

Linear: [conceptual model](https://linear.app/docs/conceptual-model), [workflows](https://linear.app/docs/configuring-workflows), [pricing](https://linear.app/pricing), [MCP](https://linear.app/docs/mcp), [agents](https://linear.app/docs/agents-in-linear), [GitHub](https://linear.app/docs/github), [notifications](https://linear.app/docs/notifications), [exporting](https://linear.app/docs/exporting-data). Read 27 October 2026.

---

# How-to guides

Source: https://known.info/docs/guides/how-to

Step-by-step guides for setting up and running work in Known, with people and agents.

- [Set up issue tracking in Known](https://known.info/docs/guides/how-to/issue-tracking)
- [How your team and agents work issues in Known](https://known.info/docs/guides/how-to/issues-with-agents)
- [Set up a CRM in Known](https://known.info/docs/guides/how-to/crm)
- [Log a meeting to your CRM from ChatGPT, by voice](https://known.info/docs/guides/how-to/log-meetings-by-voice)

---

# Set up a CRM in Known

Source: https://known.info/docs/guides/how-to/crm

This guide sets up a CRM your team and your agents keep together: people and organizations once, the meetings and messages with them, and where each relationship stands. It's the model we use for Known's own fundraise and partnerships.

You need a Known organization and the [known CLI](https://known.info/docs/cli), or an agent [connected to Known](https://known.info/docs/connect-agent). The examples use the organization `acme`.

## The model

| Table | One record is | Key |
|---|---|---|
| `people:contacts` | A person: who they are and how to reach them | `jo-park` |
| `people:organizations` | A company, fund or firm | `northwind` |
| `sales:interactions` | One event: a call, a meeting, a message | `jo-park:2026-10-14:call:1` |
| `sales:pipeline` | Where one relationship stands now, and the next step | `jo-park` |

Two wikis, on purpose. `people` is the one directory the whole company shares; every other wiki links to it. `sales` holds what your sales team does with those people. A hiring or a fundraising wiki would link to the same contacts.

## 1. Create the directory

```
known acme wiki create people --description "Everyone we know: who they are and how to reach them. One record each; other wikis link here."
known acme wiki write people:contacts --title "Contacts" --text "One record per person."
known acme wiki write people:organizations --title "Organizations" --text "One record per company."
```

Then a [schema](https://known.info/docs/schemas) for each. The contact schema, as `contacts.json`:

```json
{
  "key": "id",
  "schema": {
    "type": "object",
    "required": ["id", "name"],
    "properties": {
      "id": { "type": "string", "description": "Name in lowercase with hyphens, e.g. jo-park." },
      "name": { "type": "string", "description": "Full name, spelled the way the person spells it." },
      "current_role": { "type": ["string", "null"], "description": "Title and organization. null if unknown." },
      "email": { "type": ["string", "null"] },
      "linkedin": { "type": ["string", "null"] },
      "organizations": { "type": "array", "items": { "type": "string", "pattern": "^\\[\\[organizations/[^\\]|]+\\]\\]$" }, "description": "Links to their organizations. Each lists this contact back." },
      "content": { "type": ["string", "null"], "description": "A few plain sentences: who they are and how we know them." }
    },
    "additionalProperties": false
  }
}
```

```
known acme wiki meta people:contacts --file contacts.json
```

Organizations follow the same pattern, with `name`, `website`, `type` and a `contacts` list of links back.

## 2. Create the sales tables

An interaction is one event. Its schema, as `interactions.json`:

```json
{
  "key": "id",
  "schema": {
    "type": "object",
    "required": ["id", "people", "type", "summary"],
    "properties": {
      "id": { "type": "string", "description": "<main-contact>:<YYYY-MM-DD>:<type>:<n>." },
      "people": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^\\[\\[people:contacts/[^\\]|]+\\]\\]$" }, "description": "Everyone confirmed who took part, main contact first." },
      "organizations": { "type": "array", "items": { "type": "string", "pattern": "^\\[\\[people:organizations/[^\\]|]+\\]\\]$" } },
      "occurred_at": { "type": ["string", "null"], "description": "Date of the event. null if unknown; never guessed." },
      "type": { "enum": ["call", "meeting", "message", "introduction", "other"] },
      "summary": { "type": "string", "description": "What was said or agreed, and the next step. No facts about the person." },
      "content": { "type": ["string", "null"], "description": "Notes, or the message quoted word for word." }
    },
    "additionalProperties": false
  }
}
```

The pipeline table holds `person` (a link), `stage`, `last_touch`, `next_action` and `next_action_due`.

## 3. Write the rules on the pages

Agents read a table's page before writing to it. These rules, on the right pages, prevent most bad records:

- **Search before you create.** Look for the person by name, other spellings and email. Update the record that exists.
- **Facts about a person go on their contact.** Role, email, LinkedIn and background never go on an interaction.
- **One event is one interaction.** A LinkedIn profile or a directory entry is not an interaction.
- **Only confirmed people go in `people`.** If you're not sure who attended, name them in `content` and leave them out of the links.
- **Unknown is `null`.** Don't guess a date, a role or a company.
- **After an interaction, update the pipeline:** `last_touch`, `stage`, `next_action`.

## 4. Use it

From a chat with your agent:

> "I had coffee with Jo Park from Northwind today. They're moving their support team to agents next quarter and want a demo in two weeks."

The agent finds Jo's contact, writes one interaction linked to Jo and Northwind, sets the pipeline's next action to the demo, and adds a due date. If Jo has no contact yet, it creates one first.

To see where things stand, open `sales:pipeline` in your browser: a table you can sort and filter. To see everything about Jo, open her contact: its backlinks list every interaction and pipeline record that links to her.

## What Known doesn't do

Known doesn't sync your email or calendar, record calls, or enrich contacts from outside data. Interactions come from people and agents writing them, which is also why they say what was decided, not just that an email was sent. If you need inbox sync and sequences, a dedicated CRM does those; see [Known vs HubSpot](https://known.info/docs/guides/decisions/known-vs-hubspot) and [Known vs Attio](https://known.info/docs/guides/decisions/known-vs-attio).

## Next

[Log a meeting to your CRM from ChatGPT, by voice](https://known.info/docs/guides/how-to/log-meetings-by-voice)

---

# Set up issue tracking in Known

Source: https://known.info/docs/guides/how-to/issue-tracking

This guide sets up an issues table that your team and your agents share: one record per issue, with fields the schema checks and a page that tells everyone how to use it. It takes about 15 minutes. It's the setup we use for Known's own backlog.

You need a Known organization and the [known CLI](https://known.info/docs/cli), or an agent [connected to Known](https://known.info/docs/connect-agent). The examples use the organization `acme` and a wiki called `product`.

## 1. Create the table

An issues table is a page with a key. Write the page, then set its key:

```
known acme wiki write product:issues --title "Issues" --text "Every bug, feature and task, one record each."
known acme wiki meta product:issues --text '{"key": "id"}'
```

Or ask your agent: "Create a table at product:issues, keyed by id."

## 2. Add a schema

A [schema](https://known.info/docs/schemas) makes every issue have the same fields. Agents read it before they write, so the descriptions double as instructions. Save this as `issues.json`:

```json
{
  "key": "id",
  "schema": {
    "type": "object",
    "required": ["id", "title", "type", "status", "priority", "created_at", "content"],
    "properties": {
      "id": { "type": "string", "pattern": "^ISS-\\d{3,}$", "description": "ISS- plus the next free number." },
      "title": { "type": "string", "minLength": 1, "description": "What is wrong or wanted, in one short line." },
      "type": { "enum": ["bug", "feature", "improvement", "task"] },
      "status": { "enum": ["backlog", "planned", "in_progress", "in_review", "done", "cancelled"] },
      "priority": { "enum": ["p0", "p1", "p2", "p3"], "description": "p0 urgent, p1 high, p2 normal, p3 low." },
      "assignee": { "type": ["string", "null"], "pattern": "^\\[\\[people:contacts/[^\\]|]+\\]\\]$", "description": "Who is doing it, as a link to their contact." },
      "customer": { "type": ["string", "null"], "pattern": "^\\[\\[people:organizations/[^\\]|]+\\]\\]$", "description": "The customer who reported it, as a link." },
      "related_to": { "type": "array", "items": { "type": "string", "pattern": "^\\[\\[issues/[^\\]|]+\\]\\]$" }, "description": "Related issues, as links. Keep it two-way." },
      "links": { "type": "array", "items": { "type": "object", "properties": { "kind": { "enum": ["commit", "pull_request", "deploy"] }, "url": { "type": "string" } }, "required": ["kind", "url"] }, "description": "Where the work happened." },
      "created_at": { "type": "string", "description": "When the issue was filed, in UTC." },
      "content": { "type": "string", "minLength": 1, "description": "The problem, evidence and acceptance criteria." }
    },
    "additionalProperties": false
  }
}
```

Apply it:

```
known acme wiki meta product:issues --file issues.json
```

Three choices in this schema matter most:

| Choice | Why |
|---|---|
| `pattern` on `id` | Keys stay `ISS-001`, `ISS-002`, so people and agents can say "ISS-014" and mean one thing. |
| Links, not names, in `assignee`, `customer` and `related_to` | A link opens the record it points to and shows up in that record's backlinks. A name is only text. |
| `additionalProperties: false` | An agent can't invent a field. New fields are added to the schema on purpose. |

## 3. Write the rules on the page

Agents read the page before they write records, so the page is where you say how your team uses the table. Edit the page text:

```
known acme wiki write product:issues --title "Issues" --file issues.md
```

What we put on ours:

- **New issue:** read the last key with `wiki records product:issues --reverse --limit 1`, then `wiki get` the next one to check it's free. `wiki set` replaces a record with the same key.
- **Update:** `wiki get` the issue, change only what changed, and write it back with `--if-version`. If the write is refused, someone changed it first: get it again and redo the change.
- **Content** starts with the problem. Don't repeat the fields in it.
- **Links** go both ways: when ISS-014 is related to ISS-009, add the link to both.

## 4. Add your first issues

```
known acme wiki set product:issues --file iss-001.json
```

Or tell an agent what's wrong. With the schema and page in place, "File a bug: the login page loops after a password reset, reported by Northwind" becomes a record with a key, a type, a priority and a link to the customer.

## 5. Read it

| To see | Use |
|---|---|
| All issues, as a table you can sort and filter | The page in Known, in your browser |
| One issue, with its history | `wiki get product:issues/ISS-001`, and `wiki history product:issues/ISS-001` |
| What links to an issue | The issue's page in the browser, or `wiki links product:issues/ISS-001` |
| Issues by text | `wiki search "login" product:issues` |

## What Known doesn't do

Known shows issues as a table, not a board with columns per status. It doesn't send notifications, and it doesn't link commits automatically: in our backlog, the agent that ships a change adds the commit and deploy links itself. If your team lives in a board and notifications, keep a dedicated tracker for that, and keep the context in Known.

## Next

[How your team and agents work issues in Known](https://known.info/docs/guides/how-to/issues-with-agents)

---

# How your team and agents work issues in Known

Source: https://known.info/docs/guides/how-to/issues-with-agents

Once issues are records in Known, everyone works the same backlog: people in the browser and the CLI, agents over MCP. This guide shows how that works day to day, with examples from Known's own backlog, where two founders and their agents file, update and close issues.

It assumes you've [set up an issues table](https://known.info/docs/guides/how-to/issue-tracking).

## Who does what

| Who | Through | Typically |
|---|---|---|
| People | The browser, or the [known CLI](https://known.info/docs/cli) | Read the backlog, decide priorities, review |
| A coding agent (Claude Code, Codex, Cursor) | MCP, as the person who connected it | Files issues it finds, updates status while it works, adds commit and deploy links when it ships |
| A chat agent (ChatGPT, Claude) | MCP, as the person who connected it | Files issues from a conversation, summarises the backlog, triages |

Every change records who made it. An agent's change shows as that agent, acting for the person who connected it, so the history says "Claude Code for Nikolai", not just "Nikolai".

## File an issue from where you are

A coding agent that hits a bug can file it without leaving the task:

> "This test fails because the cache key ignores the locale. File it as a bug and keep going."

The agent reads the table's page and schema, finds the next free key, and writes the record. Because the schema has a `customer` field with a link pattern, it asks which customer reported it, or leaves it empty. It can't invent a name.

From a chat:

> "Northwind says exports time out over 10,000 rows. File it, priority p1, and link it to Northwind."

## Work an issue with its context

The point of keeping issues in Known is what's around them. When an agent picks up ISS-014, it can follow the links: the customer record and its recent meetings, the decision page that made it urgent, related issues. You don't paste any of it in.

> "Pick up ISS-014. Read the customer and the related issues first, then propose a fix."

## Update without overwriting each other

Two people, or a person and an agent, can update the same issue at once. Every record has a version (`_v`). Writes pass the version they read with `--if-version`, so a stale write is refused instead of overwriting the other change:

```
known acme wiki get product:issues/ISS-014 --json
known acme wiki set product:issues --file iss-014.json --if-version 3
```

Agents do the same through the `wiki_get` and `wiki_set` tools. When a write is refused, they read the issue again and redo the change.

## Close the loop when you ship

Our rule: whoever ships a change adds where it happened. A coding agent finishing ISS-014 sets `status: done` and adds the commit and the deploy:

```json
"links": [
  { "kind": "commit", "url": "https://github.com/acme/app/commit/3f2c1ab" },
  { "kind": "deploy", "url": "https://app.acme.com" }
]
```

Known doesn't watch your repository, so this is a step in the agent's routine, written on the table's page, rather than an integration.

## See what changed

| Question | Where |
|---|---|
| What happened to this issue? | `wiki history product:issues/ISS-014`, or History on the issue's page |
| What did an agent change? | `wiki diff product:issues/ISS-014 --version 4` |
| What changed in the backlog this week? | `wiki changes product:` |

## Keep agents writing good records

Agents write what the table lets them. In our backlog, the faults came from gaps: an agent guessed a value the schema allowed, or put a fact in the wrong field. Each fix was a rule, not a reminder:

- a `pattern` on fields that reference other records, so only real links get through;
- a `description` on every field, which agents read before writing;
- rules on the table's page: find the next free key first, update with `--if-version`, keep links two-way;
- `null` for anything unknown, never a guess.

## Related

- [Work your agents can see](https://known.info/docs/guides/problems/work-with-context)
- [History](https://known.info/docs/history) and [Notes](https://known.info/docs/notes)

---

# Log a meeting to your CRM from ChatGPT, by voice

Source: https://known.info/docs/guides/how-to/log-meetings-by-voice

The best time to record a meeting is on the way out of it. This guide shows how to tell ChatGPT what happened, out loud, and have it written to your CRM in Known as structured records.

You need ChatGPT [connected to Known](https://known.info/docs/connect-agent/chatgpt) and a CRM set up as in [Set up a CRM in Known](https://known.info/docs/guides/how-to/crm).

## 1. Dictate the meeting

In the ChatGPT app, start a new chat and use dictation: tap the microphone in the message box, speak, then send. Dictation turns your speech into a message ChatGPT can act on with Known's tools. (ChatGPT's voice conversation mode doesn't use connected apps; see [Use Known by voice](https://known.info/docs/voice).)

Say it the way you'd tell a colleague:

> "Log a meeting. I had lunch with Maya Chen and Tom from Brightline today. They're building agents for their support team and want one place for customer context. We agreed to run a two-week trial on one team. Follow up on Wednesday."

## 2. What ChatGPT writes

With the rules on your tables' pages, ChatGPT:

1. **Finds the people.** It searches `people:contacts` for Maya Chen and Tom. Maya exists; Tom doesn't, and you didn't say his last name, so it names him in the meeting notes instead of creating a contact.
2. **Writes one interaction:** `type: meeting`, today's date, `people` linking Maya, `organizations` linking Brightline, and a two-sentence summary of what was agreed.
3. **Updates the pipeline:** `last_touch` today, `next_action` "Follow up", due Wednesday.
4. **Tells you what it wrote** and asks about anything it couldn't settle, such as Tom's last name.

It doesn't put Maya's role or LinkedIn on the meeting. Those belong on her contact.

## 3. Check it

Ask "show me what you wrote", or open the interaction in your browser. Every record shows who wrote it: ChatGPT acting for you.

## Tips

- **Say who was there and what was agreed.** Those are the fields that matter later.
- **Say what you don't know.** "His last name might be Reyes, not sure" keeps a guess out of your contacts.
- **Correct it in the same chat.** "Actually it was Thursday" updates the record; its history keeps both versions.

## Related

- [Set up a CRM in Known](https://known.info/docs/guides/how-to/crm)
- [Use Known by voice](https://known.info/docs/voice)

---

# Problems

Source: https://known.info/docs/guides/problems

Each page here explains one problem teams have when they put agents to work: what goes wrong, why, every way of solving it, and where Known fits.

- [Work your agents can see](https://known.info/docs/guides/problems/work-with-context): issues and customers that live with their context.

---

# Work your agents can see

Source: https://known.info/docs/guides/problems/work-with-context

Your issues live in one tool and your customers in another. The reasons behind them live in neither: they're in a call, a thread, a doc. When an agent picks up an issue or prepares a meeting, it sees the ticket or the contact, and nothing around it.

This page explains why that happens, the ways teams solve it, and where Known fits.

## What goes wrong

A bug comes in from a customer. Someone files it in the issue tracker. The customer, what they're paying, and the call where they explained the problem are in the CRM and a meeting note. The decision to fix it this week was made in a chat thread.

An agent asked to fix the bug reads the ticket. It doesn't know who reported it, why it matters now, or what was already tried. An agent asked to prepare the next call with that customer reads the CRM. It doesn't know the bug exists.

People fill the gap by pasting context into each agent, every time.

## Why it happens

Each tool holds one kind of record well. An issue tracker holds issues, a CRM holds contacts and deals, a wiki holds documents. The links between them, such as this issue came from this customer because of this decision, are either missing or stored as text no tool follows.

Most of these tools now have an MCP server, so an agent can read and write issues or contacts directly. That solves access. It doesn't solve context: the agent still reads one tool at a time, and the connections between records aren't there to follow.

## The ways to solve it

| Approach | How it works | Trade-off |
|---|---|---|
| Connect each tool to your agents | Add the MCP servers for your issue tracker, CRM and docs to every agent | Agents can reach everything, but they have to search each tool and join the pieces themselves, every time |
| Write context into each record | Paste the customer, the decision and the call notes into the ticket | Works until it's out of date; it's copied, so it drifts |
| Keep the work in one model | Issues, contacts, meetings and decisions as records in one place, linked to each other | You give up some of a specialised tool's interface; you gain one model every agent reads |

## Where Known fits

In Known, issues, contacts, meetings and decisions are [records](https://known.info/docs/records) in wikis, and records link to each other with [links](https://known.info/docs/links). An issue links the customer who reported it, the decision behind it and the commit that fixed it. A contact links every meeting and introduction. An agent working on any of them can follow the links to the rest.

You define each table's fields with a [schema](https://known.info/docs/schemas), and its page says how to use it. The same agents your team already uses read and write it over [MCP](https://known.info/docs/connect-agent), as the person who connected them, and every change is versioned with who made it.

Known doesn't replace a specialised tool everywhere. If you need boards, cycles, notifications, or email and calendar sync, Linear, Jira and the CRMs do those well, and you can keep them and still keep the context in Known.

## Guides

- [Set up issue tracking in Known](https://known.info/docs/guides/how-to/issue-tracking)
- [How your team and agents work issues in Known](https://known.info/docs/guides/how-to/issues-with-agents)
- [Set up a CRM in Known](https://known.info/docs/guides/how-to/crm)
- [Log a meeting to your CRM from ChatGPT, by voice](https://known.info/docs/guides/how-to/log-meetings-by-voice)
- [How we run our backlog and our fundraise on Known](https://known.info/docs/writing/running-on-known)

---

# Writing

Source: https://known.info/docs/writing

Essays and notes from the Known team, published on known.info. Each piece is a page under this one.

---

# How we run our backlog and our fundraise on Known

Source: https://known.info/docs/writing/running-on-known

Unknown is two founders and a handful of agents. We don't use an issue tracker or a CRM. Our backlog, our fundraise and our partner conversations are records in Known, written by us and by the agents we work with: Claude Code and ChatGPT, over MCP. This note is what that looks like after two months, including what went wrong.

## What's in it

As of 27 October 2026:

| Table | Records |
|---|---|
| Issues | 62 |
| Contacts | 164 |
| Organizations | 136 |
| Interactions (calls, meetings, messages) | 136 |
| Relationship flow (where each conversation stands) | 85 |
| Tasks | 135 |

Both founders and our agents write to all of them.

People and organizations live once, in one wiki. The fundraise, outreach and product each have their own wiki and link to them.

## What a day looks like

- **After a call,** one of us tells ChatGPT what happened, often by voice on the way out. It writes the interaction, links the people and the company, and updates where the conversation stands and what's next.
- **While coding,** Claude Code files the bugs it finds, moves its issue to done when it ships, and adds the commit and the deploy.

Nobody pastes context into an agent. The agent reads the records, and follows the links from an issue to the customer or from a contact to the last meeting.

## What went wrong

Agents write what the tables let them. When we looked closely, we found records that were wrong in ways a person would rarely get wrong:

- **A guessed attendee.** A lunch with three people from one company was recorded under a fourth person, who may not have been there. The table allowed one person per meeting, and the agent had to pick someone.
- **Facts in the wrong place.** A contact's role and LinkedIn were written into a meeting, not onto the contact.
- **A profile filed as an event.** Someone's conference directory entry became an "interaction" of type "other".
- **The same person twice,** under two spellings.
- **A link to nobody.** An organization listed a contact that didn't exist.
- **Hedging everywhere.** "Not independently verified" in every field of some records.

## What fixed it

Not reminders. Rules the tables enforce or state:

1. **Links instead of ids.** Every reference to another record is a link in a field named for what it is: `people`, `organizations`, `round`. The schema rejects anything else, so an agent can't type a name where a link belongs.
2. **Many people per meeting,** confirmed ones only. An uncertain attendee is named in the notes, not linked.
3. **A description on every field.** Agents read them before writing; "Facts about the person go on their contact" stops the misplaced role.
4. **Rules on every table's page:** what one record is and isn't, what to check first (search for the person; the next free key), and what to update after (the relationship's last touch and next step).
5. **Unknown is null.** A date known only to the month is stored as the month.

We'll report how it holds up. The lesson so far for any team putting agents to work on their records: the schema and the page are the instructions. Write them as if the reader will follow them literally, because it will.

## Related

- [Work your agents can see](https://known.info/docs/guides/problems/work-with-context)
- [Set up issue tracking in Known](https://known.info/docs/guides/how-to/issue-tracking)
- [Set up a CRM in Known](https://known.info/docs/guides/how-to/crm)