Knowledge

Knowledge is the shared source library for your workspace.

Use it for reference material that should be available across agents, projects, chats, and structured sessions.

Knowledge vs Memory

  • Memory stores durable agent and conversation learnings.
  • Knowledge stores shared source material, ingestion metadata, grounding evidence, and citations.

Use memory for learned context. Use knowledge for reference sources and grounded retrieval.

Source Types

Knowledge sources can be created from:

  • manual text
  • local files
  • URLs

Files cover a broad range of formats including code, markup, text, PDF, and common document types. URL sources are fetched and normalized into indexed content.

Source Lifecycle

Each knowledge source has its own lifecycle:

  • create
  • sync
  • archive
  • restore
  • supersede
  • delete

This makes it possible to treat knowledge as an operational dataset instead of a one-shot blob upload.

Grounding and Citations

As of v1.3.5, SwarmClaw can ground responses against knowledge retrieval at runtime.

Citations can be persisted on:

  • chat messages
  • protocol events
  • run records and artifacts

The grounding panel surfaces:

  • retrieval query
  • hit scores
  • snippets
  • source links and metadata
  • match rationale

Hygiene

Knowledge hygiene detects and helps clean up:

  • stale sources
  • duplicates
  • overlaps
  • broken sources
  • superseded material

File and URL sources can be re-synced, and exact duplicates can be archived or consolidated.

API and CLI

Entries

  • GET /api/knowledge
  • POST /api/knowledge
  • GET /api/knowledge/:id
  • PUT /api/knowledge/:id
  • DELETE /api/knowledge/:id
  • POST /api/knowledge/upload

Hygiene

  • GET /api/knowledge/hygiene
  • POST /api/knowledge/hygiene

Sources

  • GET /api/knowledge/sources
  • GET /api/knowledge/sources/:id
  • PUT /api/knowledge/sources/:id
  • DELETE /api/knowledge/sources/:id
  • POST /api/knowledge/sources/:id/archive
  • POST /api/knowledge/sources/:id/restore
  • POST /api/knowledge/sources/:id/supersede
  • POST /api/knowledge/sources/:id/sync

CLI Examples

swarmclaw knowledge list
swarmclaw knowledge create --data '{"title":"Release runbook","content":"...","tags":["ops"]}'
swarmclaw knowledge upload --data '{"filename":"spec.md"}'
swarmclaw knowledge hygiene
swarmclaw knowledge sources
swarmclaw knowledge source-sync <sourceId>
swarmclaw knowledge source-archive <sourceId>