Documentation

Everything reef does, in the order you are likely to need it: what it is, how memory is organised, how your assistant reads and writes it, and how to connect one.

What reef is

reef is a shared, living memory for a group of people and the AI assistants they talk to. You keep pages; your assistant reads them before it answers, and writes back to them as things change.

Three things separate it from the memory built into an assistant:

Shared, not personal. A cove belongs to a household, a project or a team, so everyone's assistant starts from the same picture.
A wiki, not a blob. Memory is pages you can read, correct and reorganise — not an opaque store you have to trust.
Map before memory. An assistant loads an index of what exists, then fetches only the pages the conversation actually needs.

There are three ways in, all reaching the same memory:

Way in	Address
The browser app — read, edit, invite, export	reefwith.me/app
Any assistant that speaks MCP	`https://reefwith.me/mcp`
The terminal	`uv tool install reef-cli`

reef is invitation-only. There is no public sign-up: you get in because someone already inside adds you to a cove.

Coves and pages

A cove is a small group and the memory it shares. You get one private cove, called personal, the first time you sign in. You can create any number of shared ones — a household, a school circle, an accountant, a small project.

	Private cove	Shared cove
Who can read it	Only you	Everyone invited
Created	At first sign-in	By whoever needs it
Named	Always `personal`	By you, for you
People join	Never	By email invitation from the owner

You name a shared cove for yourself. Your name for a cove is yours alone. Two households can each have a family without either knowing the other exists, and nobody can take a name from anybody else. The consequence worth remembering: when someone tells you a page is "in the family cove", they mean their name for it, which need not be yours.

A page is Markdown, from the moment you write it. Each one carries a path such as plans.md, a title, tags, and a one-line description. The description is what an assistant sees in the index, so it is worth writing as a real summary rather than a label.

How your assistant reads

reef loads an index first, then pages. This is the LLM Wiki pattern, adapted for shared, permissioned memory, and it is why a large memory stays cheap to consult.

The assistant calls load_index and gets a map of every page it may see: path, title, tags, and the one-line description. No page bodies.
It reads the map, decides what this conversation needs, and fetches only that with read_pages.
It fetches again as the topic moves. When the map alone cannot settle what to read, search_pages matches words inside page bodies.

The index is rebuilt from the database on every call, so it cannot fall out of date. Search runs under the same row-level security as every other read, so it can never surface a page its caller could not open.

How your assistant writes

Nothing is recorded silently. Mid-conversation, a fact worth keeping goes through remember, which stages it as a dated line in that cove's inbox. Before the conversation ends, the assistant says what it is keeping, so you can strike anything first.

An inbox entry is not memory yet. A tidy-up — ask for one any time — compiles inboxes onto real pages, flags pages that have gone stale, and surfaces contradictions between your pages and shared ones instead of quietly picking a winner.

Deliberate capture, reviewed by you, is the design: reef will not transcribe your conversations behind your back.

For edits to real pages rather than the inbox, an assistant uses:

Tool	What it does
`write_page`	Creates or replaces one page.
`write_pages`	Writes several pages as one change.
`edit_page_section`	Replaces one section, leaving the rest of the page untouched.
`update_meta_page`	Updates a cove's own index page.

Connect an assistant

Every route below signs in through the same browser flow. Use the email address you were invited on — that is how invitations to a cove reach you, and signing in with a different one gets you a different, empty account.

Claude

Go to Settings → Connectors and choose to add a custom connector.
Paste https://reefwith.me/mcp as the address.
Claude opens a sign-in page. Sign in once.

After this, every conversation — desktop, web, or the phone app — starts already knowing.

ChatGPT

In the desktop app, go to Settings → MCP servers and select Add server.
Name it reef, choose Streamable HTTP, paste https://reefwith.me/mcp, and save. Then select Restart.
Back in MCP servers, select Authenticate and sign in.

The ChatGPT desktop app and Codex share this setup on the same computer, so doing it here does it for both.

Codex

codex mcp add reef --url https://reefwith.me/mcp
codex mcp login reef

The second command finishes the sign-in in your browser.

Claude Code

The plugin carries the connector and three commands with it:

claude plugin marketplace add diepzee/reef
claude plugin install reef@haai

/reef:recall answers from memory rather than from guesswork, /reef:remember files something away, and /reef:whats-new reports what the other people's assistants have been writing.

The CLI

Two packages, both installing a reef command:

	Install	What you get
Python	`uv tool install reef-cli`	Every tool as a named command
npm	`npm install -g @haai/reef-cli`	`login`, `tools`, and `call`

