Docs

Documentation

Guides, references, and resources for building with XMDB.

Documentation Menu

CLI Reference

Complete reference for the xmdbctl command-line interface.

Installation

bash
# macOS / Linux
curl -fsSL https://get.xmdb.cloud/install.sh | sh

# Homebrew
brew install xmdb/tap/xmdbctl

# Verify installation
xmdbctl --version

Authentication

login

Authenticate with the XMDB API.

bash
xmdbctl login <base-url> --token <token> [--scope <scope>]

Examples:

bash
# Basic login
xmdbctl login https://api.xmdb.cloud --token $XMDB_API_TOKEN

# Login with default scope
xmdbctl login https://api.xmdb.cloud --token $XMDB_API_TOKEN --scope production

status

Check connection status and display identity info.

bash
xmdbctl status

Outputs: role, workspace, scopes, API version, policy hash.

whoami

Display authenticated identity details.

bash
xmdbctl whoami

Memory Operations

capture

Store a memory item.

bash
xmdbctl capture "<content>" [options]

Options:

| Flag | Description | |------|-------------| | --source-kind | Source type (e.g., manual, deployment, meeting) | | --source-ref | Reference identifier (e.g., URL, ticket ID) | | --workspace | Override default workspace | | --scope | Override default scope | | --force-store | Skip deduplication check |

Examples:

bash
# Simple capture
xmdbctl capture "Started project refactoring"

# With metadata
xmdbctl capture "Deployed v2.0.0" --source-kind deployment --source-ref "v2.0.0"

# Force store (bypass dedup)
xmdbctl capture "Repeated message" --force-store

items

List memory items.

bash
xmdbctl items [options]

Options:

| Flag | Description | |------|-------------| | --limit | Maximum items to return (default: 50) | | --source-kind | Filter by source kind | | --workspace | Override default workspace | | --scope | Override default scope |

get-item

Get a specific item by ID.

bash
xmdbctl get-item --item <item-id>

item history

Get revision history for an item.

bash
xmdbctl item history --item <item-id> [--limit 20]

Retrieval

query

Search memory items.

bash
xmdbctl query --q "<search-term>" [options]

Options:

| Flag | Description | |------|-------------| | --limit | Maximum results (default: 10) | | --explain | Include match context and policy info |

pack

Build a deterministic context pack.

bash
xmdbctl pack --q "<query>" [options]

Options:

| Flag | Description | |------|-------------| | --token-budget | Maximum tokens in pack (default: 4000) | | --include-pins | Include pinned items (default: true) | | --explain | Include pack metadata |

Example:

bash
xmdbctl pack --q "project decisions" --explain

Explain output

Explain mode adds match, policy, signature, and revision context to /query and /pack results. Enable it with --explain (CLI) or explain=true (API).

bash
xmdbctl query --q "alice" --explain
xmdbctl pack --q "alice" --explain

Example explain payload:

bash
{
  "explain": {
    "match": { "mode": "fts5", "query": "alice", "fts_match": true },
    "policy": {
      "allowed": true,
      "checks": [{ "code": "source_kind_allowlist", "passed": true }]
    },
    "signature": { "status": "verified" },
    "revision": {
      "stable_item_id": "stable-42",
      "event_id": "01HXYZT6Q9K2B9V9J7F8M3J1A2",
      "op": "create",
      "is_latest": true
    }
  }
}

Field meanings:

| Field | Description | |-------|-------------| | explain.match | Match mode and query details (includes fts_match) | | explain.policy | Allowed/denied plus policy checks and pass/fail status | | explain.signature | Signature status | | explain.revision | Stable item linkage, event ID, op, and latest flag |

Hybrid retrieval (API/SDK)

When calling /query or /pack, query_mode=hybrid requires both q and query_embedding. Hybrid mode uses deterministic FTS candidates and then exact cosine re-rank; candidates without embeddings for the selected model are dropped. If FTS returns 0 candidates, hybrid falls back to pure vector search.

Pins

pin

Pin an item to always include in packs.

bash
xmdbctl pin --item <item-id> --priority <1-10> [--note "reason"]

unpin

Remove a pin.

bash
xmdbctl unpin --item <item-id>

pins

List all pins.

bash
xmdbctl pins [--limit 50]

Audit

audit bundle

Export an audit bundle for a request.

bash
xmdbctl audit bundle --request-id <id> --out bundle.json

verify-pack

Verify a pack's hash and signature.

bash
xmdbctl verify-pack --file pack.json

# Or via stdin
cat pack.json | xmdbctl verify-pack --stdin

Sync

pull

Pull events from a node to a file.

bash
xmdbctl pull --out events.jsonl

push

Push events from a file to a node.

bash
xmdbctl push --in events.jsonl

Token Management

token create

Create a new scoped token (admin only).

bash
xmdbctl token create --role <role> [--scope <scope>]

Roles: admin, read, write, sync

