skill-memory

name	skill-memory
description	Memory vault management - create, search, classify, and index memories. Invoke for /learn command memory operations.
allowed-tools	Bash, Grep, Read, Write, Edit, AskUserQuestion

Memory Skill (Direct Execution)

Direct execution skill for memory vault management. Handles memory creation, similarity search, classification, and index maintenance through content mapping, MCP-based deduplication, and three memory operations (UPDATE, EXTEND, CREATE).

MANDATORY INTERACTIVE REQUIREMENT -- DO NOT SKIP:

• STOP at Step 4 and call AskUserQuestion to show files. Write NOTHING to disk until user responds.
• STOP at Memory Search and call AskUserQuestion for each segment. Write NOTHING to disk until user responds.
• These are not optional. Running autonomously without user input is a critical failure.

Context References

Reference (do not load eagerly):

• Path: @.memory/30-Templates/memory-template.md - Memory template
• Path: @.memory/20-Indices/index.md - Memory index
• Path: @.memory/memory-index.json - Machine-queryable memory index
• Path: @.opencode/context/project/memory/learn-usage.md - Usage guide

---

Execution Modes

Mode	Input	Description
text	Text content	Add quoted text as memory
file	File path	Add single file content as memory
directory	Directory path	Scan directory for learnable content
task	Task number	Review task artifacts and create memories

All non-task modes flow through: Content Mapping -> Memory Search -> Memory Operations

---

Content Mapping

Content mapping is the intermediate representation between input acquisition and memory operations. It segments input into topic-aligned chunks that can be matched against existing memories.

Content Map Data Structure

{
  "source": {
    "type": "text|file|directory",
    "path": "/path/to/input",
    "total_tokens": 2500
  },
  "segments": [
    {
      "id": "seg-001",
      "topic": "python/libs/requests",
      "source_file": "/path/to/file.md",
      "source_lines": "15-42",
      "summary": "HTTP request retry pattern with backoff",
      "estimated_tokens": 350,
      "key_terms": ["requests", "retry", "backoff", "session", "timeout"]
    }
  ]
}

Field Descriptions

Field	Type	Description
id	string	Unique segment identifier (seg-NNN)
topic	string	Inferred topic path (slash-separated hierarchy)
source_file	string	Original file path (for file/directory modes)
source_lines	string	Line range in source file (e.g., "15-42")
summary	string	1-2 sentence summary of segment content
estimated_tokens	number	Approximate token count for this segment
key_terms	array	3-5 significant terms for matching

Segmentation Algorithms

Structured Files (Markdown)

Split at heading boundaries:

