Reef MCP Server

reef

Shared, living memory for you and the people you share your life with — and for the AI assistants you both already use.

Your assistant forgets you between conversations. reef gives it a memory that lasts — and one your partner, your household, or your project can share.

• Ask once. Tell your assistant the boiler is a Vaillant. Next month, in a different conversation, it still knows.
• Share on purpose. Your private notes stay private. A shared cove holds only what you deliberately put there.
• Bring your own assistant. Claude, ChatGPT desktop, or Codex. reef is a remote MCP connector, not another chat app.

---

Try it

You need an invitation — reef is invite-only. Once you have one:

uv tool install reef-cli   # or: npm install -g @haai/reef-cli
reef login
reef load-index

To use it from an assistant instead, add https://reefwith.me/mcp as a remote MCP connector and sign in with the address you were invited on.

In Claude Code, the plugin carries that 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.

There is a browser app too, at reefwith.me/app. Use it to read and edit pages without an assistant.

How memory is organised

Memory lives in coves. You get one private cove the first time you sign in. You can create any number of shared ones — a household, a school circle, an accountant, a small project.

You name shared coves 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.

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

Writing private content into a shared cove any other way is refused — not discouraged, refused. And there is no un-sharing.

How your assistant reads it

reef loads an index first, then pages — the LLM Wiki pattern, adapted for shared, permissioned memory.

1. The assistant calls load_index and gets a map of every page it may see: path, title, tags, and a one-line description. No page bodies.
2. It reads the map, decides what this conversation needs, and fetches only that with read_pages.
3. It fetches again as the topic moves. When the map alone cannot settle what to read, search_pages matches words inside page bodies — and because it runs under the same row-level security as every read, a search can never surface a page its caller could not open.

The index is rebuilt from the database on every call, so it cannot fall out of date.

How your assistant writes it

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 — and 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 silently picking a winner. Deliberate capture, reviewed by you, is the design: reef will not transcribe your conversations behind your back.

How your privacy is protected

The database enforces it, not the application code.

Every page, file, and membership is guarded by PostgreSQL Row-Level Security. A query with a forgotten filter returns nothing rather than somebody else's data. Getting it wrong fails closed.

This works only because the app connects as an ordinary database role. A superuser ignores every policy, so reef runs as rif_app — which can read and write rows but cannot change the schema. Migrations and backups use a separate, more privileged credential. See scripts/provision_app_role.py.

Your data stays yours

Pages are Markdown from the moment you write them. The web app exports:

• current content, as a Markdown archive or JSON, and
• 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.

Using the CLI

Two packages, both installing a reef command:

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

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 add-file personal ./lease.pdf --description "Signed rental agreement"
reef call read_pages '{"cove":"personal","paths":["plans.md"]}'

reef call takes any MCP tool name and a JSON object, so it reaches everything the named commands do. Large inputs can come from a file or stdin; uploads are encoded for you.

Both packages sign in through the same browser flow. Each caches its own token, so logging in with one does not log in the other. Tokens live in a user-private config file.

Set REEF_MCP_URL to point at another server, or REEF_ACCESS_TOKEN for a headless run.

Run reef tools for the live schemas, and reef <command> --help for arguments.

Agent skill: skills/reef/SKILL.md teaches an assistant the retrieval protocol, private-by-default writing, optimistic locking, and when it must ask you before acting.

Status

Live since 6 August 2026 at reefwith.me, deployed on Railway behind WorkOS AuthKit, and in daily use.

Complete and reviewed: the schema and access control, index and page reads, versioned writes, and section-level sharing. Also multi-user coves with owner-managed invitations, file storage, the browser app, import, backup, and export.

Tests run against a real PostgreSQL, not a mock.

Known gaps, honestly:

• Backups run by hand. One real dump exists and a restore drill passed against it, but the daily job is not set up yet.
• Few people are on it. Growth is one invitation at a time, by design.
• The context ceiling has not been measured on a phone.

Everything outstanding is tracked in the "Open items" list at the top of docs/runbook.md.

Development

You need Docker and uv. just is optional but does the setup for you.

just setup   # dependencies, database, and the roles the tests need
just test    # lint, Python suite, frontend suite
just dev     # serve the app locally

just on its own lists every task. Without it:

docker compose up -d              # PostgreSQL on port 5433
uv sync && (cd frontend && bun install)
uv run pytest                     # builds its own schema in rif_test

A cluster created before the test roles existed is missing them, and the suite says so loudly rather than testing a weaker shape. just db-roles repairs it.

Two things about the local database are deliberate, not accidental:

• It does not run the app as a superuser. A superuser ignores Row-Level Security, so the security tests would pass without proving anything. See the comment in docker-compose.yml.
• It creates a separate non-owner role for tests. A table's owner is not bound by column grants. Without that role, a test asserting "a member cannot rename a cove" would pass for the wrong reason.

Migrations seed one person and their coves. Nobody else is seeded, on purpose. An email address is the key a first sign-in binds against, and a migration does not re-run to correct a wrong guess. Everyone else arrives by invitation.

Write your PR title as a Conventional Commit (PRs are squash-merged, so the title is what decides the release version), and add a one-sentence fragment under changes/ if a person using reef would notice the change — see docs/releasing.md.

Documentation

Licence

The server — everything at the repository root — is AGPL-3.0-or-later. Read it, run it for yourself, fork it. The one condition that bites is the network one: if you run a modified reef as a service other people use, you owe them your changes. That matches what reef asks of itself. If somebody else is holding your memory, you should be able to see the code that holds it.

The parts you install rather than host are MIT, because a licence should not be a reason to hesitate over a client:

Copyright is held by Haai BV.

A note on the name

The product is reef, and so is the Python module. rif was the working name, and it survived far longer than intended.

What is still called rif is everything a running system remembers, because those are not names anybody reads — they are keys something already wrote down:

The rule, if you are adding something: if the database or the deployment will remember the name, it is rif. If a person will read it, it is reef.