Marrow
Docs Sign in

Quickstart

One context. Every AI.

This Quickstart connects one small work note and retrieves the part a task needs. Direct HTTP is the canonical path. The Python client and CLI run the same ingest, job, and query contract; the TypeScript client adds the same typed contract for trusted Node.js applications. Hosted MCP is the recommended agent path, with local stdio available for clients that require it.

Use the exact public clients @marrowid/[email protected], @marrowid/[email protected], and marrowid==1.0.4; Python imports the client with from marrow import Marrow. HTTP is their semantic authority. Direct HTTP, Python, and CLI examples run in a trusted application process; keeping credentials there does not provide prompt-injection isolation for untrusted content. Use the OpenAPI document for the machine contract and the Native Memory API for the complete memory lifecycle.

Before you start

  1. Open the Marrow Account page and choose Create account.
  2. Create your account with email, Google, or Apple. Email signup sends an 8-digit verification code to the address you enter. Review the Privacy Notice and agree to the Terms of Use when you create the account.
  3. Continue to Console.
  4. Create an API key named Quickstart with ingest and query scopes.
  5. Copy the key into your secret store, confirm that you saved it, then continue back to this Quickstart.

Account creation starts a browser session. Console manages API keys, usage, and connected context. The customer API key authorizes product requests; it does not sign you in to either surface. Return through the Marrow Account page when you need to sign in again.

Use the same sign-in method you used when creating the account. Marrow does not link Google, Apple, and email/password accounts merely because they report the same email address. This protects an existing account from being claimed through a different credential. An invitation link is optional and only prefills the invited email address.

On macOS, you can instead connect an explicit CLI account session and create the same key:

marrow auth login
# Review the account, short code, expiry, and consequence in Console, then approve.
marrow auth status
marrow api-keys create --name "Quickstart" --scope ingest --scope query

On Linux or Windows, create the key in Console. Device sign-in is macOS-only; product commands remain available through MARROW_API_KEY on every supported platform.

1. Store the API key

Keep the copy-once value in a shell, process manager, or secret store. Never put it in source code, browser code, command arguments, MCP JSON, screenshots, logs, or chat.

# macOS or Linux
export MARROW_API_BASE_URL="https://api.marrow.id"
export MARROW_API_KEY="<copy-once key>"

# Windows PowerShell
$env:MARROW_API_BASE_URL = "https://api.marrow.id"
$env:MARROW_API_KEY = "<copy-once key>"

2. Create one deterministic context note

The same local file is used by every client example:

printf '%s\n' \
  '# Launch update preference' \
  'Avery prefers project updates that begin with the decision and use short bullets.' \
  'The open launch risk is onboarding copy approval.' \
  > marrow-quickstart.md

The task question will be: How should Avery structure the launch update, and what risk is still open?

3. Run the canonical HTTP path

Encode the file, submit it once, and keep the returned job.id:

CONTENT_BASE64="$(base64 < marrow-quickstart.md | tr -d '\n')"

curl -sS -X POST "$MARROW_API_BASE_URL/v1/ingest/file" \
  -H "Authorization: Bearer $MARROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\":\"marrow-quickstart.md\",\"contentType\":\"text/markdown\",\"contentBase64\":\"$CONTENT_BASE64\",\"dryRun\":false,\"datedAt\":\"2026-07-12\",\"idempotencyKey\":\"quickstart-context-20260712\"}"

Live ingest requires a caller-owned idempotencyKey between 8 and 160 characters. Reuse the same key only when retrying this exact submission.

Poll the job until its status is succeeded, failed, or quarantined:

export MARROW_JOB_ID="<job.id from the ingest response>"

curl -sS "$MARROW_API_BASE_URL/v1/ingest/jobs/$MARROW_JOB_ID" \
  -H "Authorization: Bearer $MARROW_API_KEY"

After the job succeeds, retrieve the context the task needs:

curl -sS -X POST "$MARROW_API_BASE_URL/v1/query" \
  -H "Authorization: Bearer $MARROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"How should Avery structure the launch update, and what risk is still open?","limit":5,"evidenceLimit":3}'

A useful result has answer.status: "partial" and includes the supporting citations and excerpts. If the connected context cannot support the request, Marrow returns insufficient_evidence and names the limitation instead of filling the gap.

4. Run the same path with Python

Install Python client version 1.0.4, then verify the import and version:

python -m pip install marrowid==1.0.4
python -c "from marrow import Marrow, __version__; print(Marrow.__name__, __version__)"

import os
from marrow import Marrow

client = Marrow(
    api_key=os.environ["MARROW_API_KEY"],
    host=os.environ["MARROW_API_BASE_URL"],
)

queued = client.ingest.file(
    "marrow-quickstart.md",
    content_type="text/markdown",
    dry_run=False,
    dated_at="2026-07-12",
    idempotency_key="quickstart-python-20260712",
)
job = client.ingest.jobs.wait(queued["job"]["id"])

if job["job"]["status"] == "succeeded":
    result = client.query(
        "How should Avery structure the launch update, and what risk is still open?",
        limit=5,
        evidence_limit=3,
    )
    print(result["answer"]["status"], result["answer"]["text"])

