Memory

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)

1. 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.
2. Determine the type and derive the file slug from the entry name: <type>_<slug>.md (e.g. feedback_pve-env-confusion.md).
3. Create the file with the frontmatter + body template above.
4. Append a bullet to MEMORY.md (create the index if absent).
5. If MCP semantic memory is available, call:

   mcp__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)

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

DELETE (remove entry)

1. Delete the .md file.
2. Remove the corresponding bullet from MEMORY.md.
3. 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__memory__semantic_search(
  query="<natural-language query>",
  project_id="scaffold:831a4a3fd343b902"
)

or

mcp__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__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