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
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 |
| 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
