npm package: @ontos-ai/knowhere-claw
Description: OpenClaw plugin for Knowhere-powered document ingestion and automatic grounding.
Latest version: 0.2.10

# Knowhere for OpenClaw

Knowhere is an OpenClaw plugin that parses documents and URLs with Knowhere,
stores extracted Knowhere files in OpenClaw state, and gives agents a
browse-first toolset for grounded document work.

Quick mental model:

- Install the plugin
- Restart the Gateway
- Configure `plugins.entries."knowhere-claw".config`
- Ask an agent to read, search, or compare a document
- Let the bundled `knowhere` and `knowhere_memory` skills steer the agent toward the right tools

## Where It Runs

This plugin runs inside the OpenClaw Gateway process.

If your agents talk to a remote Gateway, install and configure the plugin on
the machine running that Gateway, then restart that Gateway.

## What You Get

- Ingest local files or document URLs with Knowhere
- Store parsed documents inside OpenClaw-managed state
- Preview document structure, search chunks, and inspect raw result files
- Reuse stored documents across `session`, `agent`, or `global` scope
- Ship bundled `knowhere` and `knowhere_memory` skills so agents prefer this
  toolchain for document-heavy tasks and knowledge-base lookups

## Install

```bash
openclaw plugins install @ontos-ai/knowhere-claw
```

Restart the Gateway afterwards.

## Config

Set config under `plugins.entries."knowhere-claw".config`:

```json5
{
  plugins: {
    allow: ["knowhere-claw"],
    entries: {
      "knowhere-claw": {
        enabled: true,
        config: {
          // apiKey is optional
        },
      },
    },
  },
}
```

Config notes:

- `apiKey`: optional Knowhere API key. If omitted, the plugin falls back to
  `KNOWHERE_API_KEY` and any API key previously stored with
  `knowhere_set_api_key`.
- If no API key is available when the agent first needs Knowhere, the plugin
  guides the user to the Knowhere API key page at
  `https://knowhereto.ai/api-keys`.
- `baseUrl`: optional Knowhere API base URL. Falls back to
  `KNOWHERE_BASE_URL` and defaults to `https://api.knowhereto.ai`.
- `storageDir`: optional directory for persisted parsed documents. By default,
  the plugin stores data under the OpenClaw state directory for
  `knowhere-claw`.
- `scopeMode`: document sharing boundary. Supported values are `session`,
  `agent`, and `global`. If omitted, the plugin defaults to `session`.
- `pollIntervalMs`, `pollTimeoutMs`, `requestTimeoutMs`, `uploadTimeoutMs`:
  optional tuning for job polling, API calls, and large uploads.
- An explicit `storageDir` such as
  `/home/<user>/.openclaw/plugin-state/knowhere` makes stored documents
  easier to inspect, back up, or clean up.

## How OpenClaw Uses It

Once the plugin is enabled, you can ask an OpenClaw agent to:

- summarize a local document
- read a document URL
- find a table or section in a previously ingested document
- compare a new document with documents already stored in scope

The bundled `knowhere` skill teaches agents to use the `knowhere_*` tools
instead of raw file reads when document parsing matters.

The bundled `knowhere_memory` skill teaches agents to treat previously parsed
Knowhere content as a knowledge base when users ask to search their materials,
look something up, or summarize what data they already have.

If you use skill filters or allowlists in OpenClaw, keep the bundled
`knowhere` and `knowhere_memory` skills enabled or the tools will load without
their intended usage guidance.

If your agent runtime uses a tool allowlist, include `knowhere_*` so agents can
actually call the plugin tools.

## Scope And Storage

`scopeMode` controls who can reuse parsed documents:

- `session`: only the current session can reuse the stored documents
- `agent`: all conversations for the same agent can reuse them
- `global`: all agents on the same Gateway can reuse them

Within each scope, the plugin keeps:

- an `index.json` cache of stored document summaries
- a `metadata/` directory with one JSON record per stored document
- the extracted Knowhere result files directly inside each document directory

## Common Workflow

1. Provide a file path or URL to the agent.
2. The agent ingests it into Knowhere. By default this starts parsing asynchronously and returns a job ID; when the current turn needs the parsed result immediately, the agent can call `knowhere_ingest_document` with `blockUntilComplete: true`.
3. Follow-up questions reuse stored results from the current scope.
4. When needed, the agent can preview structure, search chunks, read raw result
   files, or clear stored documents.

## Schema v2.1 Media Handling

- `knowhere_read_chunks` now treats `[images/...]` and `[tables/...]` path references in `chunks.json` content as the primary media enrichment path.
- Standalone `image` and `table` chunks resolve their real asset locations from `metadata.file_path`.
- Assets without `metadata.file_path` are ignored by the runtime enrichment and delivery pipeline.

## Troubleshooting

- Missing API key: `apiKey` config is optional. You can set
  `plugins.entries."knowhere-claw".config.apiKey`, export
  `KNOWHERE_API_KEY`, or let the plugin guide the user to
  `https://knowhereto.ai/api-keys` and store the key with
  `knowhere_set_api_key`.
- Documents are not shared between conversations: change `scopeMode` from
  `session` to `agent` or `global`.
- The plugin is enabled but agents do not reach for Knowhere: check that the
  bundled `knowhere` skill is not filtered out.
- Large documents time out: increase `pollTimeoutMs` or `uploadTimeoutMs`.

## Developer Docs

Contributor-oriented architecture, workflow, and packaging notes live in
`DEVELOPMENT.md` at the repository root.

Release-process details for maintainers live in
[`docs/release-workflow.md`](./docs/release-workflow.md).