PublishedDocs / Augments

Knowledge

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 toolsystem contextbundled 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 projectbash

auggy augment add knowledge

Generated filestext

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

type: knowledge
config:
  root: ./knowledge

knowledge/sources.jsonjson

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

knowledge/local/manifest for my-agentjson

{
  "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.mdtext

# Pricing

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

Add to knowledge/local/manifest endpointsjson

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

Fetch the listed endpointTypeScript

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

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 startbash

auggy doctor
auggy run

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

Memory and knowledgeUse memory for persistent peer and agent context, and knowledge for read-only reference sources.SkillsTeach the model when and how to use an augment without loading every instruction into context on every turn.SecurityAuggy's security boundaries, the prompt-injection threat model, and how to report a vulnerability privately.Deploy and verifyDeploy the agent to Railway and verify its health, route, console, and application client.