sdd-memory

name	sdd-memory
description	Recall and persist durable project knowledge (decisions, conventions, gotchas, architecture) across SDD sessions. Provider-aware — supports standard (rules-only), Cursor native Memories, and mem0. Use at the start of planning/implementation to recall context, and at the end to persist discoveries.

SDD Memory Skill

Give SDD agents a configurable, optional long-term memory. The active backend is set in .sdd/config.json → memory.provider. This skill is a thin, provider-agnostic protocol: recall before you plan, persist after you learn.

When to Use

• Recall — starting /brief, /research, /specify, /plan, or /implement: load relevant prior decisions, conventions, and gotchas before acting.
• Persist — finishing a task or hitting a durable discovery: save facts worth remembering next time.
• Manage — /sdd-memory configures, seeds, or disables the backend.

If memory.enabled is false or provider is standard, this skill is a no-op beyond reading .cursor/rules/ and specs/. Never block work waiting on memory.

Step 0: Resolve Provider (always first)

Read .sdd/config.json → memory. Branch on provider:

Provider	Recall source	Persist target
standard	.cursor/rules/ + specs/ only	nothing (write specs/rules instead)
cursor-native	Cursor-injected Memories + rules/specs	surface durable facts as memory candidates (Cursor captures them)
mem0	mem0 MCP search + rules/specs	mem0 MCP add

Full per-provider read/write recipes: references/providers.md.

Step 1: Recall

1. Derive 2–4 search intents from the task (e.g. "auth token storage decision", "API error-handling convention").
2. Query the active provider (see references/providers.md). For standard, scan specs/ + rules.
3. Summarize the top relevant memories into the working context. Cite the source. If a recalled memory conflicts with the current request, surface the conflict — do not silently follow stale memory.

Step 2: Persist (what is worth remembering)

Save only durable, reusable, non-obvious facts in these categories (memory.scope):

• decisions — chosen approach + the why (e.g. "Use Postgres over Mongo for relational integrity").
• conventions — project rules an agent should follow (naming, structure, test style).
• gotchas — traps, flaky areas, env quirks, "don't do X".
• architecture — durable system shape (service boundaries, data flow).

Do not persist: transient state, secrets/tokens, full file contents, or anything already captured in a spec/rule.

Memory record shape

[category] <one-line fact> — <short why/context> (source: <task-id or file>)

Step 3: Hygiene

• Prefer updating an existing memory over creating a near-duplicate.
• When a decision is reversed, persist the reversal and mark the old one outdated (for cursor-native, tell the user it can be deleted in the UI; for mem0, update/delete the record).

Integration

• Called by sdd-explorer, sdd-planner, and sdd-implementer (recall at start, persist at end).
• Configured by /sdd-memory.
• secrets are never stored — enforce this regardless of provider.

References

• references/providers.md — exact recall/persist recipes for standard, cursor-native, and mem0 (incl. mem0 MCP tool calls and self-host notes).