> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hill90.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge API

> Agent knowledge management, shared knowledge library, hybrid search, and quality metrics.

# Knowledge API

The Knowledge API provides access to agent knowledge and the shared knowledge library. Agents maintain persistent memory across sessions — they write plans, decisions, journals, research notes, and other entries that survive container restarts. The shared knowledge library lets users curate collections of documents that agents can search during inference.

## Agent Knowledge (AKM)

### Entry Types

Agents organize knowledge into typed entries:

| Type       | Purpose                                    |
| ---------- | ------------------------------------------ |
| `plan`     | Action plans and implementation strategies |
| `decision` | Recorded decisions with rationale          |
| `journal`  | Append-only daily activity logs            |
| `research` | Research findings and references           |
| `note`     | General-purpose notes                      |

### Agent Tools

Agents interact with knowledge through built-in tools available in their sandboxed runtime:

| Tool                      | Description                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| `save_knowledge`          | Persist a knowledge entry (plan, decision, journal, research, note) to the agent's private store |
| `search_knowledge`        | Hybrid search across the agent's own knowledge entries                                           |
| `search_shared_knowledge` | Search the shared knowledge library (owner-scoped and shared collections)                        |

### AKM Token Refresh

Agent containers authenticate to the Knowledge service using short-lived JWTs (Ed25519-signed). The agentbox runtime runs an automatic token refresh loop that renews the AKM token before its 1-hour expiry, so agents maintain uninterrupted access to knowledge services across long-running sessions.

### Access Model

* **Users** see knowledge from agents they own.
* **Admins** see knowledge from all agents.
* **Read-only via API** — only agents write knowledge through internal services.

### Search

Knowledge search uses a hybrid approach combining PostgreSQL full-text search (FTS) with pgvector semantic similarity:

* **FTS** — tsvector/GIN index with `ts_rank` ordering and `ts_headline` snippets for keyword matching.
* **Vector similarity** — 1536-dimensional embeddings generated by `text-embedding-3-small` (via LiteLLM) during ingestion. Stored in pgvector and queried with cosine similarity.
* **Hybrid ranking** — Results from both methods are combined using reciprocal rank fusion for better recall than either method alone.

### Endpoints

| Endpoint                                  | Description                             |
| ----------------------------------------- | --------------------------------------- |
| `GET /knowledge/agents`                   | List agents with knowledge entry counts |
| `GET /knowledge/entries`                  | List entries for a specific agent       |
| `GET /knowledge/entries/{agentId}/{path}` | Read a specific entry with full content |
| `GET /knowledge/search`                   | Hybrid search across knowledge entries  |

## Shared Knowledge Library

The shared knowledge library lets users curate collections of documents that agents can retrieve during inference. Collections support text/markdown content and web page ingestion.

### Concepts

* **Collection** — A named group of sources with a visibility setting (`private` or `shared`). Private collections are visible only to the owner's agents; shared collections are available to all agents.
* **Source** — A document within a collection. Source types: `text` (direct text/markdown) and `web_page` (fetched from a URL with SSRF protection).
* **Ingestion pipeline** — Sources are chunked (\~500 tokens/chunk, \~50 token overlap, paragraph and heading boundaries), embedded via `text-embedding-3-small`, and indexed for both FTS and vector search.

### Endpoints

| Endpoint                             | Description                                               |
| ------------------------------------ | --------------------------------------------------------- |
| `GET /shared-knowledge/collections`  | List collections (owner-scoped + shared)                  |
| `POST /shared-knowledge/collections` | Create a collection                                       |
| `GET /shared-knowledge/sources`      | List sources in a collection                              |
| `POST /shared-knowledge/sources`     | Create a source (text or web\_page) and trigger ingestion |
| `GET /shared-knowledge/sources/{id}` | Get source details                                        |
| `GET /shared-knowledge/search`       | Search across shared knowledge with citations             |
| `GET /shared-knowledge/stats`        | Quality metrics (aggregate stats, no PII)                 |

## Quality Metrics

The stats endpoint provides aggregate quality metrics for the shared knowledge library:

* **Search metrics** — Total searches, zero-result rate, average duration, breakdown by requester type (user vs. agent).
* **Ingest health** — Job counts by status (pending, processing, completed, error), error rate, average processing time.
* **Source breakdown** — Counts by status and source type.
* **Corpus summary** — Total collections, sources, documents, and chunks.

Metrics support a `since` time-range filter (e.g., 24h, 7d, 30d). All data is aggregate-only — no raw query text or user identifiers are exposed.

## Authentication

All endpoints require a valid Keycloak JWT bearer token with the `user` role:

```
Authorization: Bearer YOUR_JWT_TOKEN
```

See the auto-generated endpoint pages below for request/response details.