See App integration for the full client contract and error handling.

5. Run the same path with TypeScript

Install the TypeScript client and run it in a trusted Node.js process:

npm install @marrowid/[email protected]

import { readFile } from "node:fs/promises";
import { Marrow } from "@marrowid/sdk";

const marrow = new Marrow({
  apiKey: process.env.MARROW_API_KEY!,
  baseURL: process.env.MARROW_API_BASE_URL,
});

const queued = await marrow.ingest.file({
  filename: "marrow-quickstart.md",
  contentType: "text/markdown",
  content: await readFile("marrow-quickstart.md"),
  dryRun: false,
  datedAt: "2026-07-12",
  idempotencyKey: "quickstart-typescript-20260712",
});

if (queued.schemaVersion === "marrow-ingest-job-v1") {
  const job = await marrow.ingest.jobs.wait(queued.job.id);
  if (job.job.status === "succeeded") {
    const result = await marrow.query(
      "How should Avery structure the launch update, and what risk is still open?",
      { limit: 5, evidenceLimit: 3 },
    );
    console.log(result.answer.status, result.answer.text);
  }
}

6. Run the same path with the CLI

Install CLI version 1.0.4:

npm install -g @marrowid/[email protected]
marrow --version
marrow doctor

Product commands read MARROW_API_KEY; the CLI account session is not the product credential.

marrow ingest file ./marrow-quickstart.md \
  --dated-at 2026-07-12 \
  --idempotency-key quickstart-cli-20260712

marrow ingest jobs show <job-id>

marrow query \
  "How should Avery structure the launch update, and what risk is still open?" \
  --limit 5 \
  --evidence-limit 3

Human-readable output is the default. Add --json when automation needs the structured response.

7. Connect an agent with hosted MCP

Use the canonical endpoint in a remote-capable MCP client:

https://mcp.marrow.id

Choose the credential path that matches who operates the client:

  • Interactive authorization is the recommended path for a person connecting an MCP client to an existing Marrow account. The client discovers authorization from the endpoint, opens the consent flow, and stores its own credential. The connection grants the hosted 15-tool resource and remains visible and revocable in Console.
  • Customer API key is appropriate for a server-managed MCP client. Create a dedicated key with the minimum memory scopes and configure it through the client's protected authorization-header or secret setting. Never put the key in a URL, prompt, or shareable client configuration.

Clients with official MCP registry installation can select id.marrow/marrow; the published descriptor points to this same hosted URL and also identifies the CLI stdio compatibility package.

Every transport advertises these exact 15 tools:

create_peer
ask_peer
get_peer_context
get_peer_representation
create_session
add_messages_to_session
get_session_context
query_claims
list_claims
get_claim
get_claim_history
update_claim
delete_claim
get_event_status
get_queue_status

After connecting, create peer avery and session quickstart. Add the two statements from marrow-quickstart.md with the succeeded ingest job ID from step 3 in source_ids. Wait for the event to finish, then ask: “How should Avery structure the launch update, and what risk is still open?” Show the supporting context or say what is missing.

Disconnecting an interactively authorized MCP application in Console revokes its access without changing browser sessions or customer API keys. Interactive authorization grants the full hosted 15-tool resource. Use a dedicated customer API key when a server-managed client needs narrower memory scopes.

8. Use local stdio compatibility when required

marrow mcp ships in the CLI package for clients that require a local stdio server. It calls the same hosted Marrow account and exposes the same tool registry; it does not create separate local memory.

Native memory tools require a dedicated customer API key with memory.read and memory.write. The MCP client process must inherit the key through MARROW_API_KEY; never paste the raw key into client JSON.

Verify the local entrypoint:

marrow mcp --help

Use this configuration shape in an MCP-capable local client:

{
  "mcpServers": {
    "marrow": {
      "command": "marrow",
      "args": ["mcp"],
      "env": {
        "MARROW_WORKSPACE": "default"
      }
    }
  }
}

A coding agent can prepare that non-secret command and workspace setup without an API key. The human then configures MARROW_API_KEY in the host-managed MCP environment, restarts the host, and resubmits the task. The resumed agent should discover the exact 15-tool Marrow registry and must never ask anyone or any model to print the key. The full two-phase prompt is in App integration.

Then ask the local agent to:

Use Marrow over local stdio. Create peer "avery" and session "quickstart".
Add the two statements from marrow-quickstart.md to that session with the
succeeded ingest job ID from step 3 in source_ids. Wait for the event to finish,
then ask: "How should Avery structure the launch update, and
what risk is still open?" Show the supporting context or say what is missing.

The client should discover the exact 15-tool registry listed above.

Check your result and recover safely

  • If a job is still queued or running, keep polling before querying.
  • If a live retry is needed, reuse the same idempotency key for the same bytes.
  • If the key has the wrong scope, create or rotate a narrowly scoped key in Console; do not broaden a key silently.
  • If clipboard access is denied, select the copy-once key manually before confirming that it is saved.
  • If a key is lost or exposed, revoke it. Revocation does not sign out the active Console session.
  • Review remaining credits and recent activity in Console.

See Usage and credits for credit and quota behavior, Marrow CLI for the complete command surface, and the Account API reference for key lifecycle details.