Marrow

Evidence-grounded, graph-connected, correctable memory for agents.

Open source Open in the app JSON README (API)

About

Evidence-grounded, graph-connected, correctable memory for agents.

Details

Kind: MCP servers
Topic: AI, RAG & memory
Publisher: id.marrow
Origin: official
Category: ferramentas
Transport: http
Version: 1.0.10
Added: 2026-08-29 03:01:35
Updated: 2026-08-29 03:01:35
Origin id: id.marrow/marrow

README

# Marrow CLI

Use the Marrow CLI to add records, run queries, manage API keys, and start MCP
over stdio. Connect remote-capable MCP clients directly to
`https://mcp.marrow.id`; use `marrow mcp` when a client requires a local stdio
server. Version `1.0.11` uses separate credentials for account and product work:

- a CLI session authorizes human account and API-key management;
- `MARROW_API_KEY` authorizes product commands and local MCP;
- non-secret defaults live in the Marrow config file;
- customer keys never enter command arguments or Marrow config.

The CLI runs inside a trusted application process. Keep returned text as data
and preserve citations, warnings, and `insufficient_evidence` when another
model consumes it. See the [OpenAPI document](../openapi.yaml) and the
[Native Memory API](../api-reference/memory.md).

## Install

Install CLI version 1.0.11 with Node.js 20 or newer:

```bash
npm install -g @marrowid/cli@1.0.11
npm exec --package @marrowid/cli@1.0.11 -- marrow --version
marrow --version
marrow --help
```

If an older global binary is already on `PATH`, the `npm exec` check verifies
1.0.11 independently before you replace the global install.

## First setup

Create the local config, set only the defaults you need, then inspect the local
setup without making a network request:

```bash
marrow init
marrow config --workspace default
marrow doctor
```

`marrow init` and `marrow config` write only the API base URL and workspace
default. `marrow doctor` reports package, platform, config permissions,
and whether `MARROW_API_KEY` is present. It reports presence, never the key.

An upgraded client that finds a legacy plaintext `apiKey` refuses every network
request. Set `MARROW_API_KEY` through your shell, process manager, or secret
store; the next network command removes only the legacy key field atomically and
preserves the non-secret defaults.

## Credentials and platform support

## Auth

Customer API keys are for apps and automation, not for signing in to this local CLI.

Device sign-in is available on macOS in version 1.0.11:

```bash
marrow auth login
marrow auth status
```

The browser flow must show the account, short code, expiry, and consequence
before deliberate approval. Login or signup alone does not approve a device.
Linux and Windows reject `marrow auth login` before sending a device request;
use the Console for account management and an environment customer key for
product commands and local MCP.

Sign out the device when it should no longer manage the account:

```bash
marrow auth logout
```

Logout clears the CLI session. It does not revoke or rotate customer API keys.

## Add records

Product commands require `MARROW_API_KEY`. Preview a source before writing:

```bash
marrow ingest url https://example.com/onboarding-note --dry-run --dated-at 2026-05-16
marrow ingest file ./onboarding.md --dry-run --dated-at 2026-05-16
```

Submit it when the preview is correct:

```bash
marrow ingest url https://example.com/onboarding-note --dated-at 2026-05-16 --idempotency-key onboarding-note-2026-05-16
marrow ingest file ./onboarding.md --dated-at 2026-05-16 --idempotency-key onboarding-file-2026-05-16
```

Use the authored, published, or otherwise relevant date. A live submission
requires a caller-owned idempotency key between 8 and 160 characters. Reuse the
same key when retrying the same submission; use a new key for a different
source or changed content. Dry-runs may omit it. Poll the returned job until it
reaches `succeeded`, `failed`, or `quarantined`:

```bash
marrow ingest jobs list --limit 5
marrow ingest jobs show <job-id>
```

## Query Marrow

Ask one concrete question after processing succeeds:

```bash
marrow query "What should this workflow remember about onboarding?" \
--mode answer \
--preset accuracy
```

The response includes citations, source labels, excerpts, and warnings. If
Marrow returns `insufficient_evidence`, add relevant material or continue
without Marrow.

Native workspace, peer, session, claim, event, and queue commands use the same
environment customer key. Use each command's `--help` option for its exact
arguments.

## Manage API keys on macOS

With an active CLI account session:

```bash
marrow api-keys list
marrow api-keys create --name "Production app"
marrow api-keys create --name "Query only" --scope query
marrow api-keys create --name "Memory app" --scope ingest --scope query --scope memory.read --scope memory.write
marrow api-keys rotate <key-id>
marrow api-keys revoke <key-id>
```

Omit scope flags for the `ingest,query` default. Available scopes are `ingest`,
`query`, `memory.read`, and `memory.write`. Create and rotate show a new secret
once; list and revoke never reveal it.

## MCP

Connect remote-capable clients to:

```text
https://mcp.marrow.id
```

People can use interactive authorization to connect an MCP client to their
Marrow account. A server-managed client can use an API key with the required
memory scopes. Connected applications remain visible and revocable in Console.

Use `marrow mcp` when the MCP client requires a local stdio server. It connects
to the same Marrow account and exposes the same 14 tools as Hosted MCP.

`marrow mcp` is the shipped local newline-delimited JSON-RPC entrypoint over
stdio. Start the MCP client from a process that already inherits
`MARROW_API_KEY`; do not paste a key into MCP client JSON.

```bash
marrow mcp
```

The server exposes 14 tools for query, peer, session, claim, event, queue, and
representation workflows. The canonical query tool requires `query`;
native-memory reads require `memory.read`; writes require `memory.write`.
Wrong-scope and revoked-key errors are returned to the client. See the
[MCP tool table](./app-context.md#mcp-tools) and the short
[coding-agent prompt](./app-context.md#prompt-for-a-coding-agent).

The local MCP server and tool schemas are available with the CLI. Calls to
native memory remain scoped by `memory.read` and `memory.write`.

## Output and troubleshooting

Human-readable output is the default. Use `--json` only when automation needs a
stable structured response.

- Missing key: configure `MARROW_API_KEY` in the invoking process.
- Missing live-ingest replay key: add `--idempotency-key <key>`, or use
`--dry-run` while previewing.
- Legacy plaintext key: supply the environment key once so the client can
remove the legacy config field before network use.
- Wrong scope: rotate or create a key with only the required scope.
- Revoked key: replace the environment value; do not restore the old key.
- Device login on Linux or Windows: use the Console for account work.
- Local setup uncertainty: run `marrow doctor`; it performs no network request.

Proprietary. `UNLICENSED` means the package is a distribution channel, not an
open-source grant.

Marrow

About

Details

README

More