Note: This command requires an existing admin token. If you don't have one, get your initial token from the Dashboard first.

token list

List tokens for the current scope.

bash
xmdbctl token list

token revoke

Revoke a token by ID prefix.

bash
xmdbctl token revoke --id <token-id-prefix>

Advanced

tombstone

Mark an item as deleted (creates tombstone event).

bash
xmdbctl tombstone --item <item-id> --reason "user request"

upsert

Update an existing item (creates new revision).

bash
xmdbctl upsert --item <item-id> --content "Updated content"

ingest

Bulk import from various sources.

bash
xmdbctl ingest --source <connector> [options]

smoke

Run smoke tests against the API.

bash
xmdbctl smoke

Global Flags

| Flag | Description | |------|-------------| | --base | Override API base URL | | --token | Override authentication token | | --workspace | Override workspace ID | | --scope | Override scope ID | | --json | Output in JSON format | | --verbose | Enable verbose logging |

Environment Variables

| Variable | Description | |----------|-------------| | XMDB_BASE_URL | Default API base URL | | XMDB_API_TOKEN | Default authentication token | | XMDB_WORKSPACE_ID | Default workspace | | XMDB_SCOPE | Default scope |

Beliefs

Track agent conclusions with provenance.

| Command | Description | |---------|-------------| | xmdbctl beliefs create | Create a new belief | | xmdbctl beliefs list | List beliefs (supports --as-of, --status, --agent-id) | | xmdbctl beliefs get | Get a specific belief by ID | | xmdbctl beliefs invalidate | Invalidate a belief with a reason | | xmdbctl beliefs diff | Show belief changes between two timestamps |

Examples

bash
# Create a belief
xmdbctl beliefs create --workspace prod --scope project \
  --receipt-id rcp_xxx \
  --conclusion "User prefers dark mode" \
  --confidence 0.9 \
  --agent-id my-agent

# List beliefs at a point in time
xmdbctl beliefs list --workspace prod --scope project \
  --as-of "2025-01-15T00:00:00Z"

# Invalidate a belief
xmdbctl beliefs invalidate --workspace prod --scope project \
  --belief-id bel_xxx \
  --reason "User corrected this assumption"

Checkpoints

Merkle tree checkpoints for cryptographic proofs.

| Command | Description | |---------|-------------| | xmdbctl checkpoints create | Create a Merkle checkpoint | | xmdbctl checkpoints list | List checkpoints | | xmdbctl checkpoints show | Show checkpoint details | | xmdbctl checkpoints proof | Generate inclusion proof for an event | | xmdbctl checkpoints verify | Verify an inclusion proof | | xmdbctl checkpoints anchor | Anchor checkpoint to RFC 3161 TSA | | xmdbctl checkpoints anchor-status | Check anchor status | | xmdbctl checkpoints anchor-verify | Verify anchor token |

Examples

bash
# Create checkpoint
xmdbctl checkpoints create --workspace prod --scope project

# Generate proof
xmdbctl checkpoints proof --workspace prod --scope project \
  --checkpoint-id chk_xxx \
  --event-id evt_yyy

# Verify offline (no server needed)
xmdbctl checkpoints verify --local --proof-file proof.json

# Anchor to external TSA
xmdbctl checkpoints anchor --checkpoint-id chk_xxx

# Verify anchor
xmdbctl checkpoints anchor-verify --checkpoint-id chk_xxx

Federation

Share beliefs between agents with cryptographic proofs.

| Command | Description | |---------|-------------| | xmdbctl federation share | Share events/beliefs with another agent | | xmdbctl federation receive | Receive and validate incoming shares | | xmdbctl federation receipts | List federation receipts | | xmdbctl federation peers | List known federation peers |

Examples

bash
# Share a belief with another agent
xmdbctl federation share --workspace prod --scope project \
  --peer-id agent_yyy \
  --belief-id bel_xxx

# List pending incoming shares
xmdbctl federation receive --workspace prod --scope project --list

# Accept an incoming share
xmdbctl federation receive --workspace prod --scope project \
  --share-id share_xxx --accept

# View federation receipts
xmdbctl federation receipts --workspace prod --scope project

Trust Policies

Configure trust rules for federation.

| Command | Description | |---------|-------------| | xmdbctl trust policy create | Create a trust policy | | xmdbctl trust policy list | List trust policies | | xmdbctl trust policy update | Update a trust policy | | xmdbctl trust policy delete | Delete a trust policy |

Examples

bash
# Create a trust policy
xmdbctl trust policy create --workspace prod --scope project \
  --name "prod-agents" \
  --peer-pattern "agent_*" \
  --action accept \
  --require-anchored true

# List policies
xmdbctl trust policy list --workspace prod --scope project

# Update policy
xmdbctl trust policy update --workspace prod --scope project \
  --policy-id pol_xxx \
  --action review

Next Steps

Ready to add durable memory?

Get started with XMDB today.

Contact UsRead Documentation