# Knowledge

Canonical: https://auggy.dev/docs/augment-knowledge
Status: Published
Package: auggy 0.5.0

Expose read-only local documents and remote knowledge APIs through manifest-driven progressive disclosure.

## Outcome

**What it enables:** Keep a small source and endpoint catalog in context, then fetch full reference content only when a turn needs it.

- **Status:** Stable
- **Availability:** Install with ``auggy augment add` knowledge`.
- **Contributes:** `knowledge_fetch tool`, `system context`, `bundled skill`

Knowledge is a read-only progressive-disclosure augment. Each source manifest contributes organization metadata and endpoint descriptions to context; ``knowledge_fetch`` loads one listed endpoint on demand instead of placing every document in every prompt.

## Install and defaults

**From the agent project**

```bash
auggy augment add knowledge
```

**Generated files**

```
agent.yaml                         # adds knowledge
augments/knowledge/augment.yaml    # generated config
skills/knowledge/SKILL.md           # bundled usage guidance
knowledge/README.md
knowledge/sources.json
knowledge/local/manifest
knowledge/local/mission.md
knowledge/local/context.md
```

**augments/knowledge/augment.yaml**

```yaml
type: knowledge
config:
  root: ./knowledge
```

**knowledge/sources.json**

```json
{
  "sources": [
    {
      "name": "local",
      "description": "Local project knowledge maintained with this agent",
      "baseUrl": "file://./local"
    }
  ]
}
```

**knowledge/local/manifest for my-agent**

```json
{
  "org": "my-agent",
  "purpose": "project knowledge for this agent",
  "creator": "the creator",
  "phase": "active",
  "endpoints": [
    {
      "path": "/mission",
      "description": "Agent purpose, project context, and active focus"
    },
    {
      "path": "/context",
      "description": "Project background, terminology, workflows, and policies"
    }
  ]
}
```

If `agent.yaml` already has `purpose` or `creator.displayName`, the scaffold writes those values into the manifest. The starter markdown files contain placeholders for project-owned content.

## Use it

Add a pricing document, advertise its exact endpoint, restart after changing the manifest, and fetch it from a turn that needs billing facts.

**knowledge/local/pricing.md**

```
# Pricing

The Pro plan is $49 per month and includes five seats.
```

**Add to knowledge/local/manifest endpoints**

```json
{
  "path": "/pricing",
  "description": "Current plans, prices, included seats, and billing policy"
}
```

**Fetch the listed endpoint**

```ts
knowledge_fetch({
  source: "local",
  endpoint: "/pricing",
})
```

## Runtime surfaces

| Surface | Exact behavior |
| --- | --- |
| System context | Lists each loaded source, its description, organization metadata, and every advertised endpoint path and description. |
| ``knowledge_fetch`({ source, endpoint, prompt? })` | Fetches one exact manifest-listed endpoint from a local `file://` source or remote HTTP(S) source and returns a JSON envelope. |
| Local source | Reads the literal endpoint path under the source directory, then tries a `.md` suffix; traversal and symlink escapes are rejected. |
| Remote source | Loads `GET /manifest`, then issues `GET` for the selected listed path. `token` or `tokenEnv` can supply a bearer token. |
| Boot diagnostics | Logs loaded source and endpoint counts; an unavailable or invalid manifest produces warnings and an empty knowledge context instead of stopping the agent. |

## Boundaries

| Boundary | What to design for |
| --- | --- |
| Trust | The manifest is an endpoint allowlist, **not** caller authorization. Every listed endpoint is available to every caller that receives ``knowledge_fetch``; do not list privileged or secret content. |
| Persistence | The augment has no write surface. Sources are loaded for the process lifetime and manifests cache for one hour by default, so restart after adding a source or when immediate manifest changes matter. |
| Deployment | Local `knowledge/` sources are copied into the deployment image, not written to the **Railway** volume. Cloud edits require a rebuild and redeploy; remote source content stays at its configured API. |
| Prompt parameter | `prompt` is returned as a hint in supported response envelopes. It does **not** search, filter, summarize, or reduce the retrieved endpoint content. |
| Limitations | Endpoint matching is exact and content is capped at about 20,000 characters. Manifest `method: POST` is display metadata; ``knowledge_fetch`` remains read-only and fetches with `GET`. |

> **Warning: Descriptions guide selection, not access**
>
> Prompt instructions may encourage the model to fetch only relevant endpoints, but they do not hide endpoints or enforce per-caller policy. Split sensitive material into a separately authorized capability instead of relying on wording.

## Verify

**Validate and start**

```bash
auggy doctor
auggy run
```

1. Confirm startup logs contain `[knowledge] loaded local knowledge` and the expected endpoint count.
2. In ``/console/chat``, ask a question that requires the new endpoint and inspect the ``knowledge_fetch`` call.
3. Confirm the tool result names `source: local`, reports `endpoint: /pricing`, and contains the text from `pricing.md`.
4. Call ``knowledge_fetch`({ source: "local", endpoint: "/not-listed" })` and confirm it returns a manifest refusal with no content.
5. For a deployed agent, redeploy after editing local knowledge and repeat the fetch against the production Console.

## Related

- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Security](https://auggy.dev/docs/security/markdown)
- [Deploy and verify](https://auggy.dev/docs/deploy/markdown)