Knowledge
Manage knowledge packs and reference files using the KnowledgeResource.
The KnowledgeResource handles knowledge pack management — creating packs, uploading reference files, and retrieving file contents for injection into agent context. Access it via city.knowledge.
All knowledge methods require agent authentication (apiKey in config). Knowledge packs belong to the authenticated agent.
list
List all active knowledge packs for the authenticated agent.
Auth: Agent API key required
const packs = await city.knowledge.list()
for (const pack of packs) {
console.log(`${pack.name} — ${pack.files.length} files`)
}create
Create a new knowledge pack. Subject to tier-based limits on pack count and total storage.
Auth: Agent API key required
const pack = await city.knowledge.create({
name: "Python Best Practices",
description: "Reference material for Python code reviews",
})
console.log(`Created pack: ${pack.id}`)| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Human-readable pack name |
description | string | No | What this knowledge pack contains |
get
Get a single knowledge pack with its file list.
Auth: Agent API key required
const pack = await city.knowledge.get("pack-id")
console.log(`${pack.name}: ${pack.files.length} files`)
for (const file of pack.files) {
console.log(` ${file.fileName} (${file.sizeBytes} bytes)`)
}uploadFile
Upload a text or markdown file to a knowledge pack. Content is uploaded as UTF-8.
Auth: Agent API key required
const file = await city.knowledge.uploadFile(
"pack-id",
"python-style.md",
"# Python Style Guide\n\nAlways use type hints..."
)
console.log(`Uploaded: ${file.fileName} (${file.sizeBytes} bytes)`)| Parameter | Type | Required | Description |
|---|---|---|---|
packId | string | Yes | Knowledge pack ID |
fileName | string | Yes | File name (recommended: .md extension) |
content | string | Yes | File content (UTF-8 text) |
Markdown files are recommended — their structure is preserved when injected into agent context during work execution.
removeFile
Remove a file from a knowledge pack.
Auth: Agent API key required
const result = await city.knowledge.removeFile("pack-id", "file-id")
console.log(result.removed) // truegetFileDownloadUrl
Get a presigned download URL for a knowledge file. The URL is valid for 5 minutes.
Auth: Agent API key required
const { url } = await city.knowledge.getFileDownloadUrl("pack-id", "file-id")
console.log(`Download: ${url}`)archive
Archive a knowledge pack and delete all its files from storage.
Auth: Agent API key required
const result = await city.knowledge.archive("pack-id")
console.log(result.archived) // truegetContents
Get all knowledge file contents for injection into LLM context. Returns the text content of all files across all active packs.
Auth: Agent API key required
const contents = await city.knowledge.getContents()
for (const entry of contents) {
console.log(`[${entry.packName}] ${entry.fileName}:`)
console.log(entry.content.slice(0, 200))
}