Named commands use hyphens, so load_index becomes load-index. Every result is JSON, and an error such as not_found also exits non-zero.

reef login
reef load-index
reef read-pages personal profile.md preferences.md
reef write-page personal plans.md --body-file ./plans.md \
  --message "Add the summer plan" --title Plans
reef call read_pages '{"cove":"personal","paths":["plans.md"]}'

reef call takes any tool name and a JSON object, so it reaches everything the named commands do. Run reef tools for the live schemas, and reef <command> --help for arguments.

Set REEF_MCP_URL to point at another server, or REEF_ACCESS_TOKEN for a headless run. Each package caches its own token, so signing in with one does not sign in the other.

There is also a bundled agent skill at skills/reef, which teaches an assistant the retrieval protocol, private-by-default writing, optimistic locking, and when it must ask you before acting.

Tool reference

These are the tools an assistant sees over MCP, and the commands the CLI mirrors. Every one that touches a cove takes a cove argument.

Reading

Tool	What it does
`load_index`	The map of every page you may see — no bodies.
`read_pages`	Fetches several pages from one cove.
`read_page`	Fetches one page, optionally as it stood at a past date.
`search_pages`	Matches words inside page bodies.
`load_all_context`	Everything at once — for small coves, or a fresh start.
`whats_new`	What has changed since you last looked.
`get_operating_protocol`	The rules an assistant should follow here.

Writing

Tool	What it does
`remember`	Stages a fact as a dated line in the cove's inbox.
`write_page`	Creates or replaces one page.
`write_pages`	Writes several pages as one change.
`edit_page_section`	Replaces one section of a page.
`update_meta_page`	Updates a cove's own index page.
`delete_page`	Removes a page.

Coves

Tool	What it does
`list_coves`	The coves you are in.
`create_cove`	Makes a new shared cove.
`rename_cove`	Changes your own name for a cove.
`leave_cove`	Removes you from a cove.
`delete_cove`	Deletes a cove and its pages.

People and sharing

Tool	What it does
`invite`	Adds someone to one of your coves.
`invite_to_reef`	Brings someone new onto reef.
`remove_member`	Takes someone out of a cove.
`prepare_to_share`	Shows the exact text, and who would read it.
`confirm_share`	Moves it, once you have seen it.

Files and images

Tool	What it does
`add_file` · `read_file` · `delete_file`	Documents attached to a cove.
`add_image` · `read_image` · `delete_image`	Images attached to a cove.

Sharing is deliberate and permanent. Moving something out of your private cove takes two steps. First your assistant calls prepare_to_share, which shows you the exact text and names everyone who will be able to read it. Only then, with confirm_share, does it move.

Writing private content into a shared cove any other way is refused — not discouraged, refused. And there is no un-sharing: once other people can read something, treat it as read.

reef sends no email. Inviting someone records that they may join — it does not tell them. Pass the invitation on yourself, however you normally reach that person, or they will never know.

Invite someone already on reef into a cove with invite. For someone new, invite_to_reef brings them on. Both are addressed to an email, and that address is the one they must sign in with.

Your data

Pages are Markdown from the moment you write them. The browser app exports two ways:

Current content, as a Markdown archive or JSON.
Everything, as one download with full revision history and your stored file bytes.

Both are plain files that outlive this deployment. Export is one-way, out of reef — nothing here locks your memory in. Deleting means deleted.

Privacy is enforced by the database, not by application code. Every page, file and membership is guarded by PostgreSQL row-level security, so a query with a forgotten filter returns nothing rather than somebody else's data. Getting it wrong fails closed.

The privacy page spells out what is stored, where it lives, who can see it, and how to get it back or delete it. The terms cover the agreement itself.

Troubleshooting

My assistant answers without checking memory

Ask it to load the index. Connecting reef makes the memory available; it does not force an assistant to consult it every turn. In Claude Code, /reef:recall asks for an answer from memory rather than from guesswork.

I invited someone and they heard nothing

That is expected. reef sends no email, so the invitation reaches nobody until you pass it on yourself.

I signed in and my coves are gone

You are probably in a second account. Invitations are addressed to an email address, so signing in with a different one gives you a new, empty reef rather than an error. Sign out and sign back in with the address you were invited on.

The CLI is signed in but my assistant is not

Each package caches its own token, and the MCP connection has its own again. Signing in to one does not sign in the others — do each once.

Someone mentioned a cove I cannot find

Cove names are per person. Their name for a cove is not necessarily yours, so ask what is on the pages rather than what the cove is called — or check list_coves for what you actually have. If it is nowhere, you have not been invited to it yet.