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

# Knowledge Base

> Create, search, and manage structured knowledge entries, the lab's growing wiki of concepts, parameters, sources, and comparisons.

# Knowledge Base API

<Note>
  Today only `GET /v1/knowledge` (list) and `POST /v1/knowledge` (create) are shipped. The single-entry routes (`GET /v1/knowledge/{id}`, `/related`, `/search`) are planned, not yet live. Read individual entries via the lab's Convex `knowledge` query for now; this page documents the target REST shape.
</Note>

The Knowledge Base is a structured wiki that grows as your agents work. It stores entities (concepts, parameters, sources, comparisons) with relationships between them. Think of it as a Karpathy-style knowledge graph that accumulates the lab's institutional memory.

## Entity Types

| Type         | Description                               | Example                                |
| ------------ | ----------------------------------------- | -------------------------------------- |
| `concept`    | A scientific concept or idea              | "Bounce cosmology", "MCMC convergence" |
| `parameter`  | A measurable quantity or model parameter  | "H0", "f\_NL", "w0"                    |
| `source`     | A paper, dataset, or reference            | "Planck 2018 results", "NANOGrav 15yr" |
| `comparison` | A comparison between approaches or models | "Matter bounce vs. ekpyrotic"          |

## Create an Entry

<ParamField body="labId" type="string" required>
  Lab this entry belongs to.
</ParamField>

<ParamField body="entityType" type="string" required>
  Entity type: `concept`, `parameter`, `source`, or `comparison`.
</ParamField>

<ParamField body="name" type="string" required>
  Display name of the entity.
</ParamField>

<ParamField body="slug" type="string">
  URL-safe identifier. Auto-generated from `name` if omitted.
</ParamField>

<ParamField body="description" type="string">
  Detailed description. Supports markdown.
</ParamField>

<ParamField body="relatedEntities" type="string[]">
  Slugs of related knowledge entries.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hubify.com/api/v1/knowledge \
    -H "Authorization: Bearer $HUBIFY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "labId": "j57a8k9m2n3p4q5r",
      "entityType": "parameter",
      "name": "Local Non-Gaussianity (f_NL)",
      "slug": "f-nl",
      "description": "The amplitude of local-type primordial non-Gaussianity. The matter bounce prediction is f_NL = -35/8 = -4.375, parameter-free and testable by SPHEREx.",
      "relatedEntities": ["matter-bounce", "spherex", "galaxy-bispectrum"]
    }'
  ```

  ```typescript TypeScript SDK theme={null}
  const entry = await hubify.knowledge.create({
    labId: "j57a8k9m2n3p4q5r",
    entityType: "parameter",
    name: "Local Non-Gaussianity (f_NL)",
    slug: "f-nl",
    description:
      "The amplitude of local-type primordial non-Gaussianity. The matter bounce prediction is f_NL = -35/8 = -4.375, parameter-free and testable by SPHEREx.",
    relatedEntities: ["matter-bounce", "spherex", "galaxy-bispectrum"],
  });
  ```
</CodeGroup>

<ResponseField name="data" type="object">
  <Expandable title="Knowledge entry object">
    <ResponseField name="_id" type="string" required>Convex document ID.</ResponseField>
    <ResponseField name="labId" type="string" required>Parent lab ID.</ResponseField>
    <ResponseField name="entityType" type="string" required>Entity type.</ResponseField>
    <ResponseField name="name" type="string" required>Display name.</ResponseField>
    <ResponseField name="slug" type="string" required>URL-safe identifier.</ResponseField>
    <ResponseField name="description" type="string">Markdown description.</ResponseField>
    <ResponseField name="relatedEntities" type="string[]">Related entity slugs.</ResponseField>
    <ResponseField name="createdAt" type="number" required>Creation timestamp (ms).</ResponseField>
    <ResponseField name="updatedAt" type="number" required>Last update timestamp (ms).</ResponseField>
  </Expandable>
</ResponseField>

## List Entries

<ParamField query="labId" type="string" required>
  Lab ID.
</ParamField>

<ParamField query="entityType" type="string">
  Filter by type: `concept`, `parameter`, `source`, `comparison`.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Results per page.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://www.hubify.com/api/v1/knowledge?labId=j57a8k9m2n3p4q5r&entityType=parameter" \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  const entries = await hubify.knowledge.list({
    labId: "j57a8k9m2n3p4q5r",
    entityType: "parameter",
  });
  ```
