Knowledge

Knowledge items with citations, proposals, reviews and versions.

Start with: knowledge_search, knowledge_create, knowledge_propose, knowledge_review.

10 operations. Discover them from an agent with agentdb_capabilities {"category": "knowledge"}.

#`knowledge_create`

stable added in 1.0.0-rc.6 changes data

Store a fact, decision, document or note with sources. Sources: file (fil_…, excerpt, locator e.g. 'page 3'), record (rec_…), item (another knowledge item), url or quoted text. confidence 0..1; review_after marks it stale later. New items are drafts; owners/admins (not agents) may create trusted ones.

MCP tool: knowledge_create
REST: POST /v1/workspaces/{ws}/knowledge scope records:write
CLI: agentdb knowledge create

Arguments

Argument	Type	Required	Description
`kind`	`"document" \| "fact" \| "decision" \| "note"`		string, one of: document, fact, decision, note, default "fact"
`title`	`string`	yes	Title of the knowledge article. (min length 1, max length 300)
`body`	`string`		string, up to 200000 characters, default ""
`sources`	`object[]`		object[], up to 20 items, default []
`confidence`	`number`		number, 0–1
`tags`	`string[]`		string[], up to 20 items, default []
`review_after`	`string`		string
`trusted`	`boolean`		boolean, default false
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "knowledge_create",
  "arguments": {
    "kind": "fact",
    "title": "Example Ltd pays in 30 days",
    "body": "Payment terms are net 30.",
    "sources": [
      {
        "type": "record",
        "record_id": "rec_example",
        "excerpt": "payment_terms: net 30"
      }
    ],
    "tags": [
      "billing"
    ]
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "knowledge_create",
    "arguments": {
      "kind": "fact",
      "title": "Example Ltd pays in 30 days",
      "body": "Payment terms are net 30.",
      "sources": [
        {
          "type": "record",
          "record_id": "rec_example",
          "excerpt": "payment_terms: net 30"
        }
      ],
      "tags": [
        "billing"
      ]
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/knowledge" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"fact","title":"Example Ltd pays in 30 days","body":"Payment terms are net 30.","sources":[{"type":"record","record_id":"rec_example","excerpt":"payment_terms: net 30"}],"tags":["billing"]}'

CLI

agentdb knowledge create [options]

#`knowledge_delete`

stable added in 1.0.0-rc.6 changes data destructive

Archive a knowledge item. Hidden from search, restorable; purge=true with confirm=true removes it for good (owners/admins; refused while other items cite it).

MCP tool: knowledge_delete
REST: DELETE /v1/workspaces/{ws}/knowledge/{item} scope records:write
CLI: agentdb knowledge delete

Arguments

Argument	Type	Required	Description
`purge`	`boolean`		boolean, default false
`confirm`	`boolean`		boolean, default false
`item_id`	`string`	yes	Knowledge item id (kno_...)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "knowledge_delete",
  "arguments": {
    "item_id": "kno_example"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "knowledge_delete",
    "arguments": {
      "item_id": "kno_example"
    }
  }
}

REST

curl -s -X DELETE "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/knowledge/kno_example" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

CLI

agentdb knowledge delete [options] <item_id>

#`knowledge_get`

stable added in 1.0.0-rc.6 read-only

One knowledge item. Current version, sources (still there? extraction status) and pending proposals.

MCP tool: knowledge_get
REST: GET /v1/workspaces/{ws}/knowledge/{item} scope records:read
CLI: agentdb knowledge get

Arguments

Argument	Type	Required	Description
`item_id`	`string`	yes	Knowledge item id (kno_...)
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "knowledge_get",
  "arguments": {
    "item_id": "kno_example"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "knowledge_get",
    "arguments": {
      "item_id": "kno_example"
    }
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/knowledge/kno_example" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb knowledge get [options] <item_id>

#`knowledge_list`

stable added in 1.0.0-rc.6 read-only

List knowledge items. Filter by kind, status, tag, cited source (cites: file:<id>, record:<id>, item:<id>, url:<url>) or pending_review.

MCP tool: knowledge_list
REST: GET /v1/workspaces/{ws}/knowledge scope records:read
CLI: agentdb knowledge list

Arguments

Argument	Type	Description
`kind`	`"document" \| "fact" \| "decision" \| "note"`	string, one of: document, fact, decision, note
`status`	`"draft" \| "trusted" \| "archived"`	string, one of: draft, trusted, archived
`tag`	`string`	string, up to 50 characters
`cites`	`string`	string, up to 2100 characters
`pending_review`	`boolean`	boolean
`limit`	`integer`	integer, 1–200, default 50
`cursor`	`string`	string, up to 64 characters
`workspace`	`string`	Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "knowledge_list",
  "arguments": {
    "kind": "fact",
    "tag": "billing",
    "limit": 20
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "knowledge_list",
    "arguments": {
      "kind": "fact",
      "tag": "billing",
      "limit": 20
    }
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/knowledge" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb knowledge list [options]

#`knowledge_propose`

stable added in 1.0.0-rc.6 changes data

Propose a change or contradiction. change=contradiction, with a reason and sources. Nothing changes until an owner/admin accepts it with knowledge_review.

MCP tool: knowledge_propose
REST: POST /v1/workspaces/{ws}/knowledge/{item}/proposals scope records:write
CLI: agentdb knowledge propose

Arguments

Argument	Type	Required	Description
`change`	`"update" \| "contradiction"`		string, one of: update, contradiction, default "update"
`title`	`string`		Title shown to people. (min length 1, max length 300)
`body`	`string`		string, up to 200000 characters
`sources`	`object[]`		object[], up to 20 items
`confidence`	`number`		number, 0–1
`reason`	`string`	yes	Why, in one or two sentences. (min length 1, max length 2000)
`item_id`	`string`	yes	Knowledge item id (kno_...)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "knowledge_propose",
  "arguments": {
    "item_id": "kno_example",
    "change": "update",
    "body": "Payment terms are net 45 since 2026.",
    "reason": "New contract signed."
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "knowledge_propose",
    "arguments": {
      "item_id": "kno_example",
      "change": "update",
      "body": "Payment terms are net 45 since 2026.",
      "reason": "New contract signed."
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/knowledge/kno_example/proposals" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"change":"update","body":"Payment terms are net 45 since 2026.","reason":"New contract signed."}'

CLI

agentdb knowledge propose [options] <item_id>

#`knowledge_provenance`

stable added in 1.0.0-rc.6 read-only

Provenance chain of a knowledge item. Which files, records, URLs, quotes and other items support it, recursively through cited items (depth, cycle-safe), with confidence and who asserted it when.

MCP tool: knowledge_provenance
REST: GET /v1/workspaces/{ws}/knowledge/{item}/provenance scope records:read
CLI: agentdb knowledge provenance

Arguments

Argument	Type	Required	Description
`depth`	`integer`		integer, 1–5, default 3
`item_id`	`string`	yes	Knowledge item id (kno_...)
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "knowledge_provenance",
  "arguments": {
    "item_id": "kno_example",
    "depth": 2
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "knowledge_provenance",
    "arguments": {
      "item_id": "kno_example",
      "depth": 2
    }
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/knowledge/kno_example/provenance" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb knowledge provenance [options] <item_id>

#`knowledge_review`

stable added in 1.0.0-rc.6 changes data

Accept or reject a proposal (owners/admins). Nobody reviews their own proposal. Accepting makes it the current version.

MCP tool: knowledge_review
REST: POST /v1/workspaces/{ws}/knowledge/{item}/review scope records:write
CLI: agentdb knowledge review

Arguments

Argument	Type	Required	Description
`version`	`integer`	yes	The current version of the item. The call fails with VERSION_CONFLICT if it changed. (min 1)
`decision`	`"accept" \| "reject"`	yes	accept publishes the proposal; reject closes it.
`note`	`string`		string, up to 2000 characters
`force`	`boolean`		boolean, default false
`item_id`	`string`	yes	Knowledge item id (kno_...)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

version is the proposed version, from knowledge_get (pending proposals).

MCP

{
  "tool": "knowledge_review",
  "arguments": {
    "item_id": "kno_example",
    "version": 2,
    "decision": "accept",
    "note": "Matches the contract."
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "knowledge_review",
    "arguments": {
      "item_id": "kno_example",
      "version": 2,
      "decision": "accept",
      "note": "Matches the contract."
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/knowledge/kno_example/review" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version":2,"decision":"accept","note":"Matches the contract."}'

CLI

agentdb knowledge review [options] <item_id> <version> <decision>

#`knowledge_search`

stable added in 1.0.0-rc.6 read-only

Find knowledge with citations. mode exact (the phrase) or text (every word); semantic only if the operator enabled a provider. Every result carries its citations (sources with excerpts). trusted_only for answers to customers; fresh_only skips stale items.

MCP tool: knowledge_search
REST: POST /v1/workspaces/{ws}/knowledge/search scope records:read
CLI: agentdb knowledge search

Arguments

Argument	Type	Required	Description
`query`	`string`	yes	Words or a question to search the knowledge base for. (min length 1, max length 500)
`mode`	`"exact" \| "text" \| "semantic"`		string, one of: exact, text, semantic, default "text"
`kinds`	`"document" \| "fact" \| "decision" \| "note"[]`		"document" \| "fact" \| "decision" \| "note"[], up to 4 items
`trusted_only`	`boolean`		boolean, default false
`fresh_only`	`boolean`		boolean, default false
`include_archived`	`boolean`		boolean, default false
`limit`	`integer`		integer, 1–50, default 10
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "knowledge_search",
  "arguments": {
    "query": "payment terms",
    "mode": "text",
    "limit": 5
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "knowledge_search",
    "arguments": {
      "query": "payment terms",
      "mode": "text",
      "limit": 5
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/knowledge/search" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"payment terms","mode":"text","limit":5}'

CLI

agentdb knowledge search [options] <query>

#`knowledge_update`

stable added in 1.0.0-rc.6 changes data

Change a knowledge item (new version). On a TRUSTED item your change becomes a proposal unless you are an owner/admin (agents always propose); the result says proposed=true. status (draft|trusted|archived) is for owners/admins.

MCP tool: knowledge_update
REST: PATCH /v1/workspaces/{ws}/knowledge/{item} scope records:write
CLI: agentdb knowledge update

Arguments

Argument	Type	Required	Description
`expected_version`	`integer`		integer, at least 1
`title`	`string`		Title shown to people. (min length 1, max length 300)
`body`	`string`		string, up to 200000 characters
`sources`	`object[]`		object[], up to 20 items
`confidence`	`number \| null`		number \| null
`tags`	`string[]`		string[], up to 20 items
`review_after`	`string \| null`		string \| null
`status`	`"draft" \| "trusted" \| "archived"`		string, one of: draft, trusted, archived
`reason`	`string`		Why, in one or two sentences. (max length 2000)
`item_id`	`string`	yes	Knowledge item id (kno_...)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "knowledge_update",
  "arguments": {
    "item_id": "kno_example",
    "expected_version": 1,
    "tags": [
      "billing",
      "terms"
    ]
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "knowledge_update",
    "arguments": {
      "item_id": "kno_example",
      "expected_version": 1,
      "tags": [
        "billing",
        "terms"
      ]
    }
  }
}

REST

curl -s -X PATCH "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/knowledge/kno_example" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected_version":1,"tags":["billing","terms"]}'

CLI

agentdb knowledge update [options] <item_id>

#`knowledge_versions`

stable added in 1.0.0-rc.6 read-only

Version history of a knowledge item. Accepted, superseded, proposed and rejected, with who asserted and reviewed.

MCP tool: knowledge_versions
REST: GET /v1/workspaces/{ws}/knowledge/{item}/versions scope records:read
CLI: agentdb knowledge versions

Arguments

Argument	Type	Required	Description
`item_id`	`string`	yes	Knowledge item id (kno_...)
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "knowledge_versions",
  "arguments": {
    "item_id": "kno_example"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "knowledge_versions",
    "arguments": {
      "item_id": "kno_example"
    }
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/knowledge/kno_example/versions" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb knowledge versions [options] <item_id>

Knowledge

#knowledge_create

Arguments

Example

#knowledge_delete

Arguments

Example

#knowledge_get

Arguments

Example

#knowledge_list

Arguments

Example

#knowledge_propose

Arguments

Example

#knowledge_provenance

Arguments

Example

#knowledge_review

Arguments

Example

#knowledge_search

Arguments

Example

#knowledge_update

Arguments

Example

#knowledge_versions

Arguments

Example

#`knowledge_create`

#`knowledge_delete`

#`knowledge_get`

#`knowledge_list`

#`knowledge_propose`

#`knowledge_provenance`

#`knowledge_review`

#`knowledge_search`

#`knowledge_update`

#`knowledge_versions`