| name | memory |
| description | Unified memory CRUD: write/update/delete/query file-based markdown entries and sync to MCP semantic store. TRIGGER when: saving a new memory entry, updating or deleting an existing entry, querying stored memories, or deduplicating before write. SKIP: 3-tier agent memory (use agent-memory); in-task vector recall (use semantic-memory-mcp). |
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"
)
or
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