1. Identify all headings (# ## ### ####)
2. Each heading starts a new segment
3. Segment includes all content until next same-or-higher level heading
4. Top-level content before first heading becomes its own segment

Structured Files (Code)

Split at blank-line-separated blocks:

1. Identify function/class definitions
2. Group related comments with their definitions
3. Separate standalone comment blocks as documentation segments
4. Keep import/require blocks together

Unstructured Text

Split at paragraph boundaries with topic grouping:

1. Split at double-newline (paragraph boundaries)
2. Group adjacent paragraphs with keyword overlap >40%
3. Single-sentence paragraphs merge with adjacent

Directory Input

Each file becomes an initial segment, then large files are split:

1. Each file is an initial segment
2. Files >800 tokens are split at section boundaries
3. Files <100 tokens are candidates for merging with related files

Small-Input Bypass

Inputs under 500 tokens skip segmentation and become a single segment:

if total_tokens < 500:
  segments = [{
    "id": "seg-001",
    "topic": inferred_topic,
    "summary": first_line_or_60_chars,
    "estimated_tokens": total_tokens,
    "key_terms": extract_keywords(content, 5)
  }]

Segment Size Guidelines

Condition	Action
Segment <100 tokens	Merge with adjacent same-topic segment
Segment 200-500 tokens	Ideal size, no action
Segment >800 tokens	Split at next heading/paragraph boundary

Key Term Extraction

Extract 3-5 significant terms per segment:

1. Remove stop words (the, a, is, are, etc.)
2. Extract nouns and technical terms (>4 characters)
3. Prioritize: proper nouns > technical terms > common nouns
4. Deduplicate (case-insensitive)
5. Return top 5 by frequency within segment

---

Memory Search

After content mapping, each segment is matched against existing memories to determine the appropriate operation (UPDATE, EXTEND, or CREATE).

MCP Search Path

When MCP server is available, use the execute pattern:

For each segment in content_map.segments:
  query = segment.key_terms.join(" ")
  results = execute("search", {
    "query": query,
    "vault": ".memory",
    "limit": 5
  })

Grep Fallback Path

When MCP is unavailable, use keyword-based file search:

# For each segment
for keyword in $key_terms; do
  grep -l -i "$keyword" .memory/10-Memories/*.md 2>/dev/null
done | sort | uniq -c | sort -rn | head -5

Overlap Scoring

Score keyword overlap between segment and each matching memory:

overlap_score = |segment_terms intersect memory_terms| / |segment_terms|

Where:
- segment_terms = segment.key_terms
- memory_terms = keywords extracted from memory content (same algorithm)

Classification Thresholds

Overlap Score	Classification	Action
>60%	HIGH	UPDATE - Replace memory content
30-60%	MEDIUM	EXTEND - Append new section
<30%	LOW	CREATE - New memory

Search Result Presentation -- MANDATORY STOP

YOU MUST call AskUserQuestion for EACH segment before writing anything. Do NOT infer what the user wants. Do NOT skip segments. Do NOT write memory files without explicit user confirmation per segment.

Present each segment with related memories via AskUserQuestion:

Segment: {segment.summary}
Topic: {segment.topic}
Key terms: {segment.key_terms.join(", ")}

Related Memories:
1. MEM-requests-retry-patterns (72% overlap) -> Recommended: UPDATE
2. MEM-python-http-patterns (45% overlap) -> Recommended: EXTEND
3. MEM-api-error-handling (18% overlap) -> Recommended: CREATE (no strong match)

What would you like to do with this segment?
[ ] UPDATE MEM-requests-retry-patterns (replace content)
[ ] EXTEND MEM-python-http-patterns (append section)
[ ] CREATE new memory
[ ] SKIP - don't save this segment

Interactive Override

Users can override any recommendation:

• Change UPDATE to CREATE (preserve existing, create duplicate)
• Change EXTEND to UPDATE (replace instead of append)
• Skip any segment
• Merge segments before processing (combine into single memory)

---

Memory Operations

Three distinct operations for memory management:

UPDATE Operation

Replace memory content while preserving structure:

1. Read existing memory file
2. Preserve frontmatter: created (original), tags, topic
3. Update frontmatter: modified = today
4. Move current content to ## History section with date marker
5. Replace main content with new segment content
6. Preserve ## Connections section
7. Write updated memory

Template for UPDATE:

---
title: "{new_title_from_segment}"
created: {original_created}
tags: {merged_tags}
topic: "{existing_or_updated_topic}"
source: "{new_source}"
modified: {today}
---

# {new_title}

{new_content_from_segment}

## History

### Previous Version ({original_created})

{previous_content}

## Connections
{preserved_connections}

EXTEND Operation

Append new dated section without modifying existing content:

1. Read existing memory file
2. Find insertion point (before ## Connections, or end of file)
3. Add dated extension section
4. Update frontmatter: modified = today
5. Optionally update tags if new topics introduced
6. Write updated memory

Template for EXTEND:

## Extension ({today})

**Source**: {segment.source_file}

{segment_content}

CREATE Operation

Generate new memory from segment:

1. Generate semantic slug from topic and title:

   generate_slug() {
     local topic="$1"
     local title="$2"
     local base=""

     # Priority 1: Topic path (most specific segment)
     if [ -n "$topic" ]; then
       base=$(echo "$topic" | rev | cut -d'/' -f1 | rev)
     fi

     # Priority 2: First 2-3 words of title
     local title_slug=$(echo "$title" | tr '[:upper:]' '[:lower:]' | \
       sed 's/[^a-z0-9 ]/-/g' | tr ' ' '-' | \
       cut -d'-' -f1-3 | sed 's/-$//')

     # Combine
     if [ -n "$base" ]; then
       slug="${base}-${title_slug}"
     else
       slug="$title_slug"
     fi

     # Sanitize and truncate to 50 chars
     slug=$(echo "$slug" | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//' | cut -c1-50)

     # Handle collision - NOTE: MEM- prefix preserved for grep discoverability
     local final_slug="$slug"
     local counter=2
     while [ -f ".memory/10-Memories/MEM-${final_slug}.md" ]; do
       final_slug="${slug}-${counter}"
       counter=$((counter + 1))
     done

     echo "$final_slug"
   }

   slug=$(generate_slug "$topic" "$title")
   filename="MEM-${slug}.md"

2. Apply memory template with all fields
3. Infer and apply topic
4. Add to index (both category and topic sections)
5. Write new memory file

Template for CREATE:

---
title: "{segment.summary}"
created: {today}
tags: {inferred_tags}
topic: "{segment.topic}"
source: "{segment.source_file or 'user input'}"
modified: {today}
keywords: {segment.key_terms}
summary: "{segment.summary}"
retrieval_count: 0
last_retrieved:
---

# {segment.summary}

{segment_content}

## Connections
<!-- Add links to related memories using [[filename]] syntax -->

Note: The MEM- prefix is preserved for grep discoverability (grep -r "MEM-" .memory/). Filenames follow the pattern MEM-{semantic-slug}.md (e.g., MEM-requests-retry-patterns.md).

Topic Inference

Infer topic using four-source priority:

1. Source directory path (highest priority)
   - /project/src/utils/ -> "project/utils"
   - /home/user/notes/python/ -> "python"

2. Keyword analysis
   - Extract domain indicators: python, requests, http, api
   - Map to topic: "python/libs" or "python/patterns"

3. Related memory topics
   - If UPDATE/EXTEND: inherit topic from target memory
   - If CREATE with high-overlap match: suggest that topic

4. User confirmation/override
   - Always present inferred topic for confirmation
   - User can modify or create new topic path

Index Maintenance

Note: After each operation, update all three indexes: index.md, .memory/10-Memories/README.md, and memory-index.json. See "JSON Index Maintenance" and "Index Regeneration Pattern" below.

After each operation, update both index.md and .memory/10-Memories/README.md:

index.md:

1. Add/update entry in "## By Category" under appropriate tag
2. Add/update entry in "## By Topic" under topic path
3. Update "## Recent Memories" (prepend, keep last 10)
4. Update "## Statistics" counts

.memory/10-Memories/README.md -- regenerate the full file listing: