Knowledge Manual
Knowledge is private, local long-term memory: facts, decisions, observations,
paths, mail context, and operational lessons. It has no public capability tool;
psyche only returns this signpost. Skills are portable procedures, while
knowledge may contain private paths, IDs, and logs. Reusable how-to belongs in a
skill; shared skills must not point inward to private knowledge.
Layout and catalog
Each entry is <agent>/knowledge/<name>/KNOWLEDGE.md, optionally with
references/, scripts/, assets/, or notes/. Its YAML needs name and
description. The prompt receives only each entry's name, description, and
location; read the body on demand. Setup/refresh and every full rebuild rescan
the store and recompose the catalog.
A top-level entry may be a short routing/index parent with nested children. Keep one hook and relative child path per child, and put the substance in the child; use the Skills manual's nested reference pattern for the catalog shape.
Public call and first action
psyche(action="knowledge", input={}, reasoning="load knowledge guidance")
The strict-empty call creates, edits, searches, rescans, and loads nothing. For an ordinary schema-sufficient call no ritual manual reload is needed; read this page when authoring or reorganizing an unfamiliar store.
Author, edit, read, apply
Use shell for every durable change, anchored to your working directory:
shell(action="run", input={"command": "mkdir -p knowledge/<name> && cat > knowledge/<name>/KNOWLEDGE.md <<'EOF'\n---\nname: <name>\ndescription: ...\n---\n...\nEOF\ncat knowledge/<name>/KNOWLEDGE.md", "timeout": null, "working_dir": null, "async": null, "reminder": null}, reasoning="write knowledge and read it back")
shell(action="run", input={"command": "sed -n '1,120p' -- \"<location>\"", "timeout": null, "working_dir": null, "async": null, "reminder": null}, reasoning="read knowledge, bounded")
For an edit, first prove the old text exists exactly once (for example
grep -c -F -- '<old>' knowledge/<name>/KNOWLEDGE.md must print 1), then
replace it and read the file back to verify; never replace blindly. Keep output
bounded, and treat a binary or non-UTF-8 file honestly rather than as text.
Writing does not hot-load the catalog. Prefer letting the next natural
refresh/molt reconstruction apply it; a manual rebuild is strongly discouraged
(costly full replay). Only when the entry must be cataloged in this conversation
and a molt is unsuitable, make one targeted
context(action="rebuild", input={}, reasoning="refresh knowledge catalog"). Psyche's
settings/psyche.json does not configure Knowledge and there is no Knowledge
settings, set, reset, migration, or writeback action.
Cross-references and cleanup
Prefer move-stable relative links such as ../architecture/KNOWLEDGE.md. A
knowledge entry may point outward to a reusable Skills manual, never the reverse.
Knowledge is durable memory, not cache: do not delete it just to save space.
Cleanup normally consolidates, renames, or archives stale entries. For a footprint
report, use skills-manual → reference/cleanup-footprint-contract.md and
select only knowledge/; inspection writes nothing. The shared recipe’s optional
audit append is a separate write, not an automatic side effect of inspection. Show the dry-run,
explain what would change, obtain explicit user consent, and record an approved
cleanup in logs/cleanup.jsonl before rebuilding the catalog.