define-category

name	define-category
description	Use this skill proactively when creating a reusable category, when configuring retrieval weight, when refining an auto-created definition, or when organizing repeated memory types. Trigger when category configuration is needed; invoke automatically for durable taxonomy work, not one-off tags.

Define Category

Use this skill when the user wants a new memory category or wants to tune how strongly an existing category is retrieved.

RECALL is local-only project memory. Category definitions are stored in the active project's RECALL memory config: .recall/memory_config.json for new projects, or existing .codex_memory/memory_config.json stores for legacy projects. Never require hosted services or external APIs. Do not put secrets, credentials, tokens, private keys, passwords, or sensitive personal data in category names or descriptions.

Execution Path

Use this skill as the public RECALL category-management interface. When shell execution is needed, run the bundled skill adapter from the installed plugin root or source plugin root. Treat lower-level backend scripts as internal support code, not as the user-facing RECALL workflow.

All python ./scripts/recall_skill.py ... examples assume the current directory is the plugin root. If the shell is in the active project repository, do not look for ./scripts there; locate the installed/source plugin root or use an absolute adapter path, then pass --root <project-root> when needed.

Contract

This skill receives a category-design request and returns one normalized category definition: name, description, and retrieval weight. It owns durable taxonomy only — not ordinary tagging, memory writing, broad cleanup, or retrieval. Storing a fact is save-insight's contract; inspecting category counts or noisy records is review-memory's contract. Those requests are out of scope here, not requests this skill routes elsewhere.

Use the contract asset as the quick boundary check:

{"asset":"assets/contract.json","kind":"category-boundary"}

Workflow

1. Normalize the category to lower snake case.
2. List existing categories when you need to avoid creating a near-duplicate category:

python ./scripts/recall_skill.py list-categories

3. Write a short description that explains what belongs in the category.
4. Choose a positive weight. Use 1.0 for normal priority, higher values such as 1.3 to surface the category more aggressively, and lower values such as 0.8 for background context.
5. If RECALL auto-created this category from a saved memory, preserve the normalized name and refine only the description/weight.
6. Run:

python ./scripts/recall_skill.py define-category <category> --description "<description>" --weight <weight>

Add deterministic usage guidance whenever the category will be reused — agents pick categories correctly when each carries examples, non-examples, and an update rule:

python ./scripts/recall_skill.py define-category <category> --description "<description>" --weight <weight> \
  --example "<memory that belongs here>" --non-example "<memory that does not>" \
  --update-rule "<how cards in this category age or get superseded>"

7. Return the normalized category and explain whether this was a new category or a refinement.
8. When a proposed category overlaps an existing one, reuse or refine the existing category instead of creating a synonym.

Example

python ./scripts/recall_skill.py define-category api_contracts --description "Stable API shapes and compatibility promises." --weight 1.4

Inputs

• Category name: normalized to lower snake case.
• Description: concrete inclusion rule, not a vague label.
• Weight: positive number; 1.0 normal, >1.0 stronger, <1.0 quieter.

Output Format

Returns JSON containing normalized category and stored description/weight. Mention normalization when the output name differs from user input.

{"action":"define-category","category":"api_contracts","details":{"description":"Stable API shapes.","weight":1.4}}

Examples

Moderate priority:

python ./scripts/recall_skill.py define-category release_evidence --description "Verified packaging, install, and release checks." --weight 1.2

Quiet background context:

python ./scripts/recall_skill.py define-category research_notes --description "Exploratory notes not yet promoted to decisions." --weight 0.8

Refining an auto-created category:

python ./scripts/recall_skill.py define-category eval_findings --description "Durable evaluation scores, score drivers, and quality-gate outcomes." --weight 1.3

Rejecting a one-off tag:

{"action":"no-category","reason":"Use a tag because this is not a repeated retrieval purpose."}

Edge Cases

• Near-duplicate category: reuse existing category and refine it.
• Empty or punctuation-only name: reject it.
• Zero/negative weight: reject it.
• One-off label: use tags instead of creating category.
• Sensitive or personal category label: reject it and suggest a non-sensitive abstraction.
• Category too broad: narrow the inclusion rule before raising weight.
• Category too narrow: use tags unless multiple future memories need the same retrieval lane.

Decision Guide

Need	Choice
Existing built-in meaning	Reuse built-in category
Repeated distinct retrieval purpose	Define custom category
One-off grouping	Add tag instead
Broad category dominates results	Lower weight

Troubleshooting

• Unexpected normalized name: run list-categories and use returned name.
• Category dominates retrieval: lower weight toward 1.0.
• Category remains too broad: narrow description or split only when durable use cases differ.
• Category cannot be explained in one sentence: it is probably a workflow or document, not a category.
• Two categories match the same memory equally well: merge the meaning into one category and use tags for the distinction.

Related

• Save Insight for writing category members.
• Review Memory for category counts and quality.
• Category guide for naming and weighting.
• Sibling routes: skills/save-insight, skills/review-memory, skills/retrieve-memory.