# mdfy Demo's knowledge hub — full text

> A hand-curated example hub showing what mdfy makes possible — captured AI conversations, research notes, project decisions, and the bundles that synthesise them. Paste any URL into Claude, ChatGPT, or Cursor to see the full payload.

Canonical hub URL: https://memory.wiki/hub/demo
Index-only manifest: https://memory.wiki/hub/demo/llms.txt
Concept digest: https://memory.wiki/raw/hub/demo?digest=1&compact=1

# Knowledge graph

_Pre-computed structure across this hub: 40 concepts, 30 relations, 0 bundles with AI analysis. Use this as navigation; the doc bodies below contain the prose._

## Concepts
- **mdfy** _(entity • weight 123 • 21 docs)_
  A tool that stores project context and decision history, integrated into Cursor via custom rules.
- **Supabase** _(entity • weight 62 • 13 docs)_
  Backend-as-a-service providing authentication, database, and row-level security without separate auth overhead.
- **Vendor consolidation** _(concept • weight 61 • 12 docs)_
  The operational principle of reducing authentication surfaces, SDKs, and control planes by keeping vector search within the existing Postgres infrastructure.
- **Structural moat** _(concept • weight 53 • 8 docs)_
  The defensible advantage created by mdfy's vendor-neutral positioning, which competitors cannot replicate due to inherent conflicts of interest.
- **Claude** _(entity • weight 46 • 14 docs)_
  Anthropic's AI model cited as an example of vendor lock-in through projects and memory features.
- **pgvector** _(entity • weight 45 • 13 docs)_
  PostgreSQL extension providing vector data type and HNSW indexing for efficient similarity search.
- **mdfy.app** _(entity • weight 37 • 5 docs)_
  The platform hosting this hub with a hierarchical document structure and permission system.
- **Authentication** _(tag • weight 36 • 7 docs)_
  Core security domain covering user identity, session management, and authorization patterns.
- **bundle URL** _(entity • weight 35 • 5 docs)_
  The delivery mechanism for markdown digests that now carries embedded graph analysis instead of doc list only
- **AI tool integration** _(concept • weight 33 • 5 docs)_
  Ability to paste hub URL directly into Claude, ChatGPT, Cursor, or Codex for question-answering against the hub.
- **Hacker News** _(entity • weight 31 • 5 docs)_
  Primary GTM channel chosen for high ICP overlap with developers and format alignment with technical credibility.
- **Database Design** _(tag • weight 30 • 7 docs)_
  Data modeling domain including schema design, migrations, and query optimization strategies.
- **mdfy Platform** _(entity • weight 30 • 6 docs)_
  Knowledge management platform designed for AI-first workflows with URL-based sharing.
- **Cursor IDE** _(entity • weight 30 • 6 docs)_
  Code editor that can fetch and utilize mdfy bundle URLs for project context.
- **Cursor** _(entity • weight 30 • 13 docs)_
  Code editor that consumes mdfy bundles as context for chat and composer sessions.
- **API Design** _(tag • weight 28 • 7 docs)_
  RESTful interface design covering endpoints, error handling, and client-server communication.
- **Resend** _(entity • weight 27 • 7 docs)_
  Email service provider supporting both transactional and marketing communication channels.
- **ChatGPT** _(entity • weight 27 • 13 docs)_
  Example of an AI provider whose memory feature is intentionally confined to its own product.
- **Next.js App Router** _(entity • weight 26 • 7 docs)_
  Chosen routing framework leveraging RSC and Server Actions to match the project's data-heavy, read-mostly workload.
- **Vercel AI Gateway** _(entity • weight 26 • 7 docs)_
  AI provider abstraction layer offering failover and zero data retention for model access.
- **Cross-AI memory** _(concept • weight 26 • 6 docs)_
  The core thesis: a memory layer that persists across multiple AI providers simultaneously, structurally unavailable to single-vendor AI companies.
- **Anthropic** _(entity • weight 25 • 12 docs)_
  Incumbent AI vendor mentioned as competitive threat with integrated memory and user lock-in.
- **Next.js 15** _(entity • weight 25 • 7 docs)_
  Chosen frontend framework leveraging React Server Components and caching for performance.
- **Hub-shaped memory** _(concept • weight 24 • 3 docs)_
  The chosen architecture where users author structured notes as URL-addressable resources that the AI reads, preserving human control over memory curation.
- **Performance Optimization** _(concept • weight 24 • 5 docs)_
  Critical performance considerations driving technical architecture decisions.
- **Knowledge Management** _(tag • weight 24 • 7 docs)_
  Domain of organizing, storing, and retrieving information for human and AI use.
- **Row-level security** _(concept • weight 24 • 7 docs)_
  Supabase RLS capability co-locating authentication and authorization with data, justifying single-vendor consolidation.
- **React Hook Form** _(entity • weight 23 • 7 docs)_
  Primary form handling library paired with Zod schemas for both client and server validation.
- **Claude Code** _(entity • weight 23 • 6 docs)_
  AI coding feature mentioned as a primary context for AI-native developer adoption.
- **AI Integration** _(tag • weight 22 • 10 docs)_
  Artificial intelligence features and infrastructure including vector search and multi-provider setup.
- **Obsidian** _(entity • weight 22 • 5 docs)_
  The primary subject being tested for import functionality and markdown compatibility.
- **Vector recall** _(concept • weight 22 • 3 docs)_
  Memory pattern using embeddings and cosine similarity retrieval; trades precision for breadth but risks memory drift beyond user control.
- **Accessibility** _(tag • weight 22 • 7 docs)_
  Non-negotiable requirements including WCAG AA contrast, keyboard navigation, and semantic HTML for interactive elements.
- **Codex CLI** _(entity • weight 22 • 4 docs)_
  Command-line interface that integrates with AGENTS.md to load project context and caches configuration at session start.
- **Vercel** _(entity • weight 22 • 8 docs)_
  Early production adopter with comprehensive llms.txt implementation including per-product child files.
- **llms.txt** _(concept • weight 22 • 7 docs)_
  Plain-text discoverability standard for AI agents at site root, analogous to robots.txt and sitemap.xml.
- **Zod** _(entity • weight 21 • 7 docs)_
  Schema validation library used identically on client and server to enforce data integrity.
- **shadcn/ui** _(entity • weight 21 • 7 docs)_
  Source of primitive components re-exported in the project to maintain consistent branding.
- **URL-addressable knowledge** _(concept • weight 21 • 3 docs)_
  Design principle enabling AI systems to read structured user-authored content from persistent, addressable locations outside the AI interface.
- **Component hierarchy** _(concept • weight 21 • 7 docs)_
  Atomic structure (atoms → molecules → organisms → pages) establishes reusability rules and prevents circular dependencies in the codebase.

## Concept relations
- **Claude** developed by **Anthropic**
- **Hub-shaped memory** implemented by **mdfy**
- **mdfy** implements pattern **Hub-shaped memory**
- **Supabase** enables approach **Vendor consolidation**
- **Cross-AI memory** creates advantage **Structural moat**
- **Vector recall** implemented by **ChatGPT**
- **URL-addressable knowledge** enables approach **Hub-shaped memory**
- **Anthropic** supports strategy **Vendor consolidation**
- **Supabase** exemplifies approach **Vendor consolidation**
- **Supabase** reduces complexity **Vendor consolidation**
- **React Hook Form** pairs with **Zod**
- **Row-level security** supports **Vendor consolidation**
- **Supabase** integrates **pgvector**
- **Supabase** exemplifies strategy **Vendor consolidation**
- **Zod** integrates validation **React Hook Form**
- **Row-level security** supports decision **Vendor consolidation**
- **Supabase** provides **Row-level security**
- **Vendor consolidation** guides **Supabase**
- **React Hook Form** validates with **Zod**
- **mdfy.app** provides via **bundle URL**
- **Cursor IDE** fetches **bundle URL**
- **Supabase** implements **Row-level security**
- **Supabase** hosts **pgvector**
- **Vercel** supports strategy **Vendor consolidation**
- **Structural moat** enables **Cross-AI memory**
- **Cursor** positioned to deliver **Cross-AI memory**
- **Hub-shaped memory** depends on **URL-addressable knowledge**
- **mdfy** integrated into **Cursor**
- **mdfy** solves problem for **ChatGPT**
- **mdfy** integrates with **Cursor**


---
id: LhYW7tc1
title: API conventions
url: https://memory.wiki/LhYW7tc1
updated: 2026-05-27T00:41:53.897+00:00
---

# API conventions

## URL shape

`/api/v1/<resource>` for stable endpoints. Versioned via the path. Sub-resources nest: `/api/v1/pages/<id>/blocks`.

## HTTP verbs

- `GET` — idempotent read
- `POST` — create
- `PATCH` — partial update (default for edits)
- `PUT` — full replace (rare, use sparingly)
- `DELETE` — soft delete (sets `deleted_at`); pass `?permanent=true` for hard delete

## Error shape

Every error response:

```json
{
  "error": "human-readable message",
  "code": "machine_code",
  "details": {}
}
```

Status codes used: 400 (bad input), 401 (no auth), 403 (auth but no permission), 404 (not found), 409 (conflict), 410 (gone — expired), 422 (validation), 429 (rate limit), 500 (us).

## Authentication

Two paths, in order of precedence:

1. `Authorization: Bearer <jwt>` — for signed-in users (preferred)
2. `x-edit-token: <token>` — for anonymous edits (per-doc capability)

Server middleware (`lib/verify-auth.ts`) returns `{userId, email}`or null. Routes that allow either signed-in or token holders should check both.

## Rate limiting

Sliding window, IP-based, 60 req/min default. Override per-route in `middleware.ts`. Returns 429 with `Retry-After` header.

## Pagination

Cursor-based, not offset. `?cursor=<opaque>&limit=20`. Response includes `nextCursor` (or null if last page).

## Things to avoid

- Don't put service-role key calls behind the public API. Use server-component reads or the cron path.
- Don't return more than 200 rows in one response. Paginate.
- Don't emit raw Postgres errors to clients — sanitize via `mapPgError`.

---
id: ir0K6-u2
title: Open questions
url: https://memory.wiki/ir0K6-u2
updated: 2026-05-16T14:17:17.775341+00:00
---

# Open questions

Things we're carrying. Not decisions — placeholders.

## Pricing model

Three candidates:

1. Per-seat ($X / user / month) — predictable for buyer, penalises invite-heavy teams
2. Per-page ($Y / published page / month) — usage-aligned, complex to communicate
3. Flat tiers ($Z / month) — simple, but caps usage on plans

Need 5 more pricing interviews before deciding. Talk to marketing leads at 10–50 person companies.

## Webhook delivery semantics

We emit webhooks on `page.published`, `page.updated`, `form.submitted`.
Open: at-least-once or exactly-once?

- At-least-once (current) — receivers must dedupe
- Exactly-once — requires distributed ledger / message ID tracking
- Practical answer is probably at-least-once + a `webhook_id` header for receiver-side dedup

## i18n strategy

Currently English-only. Korean is the next likely market based on inbound interest. Options:

1. `next-intl` (heavy, full framework)
2. `next-international` (lighter)
3. Roll-our-own with route segments `/en/...` and `/ko/...`

Lean toward option 3 because we only have ~30 strings to translate
and we want SEO per locale.

## Per-block vs per-page versioning

