mokhtarabadi/cognitive-lead-hq / skill-templates/project-memory
project-memory
VerifiedSmart note-taking and persistent project memory. Automatically saves Manager constraints and proactively retrieves context to prevent hallucinations.
Project Memory Skill
Purpose
This skill provides persistent, long-term memory for the project. It prevents the Manager from having to repeat project-specific rules, quirks, test commands, or architectural decisions. It uses the mcp-memory-server to slice notes into logical namespaces, preventing context bloat.
When to STORE Memory (Trigger)
Whenever the Manager explicitly states a rule, preference, or architectural constraint (e.g., "For this project, always use flag X" or "Never use Prisma push"), you MUST proactively save this context.
What to save: standing rules, architectural constraints, reusable quirks, test commands, Manager preferences. What to NEVER save: task progress, transient bug states, code snippets, or single-task details — those belong in the task file, not memory.
-
Choose a
namespacefrom this closed list only:architecture,opencode_config,project,quirks,release,telegram-sync,workflows. (testing/databasememories go underprojectunless the Manager approves a new namespace.) Do not invent a new namespace without Manager approval. -
Choose a concise, snake_case
key(e.g.,prisma_migration_rule). -
Write the memory with frontmatter so the index stays useful:
--- tags: [tag1, tag2] --- # One-line summary (becomes the index Summary, clamp to 120 chars) Rule or constraint in full, with reason and scope.Tags are optional but recommended. The first non-empty line after frontmatter becomes the index
Summary. -
Call the
store_memoryMCP tool with the content. Ensureoverwrite=Trueif updating an existing rule.
When to DELETE Memory (Trigger)
If the Manager explicitly states that a previous rule or constraint is no longer valid, or if supersession requires deletion:
- Safety Gate: Before calling
delete_memory, you MUST output: "⚠️ Memory deletion requested:{namespace}/{key}. Manager, please confirm." - Wait for explicit Manager approval (unless it is an automatic store-time supersession within the same namespace/key topic, which is logged as
Supersedes: {old_namespace}/{old_key}). - Upon approval, call
delete_memorywith the obsoletenamespaceandkeyto prune the memory bank.
Supersession Detection Heuristic
When storing a new memory, check if an existing memory in the same namespace covers the same topic:
- Before calling
store_memory, callsearch_memorywith the key topic keywords. - If a matching memory exists, compare dates/task references.
- If the new memory supersedes the old one (newer date, updated workflow, or explicit Manager instruction), call
delete_memoryon the old entry BEFORE storing the new one. This is the ONE allowed auto-deletion path — it only applies during store-time supersession within the same namespace and key topic. All other memory deletions require Manager approval. - Log the supersession in the new memory's content:
Supersedes: {old_namespace}/{old_key}.
Memory Index (Auto-Generated)
Canonical location: .opencode/memory/index.md — auto-generated Markdown index of all memory shards. Do not edit directly.
- Format:
| Namespace | Key | Summary | Tags |Markdown table, sorted bynamespacethenkey.Summaryis the first non-empty content line after frontmatter, clamped to 120 chars, pipes escaped.Tagsfrom frontmattertags:. - Generation: Atomically rebuilt after every successful
store_memoryanddelete_memoryviabuild_memory_index()(tempfile.mkstemp(dir=MEMORY_DIR)+os.replace+fsyncdir). Handles empty store (*No memories recorded yet.*) and pipe-escaping. Failures are logged but never fail the parent mutation. Also exposed asrebuild_memory_indexMCP tool for manual recovery after out-of-band file operations. - Workflow (Two-Step — Mandatory):
- Phase 0 — Read the index: In the Context Phase, read
.opencode/memory/index.md(if present) alongsideAGENTS.md/DESIGN.mdto get a compact overview before planning. - Selective fetch: Choose relevant rows from the index, then fetch the full content via
read_memory(namespace, key)orsearch_memory(query)— never auto-load all memories.
- Phase 0 — Read the index: In the Context Phase, read
The index is derived state: it will be recreated automatically; do not commit it as a source of truth, and do not create TODO.md/STATE.md equivalents elsewhere.
When to RETRIEVE Memory (Trigger)
At the start of EVERY new implementation task (during the Context Phase):
- Read
.opencode/memory/index.mdfirst (if present) for the compact overview. - Identify the domain of the task (e.g., are we modifying Docker? Writing Jest tests? Editing Auth?).
- Select relevant rows from the index and fetch via
read_memory(namespace, key); usesearch_memoryonly for unknown keys, andlist_namespacesonly as fallback if the index is missing (then triggerrebuild_memory_indexif needed). - Inject these retrieved constraints into your reasoning log to ensure you do not violate established project rules. On architectural ambiguities from memory, re-ask the Manager directly — never guess.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |