Skill

memory

CRUD operations for file-based markdown memory entries with deduplication and sync to MCP semantic store. Manages user, feedback, project, and reference memory types.

developer-tools

Popularity

Stars

Invocation

How this skill is triggered — by the user, by Claude, or both

Slash command

/scaffolding:memory

User invocable

Model invocable

Inline context

Default effort

Context Preview

The summary Claude sees in its skill listing — used to decide when to auto-load this skill

Unified CRUD operations over the scaffolding memory system. Handles file-based

SKILL.md

203 lines · ~1.7k tokens

Stats

LanguageShell

Stars14

MaintenanceExcellent

Last CommitJun 15, 2026

Actions

View Source View Plugin View on GitHub View README

Memory Skill

Purpose

Unified CRUD operations over the scaffolding memory system. Handles file-based markdown entries under ~/.claude/projects/.../memory/ and synchronises every write/delete with the MCP semantic vector store when available.

Use this skill when an explicit memory management action is requested: save a new entry, update or delete an existing one, query/search stored entries, or rebuild the MEMORY.md index.

Memory Types

Type	File prefix	Use for
`user`	`user_*.md`	Personal preferences, identity, recurring instructions
`feedback`	`feedback_*.md`	Corrections, tone/style adjustments, behavioural feedback
`project`	`project_*.md`	Stack details, environment facts, team conventions
`reference`	`reference_*.md`	External resources, URLs, credentials pointers

File Layout

~/.claude/projects/{project-slug}/memory/
├── MEMORY.md           ← index (one bullet per entry)
├── user_*.md           ← user-type entries
├── feedback_*.md       ← feedback-type entries
├── project_*.md        ← project-type entries
└── reference_*.md      ← reference-type entries

The project slug is the filesystem-safe version of the working directory path (hyphens replacing /, e.g. -home-komluk-repos).

Entry File Format

Every entry file MUST begin with YAML frontmatter followed by the body:

---
name: <kebab-case-slug>
description: "<one-line summary>"
metadata:
  node_type: memory
  type: <user|feedback|project|reference>
  originSessionId: <session-uuid-or-unknown>
---

<Body content — concise markdown. Max ~40 lines per file.>

**Why:** <rationale or context>

**How to apply:** <when/how to use this entry>

Rules:

name must be kebab-case and equal the file slug (after the prefix).
description is the single line shown in MEMORY.md.
Body MUST include Why and How to apply sections.
Do NOT store secrets, tokens, or passwords.

MEMORY.md Index Format

# Memory Index

- [<Title>](<filename>.md) — <one-line description>

One bullet per file, alphabetical order within each type group. The title is the human-readable name; the description matches the frontmatter description.

Operations

WRITE (new entry)

Deduplicate first — scan existing *.md files in the memory dir for entries with the same name or near-identical description. If a match exists, perform UPDATE instead of creating a new file.
Determine the type and derive the file slug from the entry name: <type>_<slug>.md (e.g. feedback_pve-env-confusion.md).
Create the file with the frontmatter + body template above.
Append a bullet to MEMORY.md (create the index if absent).

If MCP semantic memory is available, call:

mcp__semantic-memory__semantic_store(
  content="<description + key facts from body, ≤500 chars>",
  agent_name="memory",
  content_type="learning",
  tags=["<type>", "<slug>", ...],
  project_id="scaffold:831a4a3fd343b902"
)

Do NOT store secrets or file-system paths in the vector store.

UPDATE (existing entry)

Identify the target file by name/slug or MEMORY.md lookup.
Read the file, apply the change to frontmatter or body.
Overwrite the file (preserve frontmatter structure).
Update the bullet in MEMORY.md if the description changed.
If MCP available, re-store with updated content (the backend deduplicates by content hash and merges tags/timestamp).

DELETE (remove entry)

Delete the .md file.
Remove the corresponding bullet from MEMORY.md.
MCP semantic store does not expose a delete API — leave the vector entry (it will decay naturally and will not surface unless re-queried with high similarity).

QUERY (search/recall)

File-based query:

Scan MEMORY.md for keyword match in title or description.
Read matching files and return their body content.

Semantic query (if MCP available):

mcp__semantic-memory__semantic_search(
  query="<natural-language query>",
  project_id="scaffold:831a4a3fd343b902"
)

mcp__semantic-memory__semantic_recall(
  context="<task context summary>",
  project_id="scaffold:831a4a3fd343b902"
)

Return both file-based and semantic results, deduplicating overlaps.

Deduplication Rules

Before every WRITE check:

Check	Method	Action on match
Exact `name` match	frontmatter `name` field	UPDATE existing
Near-identical description	string similarity > 80 %	UPDATE existing
Same slug	filename match	UPDATE existing
Semantic duplicate	MCP `semantic_search` score > 0.92	UPDATE existing

If unsure, prefer UPDATE over creating a duplicate.

MCP Availability

If mcp__semantic-memory__* tools are not accessible (MCP server not wired or returns an error), skip all MCP calls silently. File-based memory is always sufficient; semantic memory is an optional enhancement layer.

Check by attempting a no-op recall — if it throws, set a local flag mcp_available = false and proceed without MCP for the remainder of the task.

Anti-Patterns

Avoid	Instead
Storing secrets or tokens	Note that the secret is in Vault/env; link the location
Duplicate files for the same topic	Deduplicate before writing; run UPDATE
MEMORY.md out of sync with files	Always update index on every write/delete
Oversized entry files (>60 lines)	Split into two entries with distinct slugs
Storing raw code snippets	Summarise the insight; keep ≤500 chars for MCP
Using generic slugs (`notes`, `info`)	Use descriptive kebab-case slugs
Writing to MCP without file write	Always write file first; MCP is the mirror

Quality Checklist

File has valid YAML frontmatter with name, description, metadata
name in frontmatter equals the slug in the filename
Entry has Why and How to apply sections
MEMORY.md updated (bullet added, modified, or removed)
No secrets, tokens, or passwords in any file or MCP content
Deduplication check ran before creating a new file
If MCP available: semantic_store called with project_id="scaffold:831a4a3fd343b902"
File is under 60 lines

memory

Popularity

Invocation

Context Preview

SKILL.md

memory

Popularity

Invocation

Context Preview

SKILL.md

Memory Skill

Purpose

Memory Types

File Layout

Entry File Format

MEMORY.md Index Format

Operations

WRITE (new entry)

UPDATE (existing entry)

DELETE (remove entry)

QUERY (search/recall)

Deduplication Rules

MCP Availability

Anti-Patterns

Quality Checklist

Similar Skills

Memory Skill

Purpose

Memory Types

File Layout

Entry File Format

MEMORY.md Index Format

Operations

WRITE (new entry)

UPDATE (existing entry)

DELETE (remove entry)

QUERY (search/recall)

Deduplication Rules

MCP Availability

Anti-Patterns

Quality Checklist

Similar Skills