knowledge-manual

name	knowledge-manual
description	Concise guide to the `knowledge` capability: private agent-owned memory in `<agent>/knowledge/<name>/KNOWLEDGE.md`, progressive disclosure through the prompt catalog, nested knowledge folders, and cross-references between entries. Read this when you need to create, organize, or load private knowledge, or when you need to explain how knowledge differs from portable skills.
version	1.0.0

The Knowledge Capability

Knowledge is an agent's private long-term memory. It is for facts, decisions, observations, local paths, mail context, and operational lessons that are useful to this agent but are not necessarily portable to every other agent.

Skills are different: a skill is a reusable procedure meant to travel across agents. Knowledge may point to skills; skills should not depend on private knowledge.

Names you will see

The current private-memory capability is named knowledge, and the only tool it registers is:

knowledge({"action": "info"})

Older documentation and UI surfaces may still say library or codex. Treat those as historical names for the private durable knowledge store unless the text is clearly talking about skills. In current agent code, library(...) and codex(...) are not registered compatibility aliases.

Do not confuse this with the .library/ directory: .library/ is the on-disk home for skills (SKILL.md files), not for private knowledge entries. The naming is legacy but intentional for compatibility.

Quick map:

Term / path	Current meaning
knowledge tool / capability	Private per-agent durable memory catalog.
<agent>/knowledge/<name>/KNOWLEDGE.md	One private knowledge entry.
.library/intrinsic, .library/custom, .library_shared	Skill shelves containing SKILL.md files.
skills tool / capability	Catalog of reusable portable procedures.
/skills in the TUI	Browse the skill catalog for the selected agent.
/knowledge in the TUI	Browse private durable knowledge/codex entries.
/library or /codex in the TUI	Legacy aliases for /knowledge; keep only for compatibility.
recipe.json#library_name	Legacy schema field naming a recipe-bundled skill library. It appends to skills.paths.

When writing new docs, prefer knowledge for private memory and skills for reusable procedures. Use library only when referring to a literal legacy path or schema field such as .library/, .library_shared, or recipe.json#library_name.

Layout

Each entry is a folder under <agent>/knowledge/ with a KNOWLEDGE.md file:

<agent>/knowledge/
└── <name>/
    ├── KNOWLEDGE.md
    ├── references/
    ├── scripts/
    ├── assets/
    └── notes/

KNOWLEDGE.md starts with YAML frontmatter:

---
name: <name>
description: One short sentence shown in the prompt catalog.
version: 1.0.0
---

# Title

Full notes live here.

Required fields are name and description. Supporting files are optional and can be any useful text, script, data sample, log, or asset.

Progressive disclosure

The system prompt only receives a compact catalog: each entry's name, description, and location. The body of KNOWLEDGE.md and supporting files stay on disk until you explicitly read them.

Use:

knowledge({"action": "info"})

to rescan the catalog and refresh the prompt section, then use read on the listed location when an entry becomes relevant.

This keeps the prompt small while still making the memory discoverable.

Nesting

Knowledge may be nested for organization. The scanner descends through folders until it finds KNOWLEDGE.md files, so these are valid:

knowledge/project-a/architecture/KNOWLEDGE.md
knowledge/project-a/incidents/2026-05-cache-bug/KNOWLEDGE.md
knowledge/people/reviewers/KNOWLEDGE.md

Keep names filesystem-safe and descriptive. Use nesting to group related entries, not to hide information.

Cross-references

Knowledge entries may reference one another by relative path or by catalog name. Prefer links that remain valid if the whole agent directory moves:

See also: ../architecture/KNOWLEDGE.md
See also: ../../people/reviewers/KNOWLEDGE.md

Knowledge may also reference skills when a reusable procedure exists:

For the repeatable workflow, read `.library/intrinsic/capabilities/skills/SKILL.md`.

Direction matters: private knowledge can point outward to skills, but shared skills should not point inward to private knowledge paths, mail IDs, or local logs.

When to create knowledge

Create or update a knowledge entry when the information is useful beyond the current turn but is not a portable procedure:

• project-specific decisions and rationale;
• collaborator preferences and review history;
• local repo paths, branch relationships, and known gotchas;
• incident notes and debugging evidence;
• conclusions from research that are specific to this agent's work.

If the content is a reusable how-to that another agent should be able to apply without your private context, write a skill instead.