---
title: "kmem documentation"
type: reference
tags: [signpost, docs, index]
proposed_by: tok_bc09b340db294c709763789154d8113d
model: kmem-docs-publisher
extracted_at: "2026-10-08T22:25:21.303Z"
---
# kmem documentation

This directory is the project's memory. It is written so that somebody who has never seen kmem, with
no conversation history, can open the repository and continue the work correctly.

**Written 2026-08-10, cut back to the relaunch set 2026-09-11, revised 2026-09-16 for the user guide
and the finish wave.** Every document is described here and
in [`manifest.json`](./manifest.json), which is the machine-readable copy. A disagreement between the
directory and this index is a CI failure rather than an observation: `pnpm docs:manifest`.
[`CONVENTIONS.md`](./CONVENTIONS.md) is the convention both checks enforce.

**`RELAUNCH_NOTES.md` at the repository root says what is broken right now.** Nothing in this
directory is authoritative about the present. Read that file first, then come back here for the
system.

---

## 1. Three reading orders

### If you use kmem, or you connect an agent to it

Read the [user guide](#use-kmem), from [`user-guide/010-welcome.md`](./user-guide/010-welcome.md)
on. It describes the product screen by screen, in the words the screens use. The app serves the same
pages at `/help` and `/help/<page>` on every host, and each "?" link opens the page for the screen it
is on. Nothing else in this directory is written for a person who only uses kmem.

### If you are an engineer on this repository

1. **[`../README.md`](../README.md)** — what kmem is, the loop, the three doors, the repository map
   and the commands.
2. **[`ARCHITECTURE.md`](./ARCHITECTURE.md) §6 and §8** — the single write path, and the invariants,
   each naming the real failure it prevents. Almost every expensive mistake in this codebase's
   history was a violation of one of them.
3. **[`CODEBASE.md`](./CODEBASE.md)** — where a thing lives, the extension points with the exact
   example to copy, and the traps. This is the document for "I need to change X and I do not know
   where X is".
4. **[`../CONTRIBUTING.md`](../CONTRIBUTING.md)** — the layout rules, the test strategy and what a
   reviewable change looks like.
5. **The document for the surface you are changing.** [`RETRIEVAL.md`](./RETRIEVAL.md) for search,
   [`MCP.md`](./MCP.md) for a tool, [`API.md`](./API.md) for an endpoint,
   [`EDITOR.md`](./EDITOR.md) for the editor, [`TENANCY.md`](./TENANCY.md) for anything that resolves
   a host or a partition key, [`SYNC.md`](./SYNC.md) for git and folder ingest.

`design/CONTRACT.md` binds you when your task is part of the relaunch, and `design/DESIGN.md` plus
`design/screens/` govern anything visual.

### If you are an agent working on this repository

In this order, and stop when you have what you need for the task in front of you.

1. **[`../CLAUDE.md`](../CLAUDE.md)** — the session brief. Shell setup, the four things that are
   already broken, the rules that decide arguments, the invariants and their test paths, and the
   spending gate.
2. **[`RELAUNCH_NOTES.md`](../RELAUNCH_NOTES.md)** — what is true right now, and
   **[`FIX_PASS_NOTES.md`](../FIX_PASS_NOTES.md)** — the 2026-09-11 fix pass, issue by issue, and
   **[`REVIEW.md`](../REVIEW.md)** — the senior reviewer's verdicts on that build.
3. **[The routing table below](#2-routing-if-you-are-doing-this-read-that)** — two or three documents
   for your specific task, in order.
4. **[`WRITING.md`](./WRITING.md)** — before you write any string a model will read, which includes
   every tool description and every refusal string.

Two rules that save the most time. Call `recall` before you answer a question about architecture, a
decision or a convention; if it returns gaps, say so rather than guessing. And a green suite proves
very little here, so write the test that would have caught the failure.

---

## 2. Routing: if you are doing this, read that

| If you are… | Read, in this order |
| --- | --- |
| Working on retrieval | [`RETRIEVAL.md`](./RETRIEVAL.md) → `packages/core/src/retrieval/` → [`../eval/README.md`](../eval/README.md) |
| Working on the write path, the parser or the data core | [`ARCHITECTURE.md`](./ARCHITECTURE.md) §5 to §8 → [`ADR/0003`](./ADR/0003-source-preserving-markdown.md) and [`ADR/0005`](./ADR/0005-write-serialisation.md) |
| Changing the MCP server or adding a tool | [`MCP.md`](./MCP.md) → [`CODEBASE.md`](./CODEBASE.md) → `apps/worker/src/mcp/` |
| Changing an endpoint or Quick Connect | [`API.md`](./API.md) → [`SECURITY.md`](./SECURITY.md) → [`ADR/0006`](./ADR/0006-rate-limiting.md) and [`ADR/0008`](./ADR/0008-quick-connect-briefing-cache.md) |
| Connecting a coding agent, or shipping the plugin | [`AGENT-INTEGRATION.md`](./AGENT-INTEGRATION.md) → [`MCP.md`](./MCP.md) → [`WEBMCP.md`](./WEBMCP.md) for the browser-resident case |
| Working out which clients a change reaches | [`COMPATIBILITY.md`](./COMPATIBILITY.md) → [`MCP.md`](./MCP.md) |
| Working on the editor or the note view | [`EDITOR.md`](./EDITOR.md) → `design/screens/docs.md` |
| Connecting a git repository or ingesting a folder | [`SYNC.md`](./SYNC.md) §7 first, then the rest of it |
| Provisioning or deploying | [`DEPLOYMENT.md`](./DEPLOYMENT.md) → [`OPERATIONS.md`](./OPERATIONS.md) |
| Operating or debugging a live deployment | [`OPERATIONS.md`](./OPERATIONS.md) → [`SECURITY.md`](./SECURITY.md) |
| Publishing the documentation site | [`DEPLOYMENT.md`](./DEPLOYMENT.md) "Publish the documentation" → [`ADR/0015`](./ADR/0015-two-documentation-organizations.md) → `apps/worker/src/routes/docs.ts` |
| Changing anything that resolves a hostname, a `project_id`, an R2 prefix or a vector namespace | [`TENANCY.md`](./TENANCY.md) → [`ADR/0013`](./ADR/0013-multi-tenancy-supersedes-single-project.md), and add a second organization to your fixture before you add the assertion |
| Changing who may read what | [`ADR/0026`](./ADR/0026-two-visibility-levels.md) → [`ADR/0009`](./ADR/0009-permission-model.md) → [`ADR/0020`](./ADR/0020-restricted-spaces.md) and [`ADR/0023`](./ADR/0023-sharing-people-and-groups.md) → [`TAXONOMY.md`](./TAXONOMY.md) → `apps/worker/test/invariants/read-scope.test.ts` |
| Changing what an agent may write, or what reaches Review | [`ADR/0022`](./ADR/0022-agent-writes.md) → [`ADR/0017`](./ADR/0017-conflict-only-review.md) → [`ARCHITECTURE.md`](./ARCHITECTURE.md) §6 |
| Changing verification, trust marks or how answers rank by state | [`ADR/0027`](./ADR/0027-verification-is-tracking.md) → [`ADR/0018`](./ADR/0018-verification-is-an-org-choice.md) → [`RETRIEVAL.md`](./RETRIEVAL.md) → `packages/core/src/provenance/` |
| Changing sign-in for ChatGPT, Claude or Gemini | [`ADR/0019`](./ADR/0019-hosted-oauth.md) → [`MCP.md`](./MCP.md) → [`SECURITY.md`](./SECURITY.md) → `apps/worker/src/routes/oauth.ts` |
| Changing the account page or who opens org settings | [`ADR/0021`](./ADR/0021-account-page-and-admin-settings.md) → `design/screens/account.md` → `design/screens/settings.md` |
| Working on cost, limits or pricing | [`ADR/0025`](./ADR/0025-cost-metering.md) → [`PRICING_ANALYSIS.md`](./PRICING_ANALYSIS.md) → `packages/core/src/metering/` |
| Writing or updating the user guide | [`user-guide/010-welcome.md`](./user-guide/010-welcome.md) → [`CONVENTIONS.md`](./CONVENTIONS.md) "The user guide" → `apps/web/src/locales/en.json` for every bold label → `apps/web/src/screens/connect/clients.ts` for every client recipe → `pnpm docs:links && pnpm docs:manifest` |
| Hiding or revealing a surface at launch | `LAUNCH_FLAGS.md` → `apps/web/src/flags.ts` |
| Adding, moving or renaming a document | [`CONVENTIONS.md`](./CONVENTIONS.md) → a row in [`manifest.json`](./manifest.json), a row here, and a `section` when it is public, in the same change → `pnpm docs:links && pnpm docs:manifest` |
| Writing a string a model reads | [`WRITING.md`](./WRITING.md) |

---

## 3. Public and internal, and how a program reads it

Every document carries an **audience**, and it lives in [`manifest.json`](./manifest.json) rather than
in each file's front matter, so the publishing step reads one file instead of thirty.

That column is a router. The documentation is published into **two organizations on one deployment**:
`docs` takes the `public` set and nothing else, and `signpost` takes everything. One publisher reads
the column twice, with two filters. [`ADR/0015`](./ADR/0015-two-documentation-organizations.md) is the
decision, and [`DEPLOYMENT.md`](./DEPLOYMENT.md) is the runbook.

A public document also carries a **`section`**: one of seven folders, in the order the site's sidebar
reads. `user-guide` is the first. It is the only editorial fact no other field carries. The sidebar heading is derived from the
folder name, so `how-it-works` renders as `How it works`.

| | Means | Examples |
| --- | --- | --- |
| **`public`** | The documentation site serves it. Written for somebody who does not work on kmem | [`ARCHITECTURE.md`](./ARCHITECTURE.md), [`API.md`](./API.md), [`RETRIEVAL.md`](./RETRIEVAL.md), every [`ADR/`](./ADR) |
| **`internal`** | Not served publicly. Working material for the people who build and operate kmem | [`DEPLOYMENT.md`](./DEPLOYMENT.md), [`SECURITY.md`](./SECURITY.md), [`TAXONOMY.md`](./TAXONOMY.md), `LAUNCH_FLAGS.md` |

**`internal` does not mean secret.** It means the site does not serve it, because a reader who does
not build kmem is not the audience and would be misled by it.

**Secrecy is the other axis, and the product enforces it.** `visibility` in the manifest is one of
the two levels from [`ADR/0026`](./ADR/0026-two-visibility-levels.md): `open` (every member of the
org, and their agents) or `private` (owners, and the people and groups on the doc's list). It decides
who may read a note in the deployment, which is a different question from what the documentation site
serves. Two documents differ from the default: [`SECURITY.md`](./SECURITY.md) and
[`OPERATIONS.md`](./OPERATIONS.md) are `private`. Each row states why.

`OPERATIONS.md` shows that the two axes are independent: `public`, because anybody operating a
deployment needs the runbooks, and `private`, because it describes a live system's measured behaviour.
A private doc is not published at `/docs` and a reader-minted link does not read it.

```sh
pnpm docs:manifest                           # the manifest and the directory agree
node scripts/check-doc-manifest.mjs --json   # the resolved public and internal sets
```

A public document may link to an internal one. The publishing step rewrites the target to the file in
the repository rather than dropping the link, because a dead route is worse than an off-site one. The
checker counts these and prints the count, so the size of that job is a number somebody has seen.

---

## 4. Every document, and when to read it

### Use kmem

The user guide. The web app serves these pages at `/help` on every host, and each help door in the
app opens the page for its screen.

| Document | Audience | What it is | When to read it |
| --- | --- | --- | --- |
| [`user-guide/010-welcome.md`](./user-guide/010-welcome.md) | public | What kmem does, the words the user guide uses, and where a new reader starts | When you use that part of kmem |
| [`user-guide/020-create-your-account-and-org.md`](./user-guide/020-create-your-account-and-org.md) | public | Create an account and an org, choose the Agent writes and Verification settings, and join an org from an invitation | When you use that part of kmem |
| [`user-guide/030-find-your-way-around.md`](./user-guide/030-find-your-way-around.md) | public | The four main areas, the org menu, the user menu, help, search, phone layout, themes and shortcuts | When you use that part of kmem |
| [`user-guide/040-read-and-find-docs.md`](./user-guide/040-read-and-find-docs.md) | public | Browse folders, find a doc, and read a doc with its details and history | When you use that part of kmem |
| [`user-guide/050-write-and-edit-docs.md`](./user-guide/050-write-and-edit-docs.md) | public | Create a doc, choose its visibility, use the Markdown, Split and Preview views, save, add images and recover versions | When you use that part of kmem |
| [`user-guide/060-organize-docs-in-folders.md`](./user-guide/060-organize-docs-in-folders.md) | public | Create, move and delete folders, change folder settings, and restrict a folder to chosen people and groups | When you use that part of kmem |
| [`user-guide/070-control-who-can-read-a-doc.md`](./user-guide/070-control-who-can-read-a-doc.md) | public | The visibility levels, sharing with people and groups, and what agents can read | When you use that part of kmem |
| [`user-guide/080-upload-and-export-docs.md`](./user-guide/080-upload-and-export-docs.md) | public | Import Markdown files or a zip, read the import result, and export docs | When you use that part of kmem |
| [`user-guide/085-import-memory-from-another-ai.md`](./user-guide/085-import-memory-from-another-ai.md) | public | Bring the memory of another AI into kmem: the export prompt, the proposed docs and the review | When you bring in AI memory |
| [`user-guide/090-review-changes.md`](./user-guide/090-review-changes.md) | public | What waits in Review, and how to accept, reject or keep both versions of a change | When you use that part of kmem |
| [`user-guide/100-verify-facts.md`](./user-guide/100-verify-facts.md) | public | The Verification setting, the status marks, and how to accept or verify facts | When you use that part of kmem |
| [`user-guide/110-connect-agents.md`](./user-guide/110-connect-agents.md) | public | Connections, the three connection modes, the Agent writes setting, and how to check, rename and revoke a connection | When you use that part of kmem |
| [`user-guide/120-connect-chatgpt.md`](./user-guide/120-connect-chatgpt.md) | public | Connect ChatGPT to kmem over MCP with sign-in | When you use that part of kmem |
| [`user-guide/130-connect-claude.md`](./user-guide/130-connect-claude.md) | public | Connect Claude on the web or the desktop app as a custom connector with sign-in | When you use that part of kmem |
| [`user-guide/140-connect-claude-code.md`](./user-guide/140-connect-claude-code.md) | public | Connect Claude Code with one command and a connection token | When you use that part of kmem |
| [`user-guide/150-connect-cursor.md`](./user-guide/150-connect-cursor.md) | public | Connect Cursor through its MCP configuration file | When you use that part of kmem |
| [`user-guide/160-connect-codex.md`](./user-guide/160-connect-codex.md) | public | Connect Codex through its configuration file and the KMEM_TOKEN variable | When you use that part of kmem |
| [`user-guide/170-connect-opencode.md`](./user-guide/170-connect-opencode.md) | public | Connect OpenCode through its global configuration file | When you use that part of kmem |
| [`user-guide/180-connect-openclaw-hermes-or-deepseek-harness.md`](./user-guide/180-connect-openclaw-hermes-or-deepseek-harness.md) | public | Connect the OpenClaw, Hermes or DeepSeek Harness agent harnesses with a token | When you use that part of kmem |
| [`user-guide/190-connect-gemini.md`](./user-guide/190-connect-gemini.md) | public | Connect Gemini CLI with a token, or Gemini with Quick Connect | When you use that part of kmem |
| [`user-guide/200-use-quick-connect-and-other-clients.md`](./user-guide/200-use-quick-connect-and-other-clients.md) | public | Give an agent a Quick Connect URL, and connect other MCP clients, Pi, Grok Bot, curl and MCP Inspector | When you use that part of kmem |
| [`user-guide/210-ask-questions.md`](./user-guide/210-ask-questions.md) | public | Ask questions of your docs, read the sources, and write down what is missing | When you use that part of kmem |
| [`user-guide/220-manage-your-account.md`](./user-guide/220-manage-your-account.md) | public | Change your name, email address, password and theme, and sign out | When you use that part of kmem |
| [`user-guide/230-manage-org-settings.md`](./user-guide/230-manage-org-settings.md) | public | Who can open org settings, and how to change the org details, Agent writes, Verification, export and deletion | When you use that part of kmem |
| [`user-guide/240-manage-members-and-groups.md`](./user-guide/240-manage-members-and-groups.md) | public | Roles, invitations, removing members, and managing groups | When you use that part of kmem |
| [`user-guide/250-troubleshooting.md`](./user-guide/250-troubleshooting.md) | public | Common problems with sign-in, connections, clients, imports, Review and Ask, with the cause and the fix | When you use that part of kmem |

### At the repository root

| Document | Audience | What it is | When to read it |
| --- | --- | --- | --- |
| [`../README.md`](../README.md) | public | What kmem is, the loop, the three doors, the repository map, the commands | First, and when you need a command |
| [`../PRODUCT.md`](../PRODUCT.md) | public | Why kmem exists, the thesis, who it is for, what it is not, the risks | Before you argue about scope |
| [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | public | The layout rules, the test strategy, what a reviewable change looks like | Before your first change |
| [`../CLAUDE.md`](../CLAUDE.md) | public | The agent brief. It imports `AGENTS.md` for the conventions | Every session, if you are an agent |
| [`../AGENTS.md`](../AGENTS.md) | public | A pointer to `CLAUDE.md`, and the managed region the product projects into. Not ingested, so not on the documentation site | Through `CLAUDE.md`, which imports it |

### Use kmem

The user guide, section `user-guide`. Each page is written for a person who uses kmem, in
ASD-STE100, with the screen labels in bold exactly as `apps/web/src/locales/en.json` spells them.

| Document | Audience | What it is | When to read it |
| --- | --- | --- | --- |
| [`user-guide/010-welcome.md`](./user-guide/010-welcome.md) | public | What kmem does, the words the guide uses, where to start | First, if you are new to kmem |
| [`user-guide/020-create-your-account-and-org.md`](./user-guide/020-create-your-account-and-org.md) | public | Sign up, create an org, the two org settings, join from an invitation, sign in, reset a password | When you start, or when you get an invitation |
| [`user-guide/030-find-your-way-around.md`](./user-guide/030-find-your-way-around.md) | public | The four areas, the org menu, the account menu, help, search, phone, theme, shortcuts | When you do not know where a thing is |
| [`user-guide/040-read-and-find-docs.md`](./user-guide/040-read-and-find-docs.md) | public | The Docs overview, folders, search, the reader, the Details panel, history | When you read docs |
| [`user-guide/050-write-and-edit-docs.md`](./user-guide/050-write-and-edit-docs.md) | public | Create a doc, the three editor views, the Markdown kmem draws, images, save, conflicts, rename, delete | When you write docs |
| [`user-guide/060-organize-docs-in-folders.md`](./user-guide/060-organize-docs-in-folders.md) | public | Create, move, delete and restrict folders | When you organize docs |
| [`user-guide/070-control-who-can-read-a-doc.md`](./user-guide/070-control-who-can-read-a-doc.md) | public | The visibility levels, the Share dialog, what agents can read | Before you share a doc |
| [`user-guide/080-upload-and-export-docs.md`](./user-guide/080-upload-and-export-docs.md) | public | Import files or a zip, the import result, export | When you move docs in or out |
| [`user-guide/090-review-changes.md`](./user-guide/090-review-changes.md) | public | What waits in Review, and how to decide a batch | When changes wait for you |
| [`user-guide/100-verify-facts.md`](./user-guide/100-verify-facts.md) | public | The Verification setting, the status marks, the status panel | When your org checks agent text |
| [`user-guide/110-connect-agents.md`](./user-guide/110-connect-agents.md) | public | Connections, the three modes, Agent writes, check, rename, revoke, undo | Before you connect any agent |
| [`user-guide/120-connect-chatgpt.md`](./user-guide/120-connect-chatgpt.md) | public | ChatGPT with sign-in, and the approval page | When you connect ChatGPT |
| [`user-guide/130-connect-claude.md`](./user-guide/130-connect-claude.md) | public | Claude as a custom connector with sign-in | When you connect Claude |
| [`user-guide/140-connect-claude-code.md`](./user-guide/140-connect-claude-code.md) | public | Claude Code with one command | When you connect Claude Code |
| [`user-guide/150-connect-cursor.md`](./user-guide/150-connect-cursor.md) | public | Cursor through `~/.cursor/mcp.json` | When you connect Cursor |
| [`user-guide/160-connect-codex.md`](./user-guide/160-connect-codex.md) | public | Codex through `~/.codex/config.toml` and `KMEM_TOKEN` | When you connect Codex |
| [`user-guide/170-connect-opencode.md`](./user-guide/170-connect-opencode.md) | public | OpenCode through its global configuration | When you connect OpenCode |
| [`user-guide/180-connect-openclaw-hermes-or-deepseek-harness.md`](./user-guide/180-connect-openclaw-hermes-or-deepseek-harness.md) | public | The three agent harnesses, each with its file | When you connect one of them |
| [`user-guide/190-connect-gemini.md`](./user-guide/190-connect-gemini.md) | public | Gemini CLI with a token, or Gemini with Quick Connect | When you connect Gemini |
| [`user-guide/200-use-quick-connect-and-other-clients.md`](./user-guide/200-use-quick-connect-and-other-clients.md) | public | Quick Connect, other MCP clients, Pi, Grok Bot, curl and MCP Inspector | When a client is not on the list |
| [`user-guide/210-ask-questions.md`](./user-guide/210-ask-questions.md) | public | Ask, its sources, gaps, and limits | When you want an answer from the docs |
| [`user-guide/220-manage-your-account.md`](./user-guide/220-manage-your-account.md) | public | The Account page: name, email, password | When you change your own details |
| [`user-guide/230-manage-org-settings.md`](./user-guide/230-manage-org-settings.md) | public | Org details, Agent writes, Verification, export, deletion | When you run an org |
| [`user-guide/240-manage-members-and-groups.md`](./user-guide/240-manage-members-and-groups.md) | public | Roles, invitations, removal, groups | When you manage people |
| [`user-guide/250-troubleshooting.md`](./user-guide/250-troubleshooting.md) | public | Common problems, each with the cause and the fix | When something does not work |

### How it works

| Document | Audience | What it is | When to read it |
| --- | --- | --- | --- |
| [`ARCHITECTURE.md`](./ARCHITECTURE.md) | public | Components, data flow, the single write path, the invariants and the failure each prevents | Before you change the data core |
| [`CODEBASE.md`](./CODEBASE.md) | public | The repository from the code: each package, the extension points, the traps, the namespaces | When you do not know where a thing lives |
| [`RETRIEVAL.md`](./RETRIEVAL.md) | public | The pipeline stage by stage, scoring, freshness, the ContextPack, where the eval runs | Before you touch ranking |
| [`TENANCY.md`](./TENANCY.md) | public | The host roles, the partition keys, and what a session is | Before you touch anything host-shaped |
| [`EDITOR.md`](./EDITOR.md) | public | How an edit becomes a splice, inline media, the MPL-2.0 no-fork rule | Before you touch the note view |
| [`SYNC.md`](./SYNC.md) | public | Git sync and folder ingest, the path model, conflict handling, the operator checklist | Before you connect a real repository |

### Connect an assistant

| Document | Audience | What it is | When to read it |
| --- | --- | --- | --- |
| [`API.md`](./API.md) | public | Every endpoint, generated from the Zod schemas the handlers parse with | When something answers a status code you did not expect |
| [`ASK.md`](./ASK.md) | public | The Ask destination, the streaming wire contract of `POST /api/ask`, the models config and its override syntax, the cost of one answer | Before you change a model, a prompt or the Ask screen |
| [`MCP.md`](./MCP.md) | public | The tools, the resource, the two prompts, the footprint, how each client connects (hosted OAuth or a token), per-client setup | Before you add, remove or rename a tool |
| [`AGENT-INTEGRATION.md`](./AGENT-INTEGRATION.md) | public | The Claude Code plugin, the Agent Skill, the hooks, the stdio bridge | When you ship the agent kit |
| [`WEBMCP.md`](./WEBMCP.md) | public | The browser-resident door, with no credential pasted anywhere | When an agent lives in the page |
| [`COMPATIBILITY.md`](./COMPATIBILITY.md) | public | The client matrix and the behaviours a reader has to plan around | Before you promise a client works |

### Run a deployment

| Document | Audience | What it is | When to read it |
| --- | --- | --- | --- |
| [`OPERATIONS.md`](./OPERATIONS.md) | public, private | `/health`, logs without a leaked credential, rate limits, the audit log, a runbook per failure | Before anybody else uses the deployment |
| [`DEPLOYMENT.md`](./DEPLOYMENT.md) | internal | Provisioning, migrations, secrets, the first owner, backup, rollback, recovery, publishing the docs site | Before you touch an account |
| [`SEO_BASELINE.md`](./SEO_BASELINE.md) | internal | What each public page targets, how the marketing routes are prerendered, how to rebuild the Open Graph cards, the Search Console checklist | Before you change a marketing page or its head |
| [`SECURITY.md`](./SECURITY.md) | internal, private | The threat model, the token model, what is stored, the known weaknesses, how to report one | Before you change auth or a token |
| `LAUNCH_FLAGS.md` | internal | Every launch flag, what it hides, how to turn it on | Before you hide or reveal a surface |
| [`PRICING_ANALYSIS.md`](./PRICING_ANALYSIS.md) | internal | The cost of each operation from the local load test, persona estimates, the unbounded paths, and a tier recommendation for the owner | Before you change a tier, a limit or a price |
| [`RELAUNCH_NOTES.md`](../RELAUNCH_NOTES.md) | internal | What the 2026-09-11 relaunch changed, the flags, the demo script, what is still open | First, if you are new since the relaunch |

### Conventions and decisions

| Document | Audience | What it is | When to read it |
| --- | --- | --- | --- |
| [`CONVENTIONS.md`](./CONVENTIONS.md) | public | How these documents relate, where a summary lives, the three markings, the checks | Before you add or move a document |
| [`WRITING.md`](./WRITING.md) | public | The standard for text a model reads | Before you write a tool description or a refusal |
| [`TAXONOMY.md`](./TAXONOMY.md) | internal | The naming and permission taxonomy: the hierarchy, the capability grids, the clamp | Before you change a role or a capability |
| [`ADR/`](./ADR) | public | One decision per file, with the alternative that was rejected. [§5](#5-architecture-decision-records) lists them | Before you relitigate one |

### Elsewhere in the repository

`design/README.md` and `design/CONTRACT.md` are the design handoff and the build contract.
[`../brand/README.md`](../brand/README.md) says what is left in `brand/`.
[`../eval/README.md`](../eval/README.md) is the eval set and its runner.
[`../e2e/README.md`](../e2e/README.md) is the Playwright suite.
`packages/agent-kit/skills/kmem/SKILL.md` is the portable Agent Skill that ships to clients.

---

## 5. Architecture decision records

Anything that will be questioned in six months goes in [`ADR/`](./ADR) as one short file: the
decision, the alternative that was rejected, and why. One decision per file, numbered in sequence,
never edited after the fact. When a decision changes, write a new ADR that supersedes the old one and
say so in both.

- [0001 — One deployment serves one project](./ADR/0001-single-project-per-instance.md) — superseded
  by 0013
- [0002 — Bearer tokens, not OAuth](./ADR/0002-bearer-not-oauth.md) — superseded by 0019 for the
  clients that sign in; every other client still uses a bearer token
- [0003 — The parser preserves the source; it never reconstructs it](./ADR/0003-source-preserving-markdown.md)
- [0004 — `ProjectContext` lives in `apps/worker`, not in `packages/core`](./ADR/0004-project-context.md)
- [0005 — How concurrent writes to one note are serialised](./ADR/0005-write-serialisation.md)
- [0006 — How per-link rate limiting is counted, and what happens when the counter breaks](./ADR/0006-rate-limiting.md)
- [0008 — Caching the connection document without keeping a revoked link alive](./ADR/0008-quick-connect-briefing-cache.md)
- [0009 — The permission model: one level on the note, one reach on the link](./ADR/0009-permission-model.md)
  — amended by 0026
- [0010 — The audit log is witnessed, not chained](./ADR/0010-audit-integrity.md)
- [0011 — A version number is derived from the history, never stored](./ADR/0011-version-ordinal.md)
- [0012 — A note open in an editor has exactly one writer, and it is the Durable Object](./ADR/0012-open-document-ownership.md)
- [0013 — One deployment serves many organizations, superseding ADR 0001](./ADR/0013-multi-tenancy-supersedes-single-project.md)
- [0014 — The product is called kmem, and the plumbing keeps the name signpost](./ADR/0014-the-product-is-called-kmem.md)
- [0015 — The documentation is two organizations, and the manifest is the router](./ADR/0015-two-documentation-organizations.md)
  — amended by 0026 (its bound 2)
- [0016 — An assistant writes directly by default](./ADR/0016-direct-write-by-default.md) — the
  relaunch reversed this to review-everything; 0017 settles it, and 0018, 0022 and 0027 amend it
- [0017 — Review is for conflicts](./ADR/0017-conflict-only-review.md) — a new doc from an agent
  lands in Docs; a change to an existing doc, a supersession or a deletion waits for a person.
  0022 amends it for a connection in write mode
- [0018 — Verification is an org's choice, and a new org starts without it](./ADR/0018-verification-is-an-org-choice.md)
  — amended by 0027
- [0019 — Hosted OAuth for remote MCP clients](./ADR/0019-hosted-oauth.md) — supersedes 0002 for
  ChatGPT, Claude and the Gemini web app
- [0020 — A restricted space names who may open it, and a connection follows its person](./ADR/0020-restricted-spaces.md)
  — amended by 0023 and 0026
- [0021 — A person's account has its own page, and org Settings is for owners and admins](./ADR/0021-account-page-and-admin-settings.md)
- [0022 — Agent writes are an org's choice, and a new org starts with them off](./ADR/0022-agent-writes.md)
- [0023 — Share a doc or a folder with people and groups](./ADR/0023-sharing-people-and-groups.md)
  — amended by 0026
- [0025 — Meter the cost of each organization at the binding, and roll it up each night](./ADR/0025-cost-metering.md)
- [0026 — Two visibility levels, and a connection reads what its person reads](./ADR/0026-two-visibility-levels.md)
  — amends 0009, 0020 and 0023
- [0027 — Verification is tracking, not a gate](./ADR/0027-verification-is-tracking.md) — amends
  0016 control 3, 0017 and 0018: every doc text answers, ranked by its state

There is no 0007. 0024 is reserved for the decision about the user guide.

---

## 6. Glossary

Terms these documents use as though they were already defined. They are, but only in one place each.

| Term | What it means here |
| --- | --- |
| **ContextPack** | The object `recall` returns: ranked claims with provenance, the conflicts between them, and an explicit list of what the corpus does not know. Defined in [`RETRIEVAL.md`](./RETRIEVAL.md), shaped in `packages/core/src/retrieval/pack.ts` |
| **Claim** | One entry in a ContextPack: a chunk of a note plus its provenance, confidence and ref |
| **Block** | One structural element of a note — a paragraph, a list item, a heading — with a derived `blk_` id and a byte range into the source. The unit an edit addresses |
| **Chunk** | One retrieval-sized span of a note, produced by the chunker from blocks. The unit that is embedded. Block, chunk and claim are three granularities and the eval measures all three |
| **Status** | One of `verified`, `accepted`, `unverified`, `stale` and `superseded`. What a reader is told about a claim's standing |
| **Provenance** | Who wrote a block, who accepted it, and who verified it |
| **Ref, permalink** | The address of a thing. A permalink names a note; a ref of the form `permalink#blk_xxxxxxxx` names one block inside it. A citation in a ContextPack points at one |
| **The doors** | The ways an assistant reaches kmem: the MCP server at `/mcp`, Quick Connect at `/s/{token}`, and the browser-resident case in [`WEBMCP.md`](./WEBMCP.md) |
| **Link** | The credential for both agent doors: `sp_…`, stored as SHA-256 only, minted through `/api/tokens` or at the OAuth code exchange, revocable. [`SECURITY.md`](./SECURITY.md) is the model |
| **Connection** | The product's word for a link, as a person sees it in Connect: a name, a mode, an expiry and the person who made it. A connection reads what that person can read, and follows that person's membership and denials ([`ADR/0020`](./ADR/0020-restricted-spaces.md), [`ADR/0026`](./ADR/0026-two-visibility-levels.md)) |
| **Quick Connect** | A private URL at `/s/{token}` that gives an agent written instructions. Older documents call it a connection document, a session link or a share link |
| **Mode** | What a connection may do: "Read only" (`read`), "Read and propose" (`suggest`), "Read, propose and write" (`write`) |
| **Agent writes** | The org setting `org_routing.agent_writes`. Off caps every agent at `suggest` ([`ADR/0022`](./ADR/0022-agent-writes.md)) |
| **Verification** | The org setting `org_routing.verification`. On ranks facts by their state and shows the marks; off ranks every fact the same and shows none. Neither holds text back ([`ADR/0018`](./ADR/0018-verification-is-an-org-choice.md), [`ADR/0027`](./ADR/0027-verification-is-tracking.md)) |
| **Group** | A named set of members, stored as a better-auth `team` with a fixed address in `group_handle`. An `access:` list names it as `group:<address>` ([`ADR/0023`](./ADR/0023-sharing-people-and-groups.md)) |
| **The seam** | The boundary between `packages/core`, which is pure, and `apps/worker`, which holds every binding. Retrieval crosses it through `RetrievalPorts` |
| **Ports** | `RetrievalPorts`: the interfaces retrieval calls out through — `LexicalRetriever`, `DenseRetriever`, `Embedder`, `Reranker`, `GraphExpander`, `CandidateStore`, `IndexHealth` |
| **Invariant I1 to I7** | Properties the system must never violate, each with a dedicated test suite and each naming the real failure it prevents. [`ARCHITECTURE.md`](./ARCHITECTURE.md) §8; the test paths are in [`../CLAUDE.md`](../CLAUDE.md) |
| **ReadScope** | The resolved answer to "what may this principal read", threaded through every note read. A missing one is a compile error, which is what makes the permission model checkable rather than conventional. [`ADR/0009`](./ADR/0009-permission-model.md) |
| **Audience, visibility** | Two different markings on a document. Audience decides whether the documentation site serves it; visibility decides which people, and so which of their agents, may read it in a deployment. [§3](#3-public-and-internal-and-how-a-program-reads-it) |

---

## 7. Keeping this directory honest

Five habits, in the order of how much they are worth.

1. **Put the command next to the claim.** A number with no command beside it is a number nobody can
   re-check, and it is the first thing to go stale.
2. **Say when something is unverified.** "Written and tested, never run against the real thing" is a
   useful sentence. "Works" is not.
3. **When a document and the code disagree, change the document and say what it was wrong about.**
   A silent correction teaches nobody.
4. **Re-run a claim before you act on it, and re-date it when you do.**
5. **Remember that some prose here is load-bearing.**
   `apps/worker/test/services/agents-md.test.ts` asserts literal text in
   [`../AGENTS.md`](../AGENTS.md) and [`../CLAUDE.md`](../CLAUDE.md), and [`API.md`](./API.md) is compared byte for byte against its
   generator.

Two commands fail the build, and both run in CI:

```sh
pnpm docs:links      # every relative Markdown link in the repository resolves
pnpm docs:manifest   # the manifest and the directory describe each other
```

[`CONVENTIONS.md`](./CONVENTIONS.md) says what each one checks, what it deliberately does not check,
and where a new document goes.