---

name: using-xdb description: Use XDB CLI to store and manage structured data. Use when you need to persist data, create schemas for tracking information (issues, scraped data, metrics, logs), or organize data by namespace for different projects/users/contexts. allowed-tools: Bash(xdb:*), Write

Using XDB CLI for Data Management

Run xdb --help for command syntax and flags.

URI Format

xdb://NAMESPACE/SCHEMA/ID#ATTRIBUTE

| Component | Required | Example | | --------- | ------------ | --------------------------------------------- | | Namespace | Yes | agent.scraper, user.john, project.myapp | | Schema | For data ops | articles, issues, tasks | | ID | For records | article-123, issue-1 | | Attribute | Optional | #title, #status, #author.name |

Namespace Strategy

| Pattern | Use Case | Example | | ---------------- | ------------------- | ----------------------------------- | | agent.<name> | Agent-specific data | agent.scraper, agent.researcher | | user.<id> | Per-user data | user.john, user.admin | | project.<name> | Project data | project.webapp, project.api | | team.<name> | Team shared data | team.engineering, team.support | | org.<name> | Organization data | org.acme, org.internal |

Schema Definition Format

Modes:

| Mode | Behavior | | ---------- | ------------------------------------------------------- | | flexible | Accepts any attributes (default, no schema file needed) | | strict | Only allows attributes defined in schema | | dynamic | Auto-infers and adds new fields from data |

Flexible schema:

xdb make-schema xdb://agent.scraper/articles

Strict or dynamic schema with JSON definition:

{
  "name": "Article",
  "mode": "strict",
  "fields": [
    { "name": "title", "type": "STRING" },
    { "name": "tags", "type": "ARRAY", "array_of": "STRING" },
    {
      "name": "metadata",
      "type": "MAP",
      "map_key": "STRING",
      "map_value": "STRING"
    },
    { "name": "author.name", "type": "STRING" },
    { "name": "author.email", "type": "STRING" }
  ]
}

Types: STRING, INTEGER, UNSIGNED, FLOAT, BOOLEAN, TIME, BYTES, ARRAY, MAP

Nested fields: Use dot notation (author.name, stats.views)

Nanoid Helper

Generate unique IDs:

nanoid() { openssl rand -base64 12 | tr -dc 'a-zA-Z0-9' | head -c 21; }

Example Use Cases

| Use Case | Mode | Namespace | Schema | | ------------------- | ---------- | ------------------ | --------------- | | Web scraping | flexible | agent.scraper | pages | | Issue tracking | strict | project.<name> | issues | | Research notes | dynamic | agent.researcher | notes | | API cache | flexible | agent.api | cache | | Conversation memory | dynamic | agent.memory | conversations | | Bookmarks | flexible | user.<id> | bookmarks | | Code snippets | strict | team.<name> | snippets | | Meeting notes | dynamic | org.<name> | meetings | | Error logs | dynamic | project.<name> | errors | | Feature flags | strict | project.<name> | flags |

Workflow Examples

• Web Scraper Agent - Store scraped pages
• Issue Tracker Agent - Track issues with strict schema
• Metrics Tracking Agent - Time-series metrics
• Multi-User Task Manager - Per-user namespaces