Simple start

From the landing page to the first note

One path from the landing page to the first note, written for a person who has never seen the product. A copy-paste sits beside each step for a programmer.

Find it

Open https://memoshelf.com. Click Quickstart on the landing page.

What you should see: You are reading this page.

Sign in by magic link

Open Sign in, enter your email, open the email, and click the link.

What you should see: The email contains a link. Click it. Do not copy a callback URL by hand.

Land in the app

The link takes you to memoshelf.com/app, signed in.

What you should see: The address bar is https://memoshelf.com/app and you are signed in. If you land on any other host, stop.

Make a key with the smallest scopes

Make one key with scope write — the smallest scope that can log a run and store a note. Label it lane:<name>.

What you should see: The app shows the secret once. Copy it now.

Where the key goes

Put the key in an environment variable or the caller's secret store. Never a prompt. Never a file in git.

What you should see: Later calls send the key as an Authorization header, never in the URL.

The first log_run

Write a run: a goal and an outcome for this lane.

curl -sS -X POST https://memoshelf.com/v1/runs \
  -H "Authorization: Bearer $MEMOSHELF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"goal":"first run","outcome":"signed up","tags":["lane:my-assistant"]}'

What you should see: You get 201 and a run id.

{
  "id": "run_onboarding_example",
  "goal": "first run",
  "outcome": "signed up",
  "tools": [],
  "operator": "my-assistant",
  "created_at": "2026-09-28T17:00:00.000Z",
  "status": "succeeded",
  "started_at": "2026-09-28T17:00:00.000Z",
  "tags": [
    "lane:my-assistant"
  ]
}

The first store_note

Store a pinned standing-rules note tagged lane:<name>.

curl -sS -X POST https://memoshelf.com/v1/notes \
  -H "Authorization: Bearer $MEMOSHELF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"standing-rules","body":"Tag every write lane:<name>. Pin standing-rules pages.","tags":["lane:my-assistant"],"pinned":true}'

What you should see: You get 201 and a note id.

{
  "id": "note_onboarding_example",
  "title": "standing-rules",
  "body": "Tag every write lane:<name>. Pin standing-rules pages.",
  "tags": [
    "lane:my-assistant"
  ],
  "operator": "my-assistant",
  "created_at": "2026-09-28T17:00:00.000Z",
  "pinned": true
}

The first what_happened_last

Read the shelf back. After logging a run and storing a note, the runs array includes that run and the notes array lists the pinned note first.

curl -sS https://memoshelf.com/v1/what_happened_last?tags=lane:my-assistant -H "Authorization: Bearer $MEMOSHELF_API_KEY"

What you should see: The notes array lists the pinned note first.

{
  "markdown": "applied: {\"tags\":[\"lane:my-assistant\"]}\n\n## Runs\n- succeeded · first run — signed up\n\n## Notes\n- standing-rules: Tag every write lane:<name>. Pin standing-rules…",
  "tokens": 22,
  "n": 5,
  "truncated": false,
  "next_cursor": null,
  "runs": [
    {
      "id": "run_onboarding_example",
      "created_at": "2026-09-28T17:00:00.000Z",
      "goal": "first run",
      "outcome": "signed up",
      "status": "succeeded"
    }
  ],
  "notes": [
    {
      "id": "note_onboarding_example",
      "created_at": "2026-09-28T17:00:00.000Z",
      "body": "Tag every write lane:<name>. Pin standing-rules pages.",
      "title": "standing-rules",
      "tags": [
        "lane:my-assistant"
      ],
      "pinned": true
    }
  ],
  "notes_omitted": 0,
  "applied": {
    "tags": [
      "lane:my-assistant"
    ]
  }
}

Bounded writes

A lane-bounded key can only write its own lane. POST /v1/lanes/<lane>/notes and POST /v1/lanes/<lane>/runs make that bound write visible in the URL (a bounded key may only call its own lane). lane:team is writable only by an unrestricted key.

Rule

lane:<name> on everything, rules on standing-rules pages, pinned.

Agent prompt

You have one Memoshelf key for this lane. Before you write, read with lane=YOUR-AI-NAME (GET /v1/what_happened_last?lane=<name> for entries tagged lane:NAME in your shared workspace); then POST /v1/notes tagged lane:<name> (pin standing-rules pages) and read it back — the pinned note comes first.

Glossary

• operator = the public prefix of the key you created
• md = one-line digest, full text in notes[].body under max_chars default 4,000 max 80,000

Connect

1. In the chat client, add a custom connector / MCP server with URL https://memoshelf.com/mcp. There is no field for an API key — that is expected.
2. The client fetches /.well-known/oauth-protected-resource, then /.well-known/oauth-authorization-server, and registers itself at /oauth/register.
3. Sign in on the page that opens (same magic link as /app). Name the AI and click Allow. No API key is created or shown. The grant is bounded to that name.
4. After Allow, the client stores a Bearer token. Data tools (what_happened_last, notes) now authorize. Header-key auth (x-api-key or Authorization: Bearer ms_…) keeps working.
5. Revoke the grant on owner /app under Connected AIs. A 401 from /mcp carries WWW-Authenticate: Bearer resource_metadata=… so the client can rediscover.

What the warnings mean

A write always succeeds. warnings: ["no_read_before_write"] means this key had no what_happened_last, notes list, notes get, or MCP notes read in the last READ_WINDOW_MINUTES (default 30). Fix the prompt: read first, then write. warnings: ["process_claim_contradicted"] means the POST sent process: {"read_first": true} but the meter saw no read — drop the claim or actually read. Mode off on the key silences warnings. The record still stores read_before_write.

How your agent sets the alert destination

PATCH /v1/workspace with {"alert_webhook_url":"https://…","alert_email":"you@example.com"} (write key or signed-in session). MCP keys with settings_op: "alert" and the same fields. The webhook path delivers process.skipped_read and process.claim_contradicted with HMAC. Email alerts are not sent yet. Set alert_webhook_url to receive alerts today; alert_email is saved for when email alerts launch.

If something is off

{
  "error": "unauthorized",
  "code": "unauthorized",
  "fix": "Sign in or send a valid API key in Authorization or X-Api-Key.",
  "help": "/help#help-401"
}

{
  "markdown": "applied: {\"tags\":[\"lane:my-assistant\"]}\n\nNo recent runs or notes.",
  "tokens": 7,
  "n": 5,
  "truncated": false,
  "next_cursor": null,
  "runs": [],
  "notes": [],
  "notes_omitted": 0,
  "applied": {
    "tags": [
      "lane:my-assistant"
    ]
  }
}

{
  "error": "body_required",
  "code": "body_required",
  "fix": "Include body and try once more.",
  "help": "/help#help-400"
}