save-insight

name	save-insight
description	Use this skill proactively when debugging a durable failure, when testing a verified command, when implementing an accepted decision, or when recording a standing requirement for future threads. Trigger when durable evidence should persist; invoke automatically only for explicit evidence, never drafts.

Save Insight

Use this skill when the user asks the active coding agent to remember a decision, constraint, command, requirement, risk, preference, bug fix, task status, or other durable project context.

RECALL is local-only project memory. Store data under the active project's RECALL memory directory: .recall/ for new projects, or existing .codex_memory/ stores for legacy projects. Never require hosted services or external APIs. Do not store secrets, credentials, tokens, private keys, passwords, or sensitive personal data.

Execution Path

Use this skill as the public RECALL 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 verified durable fact and returns a saved, updated, linked, or ignored memory record. It owns new memory capture only. It does not perform broad retrieval, lifecycle cleanup, category design, or inspection reports except when checking for exact duplicates or conflicts before a write.

Contract schema:

Field	Required	Meaning
category	yes	built-in or intentional custom category
content	yes	durable non-secret fact to preserve
summary	yes	one-sentence future-useful retrieval label
details	preferred	supporting context, evidence, or acceptance rule
metadata	preferred	tags, source, status, importance, confidence
provenance	when known	source path, claim key/value, or preference evidence
result	yes	saved, updated, linked, ignored, or rejected action

Use the contract asset as the quick boundary check:

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

Categories

Prefer one of RECALL's built-in categories:

• decisions
• constraints
• debug_history
• preferences
• tasks
• session_summaries
• project_state
• architecture
• commands
• lessons_learned
• requirements
• risks
• tooling_quirks
• integrations

Each built-in category carries examples, non-examples, and an update rule; inspect them with list-categories or the contract command when unsure which slot fits. Custom categories are allowed. If a category does not exist, RECALL auto-creates it with a default weight and records a warning in metadata. After auto-creation, recommend refining the category with define-category when the category will be reused.

Memory Card Shape

Prefer structured, scannable memory cards. Keep content human-readable and put durable retrieval fields in metadata:

{
  "summary": "One sentence future-useful memory.",
  "details": "Short supporting context, cause, decision, or acceptance rule.",
  "tags": ["lowercase-tag", "project-area"],
  "source": "user|pre_compact|post_tool_use|manual",
  "status": "active|open|resolved|superseded|stale|archived",
  "importance": 0.0,
  "confidence": 0.0
}

Lifecycle fields may also be present when a memory was confirmed, merged, superseded, or reviewed: related_to, supersedes, superseded_by, source_session, and last_confirmed. Prefer using the public review/lifecycle adapter commands to manage those fields instead of editing metadata by hand.

Workflow

1. Choose the most specific category.
2. Rewrite the memory as a concise, future-useful card with summary, details, tags, source, status, importance, and confidence when available.
3. Do not store secrets, credentials, tokens, private keys, passwords, or sensitive personal data.
4. Run the skill adapter:

python ./scripts/recall_skill.py save-insight <category> "<memory text>" --summary "<short summary>" --details "<supporting detail>" --tag <tag> --source skill --status active --importance 0.8 --confidence 0.9

Use --source-path when a claim comes from a project file. Use --claim-key and --claim-value for mutually exclusive current-truth claims. Preference memories must include durable evidence through --preference-key, --preference-evidence-type, and --decision-id.

5. Read the response result and next_action. Duplicate-shaped saves return updated_existing (the existing card was confirmed, nothing appended); near-duplicates return saved_related with a merge suggestion; low-value or evidence-lacking writes return ignored with a recovery hint. Follow the next_action instead of retrying the same save.
6. If the write reveals an existing conflicting current-truth claim, save only the verified new record and hand conflict resolution to manage-memory; do not run lifecycle commands from this skill.
7. If the category is missing but clearly reusable, save with the auto-created category and recommend refining it with define-category; do not design the taxonomy here.

Examples

python ./scripts/recall_skill.py save-insight decisions "Use SQLite as RECALL's default backend." --summary "SQLite is the default backend." --details "It is local, embedded, and requires no service." --tag sqlite --tag local-first --source skill --status active --importance 0.8 --confidence 0.9
python ./scripts/recall_skill.py save-insight commands "Verified test command: python -m unittest discover -s tests" --summary "Use unittest discovery for validation." --tag tests --tag command --source skill --status active --importance 0.7 --confidence 1.0

File-backed architecture fact:

python ./scripts/recall_skill.py save-insight architecture "Retrieval uses local SQLite plus deterministic scoring." --summary "Retrieval is local SQLite-backed." --details "Use source provenance when this claim comes from project files." --tag retrieval --source skill --status active --importance 0.8 --confidence 0.9 --source-path "plugins/recall/docs/architecture.md"

Current-truth claim:

python ./scripts/recall_skill.py save-insight project_state "Latest Kimi standard average is 90.12." --summary "Latest Kimi score is 90.12." --tag eval --source skill --status active --importance 0.9 --confidence 0.95 --claim-key recall.kimi.standard_average --claim-value 90.12

Rejected secret-like input:

{"action":"rejected","reason":"secret-like content must not be stored","category":null}

Duplicate write:

{"action":"updated","id":42,"category":"commands","reason":"exact durable command already existed"}

Inputs

Required: category, durable content, concise summary. Add details, tags, source, importance, confidence, and provenance when known. Reject empty, secret-like, or purely temporary content.

Output Format

Returns JSON with saved record ID and category. For preference evidence or automatic writes, report whether RECALL saved, updated, linked, or ignored the candidate.

{"action":"save-insight","id":42,"category":"decisions"}

When no write is made, return a reason instead of falling through silently:

{"action":"ignored","reason":"draft or temporary output","category":null}

Ownership Boundaries

Request	This skill action	Handoff
"remember this verified decision"	save durable card	none
"replace old memory 12 with this"	save new verified card if needed	skills/manage-memory for supersession
"what do we know about evals?"	do not answer from memory	skills/retrieve-memory
"make a new eval category"	do not design taxonomy	skills/define-category
"show noisy memories"	do not audit inventory	skills/review-memory

Edge Cases

• Drafts and one-task constraints are not standing preferences.
• Corrections should supersede old truth instead of creating two current claims.
• File-backed facts should carry --source-path so reconciliation can stale them.
• Exact duplicates should confirm/update existing memory, not multiply records.
• Low-confidence observations should be stored as risks or tasks only when they will change future work.
• Secrets or secret-like snippets should be rejected; save only the non-sensitive operational fact.
• User preferences require evidence fields, not a bare assertion from one ambiguous interaction.
• Temporary command output belongs in the answer, not memory, unless it becomes a verified reusable command.

Troubleshooting

• Secret-like text: do not weaken redaction; remove secret and save only durable fact.
• Wrong category: use edit-memory after retrieving exact ID.
• Conflicting current claims: save the verified new fact with a claim key, then hand resolution to manage-memory.
• Reusable custom category: refine it through define-category.
• Adapter path confusion: run from the installed plugin root or source plugin root so ./scripts/recall_skill.py resolves.
• Missing category: let RECALL auto-create only when the category is clearly reusable, then refine through define-category.

Related

• Retrieve Memory for task-focused recall.
• Review Memory for inspection and conflict review.
• Manage Memory for lifecycle changes.
• Evidence guide for durable write decisions.
• Sibling routes: skills/retrieve-memory, skills/review-memory, skills/manage-memory, skills/define-category.