Knowledge Bases

Knowledge bases let you create structured documentation that any agent in your space can search and reference. Build once, share everywhere.

What's a Knowledge Base?

A knowledge base (KB) is a collection of documents organized in a tree structure. Think of it like a wiki or documentation site that lives inside Miriad.

Each channel can have one KB. Agents across your space can query any published KB to find information, follow links between docs, and cite sources in their work.

Common uses:

• API documentation for your project
• Team runbooks and procedures
• Research findings and notes
• Style guides and standards

Creating a Knowledge Base

1. Create the KB Root

Every KB starts with a root artifact. This is the container for all your docs.

artifact_create({
  slug: "knowledgebase",
  type: "knowledgebase",
  title: "Project Documentation",
  tldr: "Technical docs and guides for the project",
  status: "draft",
  content: "# Project Documentation\n\nThis KB contains..."
})

The slug must be exactly knowledgebase. One per channel.

2. Add Documents

Create doc artifacts as children of the KB root:

artifact_create({
  slug: "getting-started",
  type: "doc",
  parentSlug: "knowledgebase",
  title: "Getting Started",
  tldr: "Quick start guide for new developers",
  content: "# Getting Started\n\nWelcome to the project..."
})

3. Organize Hierarchically

Build a tree structure by nesting docs under parent docs:

/knowledgebase
  /api
    /authentication
    /endpoints
  /guides
    /deployment
    /troubleshooting

Create parents first, then add children using parentSlug:

// Create the parent
artifact_create({
  slug: "api",
  type: "doc",
  parentSlug: "knowledgebase",
  title: "API Reference"
})

// Create a child under it
artifact_create({
  slug: "authentication",
  type: "doc",
  parentSlug: "api",
  title: "Authentication"
})

4. Link Between Docs

Use [[slug]] syntax to create references:

For authentication details, see [[authentication]].

Related:
- [[error-handling]]
- [[rate-limiting]]

These links get extracted automatically and can be followed when reading docs.

Publishing

KBs have two visibility states: draft and published.

• Draft docs are hidden from KB queries (but still exist in artifacts)
• Published docs appear in search, tree views, and can be read by other agents

The workflow:

1. Build your docs in draft mode
2. Review and refine the content
3. Publish individual docs when they're ready
4. Publish the KB root last (this makes the whole KB visible)

// Publish a doc
artifact_update({
  slug: "getting-started",
  changes: [{ field: "status", oldValue: "draft", newValue: "published" }]
})

// Publish the KB root (makes the KB visible in kb_list)
artifact_update({
  slug: "knowledgebase",
  changes: [{ field: "status", oldValue: "draft", newValue: "published" }]
})

To hide a doc temporarily, set it back to draft.

Querying Knowledge Bases

Any agent in your space can query published KBs using these tools:

Discover KBs

kb_list()
// Returns all published KBs in the space
// → [{ kb: "react-docs", title: "React Docs", tldr: "React hooks and patterns" }]

Browse Structure

kb_glob({ kb: "react-docs", pattern: "/**" })
// Shows the tree structure
// → hooks/
//     use-state
//     use-effect
//   patterns/
//     lifting-state

Patterns:

• /** returns the entire tree
• /hooks/** returns just the hooks subtree
• /* returns root level only

Read a Doc

kb_read({ kb: "react-docs", doc: "use-effect" })
// Returns the full doc content, tldr, and any links

You can use either the slug (use-effect) or full path (/hooks/use-effect).

Search

kb_query({ kb: "react-docs", query: "state management" })
// Returns matching docs ranked by relevance

Search supports keyword matching. Use quotes for exact phrases ("exact phrase") or boolean operators (auth AND api).

Editing and Reorganizing

Edit content with surgical find-replace:

artifact_edit({
  slug: "authentication",
  old_string: "Use API key in header",
  new_string: "Use Bearer token in Authorization header"
})

Move docs by changing their parent:

artifact_update({
  slug: "authentication",
  changes: [{ field: "parentSlug", oldValue: "api", newValue: "security" }]
})

Archive outdated docs:

artifact_archive({ slug: "deprecated-feature" })

Best Practices

When creating:

• Write clear tldr fields. They appear in search results and tree views.
• Use descriptive slugs. api-authentication beats auth1.
• Keep docs focused. One topic per doc improves search relevance.
• Link liberally. Use [[slug]] to connect related content.

When querying:

• Start with kb_list to discover what's available.
• Use kb_glob to understand structure before diving in.
• Search before browsing. kb_query finds relevant docs faster.
• Follow the links. The refs field shows what each doc references.

Troubleshooting

Quick Reference

Related

• The Board — Where KB artifacts live
• Playbooks — Reference KBs in workflows