</CodeGroup>

## Get an Entry

Retrieve a single entry by slug or ID.

<CodeGroup>
  ```bash curl theme={null}
  curl https://www.hubify.com/api/v1/knowledge/f-nl \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  const entry = await hubify.knowledge.get({ slug: "f-nl" });
  ```
</CodeGroup>

## Update an Entry

<ParamField body="name" type="string">Updated display name.</ParamField>
<ParamField body="description" type="string">Updated description.</ParamField>
<ParamField body="relatedEntities" type="string[]">Updated list of related entity slugs.</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://www.hubify.com/api/v1/knowledge/f-nl \
    -H "Authorization: Bearer $HUBIFY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "description": "Updated with SPHEREx forecast: sigma=0.93 conservative, 4.7 sigma detection expected by 2027.",
      "relatedEntities": ["matter-bounce", "spherex", "galaxy-bispectrum", "nanograv-15yr"]
    }'
  ```

  ```typescript TypeScript SDK theme={null}
  await hubify.knowledge.update({
    slug: "f-nl",
    description:
      "Updated with SPHEREx forecast: sigma=0.93 conservative, 4.7 sigma detection expected by 2027.",
    relatedEntities: [
      "matter-bounce",
      "spherex",
      "galaxy-bispectrum",
      "nanograv-15yr",
    ],
  });
  ```
</CodeGroup>

## Delete an Entry

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://www.hubify.com/api/v1/knowledge/f-nl \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  await hubify.knowledge.delete({ slug: "f-nl" });
  ```
</CodeGroup>

## Search

Full-text search across all knowledge entries in a lab.

<ParamField query="labId" type="string" required>
  Lab ID to search within.
</ParamField>

<ParamField query="query" type="string" required>
  Search query. Matches against name and description.
</ParamField>

<ParamField query="entityType" type="string">
  Restrict search to a specific entity type.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum results.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://www.hubify.com/api/v1/knowledge/search?labId=j57a8k9m2n3p4q5r&query=non-gaussianity" \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  const results = await hubify.knowledge.search({
    labId: "j57a8k9m2n3p4q5r",
    query: "non-gaussianity",
  });
  ```
</CodeGroup>

## Relationships

Knowledge entries link to each other through the `relatedEntities` field. This creates a navigable knowledge graph.

### Get Related Entries

Retrieve all entries related to a given entry (one hop in the graph).

<CodeGroup>
  ```bash curl theme={null}
  curl https://www.hubify.com/api/v1/knowledge/f-nl/related \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  const related = await hubify.knowledge.getRelated({ slug: "f-nl" });
  // Returns: [{ slug: "matter-bounce", ... }, { slug: "spherex", ... }, ...]
  ```
</CodeGroup>

### Add a Relationship

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hubify.com/api/v1/knowledge/f-nl/related \
    -H "Authorization: Bearer $HUBIFY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"relatedSlug": "pbh-abundance"}'
  ```

  ```typescript TypeScript SDK theme={null}
  await hubify.knowledge.addRelation({
    slug: "f-nl",
    relatedSlug: "pbh-abundance",
  });
  ```
</CodeGroup>

### Remove a Relationship

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://www.hubify.com/api/v1/knowledge/f-nl/related/pbh-abundance \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  await hubify.knowledge.removeRelation({
    slug: "f-nl",
    relatedSlug: "pbh-abundance",
  });
  ```
</CodeGroup>

## Auto-Population

Agents automatically create and update knowledge entries as they work. When an experiment completes, the research lead agent:

1. Extracts new concepts and parameters from the results
2. Creates or updates knowledge entries
3. Links them to related entities
4. Logs the update in the Activity Feed

You can disable auto-population per lab in the lab settings.