context-memory

name	context-memory
description	Use when searching or updating durable project memory in `.my-context/`, especially `MEMORY.md`, architecture notes, or other cross-task context that should survive beyond the current task.

Context Memory

Use this skill when you need durable knowledge that should survive beyond the current task.

Why This Skill Exists

Task files explain one work item.

context-memory explains what should persist across work items and sessions.

Use this skill when the information is bigger than one task, or when future work will benefit from remembering a non-obvious fact or decision.

When To Use This Skill

Use this skill when:

• you need to search past project memory before making a decision
• you discovered a non-obvious fact worth preserving across sessions
• you want to record a durable decision so it is not re-opened casually
• you need to update .my-context/MEMORY.md
• you need to add or revise .my-context/architecture/ notes or other memory docs

Do not use this skill for active task notes or execution progress. Use context-task for that.

Core Principle

Project memory should preserve high-value context, not session chatter.

Keep only information that will still matter when the current diff, current task, and current conversation are no longer open.

Memory Search First

Before making a structural change, reopening a prior decision, or writing a memory update, search existing memory first.

If the memory_search tool is available (Pi with pi-memory extension), use it directly — it defaults to the current project when YISHAN_PROJECT_ID is set.

Fallback CLI command (when running outside Pi):

yishan memory search --output json --project-id $YISHAN_PROJECT_ID "<1-3 keywords>"

Search guidance:

• use 1 to 3 concrete keywords
• if results are too broad, retry with one narrower term
• read the returned files, not just the snippets
• search memory before asking the user to restate history that may already exist

MEMORY.md

MEMORY.md is the high-signal summary layer for durable project memory.

Recommended structure:

# Project Memory

_Last updated: YYYY-MM-DD_

## Locked Decisions

## Durable Discoveries

## Open Questions

Locked Decisions

Use for durable choices that should not be casually reopened.

Suggested entry shape:

- YYYY-MM-DD - <decision>. Why: <reason>.

Durable Discoveries

Use for non-obvious facts that are likely to save time or prevent mistakes later.

Prefix each item with one label:

• [Root Cause]
• [Invariant]
• [Workflow Trap]
• [Env Trap]
• [Test Trap]

Open Questions

Use for unresolved questions worth resurfacing later.

Remove them once answered.

Rules For MEMORY.md

• Read the file before editing it
• Edit carefully; do not overwrite blindly
• Do not use it as a session diary
• Do not duplicate active task state that already belongs in task files
• Deduplicate before adding new entries
• Keep entries short and self-contained
• Update the timestamp on every meaningful write
• If an item needs multiple paragraphs, move it into a dedicated .my-context/ document and reference that instead

Keep / Drop Guide

Keep:

• decisions that should not be re-litigated repeatedly
• root causes that took real effort to discover
• invariants that future edits could plausibly break
• recurring workflow, environment, or test traps
• unresolved questions worth resurfacing later

Drop:

• play-by-play implementation logs
• transient status notes
• details obvious from current code or diff
• task-specific progress that belongs in notes.md or plan.md
• one-off trivia with no future reuse

Other Memory Documents

Not all durable memory belongs in MEMORY.md.

Use dedicated .my-context/ docs when the content needs structure, depth, or diagrams.

Examples:

• .my-context/architecture/ for architectural behavior and system flows
• .my-context/archive/ for curated overflow or summarized historical material
• other project-specific memory docs when a topic deserves its own file

When updating these docs:

• keep them aligned with the current codebase
• prefer concise factual updates over broad rewrites
• search for existing docs before creating a new parallel one

Deciding Between Task Notes And Memory

Write to task-local files when the information is mainly about the current work item.

Write to project memory when:

• a future task will likely need this
• the fact is costly to rediscover
• the decision should constrain future edits
• the knowledge applies beyond one ticket or branch

Simple test:

Ask whether future work would still benefit from this fact if the current task folder were never opened again.

If yes, it probably belongs in project memory.

Update Timing

Update memory when the durable information becomes clear.

Do not wait until the end if the insight may be lost.

Good times to update memory:

• after identifying a real root cause
• after making a decision that should constrain future work
• after discovering a recurring test or environment trap
• when finishing a task that changed important architecture knowledge

Red Flags

Do not:

• dump task notes into MEMORY.md
• preserve duplicate or stale entries
• store low-value noise because "maybe it helps later"
• create parallel architecture docs without checking what already exists
• record a decision without enough context to understand why it exists

Bottom Line

Use context-memory to search, maintain, and extend the durable knowledge in .my-context/ so future work starts with the right context instead of rediscovering it.