knowledge-manual

# 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 ```text 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: ```text 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.