{
  "markdown": "# reef\n\n**Shared, living memory for you and the people you share your life with — and\nfor the AI assistants you both already use.**\n\n[![PyPI](https://img.shields.io/pypi/v/reef-cli?label=reef-cli&logo=pypi&logoColor=white)](https://pypi.org/project/reef-cli/)\n[![npm](https://img.shields.io/npm/v/%40haai%2Freef-cli?label=%40haai%2Freef-cli&logo=npm)](https://www.npmjs.com/package/@haai/reef-cli)\n[![Python](https://img.shields.io/badge/python-3.13%2B-3776AB?logo=python&logoColor=white)](https://pypi.org/project/reef-cli/)\n[![MCP](https://img.shields.io/badge/MCP-remote%20server-1f6feb)](https://modelcontextprotocol.io)\n[![Live](https://img.shields.io/website?url=https%3A%2F%2Freefwith.me&label=reefwith.me)](https://reefwith.me)\n\nYour assistant forgets you between conversations. reef gives it a memory that\nlasts — and one your partner, your household, or your project can share.\n\n- **Ask once.** Tell your assistant the boiler is a Vaillant. Next month, in a\n  different conversation, it still knows.\n- **Share on purpose.** Your private notes stay private. A shared cove holds\n  only what you deliberately put there.\n- **Bring your own assistant.** Claude, ChatGPT desktop, or Codex. reef is a\n  remote [MCP](https://modelcontextprotocol.io) connector, not another chat app.\n\n---\n\n## Try it\n\nYou need an invitation — reef is invite-only. Once you have one:\n\n```bash\nuv tool install reef-cli   # or: npm install -g @haai/reef-cli\nreef login\nreef load-index\n```\n\nTo use it from an assistant instead, add `https://reefwith.me/mcp` as a remote\nMCP connector and sign in with the address you were invited on.\n\nIn Claude Code, the plugin carries that connector and three commands with it:\n\n```bash\nclaude plugin marketplace add diepzee/reef\nclaude plugin install reef@haai\n```\n\n`/reef:recall` answers from memory rather than from guesswork,\n`/reef:remember` files something away, and `/reef:whats-new` reports what the\nother people's assistants have been writing.\n\nThere is a browser app too, at [reefwith.me/app](https://reefwith.me/app). Use\nit to read and edit pages without an assistant.\n\n## How memory is organised\n\nMemory lives in **coves**. You get one private cove the first time you sign\nin. You can create any number of shared ones — a household, a school circle, an\naccountant, a small project.\n\n| | Private cove | Shared cove |\n|---|---|---|\n| Who can read it | Only you | Everyone invited |\n| Created | At first sign-in | By whoever needs it |\n| Named | Always `personal` | By you, for you |\n| People join | Never | By email invitation from the owner |\n\n**You name shared coves for yourself.** Your name for a cove is yours alone.\nTwo households can each have a `family` without either knowing the other\nexists, and nobody can take a name from anybody else.\n\n**Sharing is deliberate and permanent.** Moving something out of your private\ncove takes two steps. First your assistant shows you the exact text and names\neveryone who will be able to read it. Only then does it move.\n\nWriting private content into a shared cove any other way is refused — not\ndiscouraged, refused. And there is no un-sharing.\n\n## How your assistant reads it\n\nreef loads an **index first, then pages** — the\n[LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f),\nadapted for shared, permissioned memory.\n\n1. The assistant calls `load_index` and gets a map of every page it may see:\n   path, title, tags, and a one-line description. No page bodies.\n2. It reads the map, decides what this conversation needs, and fetches only\n   that with `read_pages`.\n3. It fetches again as the topic moves. When the map alone cannot settle\n   what to read, `search_pages` matches words inside page bodies — and\n   because it runs under the same row-level security as every read, a\n   search can never surface a page its caller could not open.\n\nThe index is rebuilt from the database on every call, so it cannot fall out of\ndate.\n\n## How your assistant writes it\n\nNothing is recorded silently. Mid-conversation, a fact worth keeping goes\nthrough `remember`, which stages it as a dated line in that cove's inbox —\nand before the conversation ends, the assistant says what it is keeping so\nyou can strike anything first.\n\nAn inbox entry is not memory yet. A tidy-up — ask for one any time —\ncompiles inboxes onto real pages, flags pages that have gone stale, and\nsurfaces contradictions between your pages and shared ones instead of\nsilently picking a winner. Deliberate capture, reviewed by you, is the\ndesign: reef will not transcribe your conversations behind your back.\n\n## How your privacy is protected\n\nThe database enforces it, not the application code.\n\nEvery page, file, and membership is guarded by PostgreSQL\n[Row-Level Security](https://www.postgresql.org/docs/current/ddl-rowsecurity.html).\nA query with a forgotten filter returns **nothing** rather than somebody else's\ndata. Getting it wrong fails closed.\n\nThis works only because the app connects as an ordinary database role. A\nsuperuser ignores every policy, so reef runs as `rif_app` — which can read and\nwrite rows but cannot change the schema. Migrations and backups use a separate,\nmore privileged credential. See\n[`scripts/provision_app_role.py`](scripts/provision_app_role.py).\n\n## Your data stays yours\n\nPages are Markdown from the moment you write them. The web app exports:\n\n- **current content**, as a Markdown archive or JSON, and\n- **everything**, as one download with full revision history and your stored\n  file bytes.\n\nBoth are plain files that outlive this deployment. Export is one-way, out of\nreef — nothing here locks your memory in.\n\n## Using the CLI\n\nTwo packages, both installing a `reef` command:\n\n| | Install | What you get |\n|---|---|---|\n| **Python** | `uv tool install reef-cli` | Every MCP tool as a named command |\n| **npm** | `npm install -g @haai/reef-cli` | `login`, `tools`, and `call` |\n\nNamed commands use hyphens: `load_index` becomes `load-index`. Every result is\nJSON, and an error such as `not_found` also exits non-zero.\n\n```bash\nreef read-pages personal profile.md preferences.md\nreef write-page personal plans.md --body-file ./plans.md \\\n  --message \"Add the summer plan\" --title Plans\nreef add-file personal ./lease.pdf --description \"Signed rental agreement\"\nreef call read_pages '{\"cove\":\"personal\",\"paths\":[\"plans.md\"]}'\n```\n\n`reef call` takes any MCP tool name and a JSON object, so it reaches everything\nthe named commands do. Large inputs can come from a file or stdin; uploads are\nencoded for you.\n\nBoth packages sign in through the same browser flow. Each caches its own token,\nso logging in with one does not log in the other. Tokens live in a user-private\nconfig file.\n\nSet `REEF_MCP_URL` to point at another server, or `REEF_ACCESS_TOKEN` for a\nheadless run.\n\nRun `reef tools` for the live schemas, and `reef <command> --help` for\narguments.\n\n**Agent skill:** [`skills/reef/SKILL.md`](skills/reef/SKILL.md) teaches an\nassistant the retrieval protocol, private-by-default writing, optimistic\nlocking, and when it must ask you before acting.\n\n## Status\n\n**Live since 6 August 2026** at [reefwith.me](https://reefwith.me), deployed on\nRailway behind WorkOS AuthKit, and in daily use.\n\nComplete and reviewed: the schema and access control, index and page reads,\nversioned writes, and section-level sharing. Also multi-user coves with\nowner-managed invitations, file storage, the browser app, import, backup, and\nexport.\n\nTests run against a real PostgreSQL, not a mock.\n\nKnown gaps, honestly:\n\n- **Backups run by hand.** One real dump exists and a restore drill passed\n  against it, but the daily job is not set up yet.\n- **Few people are on it.** Growth is one invitation at a time, by design.\n- **The context ceiling has not been measured on a phone.**\n\nEverything outstanding is tracked in the \"Open items\" list at the top of\n[`docs/runbook.md`](docs/runbook.md).\n\n## Development\n\nYou need [Docker](https://www.docker.com/) and [uv](https://docs.astral.sh/uv/).\n[just](https://github.com/casey/just) is optional but does the setup for you.\n\n```bash\njust setup   # dependencies, database, and the roles the tests need\njust test    # lint, Python suite, frontend suite\njust dev     # serve the app locally\n```\n\n`just` on its own lists every task. Without it:\n\n```bash\ndocker compose up -d              # PostgreSQL on port 5433\nuv sync && (cd frontend && bun install)\nuv run pytest                     # builds its own schema in rif_test\n```\n\nA cluster created before the test roles existed is missing them, and the suite\nsays so loudly rather than testing a weaker shape. `just db-roles` repairs it.\n\nTwo things about the local database are deliberate, not accidental:\n\n- **It does not run the app as a superuser.** A superuser ignores Row-Level\n  Security, so the security tests would pass without proving anything. See the\n  comment in [`docker-compose.yml`](docker-compose.yml).\n- **It creates a separate non-owner role for tests.** A table's owner is not\n  bound by column grants. Without that role, a test asserting \"a member cannot\n  rename a cove\" would pass for the wrong reason.\n\nMigrations seed one person and their coves. Nobody else is seeded, on purpose.\nAn email address is the key a first sign-in binds against, and a migration does\nnot re-run to correct a wrong guess. Everyone else arrives by invitation.\n\nWrite your PR title as a Conventional Commit (PRs are squash-merged, so the\ntitle is what decides the release version), and add a one-sentence fragment\nunder `changes/` if a person using reef would notice the change — see\n[`docs/releasing.md`](docs/releasing.md).\n\n## Documentation\n\n| Document | What it covers |\n|---|---|\n| [`docs/spec.md`](docs/spec.md) | The design and why it is shaped this way |\n| [`docs/runbook.md`](docs/runbook.md) | Deploying, and what is still open |\n| [`docs/restore.md`](docs/restore.md) | Backup and restore |\n| [`docs/competitor-research.md`](docs/competitor-research.md) | The market around it |\n\n## Licence\n\nThe **server** — everything at the repository root — is\n[AGPL-3.0-or-later](LICENSE). Read it, run it for yourself, fork it. The one\ncondition that bites is the network one: if you run a modified reef as a\nservice other people use, you owe them your changes. That matches what reef\nasks of itself. If somebody else is holding your memory, you should be able\nto see the code that holds it.\n\nThe parts you install rather than host are **MIT**, because a licence should\nnot be a reason to hesitate over a client:\n\n| Part | Licence |\n|---|---|\n| The server (`src/`, this repository) | AGPL-3.0-or-later |\n| [`clients/python`](clients/python) — `reef-cli` on PyPI | MIT |\n| [`clients/ts`](clients/ts) — `@haai/reef-cli` on npm | MIT |\n| [`plugins/reef`](plugins/reef) — the Claude Code plugin | MIT |\n\nCopyright is held by Haai BV.\n\n## A note on the name\n\nThe product is **reef**, and so is the Python module. `rif` was the working\nname, and it survived far longer than intended.\n\nWhat is still called `rif` is everything a running system remembers, because\nthose are not names anybody reads — they are keys something already wrote\ndown:\n\n| Still `rif` | What it is | Why it stays |\n|---|---|---|\n| `app_name=\"rif\"` | Piccolo's key in the `migration` table | Renaming it makes Piccolo find zero applied migrations and replay the whole chain against a populated database |\n| `rif_roster`, `rif_admit_member`, … | SQL helper functions | They are the row-level-security boundary; renaming them is live DDL on the part of the system that must not be got wrong |\n| `rif`, `rif_authz`, `rif_probe` | database roles | RLS is only enforced against the right roles, and the suite asserts privileges as `rif_probe` |\n| `RIF_*` | environment variables | Twelve are set on Railway, including the signing key and the open door; a renamed variable that nobody set reads as absent |\n| `diepzee/reef` | the repository | A plugin submission under review points at this URL |\n\nThe rule, if you are adding something: if the database or the deployment\nwill remember the name, it is `rif`. If a person will read it, it is `reef`.\n",
  "bytes": 12093,
  "sha": "205430f0d4e40ef5d8505afc61aeacc0efe54173684f6250d81dc65b65157d9a",
  "repo_slug": "diepzee/reef",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_me_reefwith_reef_dcb83b1e/readme"
}