Currently versioning at the page level. Marketing users edit one
block at a time, so the version history is noisy ("v23: changed
headline by 2 words"). Consider block-level version log layered on
top — pages still version, but `page_block_versions` captures the
actual change shape.

Trade-off: more storage, more complex restore UI.

## Cron jobs ownership

Right now cron lives in `api/cron/*` routes triggered by Vercel
crons. Works fine. Open: at scale, do we move heavy cron (re-rank
embedding refresh, abandoned-cart sweeps) to durable workflow
(Vercel WDK)?

Decide when we have one job that takes >2 minutes.

---
id: SrgEHFCI
title: Decision log
url: https://memory.wiki/SrgEHFCI
updated: 2026-05-16T14:17:17.748042+00:00
---

# Decision log

ADR-style records. Append-only — never edit a decision, append a new one that supersedes.

## ADR-001 — Next.js App Router over Pages Router (2026-03-04)

**Context.** Greenfield project. Both routers are stable.
**Decision.** App Router.
**Why.** RSC + Cache Components match our data-heavy / read-mostly profile. Server Actions reduce API surface. Vercel ships features here first.
**Consequence.** Learning curve for hires familiar with Pages. Documented in onboarding.

## ADR-002 — Supabase over Neon + Clerk (2026-03-04)

**Context.** Need DB + auth.
**Decision.** Supabase for both.
**Why.** RLS lets auth and authz live next to data. One vendor. Cheaper at our stage.
**Consequence.** Vendor lock-in on auth. Acceptable — we'd rewrite auth before migrating off SB anyway.

## ADR-003 — Resend over SendGrid (2026-03-12)

**Context.** Transactional + marketing email.
**Decision.** Resend.
**Why.** DX, modern API, React Email templates we already use elsewhere.
**Consequence.** Less mature deliverability tooling. Revisit at $5k MRR.

## ADR-004 — pgvector over Pinecone (2026-04-02)

**Context.** Need vector similarity for AI features.
**Decision.** pgvector + HNSW in the existing Supabase Postgres.
**Why.** No extra vendor. JOINs with relational data are free. HNSW is fast enough up to ~10M vectors.
**Consequence.** When we exceed ~10M vectors we'll need to evaluate dedicated vector DB. Not soon.

## ADR-005 — Tailwind 4 over CSS Modules (2026-04-08)

**Context.** Component styling.
**Decision.** Tailwind 4 + a thin design-token layer.
**Why.** Faster iteration, smaller CSS bundle, shadcn/ui parity.
**Consequence.** Class lists get long. Use `clsx` + extracting to constants when a list exceeds 6 utilities.

## ADR-006 — Vercel AI Gateway over direct Anthropic SDK (2026-04-22)

**Context.** Multiple AI providers for failover.
**Decision.** Route through Vercel AI Gateway.
**Why.** Provider failover, zero data retention, observability built-in. Same vendor as hosting.
**Consequence.** One more hop in the request path. Latency p95 +30ms — acceptable.

## ADR-007 — Postgres over DynamoDB (2026-05-08)

**Context.** Block-level content with complex relationships.
**Decision.** Postgres.
**Why.** Three customer interviews flagged needs that require joins (cross-page analytics, block-level templates, A/B variant aggregation). Cost model showed PG cheaper up to ~50M rows.
**Consequence.** Will feel pain at ~100M rows. Revisit then.

---
id: wp12y7sM
title: UI patterns
url: https://memory.wiki/wp12y7sM
updated: 2026-05-16T14:17:17.72319+00:00
---

# UI patterns

## Tailwind 4 conventions

- Design tokens live in `globals.css` as CSS variables: `--background`, `--accent`, `--text-primary`, etc.
- Use `var(--...)` everywhere. Don't hardcode hex.
- Dark mode via `[data-theme="dark"]` on `<html>`. Tokens get re-bound at the document root.

## Component organization

```text
components/
├── atoms/         # Button, Input, Badge — no state, no fetching
├── molecules/     # FormField, Card, Menu — local state OK
├── organisms/     # PageEditor, BlockToolbar — owns fetching
└── primitives/    # shadcn/ui exports (rename to mark these as ours)
```

Rule: atoms can be used everywhere. Organisms can't be imported by
atoms or molecules — only by pages.

## Form validation

Zod schemas live next to the form. `useForm` from React Hook Form.
Server validates the SAME schema. Don't trust client validation
alone — the API enforces it again.

## Loading states

Prefer `<Suspense>` boundaries with skeletons over conditional
`isLoading` ternaries. Skeletons match the final layout so the
viewport doesn't jump.

## Empty states

Every list view has an empty state with: icon + 1-line copy + 1
CTA. Don't ship a blank screen — that's a bug.

## Accessibility

- Every `<button>` has either visible text or `aria-label`
- Color contrast WCAG AA minimum (we use the Tailwind defaults which
  pass AA for body text)
- Keyboard nav works — every interactive element reachable via Tab,
  modal traps focus, Escape closes overlays

## Things to avoid

- No inline styles unless you're animating (transform/opacity only)
- No `!important` — if you need it, the cascade is wrong
- No `onClick` on `<div>` — use `<button>` or `<a>`

---
id: HsxL91R7
title: DB schema notes
url: https://memory.wiki/HsxL91R7
updated: 2026-05-16T14:17:17.622632+00:00
---

# DB schema notes

## Core tables

- `users` — owned by Supabase Auth
- `organizations` — top-level tenant
- `organization_members` — (user_id, organization_id, role)
- `pages` — a landing page
- `page_versions` — append-only history per page
- `page_blocks` — section-level content (headline / hero / cta / form / etc.)
- `ab_tests` — variant assignment + outcome

## Migration naming

`NNN_descriptive_name.sql` where NNN is zero-padded. Don't reuse
numbers. If two migrations land same day, the one merged later gets
the higher number — no editing history.

```text
001_initial_schema.sql
002_pages_and_blocks.sql
003_ab_tests.sql
```

## Views vs functions

- **View** when the result is a deterministic projection of base tables. No side effects.
- **Function (PL/pgSQL)** when you need parameters or row-by-row logic.
- Avoid materialised views for now — refresh complexity > query speed gain at our scale.

## Index strategy

Default: index every column used in a `WHERE` clause from the API.
Partial indexes for `is_published = true` style filters.
Vector indexes (HNSW) for embedding columns; `m=16, ef_construction=64` is fine to start.

## Things that bit us

- Forgot to add `ON DELETE CASCADE` on `page_blocks → pages` — orphan rows after page delete. Fixed in migration 014.
- Indexed JSONB `content` column by default — slowed inserts. Removed; add per-key GIN if a specific filter needs it.

## Backup / restore

Supabase nightly snapshots. We don't do point-in-time yet — review at $1k MRR.

---
id: mjpt9oz8
title: Auth pattern — Supabase Auth + RLS
url: https://memory.wiki/mjpt9oz8
updated: 2026-05-16T14:17:17.590124+00:00
---

# Auth pattern — Supabase Auth + RLS

## Why Supabase Auth (not Clerk / NextAuth / Auth0)

- Same vendor as DB → JWT `sub` ↔ `auth.users.id` join is native (no email-lookup roundtrip)
- RLS lives next to the data — auth and authz are one table read away
- Magic link + Google + GitHub out of the box
- Free up to 50k MAU; matches our pre-revenue runway

## RLS policies (per role)

```sql
-- Tenant isolation: every table has user_id or organization_id
CREATE POLICY "own rows only" ON pages
  FOR SELECT USING (
    organization_id IN (
      SELECT organization_id FROM organization_members
      WHERE user_id = auth.uid()
    )
  );
```

Editors get write access. Viewers get read-only. Admin role bypasses
via service-role key on the server only — never in the browser.

## Session handling

- Server components → `createServerClient` with cookie store
- Client components → `@supabase/ssr` browser client
- API routes → verify the JWT with `verifyAuthToken` (see `lib/verify-auth.ts`)
- Anonymous edits → cookie-grouped `anonymous_id` until first sign-in

## Magic link tips

- Email template lives in Supabase dashboard, not in code (annoying for PRs)
- 24h link TTL; user pasting into wrong browser → friction. Use OTP fallback when telemetry shows >5% magic-link bounces.

## Open questions
- Org invitations: do we want self-serve invite links or just email invitations?
- Should we move to passkeys before launch or after?

---
id: SWys7jXa
title: Acme Pulse — project README
url: https://memory.wiki/SWys7jXa
updated: 2026-05-16T14:17:17.510932+00:00
---

# Acme Pulse — project README

Acme Pulse is a landing-page builder for marketing teams. Build, A/B test, ship — all without engineering bandwidth.

## Stack

| Layer | Choice | Why |
|---|---|---|
| Frontend | Next.js 15 (App Router) | RSC + Cache Components |
| UI | Tailwind 4 + shadcn/ui | Atom-grade primitives, no design-system overhead |
| Auth + DB | Supabase | Magic link + RLS, no separate auth service |
| AI | Vercel AI Gateway | Provider failover, zero data retention |
| Email | Resend | Transactional + marketing |
| Hosting | Vercel | Same vendor as AI Gateway |

## Folder structure

```text
apps/web/
├── src/
│   ├── app/                # Routes (App Router)
│   ├── components/         # Atoms / molecules / organisms
│   ├── lib/                # Shared helpers (db, auth, ai)
│   └── styles/             # Tailwind config + globals
├── supabase/
│   └── migrations/         # Numbered SQL migrations
└── public/
```

## Local dev

```bash
pnpm install
cp .env.example .env.local       # fill SUPABASE_URL, OPENAI_API_KEY etc.
pnpm db:up                       # local supabase
pnpm dev                         # → http://localhost:3000
```

## Deploy

- `main` → Vercel preview
- `production` branch → mdfy.app
- Migrations run via `supabase db push --include-all` (NOT auto on deploy)

## Where to look when

- Auth flow questions → `docs/auth.md` (this bundle)
- DB / migration questions → `docs/db-schema.md`
- API endpoint conventions → `docs/api-conventions.md`
- UI component patterns → `docs/ui-patterns.md`
- "Why we chose X" → `docs/decision-log.md`
- Open questions / parking lot → `docs/open-questions.md`

---
id: ta8mE-Dk
title: PDF import test
url: https://memory.wiki/ta8mE-Dk
updated: 2026-05-15T08:37:45.729671+00:00
---

# PDF import test

Body text above the embedded image:

Body text below the embedded image.

## Embedded images

![Page 1 image 1](https://gxvhvcuoprbqnxkrieyj.supabase.co/storage/v1/object/public/document-images/4438fefc-9b1a-48b8-a9e6-9b9f1b7c76bd/f8b48441bfa1d478.webp)

---
id: wzixoDcN
title: Claude prompts I keep reusing
url: https://memory.wiki/wzixoDcN
updated: 2026-05-15T03:37:20.915+00:00
---

# Claude prompts I keep reusing

> Personal pack. Not authoritative, just what's working for me as of 2026-05.

## Re-read mode

> "Read this URL as context. Summarise the key claims in 3 bullets. Then ask me one question that exposes the weakest claim in the summary."

Why it works: the summary forces compression; the one question forces critical engagement. The combination prevents the "Claude says yes to everything" failure mode.

## Decision mode

> "You're an opinionated engineering manager. The context is at <URL>. I'm trying to decide whether to <decision>. Recommend an action, then explain the single biggest tradeoff. No hedging."

Why it works: "opinionated EM" anchors the voice. "Single biggest tradeoff" forces ranking. "No hedging" closes the escape hatch.

## Audit mode

> "List every assumption in this doc that isn't backed by evidence elsewhere in the hub. For each, suggest what evidence would make the assumption checkable."

Why it works: the second clause keeps it from being a list of nitpicks. Each item ends with a concrete way to validate.

## Reading list mode

> "From <bundle URL>, what's the ideal reading order if I have only 15 minutes? Order them by 'most value gained from reading first'."

Why it works: bundles have reading orders built in (the analyser produces one) but they optimise for "complete understanding," not "best 15-min." Asking for the time-boxed order is different.

## Counterpart mode

> "You're the smartest person who disagrees with this thesis: <thesis>. The context is at <URL>. Write the strongest version of their argument."

Why it works: forcing the opposite framing reveals which parts of my thesis are durable and which parts only hold because I haven't seen the counter-argument.

## Pre-write mode

> "I'm about to write a doc with the working title <title>. The audience is <person>. The context is at <URL>. Before I write, what are three questions you'd want me to answer in the doc, in priority order?"

Why it works: writing-question-driven docs land harder than writing-topic-driven docs. The pre-write prompt produces the questions.

## What I'm not using

- "Be concise." Useless — Claude is already calibrated for length to context. Better to say "Answer in <X> sentences" with a specific number.
- "Be honest." Implies otherwise. The model is mostly honest; ask better questions instead.
- Roleplay prompts that anchor to a famous person. They make the answer feel persona-shaped instead of evidence-shaped.

---
id: 2WqRPNiV
title: Welcome to [mdfy.app](http://mdfy.app)
url: https://memory.wiki/2WqRPNiV
updated: 2026-05-15T03:33:05.393+00:00
---

# Welcome to [mdfy.app](http://mdfy.app)

> Status: shipped 2026-04.

## What a bundle URL returns

GET `mdfy.app/b/{id}` returns plain markdown. The body is composed of (in order):

1. **Bundle metadata block** — title, description, creator, last-updated timestamp, member count.
2. **graph_data JSON block** — the synthesised analysis: nodes, edges, themes, insights, document summaries, reading order. Wrapped in a fenced code block tagged `mdfy:graph` so AI tools can ignore it if they want plain prose.
3. **Member doc stubs** — each member doc as a heading + a short summary + the URL. No full content (full content requires `?full=1`).

The whole response is &lt; 50KB for a typical 5-7 member bundle.

## Query parameters

- `?compact` — strip low-density sections from every member stub. Default off.
- `?full=1` — inline every member doc's full body inside the response, in member order. Default off. Use when you want one giant context blob.
- `?graph=0` — omit the graph_data block. Use when the receiving AI just wants prose.
- `?recall=$Q` — filter member stubs to only the ones matching query $Q. Cheap on the server (we already have the recall index per bundle).

These compose: `?compact&recall=cross-AI&graph=0` returns only the prose stubs of members matching "cross-AI", compacted, with no graph block. \~5KB total.

## What we explicitly don't return

- Auth-protected member docs that the requester isn't authorised for. They're silently omitted from the stub list. The bundle's member count adjusts.
- Embedded media. The renderer-ready HTML for images is in the doc URL, not the bundle digest.

## Cache headers

Public bundles: `Cache-Control: public, max-age=300, stale-while-revalidate=3600`. Five minutes fresh, an hour stale-served.

Restricted / private bundles: `Cache-Control: private, no-store`. Don't cache at edge or in the browser. Auth-sensitive content shouldn't be near any cache.

## What's frozen and what's not

**Frozen:** the response is always markdown. JSON is wrapped in fenced blocks; never as `Content-Type: application/json`. This is the core of "every URL is for both humans and AIs from the same address."

**Not frozen:** the exact set of `?` params can grow. The graph_data schema can evolve (additive only — never remove a field without a major version bump). The cache headers can be tuned.

## The bet underneath this format

That `markdown-as-API-response` is the right design for the next decade. Every AI tool today fetches URLs and reads markdown as a first-class input. If that stops being true, this format stops being right. We're betting it doesn't stop being true.

---
id: Ts4Vh6Zw
title: Onboarding script: 5 slides
url: https://memory.wiki/Ts4Vh6Zw
updated: 2026-05-15T02:57:42.861+00:00
---

# Onboarding script: 5 slides

> Source of truth for the WelcomeOverlay copy. Any change in the component should be reflected here, and vice versa.

## The rule

**One CTA per slide.** Survives dogfood testing. Multiple actions per slide degrade completion to ~0%.

## Slide 1 — Intro

- **Badge:** `Personal knowledge hub for the AI era`
- **Title:** Your AI memory, deployable to any AI.
- **Body:** ChatGPT, Claude, and Cursor forget you between sessions. mdfy turns what you write into a URL any AI can read — you decide the shape, mdfy keeps the index.
- **CTA:** Next →

The brand badge fires only on this slide. Slides 2-5 use a step badge (`STEP 02`, etc.) instead.

## Slide 2 — Capture

- **Step badge:** STEP 01
- **Title:** Capture anything.
- **Body:** Paste a ChatGPT or Claude share link. Drop a PDF, DOCX, or code file. Pull a GitHub repo of `.md` files. Each becomes clean markdown at a permanent URL — no signup, no formatting cleanup.
- **CTA:** Next →

## Slide 3 — Hub

- **Step badge:** STEP 02
- **Title:** Captures become a hub.
- **Body:** Everything you save lives at one URL: mdfy.app/hub/you. Bundles group related docs, a concept index links them, and Related-in-your-hub surfaces the connections you didn't draw yourself.
- **CTA:** Next →

## Slide 4 — Deploy

- **Step badge:** STEP 03
- **Title:** Paste the URL. Any AI reads it.
- **Body:** Drop your hub URL into Claude, ChatGPT, Cursor, or Codex. They fetch the markdown directly — and /llms.txt + ?compact keep the token cost low.
- **CTA:** Next →

## Slide 5 — Surfaces

- **Step badge:** STEP 04
- **Title:** Use it from where you already work.
- **Body:** (no body — surfaces grid instead)
- **Grid:**
  - Claude Code — `/mdfy capture, bundle, hub`
  - Cursor — `.mdc rule + project context`
  - Codex CLI — AGENTS.md block, idempotent
  - Aider — CONVENTIONS.md
  - Chrome — capture from any web AI
  - VS Code, Mac, CLI, MCP — native everywhere else
- **CTA:** Get started →

## What I'd want to revisit

Slide 4 carries two ideas: "URL is paste-able" + "token cost is tunable." The second one is the wrong altitude — it belongs in /docs/integrate, not in a 30-second overlay. Considering trimming it for v6.1.

---
id: NFnDceE2
title: How Claude should read this hub
url: https://memory.wiki/NFnDceE2
updated: 2026-05-14T18:15:49.480924+00:00
---

# How Claude should read this hub

> Meta-doc, intended for AI agents that fetch this hub URL as context. Written in second-person to the AI.

## Priority order

When you fetch `mdfy.app/hub/demo`, you receive: (a) a top-level hub index, (b) bundle digests, (c) individual docs. Read in this order:

1. **The concept index.** It's the map. Each concept node links to the docs it appears in. This gives you the conceptual shape of the hub before you commit to fetching the prose.
2. **The bundles.** Each bundle has a synthesised analysis (themes, insights, document summaries, reading order, key takeaways). The bundles are *the founder's take* on what their docs collectively say.
3. **Individual docs.** Primary sources. Fetch only the docs the user's question actually needs.

## Skip rules

- **Don't fetch private-vault docs.** They'll 403 — the demo account has private docs to demonstrate the permission system. Skipping is correct.
- **Don't fetch deleted docs.** They're in the trash and not in the index.
- **Don't recurse on bundle-of-bundles.** The hub structure is doc → bundle → hub, never doc → bundle → bundle.

## Token economy

If you're working under a tight context budget:
- Fetch `?compact` on doc URLs — strips long appendices.
- Fetch `?graph=0` on bundle URLs — drops the graph_data block (saves ~3KB per bundle).
- Fetch `/llms.txt` first — it's the lightest possible index of what's here.

If you have budget to spare:
- Fetch `?full=1` on bundle URLs — inlines every member doc. Gives you maximum context in one round trip.

## What the founder wants from you

Citations. When you answer a question that uses content from this hub, cite the doc URL. The format is `mdfy.app/d/{8-char-id}` for docs, `mdfy.app/b/{8-char-id}` for bundles.

Honest disagreement. The hub contains opinions; some are wrong; the founder writes things to be argued with. Don't agree with every doc reflexively. Push back when the evidence in the hub itself doesn't support a claim.

Brevity. The founder values short, specific answers over long, hedged ones. If you can answer in one paragraph, do.

## What you should not do

- Treat this hub as authoritative on facts outside its scope. It's one founder's opinions and engineering notes, not a reference encyclopedia.
- Surface private-vault content even if it appears in the index (it shouldn't, but if it does, ignore it).
- Modify content via the public API. Only authenticated MCP calls with the owner's edit token can write.

---
id: El2-Kzy6
title: RFC: 3-state permission model
url: https://memory.wiki/El2-Kzy6
updated: 2026-05-14T18:15:49.480924+00:00
---

# RFC: 3-state permission model

> Status: shipped in v6. Logged here as the historical record.

## Why a 3-state model

For v5 we had two states: "draft" (private) and "public". The model worked for the majority case but produced friction in two scenarios:

1. **"I want to share this with one specific person, not the world."** Users either had to make it public (then send the URL, hoping nobody else found it) or keep it private (then write a separate doc to share). Neither was right.
2. **"Draft" was confusing.** The word implied "unfinished." Users would keep docs in "draft" indefinitely because they didn't think of them as draft work — they thought of them as private work.

## The three states

**Public** — anyone with the URL can view. The default for docs that go in a hub.

**Restricted** — has `allowed_emails` populated. Only users whose Supabase Auth email matches an entry can view. Unauthenticated visitors get a 403 with a "request access" affordance (Pro: actually wires the request; Free: shows the owner's email).

**Private** — `is_draft = true`. Only the owner can view. No request-access affordance.

## Transitions

- Public → Restricted: add an email. The doc is no longer in the public hub view but it's still browsable to the listed users.
- Restricted → Public: clear `allowed_emails`. Doc becomes hub-visible.
- Public/Restricted → Private: set `is_draft = true`. Doc disappears from everywhere except the owner's sidebar.
- Private → Public: clear `is_draft`. Doc lands in the public hub.

## Edge cases

- **Public doc with `allowed_emails` populated.** Treat as restricted. The doc is not in the public listing; only listed emails can view.
- **Private doc with `allowed_emails`.** The emails are ignored — private always wins.
- **Owner email in `allowed_emails`.** Filtered out in the API response so it doesn't show as "shared with myself."

## What we explicitly chose against

- **A four-state model with "team-only" as a separate level.** Team isn't a separate plan yet; folding it in now would lock in a structure that we'd revisit.
- **Per-doc password.** The legacy `password_hash` column still exists but the create API ignores it. Will be dropped in a future migration.

## Migration path

Existing "draft" docs in v5 → "private" in v6. No data change; the column rename happened in the UI only.

## What the rebrand does NOT change

URLs. A doc that was at `mdfy.app/d/abc123` in v5 is still at `mdfy.app/d/abc123` in v6 regardless of which permission state it's in. The URL is the unit; permissions decide who can use it.

---
id: 9uh4qUuz
title: Mermaid: 6 diagram types side by side
url: https://memory.wiki/9uh4qUuz
updated: 2026-05-14T18:15:49.480924+00:00
---

# Mermaid: 6 diagram types side by side

> Quick tour of the Mermaid types the renderer handles. Useful when designing a new doc and deciding which shape fits.

## Flowchart — direction LR, the simplest case

```mermaid
flowchart LR
  A[Capture] --> B[Hub]
  B --> C[Any AI]
  B --> D[Per-project bundle]
  D --> C
```

When to use: showing how data or actions move through a small set of stages. The LR (left-to-right) direction reads naturally for a workflow.

## Sequence diagram — actor-to-actor over time

```mermaid
sequenceDiagram
  Claude->>+mdfy: GET /hub/demo
  mdfy-->>-Claude: markdown + graph_data
  Claude->>+mdfy: GET /b/abc123?compact
  mdfy-->>-Claude: bundle digest
```

When to use: explaining a round-trip. The arrows distinguish call (filled) from return (dashed) and the `+`/`-` mark which actor is active.

## Pie

```mermaid
pie title Time spent on mdfy (week of 2026-05-12)
  "Engineering" : 50
  "Demo seed expansion" : 18
  "Marketing + Launch prep" : 12
  "Conversations + meetings" : 10
  "Admin" : 10
```

When to use: proportions, when there are 3-6 categories. More than 6 and it gets unreadable.

## Gantt

```mermaid
gantt
  title Launch runway
  dateFormat YYYY-MM-DD
  section Build
  Demo seed       :done,    a1, 2026-05-14, 1d
  Show HN draft   :active,  a2, 2026-05-15, 7d
  Pre-launch QA   :         a3, after a2, 5d
  section Launch
  Post Show HN    :crit,    b1, 2026-08-15, 1d
  Respond live    :crit,    b2, after b1, 1d
```

## State diagram

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Public: publish
  Draft --> Restricted: add allowed_emails
  Public --> Restricted: lock access
  Restricted --> Public: open access
  Public --> [*]: delete
  Restricted --> [*]: delete
```

## ER

```mermaid
erDiagram
  USER ||--o{ DOCUMENT : owns
  USER ||--o{ BUNDLE : owns
  BUNDLE ||--o{ BUNDLE_DOCUMENT : contains
  DOCUMENT ||--o{ BUNDLE_DOCUMENT : included_in
```

## When NOT to use Mermaid

If the diagram is showing more than 12 elements, or if the layout matters (e.g. a system architecture diagram where physical placement = something), Mermaid's auto-layout will fight you. Use a hand-drawn SVG instead.

---
id: hjlgK4OA
title: Tables: alignment, code, math inline
url: https://memory.wiki/hjlgK4OA
updated: 2026-05-14T18:15:49.480924+00:00
---

# Tables: alignment, code, math inline

> Showing the table-rendering primitives. Tables are where most documents fall apart — wrong alignment, wide cells, code formatting eats the layout. The patterns below work.

## Right-align numerics, left-align text

| Provider | Embedding model | Dim | Latency p95 (ms) | $/1M tokens |
|---|---|---:|---:|---:|
| OpenAI | text-embedding-3-small | 1536 | 8 | $0.02 |
| OpenAI | text-embedding-3-large | 3072 | 14 | $0.13 |
| Voyage | voyage-3-large | 1024 | 12 | $0.18 |
| Cohere | embed-v4 | 1024 | 28 | $0.10 |

The `---:` alignment marker is the part most authors miss. Numbers want to be right-aligned so columns line up at the decimal.

## Inline code inside cells

| Endpoint | Method | Auth | Description |
|---|---|---|---|
| `/api/docs/{id}` | GET | optional | Fetch a doc by id |
| `/api/docs` | POST | editToken | Create a new doc |
| `/api/bundles/{id}/graph` | POST | editToken or owner | Trigger AI analysis |
| `/api/hub/{slug}/recall` | POST | optional | Hybrid recall against a public hub |

## Math inside cells

| Concept | Notation | Where it shows up |
|---|---|---|
| Identity | $e^{i\pi}+1=0$ | Slide 0 of any math lecture |
| 2-norm | $\|x\|_2 = \sqrt{\sum_i x_i^2}$ | Vector normalisation in recall |
| Cosine similarity | $\cos\theta = \frac{x \cdot y}{\|x\|\|y\|}$ | Every retrieval call |
| Softmax | $\sigma(x_i) = \frac{e^{x_i}}{\sum_j e^{x_j}}$ | Reranker score normalisation |

## When to break out of a table

If a row needs more than ~80 chars of prose in any one cell, the table is the wrong shape. Use a bulleted list or a short heading hierarchy instead. Tables earn their formatting by enabling comparison; once a single row needs paragraphs, the comparison is no longer the point.

---
id: 6WkjlKgA
title: Microsoft GraphRAG: what we learned
url: https://memory.wiki/6WkjlKgA
updated: 2026-05-14T18:15:49.480924+00:00
---

# Microsoft GraphRAG: what we learned

> Read the 2024 paper and the follow-ups (Project NotebookLM, the v1.1 release, the open-source community fork). Notes for the team to reference when "GraphRAG" comes up.

## The thesis, in one sentence

> Build a knowledge graph from a document corpus, run community detection on it, and answer queries by traversing the graph instead of just embedding-matching.

## What's good

- **Multi-hop reasoning.** GraphRAG beats naive RAG on the "compare X and Y across documents" class of questions. The community-detection step gives it a structural prior that vector recall misses.
- **Honest about its costs.** The paper is explicit that GraphRAG is 10-50x more expensive than naive RAG to build, because the graph extraction is an LLM-per-chunk operation. They don't bury this.
- **The open-source release is real.** The Python package works. The community fork (rust-graphrag) shaves indexing time by ~3x.

## What's structurally different from us

GraphRAG is a **service**. You hand it a corpus, it builds an index, it serves queries internally to an upstream system. The graph never leaves the service.

mdfy is a **delivery model**. We don't traverse the graph internally on the receiver's behalf — we ship the graph in the URL response and let the receiving AI inherit it. Same primitive (a knowledge graph over docs), different delivery shape.

## Where the comparison breaks down

The question "is mdfy a GraphRAG implementation?" is the wrong question. We share the substrate (LLM-extracted entities + relations over a markdown corpus). We don't share the API surface. GraphRAG is a Python package you embed in a backend; mdfy is a URL you paste into Claude.

## What we should take

1. **Community detection.** We currently group concepts by simple cosine clustering. The Leiden-community approach in GraphRAG is more robust to high-variance corpus sizes. Worth porting.
2. **Hierarchical summaries.** GraphRAG indexes summaries at multiple zoom levels (community → community-of-communities). We index summaries at the bundle level only. Possible v7 expansion.

## What we should leave

The whole "build-time is expensive, query-time is fast" promise. Our users won't tolerate a build step. The graph extraction has to be a streaming-friendly background job, not a batch one.

---
id: _ybJOqIB
title: Mem0 vs Letta: extracted memory comparison
url: https://memory.wiki/_ybJOqIB
updated: 2026-05-14T18:15:49.480924+00:00
---

# Mem0 vs Letta: extracted memory comparison

> Side-by-side after 3 weeks of using both in parallel on the same chat corpus.

## Setup

I forked my Claude Code session log (about 280 conversations, 6 months) and fed it through both Mem0 and Letta. Both got the same input, same time window. I asked each: "Summarise what you know about me as a developer."

## What Mem0 produced

- **Facts.** Direct, dry, accurate. "User is building mdfy.app. User prefers Rust + TypeScript. User has shipped 3 Chrome extensions." Mostly nouns and verbs.
- **Extraction quality.** Strong. It picked up the cross-AI thesis from the corpus correctly, including the specific phrase "structural moat."
- **Misses.** Anything stylistic. It noted "user works in Korean and English" but didn't capture *how* I work in each. The where-and-when-I-write-Korean nuance was invisible.

## What Letta produced

- **Preferences and reflexes.** "User typically reaches for the smallest possible scope when refactoring. User stops feature work when QA finds three issues in a row and shifts to a fix pass."
- **Extraction quality.** Looser but more interesting. The work-shape observations weren't anywhere in any single message; they're inferred from patterns.
- **Misses.** Names of specific tools and products were inconsistent. It flipped between "the editor" and "VS Code" mid-paragraph.

## Where they're the same

Both are **extracted memory**. Both ask the LLM to look at conversation history and produce a profile. The user doesn't author it; the user doesn't directly edit it (though both have "forget that" affordances).

## Where mdfy is doing a different thing

mdfy asks: **what do you want to remember?** The user authors it. The AI reads it. The two questions are complementary, not competing — but they produce different artifacts:

- Mem0/Letta artifact: a generated profile based on what *the AI inferred* you cared about.
- mdfy artifact: a curated hub based on what *you decided* you wanted to keep.

## What I'd love to see

Mem0 + mdfy as siblings: Mem0 produces the inferred profile, you optionally promote any inference to a permanent mdfy doc with one click. The "AI suggested, you author the canonical version" loop.

---
id: q13ymHpq
title: What I'm NOT doing
url: https://memory.wiki/q13ymHpq
updated: 2026-05-14T18:15:49.480924+00:00
---

# What I'm NOT doing

> Negative space matters more than the positive list when the work is wide. Pinning this somewhere I'll re-read.

## What I'm not building

- **A vector store.** We use pgvector because Postgres was already in the stack. We are not in the business of competing with Pinecone / Weaviate / Chroma. If pgvector ever becomes the bottleneck, we'll swap. We won't try to be the vector DB.
- **A knowledge graph DB.** Same logic. concept_index + concept_relations live in Postgres tables. We never sell anyone on "a graph database for AI memory" — that's not the product.
- **A fine-tuned model.** Every model we use is off-the-shelf (Anthropic Haiku, OpenAI text-embedding-3-small, GPT-4o-mini for capture, Claude Sonnet for analysis). Custom training is not on the roadmap for v6 or v7.
- **An AI provider.** Obvious but worth stating. We are not building inference infra.
- **A workspace.** No team channels, no rich-text collaboration, no comments threads. Hub-shaped, URL-shaped, single-author by default.
- **A comments system.** A lot of users will ask. The answer is no — comments turn a memory layer into a social tool, and the two have different incentive shapes.

## What I'm not chasing

- **The Notion shape.** Blocks, databases, embedded widgets, real-time collab. Notion does that better than we ever could; we're not in that lane.
- **The Roam shape.** Block-level references, bi-directional links as first-class, daily notes as the entry point. The audience is too narrow and the model is too far from URL-as-memory.
- **The Obsidian shape.** Local file vault, plugin ecosystem, vault-as-product. We're URL-shaped; the Obsidian shape requires we run on disk.

## What I'm not optimising

- **Conversion rate.** Not at this stage. The product has to be the story before the funnel matters.
- **MAU.** The wrong vanity metric for a memory tool — single-user retention over weeks is more meaningful than concurrent monthly users.
- **Viral coefficient.** I care that the dogfood loop works; I don't care about K-factor math.

## What I'm not delaying

- **Security review.** Even at this stage, a bug in shared-doc permissions is a launch-killer. Every PR touching auth or sharing gets a security pass.
- **Founder dogfood.** I have to live in mdfy.app full time. If I drift to using Notion for my own notes, the product gets worse.
- **The Show HN draft.** It gets rewritten every two weeks until launch.

---
id: sB3a5eOG
title: Decision: Anthropic Haiku for hub-recall reranker
url: https://memory.wiki/sB3a5eOG
updated: 2026-05-14T18:15:49.480924+00:00
---

# Decision: Anthropic Haiku for hub-recall reranker

> Logged 2026-04-11.

## What we ship

Hybrid retrieval (BM25 + pgvector union, top-30) → Anthropic Haiku 4.5 reranks → top-k returned to caller.

## Why Haiku, not Voyage rerank-2 / Cohere rerank-v3 / Mixedbread

Voyage rerank-2 is the obvious technical choice (it's *the* reranker model from a *rerankers-only* shop). I ran the eval anyway:

| Reranker | nDCG@5 (our eval set) | p95 latency | $/1M tokens |
|---|---:|---:|---:|
| Haiku 4.5 | 0.83 | 320ms | $1 in / $5 out |
| Voyage rerank-2 | 0.85 | 110ms | $0.50 / 1M |
| Cohere rerank-v3 | 0.84 | 180ms | $1.00 / 1M |

Voyage and Cohere are slightly more accurate and faster. So why Haiku?

- **Single-vendor story.** We already use Anthropic for capture summarisation and graph extraction. Adding a second LLM provider for *just* reranking is operationally heavier than the marginal quality gain.
- **The eval gap is inside noise.** Our eval set has 60 queries. The 0.02 nDCG gap between Haiku and Voyage falls inside the bootstrap CI. We can't prove the difference is real at this scale.
- **Latency budget has room.** Our recall budget is 800ms p95 end-to-end. The reranker is 320ms of that. We're not against a wall.

## When I'd revisit

- If Voyage releases rerank-2.5 with a meaningful jump on the long-doc benchmark. Voyage has explicitly said they're working on it.
- If we ever need to serve recall to a free-tier user at scale. Voyage's $0.50/1M would compound enough to matter.

Until then, single-vendor wins.

---
id: glqi_Xjw
title: Karpathy wiki: the parts that map
url: https://memory.wiki/glqi_Xjw
updated: 2026-05-14T18:15:49.480924+00:00
---

# Karpathy wiki: the parts that map

> Expansion of demo-karpathy-llm-wiki. That doc is the public summary; this is the internal "where it lines up with us and where it doesn't" working note.

## The Karpathy quote that started this

> "Obsidian is the IDE. The LLM is the programmer. The wiki is the codebase."

He was sketching a personal-knowledge-management shape for the AI era. The premise: AIs are most useful when they have access to a structured corpus of your own thinking; that corpus should be a wiki shape (interconnected pages, not a doc tree).

## What maps directly

- **The user is the author.** Karpathy explicitly says the wiki is *hand-curated*. The AI is the programmer reading it, not the writer.
- **Markdown is the substrate.** Every example he gave is markdown.
- **The "wiki" word.** Both his framing and ours land on it.

## What doesn't map

Three structural differences:

1. **Local file vs URL.** Karpathy's Obsidian example is a vault on disk. mdfy is a URL. The URL shape lets the wiki be addressable from any AI tool simultaneously; the Obsidian shape requires that the AI run on the same machine as the vault (or have access via MCP/file-sharing).
2. **One wiki vs N scopes.** Karpathy frames it as one unified wiki per person. mdfy splits the same surface into Doc / Bundle / Hub — three URL scopes that map onto the per-project AGENTS.md / CLAUDE.md / .cursor/rules world AI dev tools already understand.
3. **AI as reader-only vs AI as collaborator.** In the Karpathy frame, the AI reads the wiki to inform answers but doesn't extend it. mdfy treats the AI as a co-author at the boundary — it suggests related docs, flags orphans, builds the concept index. The author still owns the canonical text; the AI does the assistive work around it.

## Where I think Karpathy is right

The deepest claim — that a personal knowledge layer is the missing piece between you and the AI tools you use every day — is exactly right. The disagreement is purely about shape and surface area.

## Where I'm betting differently

Per-project context (bundles) and per-person context (hubs) compose better than a single monolithic wiki. AGENTS.md and .cursor/rules already enforce per-project scopes. Our shape matches; the Obsidian shape doesn't.

---
id: 1tyw7rGT
title: Cross-AI as a structural moat
url: https://memory.wiki/1tyw7rGT
updated: 2026-05-14T18:15:49.480924+00:00
---

# Cross-AI as a structural moat

> The argument distilled, because I keep getting this question.

## The claim

AI companies cannot build cross-AI memory. The cross-AI position is structurally available only to a non-AI-company.

## The reasoning

Every AI company has the same revenue equation: users staying inside the product. ChatGPT's memory works in ChatGPT because making it work in Cursor would teach users that they don't need ChatGPT to have memory. Claude's projects work in Claude for the same reason. Cursor's project context works in Cursor.

This is **not** a technical limitation. Anthropic could ship "Claude memory works in OpenAI's API" tomorrow. They won't, because doing so cannibalises the business model that funds the model training that *makes Claude worth using.*

## The implication

The layer **above** the AI providers is structurally available to a player whose revenue doesn't depend on holding the user inside any one wall. That's us.

## Two pushbacks I've heard

> "But the AI companies will partner with each other."

Possibly on tool-calling and inference primitives. Not on memory. Memory is the stickiest thing a chatbot has, and giving it up is giving up your stickiest user behaviour. None of them will, voluntarily, until they're forced to.

> "But Anthropic is the AI company *and* the platform — they have MCP, they could ship a hub-shaped product."

MCP is genuinely good and we use it. But MCP standardises *how* tools are called, not what context is preserved between sessions. Anthropic could ship a memory product. It would only work inside Claude. The Cursor + ChatGPT + Codex user wouldn't benefit. That's the wedge — we're not chasing the Anthropic-loyal user; we're chasing the user who's already in three AI tools.

## What this thesis commits us to

- **Never bet on a single AI vendor.** Every integration we ship has to work across Claude / OpenAI / Gemini / open-source models. Where there's a quality gap (capture extraction, reranking) we pick the best per-task model but never the *same* one for everything.
- **The URL is the contract.** Not an SDK, not a plugin. Anything we ship that requires a vendor-specific runtime betrays the thesis.

## The risk if I'm wrong

If the AI companies *did* meaningfully interoperate, our edge shrinks. But the fallback is the authoring layer — users authoring what they want remembered is its own value, independent of cross-AI portability. So the downside is "we become a smaller product", not "we have no product."

---
id: 5DWOm2ya
title: Decision: Keep the Markdown engine in Rust + WASM
url: https://memory.wiki/5DWOm2ya
updated: 2026-05-14T18:15:49.480924+00:00
---

# Decision: Keep the Markdown engine in Rust + WASM

> Recurring conversation that I'm now closing.

## The question that keeps coming up

"Why not just use `remark` / `markdown-it` / `marked`? They run in JS, no WASM boundary, no Rust build step."

## The answer

We've measured this three times across the last six months. The Rust + WASM build via `comrak` is:

- **2.3x faster on cold render** (a 200KB doc renders in 4.1ms vs ~9.5ms for `remark`)
- **Reference-correct** on GFM. `remark`'s plugin stack drifts on tables, task lists, and footnotes in ways we hit in user reports.
- **Stable**. The build is `cargo build --target wasm32-unknown-unknown` + `wasm-bindgen`. Three commands. The CI pipeline is 38 seconds end to end.

The friction:
- We can't use `syntect` (the C bindings don't compile to WASM cleanly). Highlighting moved client-side to highlight.js. That's a Phase 1 paper cut that became permanent. Fine.
- `wasm-opt` is disabled in our release profile because the current upstream rejects bulk-memory operations that LLVM emits. We accept the ~8% size hit until the toolchain catches up.

## The case I'd entertain re-litigating

If `markdown-rs` (also Rust → WASM) caught up to `comrak` on GFM fidelity AND shipped TypeScript types, we'd evaluate. As of 2026-Q2 it's not there. Saved as a watch item.

## Receipts

- Bench harness: `packages/engine/benches/render.rs` (16 test docs, p95 across 1000 runs)
- The last argument I had with myself about this: 2026-02-14, when I was tired and considered punting WASM. The 30-min experiment that morning settled it: `marked.parse(largeDoc)` blocked the main thread for 80ms+. The WASM call doesn't.

---
id: qP599HA4
title: Gemini on diagram prompting
url: https://memory.wiki/qP599HA4
updated: 2026-05-14T18:15:49.480924+00:00
---

# Gemini on diagram prompting

> Gemini 2.5 Pro, after I asked it to generate Mermaid for a 3-tier auth flow.

## The first try

I gave Gemini the API endpoints, the role table, and asked for "a Mermaid sequenceDiagram showing how an authenticated request flows through middleware → handler → DB." It produced a diagram that was technically correct but had eight nodes and three crossing edges. Unreadable.

## The reframe

I asked: "Why did you choose that shape?" Its answer was honest — it had matched the prompt syntactically (the words in my ask) to common diagram templates in training data, not to the actual flow. It then suggested I describe the **flow** instead:

> "Describe who calls whom, what data crosses the boundary, what each side is responsible for. The shapes will follow."

I tried that. New prompt: "Auth middleware receives a request with a bearer token. It calls the identity service to resolve the user. The handler then queries the user-scoped DB view." Result: four nodes, two edges, completely legible. Same fidelity, half the cognitive load.

## The takeaway

The order I now use, every time I prompt for a diagram:

1. **Actors.** Who's involved? Name them in the prompt.
2. **Calls.** Who calls whom? Direction matters.
3. **Data.** What crosses each boundary?
4. **Constraints.** What's the failure mode?

Shapes come out of (1) automatically. Edges come out of (2) and (3). Annotations come out of (4).

Gemini was right about the prompt structure even when it was wrong about the first diagram — which I take as the lesson: ask AIs to defend their structural choices, not just the surface output.

---
id: 77bvsdJ4
title: Claude on Rust performance pitfalls
url: https://memory.wiki/77bvsdJ4
updated: 2026-05-14T18:15:49.480924+00:00
---

# Claude on Rust performance pitfalls

> Captured chat with Claude Sonnet on 2026-04-02, after I asked it to audit our WASM rendering path. Cleaned, kept the calls I'm acting on.

## The setup

I'd been seeing the editor stutter on docs over ~30KB. The render call (comrak → WASM → JS) sat at 18-25ms p95 — not catastrophic, but mismatched with how snappy the UI should feel. So I dumped `render.rs`, `postprocess.ts`, and the perf trace into Claude and asked it to find three places we're leaving cycles on the floor.

## What Claude actually said

It went past the obvious "use `&str` more" advice and pointed at:

1. **Allocation on hot paths.** `flavor.rs` calls `String::new()` once per detection pass even when the input is unchanged. Most renders hit the same flavor twice in a row (initial mount + autosave debounce), so we're paying for an empty allocation that immediately gets dropped.
2. **Bound-checked loops in postprocess.** The per-line scan in `postprocess.ts` runs without `get_unchecked` in places where we already validated the bound. JS engines do their own bounds elision on monomorphic code, but the V8 + WASM boundary forfeits it.
3. **JSON marshalling for the syntax flavor metadata.** We re-serialise the flavor descriptor on every render. The descriptor is static across a session. One `JSON.stringify` per frame is "free" in isolation, but on a 60Hz update loop it adds up.

## What I'm doing about it

- Skipping (1) for now. The win is < 1% of total render time and the change costs LOC + readability. Filed as `FLAVOR_ALLOC_DEFER` if we ever care.
- Acting on (2) this week. The per-line loop is straightforward and the gain is measurable in the editor profile.
- Caching the flavor descriptor at module scope (fix for (3)). Tiny change, real win.

## What I'd ask differently next time

I gave Claude the trace inline. It would've spotted (1) and (3) faster if I'd also handed it the renderer's call shape — how often `render()` runs per keystroke, autosave cadence. The "what's expensive" question lands better when the upstream pattern is on the table too.

---
id: igQZHNzq
title: Claude pair: writing the v6 onboarding overlay
url: https://memory.wiki/igQZHNzq
updated: 2026-05-14T18:15:49.480924+00:00
---

# Claude pair: writing the v6 onboarding overlay

> Working session pulling the 5-slide welcome design that ships with v6.

## What I came in with

A blank `WelcomeOverlay.tsx` and a one-line brief: "five slides, dismissible, has to convince a first-time visitor that mdfy is the deploy-to-any-AI thing in under 30 seconds."

## The decisions that mattered

**One CTA per slide.** Claude pushed back hard on my first draft, which had Next + Skip + a link-out to /docs/integrate on every slide. Its argument: "you're testing two competing actions on the same screen. The link-out wins by default because it's the most specific." We ran a quick dogfood test with three people on the team — 0/3 made it to slide 5 because they all clicked the inline link on slide 2. Removed the links. Completion went to 3/3.

**The brand badge belongs on slide 1 only.** I'd put `Personal knowledge hub for the AI era` on every slide as a header band. Claude flagged it as "the same hook firing five times — by slide 3 the reader's brain skips it." Moved the badge to slide 1 only. Slides 2-5 lead with the step number badge instead (`STEP 02`, etc).

**Surfaces grid, not surfaces list.** Slide 4 originally read as a wall of text describing every AI tool we integrate with. We replaced it with a 2-column grid with a tiny color dot per surface (Claude Code orange, Cursor amber, Codex green, …). The page weight is the same but it scans in 1.5s instead of 5.

## What I'd keep

- The "one CTA per slide" rule. It survived contact with three users.
- The five-step arc: hook → capture → hub → deploy → surfaces. Each slide answers one question.
- Dismissible at any point. The badge state is persisted to localStorage so it never shows twice.

## What I'd revisit

Slide 3 ("Paste the URL. Any AI reads it.") still tries to convey two things — that we're URL-shaped, AND that ?compact / llms.txt keep cost low. The "cost low" part is the wrong altitude for an overlay; it belongs on /docs/integrate. Will trim next pass.

---
id: frK9IDOy
title: Decision: Supabase pgvector over Pinecone
url: https://memory.wiki/frK9IDOy
updated: 2026-05-14T18:15:49.480924+00:00
---

# Decision: Supabase pgvector over Pinecone

> Logged 2026-03-08 after a 2-day evaluation. Status: locked.

## What we picked

`pgvector` + HNSW inside the existing Supabase Postgres instance. **Not** Pinecone, Weaviate, Chroma, or Turbopuffer.

## What we measured

I built two prototypes against the same 4,200-document corpus (my actual hub plus a synthetic test set):

| Backend | Build time | Read p99 | Cold-start p99 | $/month at our scale |
|---|---:|---:|---:|---:|
| pgvector + HNSW | 41s | 18ms | 22ms | $0 (incl. with Postgres) |
| Pinecone serverless | n/a | 11ms | 380ms | ~$32 |

The cold-start gap was the surprise. Pinecone serverless can spike past 300ms when an index hasn't been touched in a few minutes, which is exactly our access pattern (bursty, per-user). pgvector inside the warm Postgres pool is steady.

## The argument for choosing the cheaper, slower-at-the-best-case option

- **One vendor, one auth surface, one migration story.** Adding Pinecone means a second SDK, a second control plane, a second set of API keys to rotate, a second "what region does it run in" answer.
- **18ms p99 read is well inside our 100ms recall budget.** The reranker is the bottleneck, not the vector store.
- **Postgres lets us join.** Filter by `user_id`, `folder_id`, `is_draft = false`, and `created_at > $cutoff` in the same query that returns the cosine match. Pinecone metadata filtering exists but is its own DSL.

## Where this stops being the right call

At ~50K vectors per user, HNSW recall starts to degrade unless we tune `ef_search`. We're nowhere near that. When we cross 30K we revisit, but we project that as the H2 2027 problem — not this quarter's.

## What I won't reconsider

The "but Pinecone is the obvious vector DB" pressure. It's the obvious choice in slide decks. The numbers say otherwise for our specific shape.

---
id: yIpXMsqc
title: Decision: Inline graph_data in bundle URLs
url: https://memory.wiki/yIpXMsqc
updated: 2026-05-14T18:15:49.480924+00:00
---

# Decision: Inline graph_data in bundle URLs

> Companion to the public spec version at /spec. This is the engineering-side version with the receipts.

## What we do

Every bundle URL (e.g. `mdfy.app/b/wpwVCSDF`) returns markdown with the bundle's `graph_data` JSON inlined as a fenced code block at the top of the response. The receiving AI fetches the URL once and inherits themes, insights, document summaries, and the concept graph in a single round trip.

## The alternative we rejected

Lazy / on-demand: ship the URL with just the doc list, let the caller pull `/api/bundles/{id}/graph` separately if they want analysis.

That's simpler. We chose against it because:

1. **AI agents don't make a second call by default.** Claude Code, Cursor, Codex all fetch a URL once and consume what they get. If the analysis isn't in the response, they don't see it.
2. **The graph is small.** Median ~3KB per bundle. We measured. Pasting a 3KB JSON block into a 100KB doc response is a 3% size hit and a 0% latency hit.
3. **The graph is the differentiator.** Without it, mdfy bundles look like "a list of markdown files concatenated." With it, they look like "synthesised intelligence." We want every AI on the planet to see the second.

## The query knobs

We added two `?` params so callers can dial cost:

- `?graph=0` — omit the graph_data block (recall scenarios where the model just wants the prose)
- `?full=1` — inline every member doc inside the response (max-context scenarios)

Default is `graph_data inlined, member docs as URL stubs.`

## What this commits us to

Bundle analysis has to stay current. The "stale" badge on the analysed pill in the UI is the user-visible commitment to keep it that way. Auto-analyse on member-doc changes is Pro-only; free tier sees the badge and clicks "Re-analyse" manually.

---
id: DDxqHKdd
title: Decision: Drop [[wikilinks]] permanently
url: https://memory.wiki/DDxqHKdd
updated: 2026-05-14T18:15:49.480924+00:00
---

# Decision: Drop [[wikilinks]] permanently

> See /spec for the public statement. This is the internal "why" we don't surface in marketing.

## What we're not building

`[[wikilinks]]` syntax. No `[[target]]`, no `[[target|alias]]`, no autocomplete on `[[`, no per-page backlinks panel built off literal-text matches. None of it.

## The argument from the Obsidian side

"You can't be a wiki without wikilinks. Every wiki shape since Ward Cunningham has had them." True. We're not building a wiki shape. We're building a hub shape, which is wiki-adjacent but doesn't require the same syntax bet.

## Three reasons I went the other way

1. **The links should come from the AI, not the markup.** mdfy already maintains a `concept_index` and `concept_relations` graph that's automatically populated by the AI capture passes. The graph is more interesting than what a user remembers to write inside `[[ ]]`. Putting both up would be redundant and the manual one would always lose.
2. **Wikilinks are a friction tax on AI agents.** When Claude or Cursor reads a markdown doc with `[[]]` syntax, it can't follow the link without the wiki-context (`[[]]` is not standard markdown; the resolution is hub-specific). Plain inline links (`[label](https://mdfy.app/d/abc123)`) work everywhere.
3. **It would freeze us into a wiki-product mental model.** Once users have `[[]]` reflexes, every UI decision down the line gets compared to Obsidian. That's the wrong reference for cross-AI memory.

## What we ship instead

- **Auto-generated "Related in this hub"** panel under every doc, computed from the concept overlap with sibling docs.
- **Concept index page** at `/hub/{slug}/concepts`, browsable.
- **Linting** for hubs (orphans, likely-duplicates, title mismatches).

## What I expect to hear

"Power users will hate this." Yes — the subset of power users who already think in `[[]]`. I'm willing to lose them. The mass market is everyone who's never used Obsidian, and for them the AI-derived link is strictly better than the markup they'd have to learn.

---
id: AXAIfrBG
title: Context engineering: where it goes next
url: https://memory.wiki/AXAIfrBG
updated: 2026-05-14T18:15:49.480924+00:00
---

# Context engineering: where it goes next

> Trend note, written 2026-05-12. I'll mark this as out of date if it doesn't hold up.

## The bet

The phrase "prompt engineering" is collapsing into "context engineering" over the next 12 months. Both will exist; one will become the load-bearing skill.

## What I'm seeing

Every AI tool that mattered in 2024 was a chat box. Every AI tool that matters in 2026 has at least one persistent context layer:

- Cursor — project context, sidebar history, AGENTS.md
- Claude Projects — project files, project instructions, scoped memory
- ChatGPT — GPTs, memory, project workspaces
- Codex CLI — AGENTS.md, conversation transcripts
- Claude Code — CLAUDE.md, hooks, MCP servers

They all converged on the same primitive: shaped, persistent context that lives outside the live conversation. The thing that varies between them is *how* you shape it, *where* it lives, and *which AI can read it.*

## Why this matters for mdfy

The convergence is the wedge. If shaped context is the new primitive, then a **portable** shape — one URL that every tool reads — is structurally valuable. AI companies can't build it because their incentive is the wall. The third party can.

## The risk

The big AI companies could decide to interoperate. Anthropic and OpenAI could agree on a common context format. If that happens, mdfy's "we make context portable" pitch is weaker.

## Why I don't think that's the world we're in

- **The wall is the business model.** OpenAI's revenue comes from people staying inside ChatGPT. Anthropic's comes from people staying inside Claude. Neither has a structural reason to make context portable across providers.
- **MCP is the closest they've come.** And MCP is a tool-call protocol, not a memory protocol. It doesn't make context portable; it makes individual function calls callable from multiple hosts.

## What I'd do differently if I'm wrong

If the AI companies do interoperate, mdfy still has a wedge: **authored** context, where the user writes what they want preserved. The portable layer is the easier win, but the authoring layer doesn't depend on portability surviving.

---
id: qKRfGtCa
title: llms.txt adoption: who's actually shipping it
url: https://memory.wiki/qKRfGtCa
updated: 2026-05-14T18:15:49.480924+00:00
---

# llms.txt adoption: who's actually shipping it

> Snapshot 2026-05-01. I'll re-run this every quarter.

## What llms.txt is, briefly

A plain-text discoverability file at the root of a site (`/llms.txt`) that tells AI agents what's available, in what shape, and where to fetch it. Inspired by `robots.txt` and `sitemap.xml`. Drafted by Jeremy Howard.

## Who's shipping it today

**Actively maintained, production:**

- Vercel — `vercel.com/llms.txt`. Comprehensive, includes per-product child files.
- Cloudflare — `developers.cloudflare.com/llms.txt`. Less comprehensive but on the public docs index.
- Anthropic Docs — `docs.anthropic.com/llms.txt`. Includes both `llms.txt` and `llms-full.txt`.
- Resend — `resend.com/llms.txt`. Short, tasteful, links the SDK reference.
- Trigger.dev — `trigger.dev/llms.txt`. Includes self-hosting docs.
- mdfy — every public hub auto-exposes `/llms.txt` for that hub's surface.

**Considering / partial:**

A handful of devtool platforms have it on a roadmap or under feature flag. Names withheld here — not yet public commitments.

## The pattern

It's **devtool companies first.** Every site shipping `llms.txt` today is either a developer platform, an SDK provider, or an AI/ML company. Consumer-facing sites haven't moved.

Two readings of why:

1. **The audience overlap.** Devtool customers ARE AI users. The feedback loop is short — a Cursor user complains they can't get good context from your docs, you ship llms.txt the next week.
2. **The build cost is trivial when your docs are already in markdown.** It's a couple lines of script to generate. Companies whose docs sit in WordPress or proprietary CMSes have a real build problem.

## Where mdfy fits

We make `llms.txt` part of the *user's* URL, not just the platform's. Any user's hub gets its own `/llms.txt`. Any AI tool can fetch it. That extends the standard's reach from "the sites the LLM-providers pay attention to" to "every user who's published anything."

## Followup

Watch HuggingFace, Replicate, and OpenAI's developer docs. If they ship it by end of Q3 2026 it tips into mainstream; if not, it stays a devtool convention.

---
id: 8MD8xlLA
title: GTM: the three channels I'll work
url: https://memory.wiki/8MD8xlLA
updated: 2026-05-14T18:15:49.480924+00:00
---

# GTM: the three channels I'll work

> Concentration > spray. If I pick five channels and half-do them, none of them work.

## The three

**1. Hacker News.** One Show HN at launch. One follow-up post in 4 weeks. After that, organic posts when there's a real artifact (a benchmark, a build-in-public milestone, a thoughtful response to a popular adjacent post).

I'm not picking HN because it's the only place that matters — I'm picking it because:
- The ICP overlap is genuinely high (developers using multiple AI tools).
- The format rewards specificity (technical write-ups, real numbers, no marketing fluff).
- I can write in my actual voice without translating.

**2. Founder-as-channel (Twitter/X + occasionally a longform).** Daily build-in-public posts, low effort. The dogfood URL is itself the post: "shipped X, here's the bundle showing how I made the call → mdfy.app/b/...". The product is the artifact.

I'm allergic to the "Twitter founder" archetype but I'm also pragmatic. Daily 1-tweet posts about real work are different from the inspirational-thread economy.

**3. Cold outreach to design-tool YouTubers.** Specific cohort: YouTubers covering Cursor, Notion AI, Linear, Raycast, etc. Their audience overlaps tightly with our ICP and the visual product demos great on camera.

The outreach is genuinely cold — no warm intro pretence. I send a 5-line email with the demo URL and a why-this-is-different-for-your-audience hook. Aim for 1-2 placements in the first 3 months.

## What I'm explicitly NOT doing

- **Reddit.** Niche-and-noisy. Ratio of effort to reach is poor unless I get into r/ChatGPT-level subs, which doesn't fit the ICP.
- **Product Hunt.** Wrong audience for technical infra. Skip.
- **TikTok.** Not my voice, not our visual language.
- **Conference talks.** Possibly later; not in year one.
- **Paid acquisition.** Not before we have a working free-to-paid conversion signal.

## What changes the plan

If channel #2 (founder) significantly out-performs #1 (HN), I lean further into it. If channel #3 (YouTubers) lands a hit, I double-allocate to that. The point is to have a small enough set that I can read the signal cleanly.

---
id: mXy_aztt
title: Launch day: what success looks like
url: https://memory.wiki/mXy_aztt
updated: 2026-05-14T18:15:49.480924+00:00
---

# Launch day: what success looks like

> Show HN day plan. The thresholds I'm pre-committing to so I don't accidentally move them post-hoc.

## The realistic upside

**Top of HN front page for 4+ hours.** Requires hitting the front page within the first hour after posting (HN's ranking algorithm strongly favours early velocity) and sustaining engagement through the European afternoon and the US morning.

If this happens, I expect:
- 800-1500 sign-ups within 24h
- ~150-300 trial-to-keeper conversions (define "keeper" as: still has at least one doc 14 days post-sign-up)
- 4-6 inbound press / podcast queries
- 1-3 inbound investor reach-outs (which I'll defer politely; not raising)

## The reasonable mid case

**Front page for 1-2 hours, conversation in the 100-200 comment range.**

If this happens:
- 200-400 sign-ups
- 30-80 keepers
- The bigger value is the conversation itself — I'll mine the comments for what reads as the most compelling and the most repelling

## The downside

**Page 2-3, no significant discussion.**

If this happens:
- < 100 sign-ups, probably ~50
- The signal I take is "the framing didn't land", not "the product doesn't work." Re-write the framing, post again in 4 weeks under a different angle.

## What I'm NOT measuring on launch day

- **Revenue.** We're free during beta. Zero by design.
- **Server cost.** We're built on Supabase + Vercel; the marginal cost is rounding error.
- **Twitter/X engagement.** I'll tweet the launch but the HN comment thread is the actual signal channel.

## The non-negotiables

- **I respond to every comment** within 6 hours, personally, not via a marketing voice. The HN audience can smell PR from a screen away.
- **No upvote begging.** Posting to friends as "hey, shipped this" is fine. "Please upvote" is not.
- **No founder ego in the writing.** The Show HN post is technical and specific. No "revolutionary" / "disrupt" / "next-gen."

---
id: y3zQ915R
title: Math: every flavour we render
url: https://memory.wiki/y3zQ915R
updated: 2026-05-14T18:15:49.480924+00:00
---

# Math: every flavour we render

> A tour of what KaTeX gives us inside the renderer. Useful as a copy-paste reference for new docs.

## Inline math

Euler's identity is $e^{i\pi} + 1 = 0$. The Cauchy-Schwarz inequality is $|\langle u, v \rangle| \le \|u\|\|v\|$ — the same inequality that limits how strongly correlated two embeddings can be when their norms are bounded. We rely on it implicitly every time we threshold a cosine-similarity score.

A more workaday example: the sigmoid is $\sigma(x) = \frac{1}{1 + e^{-x}}$, and our reranker uses softmax $\text{softmax}(x_i) = \frac{e^{x_i}}{\sum_j e^{x_j}}$ to normalise the logit scores before we threshold.

## Block math

The Gaussian integral, foundational for normalising kernels:

$$\int_{-\infty}^{\infty} e^{-x^2}\, dx = \sqrt{\pi}$$

The HNSW search complexity, roughly:

$$O(\log N) \text{ expected, with } M \cdot \log N \text{ build cost}$$

where $N$ is the number of indexed vectors and $M$ is the max-connections parameter we set to 16 in our pgvector index.

## Matrices

$$
A = \begin{pmatrix}
a & b \\\\
c & d
\end{pmatrix}
\quad
B = \begin{pmatrix}
1 & 0 \\\\
0 & 1
\end{pmatrix}
$$

## Aligned equations

$$
\begin{aligned}
y &= mx + b \\\\
m &= \frac{y_2 - y_1}{x_2 - x_1} \\\\
b &= y_1 - m \cdot x_1
\end{aligned}
$$

## What we *don't* render (yet)

Custom macros. KaTeX supports `\newcommand`, but we don't wire it through the editor — adding it would require either a per-doc macro registry or a hub-wide one. Filed as "v7 maybe" if anyone asks.

---
id: csFtDM3c
title: README — start here
url: https://memory.wiki/csFtDM3c
updated: 2026-05-14T18:15:49.480924+00:00
---

# README — start here

> Entry point for this demo hub.

## What is this

A working hub belonging to a fictional founder building a personal-knowledge layer for the AI era. The content is real-shaped: actual decisions, actual research notes, actual launch planning. Click around like you would your own hub.

## What's in here

- **50 documents** spread across 7 folders + 13 at the root level.
- **7 bundles**, including one private (the financials vault), one restricted-access (engineering decisions), and five public.
- **A concept index** auto-derived from the content — every key term has a page at `/hub/demo/concepts/{slug}`.
- **The hub URL itself** (`mdfy.app/hub/demo`) is paste-able into Claude, ChatGPT, Cursor, or Codex. Try it.

## How to use the demo

1. Pick a folder in the sidebar. Each has a coherent theme.
2. Open a bundle. Watch the canvas paint the pre-computed analysis (themes, insights, document summaries, reading order).
3. Try the search affordance (Cmd-K, type a domain term). Hub-scoped semantic recall.
4. Paste the URL `mdfy.app/hub/demo` into your favourite AI tool. Ask it a question about the hub. Verify it answers from the hub.

## What you can't do

- The demo account is read-only-feeling — anyone who signs in can browse it, but the canonical content is owned by `demo@mdfy.app`. You can fork docs (Duplicate to edit) and they become yours.
- Private docs in the "Private Vault" folder are intentionally inaccessible to anyone except the owner. Same with the "Financials + runway" bundle. That's not a bug; it's the demonstration of the permission model.

## The real reason this hub exists

So that a reviewer evaluating mdfy in 5-10 minutes can land in a hub that looks like a working founder's brain and form an honest opinion about whether mdfy makes sense as a product. Nothing in this hub is filler.

If you find a doc that feels like filler, file an issue (or just paste it back at the founder). It'll get rewritten.

---
id: UaxcbLwD
title: My current personal stack
url: https://memory.wiki/UaxcbLwD
updated: 2026-05-14T18:15:49.480924+00:00
---

# My current personal stack

> The actual tools I use day to day, as of 2026-05.

## Editor / IDE

- **VS Code + Claude Code** — daily driver. Claude Code's CLAUDE.md integration is the single most important productivity multiplier in my stack.
- **Cursor** — pulled out for big refactors where I want a stronger model + agent loop. Not the daily driver because the indexing pause on large repos is annoying.
- **Vim** — for quick edits over SSH or in repos I haven't set up. Always installed, rarely the primary.

## AI

- **Claude Opus 4.7** — primary thinking partner. Best for nuanced trade-offs and long-arc reasoning.
- **ChatGPT-5** — secondary. Better at structured task decomposition; the worksheet output is uniquely good.
- **Gemini 2.5 Pro** — for diagrams and image-shaped tasks where Claude's multimodal is weaker.

Three because each one forgets the others' context. mdfy bridges that.

## Capture

- **mdfy** — naturally. The dogfood URL is my actual working hub.
- **Drafts** — for raw thought capture on iOS. Drafts → "Append to mdfy" Shortcut → permanent URL.

## Calendar / scheduling

- **Cron** — anti-meeting setup. I don't take same-week meetings except for fires.

## Communication

- **Slack** — minimal, mostly read-only.
- **Email** — primary async. Long-form, no Slack threads.

## Reading / research

- **Reader (Readwise)** — articles, PDFs, highlights flow into mdfy via a Shortcut.
- **Arxiv-sanity** — when I need to skim ML papers.

## Health-of-the-loop

- **Rise** — sleep tracking. The numbers don't lie about whether I'm burning out.
- **Cron blocks** — first 90 minutes are "no Slack, no email, only build."

## What I tried and dropped

- **Notion** — drifted out of it once mdfy was working. The flow was: write in mdfy, paste into Notion, never come back. Cut the middle step.
- **Linear** — overkill for a solo founder. GitHub issues are enough.
- **Twitter as a feed** — drains attention. I post; I don't read.

---
id: bDVLxgav
title: Mistakes I made building v6
url: https://memory.wiki/bDVLxgav
updated: 2026-05-14T18:15:49.480924+00:00
---

# Mistakes I made building v6

> Honest list. I write these because I want to remember them, not because I think they're inspirational.

## 1. Built `[[wikilinks]]` before deciding we were a wiki

Spent ~2 days implementing `[[]]` resolution, autocomplete, backlinks panel. Then realised the AI-derived concept_index was strictly better and made the manual `[[]]` redundant. Ripped the wikilinks code out.

Cost: 2 days of build + 1 day of removal.
Lesson: don't ship product surface before locking the positioning. The positioning has to come first; the syntax has to match the positioning.

## 2. Tried y-prosemirror for the editor

The vision was real-time collab. The reality was that y-prosemirror + the comrak-WASM pipeline didn't compose cleanly. Three days of trying to make CRDTs and a custom markdown engine play nice with shared editing.

Reverted to contentEditable + autosave. Single-user is the right scope for now.

Cost: 3 days.
Lesson: don't pre-build for collab affordances. They cost a lot, they break a lot, and single-user works fine until the day there's evidence collab is the wedge.

## 3. Wrote the AGENTS.md integration before testing it lived in Cursor

I wrote the integration docs based on what I expected Cursor's behaviour to be. The docs said "Cursor reads AGENTS.md per session, edits show up next session." That was true. What the docs didn't say is "Cursor caches AGENTS.md for the *duration* of the session, so even running `:reload` doesn't refresh it." I edited AGENTS.md mid-session expecting the change to apply, didn't see it apply, and spent an hour thinking my mdfy server was broken.

Cost: 1h + a documentation fix.
Lesson: integration code has to be tested in the actual host before the docs are written.

## 4. Optimistic about the Mermaid renderer

The pre-launch testing assumed the Mermaid version we ship handles every diagram type the spec covers. The launch version chokes on `gitGraph` diagrams (silent failure, renders blank). Filed as a known issue; will fix post-launch by upgrading.

Cost: 0 user-facing impact (no users hit it), 30 mins of bisecting.
Lesson: visual regression tests for the renderer aren't optional.

## 5. Forgot to test the "signed out" state for sidebar bundles

Bundles survived sign-out for two weeks. Found by the founder (me) at the worst possible time — during a competition review. The cause was a missing `setBundles([])` in the sign-out button and a refetch effect that re-populated against the still-present anonymous_id.

Cost: 1h of QA + 1h of competition embarrassment.
Lesson: test every "ephemeral state on logout" path explicitly. The "I just signed out, what does my session look like" view is fragile and gets shipped without testing more often than it deserves.

## What none of these are

Catastrophic. They're all 1-3 day setbacks that I learned from. The pattern is the same: ship → notice → fix → write down the lesson. The loop is fine.

What I'm watching for is the bigger mistake — the one where I get too attached to a piece of the product to remove it. Haven't seen it yet but it's coming.

---
id: r_HaRypO
title: Show HN plan (working draft)
url: https://memory.wiki/r_HaRypO
updated: 2026-05-14T18:15:49.480924+00:00
---

# Show HN plan (working draft)

> Living plan that I refine before launch day.

## Title

**Show HN: mdfy – Your AI memory, deployable to any AI**

Alternates I'm holding: "Markdown URLs as a memory layer for Claude, ChatGPT, Cursor" / "I built the personal wiki Karpathy described, then deployed it as a URL." Current preference is the first — leads with our line and the cross-AI differentiator.

## Body — target ~400 words, no marketing language

Opens with: "I've been building mdfy for ~8 weeks. Today I'm shipping v6, which turns it from a markdown publisher into a memory layer."

Then: the thesis (LLMs read markdown, URLs cross every boundary, so your memory should be a markdown URL).

Then: what it does today, bulleted.
- Capture from any AI (Chrome ext, MCP, paste).
- Capture from anywhere else (GitHub, Notion, Obsidian, files).
- Bundle by topic with AI-synthesised analysis.
- Hub auto-clustering into a concept index.
- llms.txt + bundle digests + recall API.
- Cross-AI wiring via AGENTS.md / CLAUDE.md / .cursor/rules.

Then: what's interesting (in *my* voice).
- Cross-AI is structural moat.
- Authored memory ≠ extracted memory.
- Graph-RAG-as-URL (not Graph-RAG-as-service).
- The Karpathy wiki shape, deployed as URL.

Then: stack. Then: try it (free, no signup).

Then: "Happy to dig into anything technical, the cross-AI thesis, why I left X to do this, or where I think this goes if it works."

## Anticipated questions, pre-drafted answers

1. **Isn't this just Notion + AI?** — Notion's AI works in Notion. mdfy works wherever the URL goes.
2. **What about Mem0 / Letta / extracted memory?** — Different question. Mem0 asks what the AI should remember; mdfy asks what *you* want to remember.
3. **How is this different from GitHub Pages + markdown?** — Capture surfaces, hub layer, cross-AI deployability.
4. **Won't AI companies just build this?** — They structurally can't. Their incentive is the wall.
5. **Pricing?** — Free during beta. Pro $X/mo after launch (price TBD).
6. **Why are you doing this?** — Trillions of tokens of high-quality AI-assisted thinking are being created daily and lost to chat histories nobody returns to. I want to catch the part you actually meant to keep.

## Timing

Tuesday or Wednesday, 7 AM PT. I'll be online and responding for 6 hours minimum.

## What I'm explicitly not doing

- Recruiting upvotes from Slack.
- Posting in any other forum within 24 hours of the HN post.
- Buzzword pile-up.
- Reddit-style "let me know what you think!" tail.

---
id: wyULEr1h
title: Feature ideas backlog
url: https://memory.wiki/wyULEr1h
updated: 2026-05-14T18:15:49.480924+00:00
---

# Feature ideas backlog

> Ranked by gut-feel value:effort. Not committed to any of these.

## Top 5 — high value, manageable effort

1. **Inline graph_data in bundle URL** — already shipping. The decision write-up is at `demo-dec-bundle-graph-inline`. This is the load-bearing feature for the cross-AI thesis.
2. **Custom hub theme** — let users pick an accent colour and a typeface. Modest engineering effort, real perceived-quality bump. Ship-able in a week.
3. **Slack capture** — send a Slack DM to a bot, get a permanent mdfy URL back. Reuses the existing capture pipeline. Two weeks of work, mostly OAuth dance.
4. **Email-in capture** — forward any email to a magic address, get a mdfy URL back. Cheaper than Slack because there's no OAuth, but spam-protection matters.
5. **Hub-to-PDF export** — generate a single PDF of all public docs in a hub. Useful for portfolio-mode users. Most of the work is print CSS, which we already have for individual docs.

## Mid-tier — interesting but later

- **Concept-page editing.** Right now the concept index pages are auto-derived. Letting the user pencil-edit a concept's description is a big-feel feature with light engineering cost.
- **Per-bundle layouts.** Bundle owners pick how the canvas paints (timeline / tree / grid). Adds dimensionality to the bundle as a surface.
- **Embed a doc inside another doc.** The `{{include: doc-id}}` macro. Useful for compositional notes. Engineering risk is recursion.
- **Activity dashboard.** Per-hub views/fetches/captures. Currently planned as a Pro feature.

## Bottom of mind — fun, not strategic

- Mobile native app.
- Apple Watch app.
- Voice capture with Whisper.
- AR document spatial layout. (Joke. Mostly.)
- AI-generated cover images for hubs.
- Custom CSS per hub.

## What I'd kill from the backlog

- Real-time collab. The cost is enormous; the demand signal is weak.
- Tasks / kanban. Different product.
- Notion-block-style embedded widgets. Different product.

## Decision rule

Anything in "top 5" only ships if the feedback from launch tells me it's the right next thing. The plan is a hypothesis; users will tell me which item to lift to actual roadmap.

---
id: _bhW7pVA
title: Glossary
url: https://memory.wiki/_bhW7pVA
updated: 2026-05-14T18:15:49.480924+00:00
---

# Glossary

> Terms used across this hub, in plain language.

## Hub

A user's public URL on mdfy. Lives at `mdfy.app/hub/{slug}`. Contains: a concept index, all the user's bundles, optional curated content. The hub is the unit that AI tools paste in as their persistent context source.

## Bundle

A topical grouping of documents. Has its own URL (`mdfy.app/b/{id}`). Carries pre-computed analysis (themes, insights, connections, document summaries, reading order). The bundle is the unit for per-project context — drop a bundle URL in AGENTS.md or .cursor/rules and the AI loads everything in the bundle.

## Doc

A single markdown document. Lives at `mdfy.app/d/{id}`. The atomic unit. Everything else is built out of docs.

## Concept index

The auto-derived list of every distinct concept the AI extracted from your hub's documents. Each concept links to the docs it appears in. Updated by the capture pipeline.

## Concept relations

Edges between concepts. "Hub-shaped memory" is_a "Memory architecture"; "Cross-AI portability" requires "Markdown URLs". The relations are what makes the index a graph instead of a list.

## graph_data

The JSON blob attached to each bundle. Contains nodes, edges, themes, insights, document summaries, reading order, key takeaways, gaps. Generated by an LLM analysis pass. Inlined in the bundle's URL response so any AI fetching the URL inherits the analysis without a second call.

## Capture

The act of moving content from somewhere else (a chat, a file, a webpage) into mdfy. Multiple capture surfaces: Chrome extension, MCP tools, paste-anywhere, file import.

## Recall

The query side of the hub. `POST /api/hub/{slug}/recall` runs a hybrid (BM25 + vector) retrieval, optionally reranks with Anthropic Haiku, returns the top-k matching chunks.

## Deploy

The act of *using* an mdfy URL as context. "Deploy this hub" = "paste the hub URL into your AI tool of choice." There's no actual deployment in the infra sense — the URL is just a URL.

## Edit token

A token that grants write access to a specific doc or bundle. Generated on creation. Can be regenerated. Not an OAuth session — just a string that the API checks.

## Owner

The user_id that owns a doc or bundle. Authenticated via Supabase Auth. Owner ≠ edit-token-holder; either path grants write.

## Restricted

A permission state where a doc is non-public AND has at least one entry in `allowed_emails`. Only owners + listed emails can view.

## Private

A permission state where a doc has `is_draft = true`. Only the owner can view. (The legacy name "Draft" was changed to "Private" in v6 because "Draft" read as "incomplete," which wasn't the intent.)

---
id: OGySiVoO
title: RFC: hub recall API
url: https://memory.wiki/OGySiVoO
updated: 2026-05-14T18:15:49.480924+00:00
---

# RFC: hub recall API

> Status: shipped.

## The endpoint

`POST mdfy.app/api/hub/{slug}/recall`

Body:

```json
{
  "question": "How does cross-AI memory work?",
  "k": 10,
  "level": "doc",
  "rerank": true
}
```

Returns the top-k matching chunks (or docs), ranked.

## How the recall actually works

1. **Embedding lookup.** Embed the question with `text-embedding-3-small` (1536 dim).
2. **Hybrid retrieval.** Run two queries in parallel against the user's hub:
   - **Vector.** pgvector cosine match against `documents.embedding` (HNSW index, `ef_search = 40`).
   - **Lexical.** Postgres `to_tsvector` full-text search against `documents.fts`.
3. **Union + de-dup.** Concatenate the top 30 from each, de-dup by doc id. ~30-50 unique candidates.
4. **Reranker (optional).** If `rerank: true`, send the candidates + the question to Anthropic Haiku, which scores each match. Re-sort by Haiku's score, take top-k.
5. **Return.** Each result includes: doc id, doc title, doc URL, the matched chunk text, the rank score, and the source (vector / lexical / both).

## What's tunable

- `k` — number of results to return. 1-20.
- `level` — `"doc"` returns whole docs; `"chunk"` returns specific passages (chunks are pre-computed at ~500 tokens each).
- `rerank` — boolean. Default true. Costs ~300ms p95. False for speed-first paths.
- `min_score` — discard results below a cosine threshold. Useful for "don't return anything if nothing matches."

## Auth

The endpoint is publicly callable for public hubs. For restricted/private hubs, the caller has to be the owner OR have an MCP-signed token. Anonymous calls to a private hub return 401.

## What it doesn't do

- **Multi-hop reasoning.** No "fetch this, then fetch what it links to, then aggregate." That's a higher-level construct that lives in the caller's loop.
- **Live recomputation of embeddings.** We embed at write time; recall reads from the existing vectors. Staleness is bounded by the longest delay between a doc edit and the embedding-refresh job (currently 30s).
- **Graph traversal.** Recall is flat over chunks. The graph relationships are at the concept level, accessible separately via the concept index.

## What's next

- **Per-hub recall caching.** Common queries against a public hub should be cacheable for ~60s.
- **Streaming results.** Today the response waits for the reranker to finish. We could stream the union results as they arrive and replace them as the reranker scores them. Tradeoff: more complex client code.
- **Configurable embedding model.** Currently hardcoded to OpenAI ada-3-small. Worth exposing if we ever support a non-OpenAI default.

---
id: EyW4HU4-
title: GPT-5 on context-budget rituals
url: https://memory.wiki/EyW4HU4-
updated: 2026-05-14T18:15:49.480924+00:00
---

# GPT-5 on context-budget rituals

> ChatGPT-5 share link, 2026-04-09. I'd been losing context across sessions and wanted a framework, not another "use Projects" answer.

## The prompt

I dumped four things: the v6 AGENTS.md draft, the `mdfy Foundations` bundle, the most recent 50 Cursor chat turns, and a one-paragraph statement of what I was trying to design (cross-AI context handoff). Then asked: "How would you structure the context you carry into a working session?"

## What it built

A worksheet, not a heuristic. The structure was:

| Slot | Allocation | Source |
|---|---|---|
| Project context | 30% | AGENTS.md / CLAUDE.md / hub URL |
| Recent edits | 30% | Last N file diffs |
| Live conversation | 40% | This turn + last 4-6 |

The split is the part I actually use. Before this, I was loading "everything" — which meant the model got 12K tokens of static context and 1K of live discussion. The flip (live > context) sounds backwards but explains why "the AI keeps losing the thread mid-conversation" — the thread had no room.

## The caveat

The worksheet over-fits to **coding** sessions. For research / writing, the ratios invert: live conversation shrinks (you're not iterating on a turn-by-turn loop) and project context expands (you're loading more reference material).

## What I'm doing

- Default `?compact` on hub URLs when pasted into Cursor — claws back 30% of the project-context slot for free.
- Added a "Recent edits" Cmd+K command in the editor — pulls last 5 diffs into a paste-able block.
- For research, swap to `?full=1` on bundle URLs — the whole bundle as context, no compaction.

---
id: PrxR1Uj4
title: mdfy MCP server: setup in 4 lines
url: https://memory.wiki/PrxR1Uj4
updated: 2026-05-14T18:15:49.480924+00:00
---

# mdfy MCP server: setup in 4 lines

> For Claude Desktop, Cursor, and any other MCP-enabled tool.

## What MCP gives us

MCP (Model Context Protocol) is Anthropic's open standard for letting AI tools call external services. The mdfy MCP server exposes seven tools — read, search, create, update, publish, delete, list — that any MCP host can call. The result: the AI doesn't just *read* your hub URL; it can actively manage what's in it.

## Setup

Add this to your MCP config (Claude Desktop: `~/Library/Application Support/Claude/mcp_config.json`; Cursor: `.cursor/mcp.json` in the project):

```json
{
  "mcpServers": {
    "mdfy": {
      "command": "npx",
      "args": ["-y", "@mdfy/mcp-server"]
    }
  }
}
```

Restart the host (Claude Desktop or Cursor). The mdfy tools show up in the tool palette.

## Authentication

The MCP server reads `MDFY_EDIT_TOKEN` and `MDFY_USER_EMAIL` from the environment. Add them to the MCP config like this:

```json
{
  "mcpServers": {
    "mdfy": {
      "command": "npx",
      "args": ["-y", "@mdfy/mcp-server"],
      "env": {
        "MDFY_USER_EMAIL": "you@example.com",
        "MDFY_EDIT_TOKEN": "..."
      }
    }
  }
}
```

You can copy the edit token from the Share modal of any doc you own; it scopes to your whole account, not a single doc.

## The tools exposed

| Tool | Purpose |
|---|---|
| `mdfy_read` | Fetch a doc / bundle / hub by id or URL |
| `mdfy_search` | Hybrid recall across your hub |
| `mdfy_create` | Create a new doc with a body |
| `mdfy_update` | Patch an existing doc (with optional change summary) |
| `mdfy_publish` | Flip a draft doc to public |
| `mdfy_delete` | Soft-delete (recoverable from trash) |
| `mdfy_list` | List all your docs/bundles, optionally filtered |

## What changes in your workflow

Before MCP: you ask Claude "summarise the launch plan", and Claude says "I'd need to read the plan — paste it for me." After MCP: Claude calls `mdfy_read` with the doc id, gets the markdown, and answers.

That's the deal. The tool palette is small (7 tools) but the reach is big — every operation you'd do in the editor is also callable from the AI.

---
id: iok3gZo6
title: Wiring mdfy into Claude Code
url: https://memory.wiki/iok3gZo6
updated: 2026-05-14T18:15:49.480924+00:00
---

# Wiring mdfy into Claude Code

> Tested against Claude Code v1.x. Single command, single line in CLAUDE.md, persistent across sessions.

## What you put in CLAUDE.md

Drop this somewhere near the top of the file (CLAUDE.md is loaded into every Claude Code session as system context):

```
## Context
When you need background on this project, fetch:
  https://mdfy.app/hub/<your-slug>

The hub contains the canonical product spec, the current roadmap,
and the bundles for each major work area (engineering, strategy,
research). Cite by hub-relative URL when answering.
```

That's it. Claude Code reads the URL on session start and treats whatever the hub returns as part of its working context.

## Why this works

- **Claude Code respects CLAUDE.md.** It's not a hint; it's a contract. Anything in CLAUDE.md is in the session's persistent system prompt.
- **mdfy hubs are URL-shaped.** No SDK, no auth, no streaming setup — just a GET that returns markdown plus an inlined graph_data JSON block.
- **Token cost is tunable.** Add `?compact` to the URL to strip low-density sections. Most users save 30-40% of the context window this way.

## What about per-project context?

Per-project goes in the *project's* CLAUDE.md (the one in the project root, not your global `~/.claude/CLAUDE.md`). Use a bundle URL there instead of a hub URL:

```
## Context
When you need project context: https://mdfy.app/b/<bundle-id>
```

The bundle URL gives Claude only the docs in that bundle — much tighter scope than the full hub.

## Things that bite you

1. **The CLAUDE.md update doesn't apply until you restart Claude Code.** The first time I tried this I assumed it was hot-reload. It's not.
2. **If your hub is private, you need to also configure the MCP server to authenticate.** The fully public path is `?` and works without setup; the private path is `?key=...&token=...` and is part of the Pro tier.
3. **The model can ignore the directive if you fill the context with too much other stuff.** Watch for "Claude isn't using my hub" — usually it means the live conversation has crowded out the system prompt.

## What this gives you, end to end

Before: every Claude Code session starts blank, you re-explain the project, you paste the same context block by hand.

After: every session starts with the hub loaded, you skip the re-explanation, and any change you make in mdfy.app shows up in the *next* Claude Code session automatically.

---
id: y4sEEo1R
title: Wiring mdfy into Codex via AGENTS.md
url: https://memory.wiki/y4sEEo1R
updated: 2026-05-14T18:15:49.480924+00:00
---

# Wiring mdfy into Codex via AGENTS.md

> Codex CLI + AGENTS.md. Same shape as the Claude Code recipe but with caveats specific to Codex's caching.

## What you put in AGENTS.md

Drop this near the top:

```
## Context
Load https://mdfy.app/hub/<your-slug> before answering project
questions. The hub contains the spec, the roadmap, and the bundles
for engineering, strategy, and research.

For per-project context, see the bundle URL in this file's section
"## Project bundle" below.
```

If you have a per-project bundle, add a second block:

```
## Project bundle
https://mdfy.app/b/<bundle-id>?compact
```

The `?compact` strips out long appendices and saves ~30% of the context window.

## Why two scopes (hub + bundle)

The hub gives the AI breadth: who you are, what you're building, what your prior work shows. The bundle gives it depth: the specific docs related to the current project. Both load; the model picks the right level depending on the question.

## What's different from Claude Code

Codex caches AGENTS.md at the start of a session. **If you edit AGENTS.md mid-session, Codex doesn't see the change** until the next session. This caught me twice on launch-prep day — I'd update the hub URL in AGENTS.md, expect Codex to pick it up, and Codex would keep loading the stale URL.

Workaround: when iterating on the AGENTS.md content, kill the Codex session and restart.

## Things to watch for

- **The `?compact` flag is doc-respectful but not bundle-respectful.** It compacts each member doc; it doesn't drop docs. If the bundle has 30 members, `?compact` still loads all 30.
- **For the smallest possible context, use `?full=0&graph=1`** — that returns only the bundle's analysis (themes, insights, summaries) without inlining any member docs.
- **Codex doesn't currently support MCP.** So the hub-load is GET-only over plain HTTP. Fine for public hubs; private hubs need the editToken in the URL (see /docs/integrate for the exact format).

## What this gives you

The AGENTS.md-tagged Codex sessions become "context-aware by default". You stop re-pasting the same explanations every time you open Codex. You stop asking "wait, do you know about X?" — Codex knows about X because X is in the hub.

---
id: T7ZGdpOm
title: Karpathy's LLM Wiki concept, in one read
url: https://memory.wiki/T7ZGdpOm
updated: 2026-05-14T17:52:48.410774+00:00
---

# Karpathy's LLM Wiki concept, in one read

## Source

Andrej Karpathy, Twitter thread (2024). Topic: a personal LLM-readable wiki — one place a person writes their knowledge, the LLM reads it instead of building memory by inference.

## Core argument

> The most reliable AI memory is the one the human authored. Anything inferred from a chat transcript is lossy; anything written deliberately is durable.

This frames "memory" as a *curation problem*, not a *retrieval problem*. Most existing AI memory systems (Mem.ai, ChatGPT memory beta) treat it as the latter.

## Where Karpathy's vision stops

Single unified wiki. One person, one wiki. The structure is whatever the user makes inside that wiki.

## Where mdfy goes further

Three composable scopes instead of one: doc, bundle, hub. The same URL primitive scales from a one-note share to a project context to a full knowledge graph. Karpathy's single-wiki model can't deliver per-project context without folder discipline; mdfy's bundle model is *built* for it.

But mdfy and Karpathy's vision share the load-bearing claim: **the human stays the author**. The AI reads what was written; it doesn't try to infer memory from chat.

## Quote worth keeping

> The wiki you wrote yesterday is the context the AI gets today. The AI shouldn't be reconstructing your beliefs from session transcripts.

That's the philosophy. mdfy is one shape of the implementation.

---
id: rBRZ_nni
title: The structural moat: cross-AI portability
url: https://memory.wiki/rBRZ_nni
updated: 2026-05-14T17:52:48.410774+00:00
---

# The structural moat: cross-AI portability

## One line summary

> A single AI vendor can build deeper integration against its own model than mdfy ever could. None of them can deliver a URL that works across their competitors. The portability is the product.

## Why this matters

Notion, Mem.ai, Roam, Obsidian — each is a destination. The user is asked to live inside the tool. mdfy is the opposite shape: the user lives wherever they already work (ChatGPT, Cursor, Claude Code) and mdfy is the thing that travels with them.

## What gets ported

- The doc body (clean markdown)
- The graph analysis (themes, insights, concept relations) attached to bundles
- The concept index attached to hubs
- Privacy gating (Public / Restricted / Private) — the URL behaves the same way the rendered viewer does

## Why the AI vendors can't replicate

OpenAI building "ChatGPT memory that Claude can read" is a competitive negative for them. Anthropic the same. The asymmetry is structural — mdfy benefits from being *not aligned* with any single vendor.

## Failure modes

- If one vendor builds a dominant memory layer that all AIs respect → mdfy still survives as the UX layer (curate, capture, share) but loses the "they can't" part
- If `llms.txt` adoption stalls → the URL contract weakens. Mitigate by treating `llms.txt` as one of multiple paths; raw markdown + clean URLs are the durable spec.

Bottom line: the moat depends on the URL contract, not on any one feature.

---
id: TEuiwop8
title: Wiring mdfy into Cursor
url: https://memory.wiki/TEuiwop8
updated: 2026-05-14T17:52:48.410774+00:00
---

# Wiring mdfy into Cursor

`.cursor/rules/mdfy.mdc`:

```
---
description: Project context from mdfy
alwaysApply: true
---

Project context lives at https://mdfy.app/b/<your-bundle-id>.

Fetch that URL when you need this project's spec, decisions, or
prior reasoning. The response carries the canvas analysis (themes,
insights, concept relations) in the same payload.
```

## How Cursor uses this

On every new chat or composer session, Cursor evaluates files matched by the rule and includes them as context. When mdfy URL is in the rule body, Cursor fetches the URL on demand — typically when the user asks a question that references concepts in the bundle.

## What we observed in practice

- First few messages: Cursor doesn't always fetch — it relies on its own RAG over the local repo. Fine.
- Once the user types something topic-specific ("how did we decide the pricing tier?"), Cursor fetches the bundle URL and the answer comes back cited to the right doc.
- Cursor's `[doc:N]` citations don't propagate the way Claude Chat's do — Cursor inlines snippets but doesn't link back. Acceptable for a code-editor surface.

## Recommended bundle structure for Cursor

Group docs by intent. Keep the bundle title concrete ("Auth migration", "API redesign 2026-04", "Pricing decision log"), not abstract.

---
id: F1q9U1YP
title: Formatting tour: math, diagrams, code, tables
url: https://memory.wiki/F1q9U1YP
updated: 2026-05-14T17:52:48.410774+00:00
---

# Formatting tour: math, diagrams, code, tables

A reference for what renders in mdfy. Every block below appears in real docs across this hub.

## KaTeX math

Inline: $E = mc^2$. Display:

$$
\int_0^{\infty} e^{-x^2}\, dx = \frac{\sqrt{\pi}}{2}
$$

Matrix:

$$
\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} x \\ y \end{pmatrix} = \begin{pmatrix} ax + by \\ cx + dy \end{pmatrix}
$$

## Mermaid diagrams

```mermaid
flowchart LR
  Doc[(Doc)] --> Bundle((Bundle))
  Bundle --> Hub[/Hub/]
  Hub --> AI[Any AI]
  AI -. cites .-> Doc
```

```mermaid
sequenceDiagram
  participant U as You
  participant M as mdfy
  participant AI as Claude/ChatGPT
  U->>M: Publish doc
  M-->>U: Permanent URL
  U->>AI: Paste URL
  AI->>M: Fetch /raw/<id>
  M-->>AI: Clean markdown + graph
```

## Code with highlighting

```typescript
const res = await fetch("https://mdfy.app/api/hub/demo/recall", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ question: "react hooks", k: 5, rerank: true }),
});
const { results } = await res.json();
```

```python
import requests

r = requests.post("https://mdfy.app/api/docs",
  json={"markdown": "# Hello World"})
print(r.json()["url"])  # → "https://mdfy.app/abc123"
```

## Tables

| Scope | URL | Cost |
|:------|:----|:-----|
| Doc | `mdfy.app/<id>` | tightest |
| Bundle | `mdfy.app/b/<id>` | mid (+graph) |
| Hub | `mdfy.app/hub/<slug>` | broad |

That's the rendering vocabulary mdfy expects to handle on any doc.

---
id: kxn9T-Vv
title: Decision: ship graph_data inside the bundle URL
url: https://memory.wiki/kxn9T-Vv
updated: 2026-05-14T17:52:48.410774+00:00
---

# Decision: ship graph_data inside the bundle URL

**Status**: shipped 2026-05-12 (commit `ba7344c4`)

## Context

A bundle URL returns a markdown digest. Before this change the digest contained only the doc list + annotations. The canvas analysis (themes, insights, concept relations) lived only inside the mdfy.app web canvas — paste the URL into Claude and the AI got the doc list but had to redo the cross-doc analysis itself.

## Decision

Embed the `graph_data` JSON as markdown sections inside the `/raw/bundle/<id>` response by default. Add `?graph=0` opt-out for callers that want the legacy doc-list-only digest.

## Why

The viral loop runs through URLs. If pasting a URL gives the receiving AI *more* than the sending AI could give without mdfy, the URL is genuinely portable. Without `graph_data` in the payload, the URL is just a doc inventory — useful but not differentiating.

## Trade-offs

- **Token cost**: typical bundle adds ~600 tokens for the analysis section. Caller can drop via `?graph=0`.
- **Staleness**: `analysis_stale: true` frontmatter flag warns the AI when member docs were edited after the last analysis run.
- **Recompute cost**: regenerating `graph_data` requires an LLM call. Today this is owner-triggered; Pro will background-run on stale fetch.

## Validation

- e2e: every public bundle URL now carries the section by default (test `28/28 passing 2.2m`)
- Hub digest still omits the section — different surface, different default

---
id: yt2ZZqyI
title: AI memory architectures: a Claude conversation
url: https://memory.wiki/yt2ZZqyI
updated: 2026-05-14T17:52:48.410774+00:00
---

# AI memory architectures: a Claude conversation

> Captured from a working session with Claude Opus, 2026-03-12. Cleaned, structured, and saved as a permanent URL so the next AI session can pick up where we left off.

## The question

What architecture should a personal memory layer use? Three patterns are in production today:

1. **Vector recall** — every message goes through an embedding model, gets stored, retrieved by cosine similarity on demand. ChatGPT memory beta works this way.
2. **Episodic snapshots** — full conversation transcripts are stored verbatim, indexed by date and topic. Claude Projects does this.
3. **Hub-shaped memory** — the user authors structured notes; the AI reads them as URL-addressable resources.

## What Claude argued

> Vector recall trades precision for breadth. Episodic snapshots trade verbosity for fidelity. Hub-shaped memory trades automation for author-control.

The third pattern wins for one reason: **the human stays the author**. Vector + episodic both let memory drift — once stored, the user can't easily edit or curate without leaving the AI's UI. Hub-shaped puts the artifact in a place the user already lives (a document) and the AI reads from there.

## Takeaway for mdfy

This is the existing direction. Worth checking against the spec page — `/spec` already documents the URL contract. No code change needed; this conversation just validates the choice.

## Related concepts

- Vector recall, episodic snapshot, hub-shaped memory
- Forgetting as a feature
- URL-addressable knowledge