/slm-remember

name: slm-remember
description: Capture durable facts, decisions, constraints, and gotchas into SuperLocalMemory. Use when the user says "remember that", "save this decision", "note this constraint", or when a session produces a conclusion worth persisting across sessions. Always recall first to avoid duplicates.
when_to_use: |
  - "Remember that we use JWT with 1h expiry"
  - "Save this architectural decision"
  - "Store the constraint that X must not Y"
  - "Note this as a gotcha / blocker / convention"
  - After making a non-obvious decision during a coding session
  - After resolving a bug whose root cause should be persisted
allowed-tools: remember, recall, update_memory, Bash

slm-remember — Capture Durable Facts

Store atomic, durable facts into SuperLocalMemory for retrieval in future sessions. One fact per call. Recall before you remember.

---

What to store (and what not to)

**Store:**

• Architectural decisions ("Decided to use Postgres not MySQL — reason: JSONB support")
• Project conventions ("All API routes follow /api/v1/resource/{id} pattern")
• Hard constraints ("Never expose raw SQL errors to the HTTP response")
• Resolved gotchas ("Ollama needs keep_alive=-1 or it unloads the model between calls")
• Security rules ("Rate limit all public endpoints at 100 req/min")

**Do not store:**

• Transient context that is only relevant within this conversation
• Large blobs of code or full file contents (those belong in the project, not memory)
• Facts the project README already captures

---

Recall-before-remember (mandatory discipline)

Before calling `remember`, always call `recall` first with the core terms of what you are about to store. If a near-duplicate exists:

• Use `update_memory(fact_id, content)` to refine the existing fact instead

of creating a new one.

• Only call `remember` when no sufficiently similar fact is found.

Duplicates degrade retrieval quality for every future session.

---

MCP-first workflow

1. Check for duplicates first

recall(query="JWT token expiry auth", limit=5, session_id="<sid>")

If a near-duplicate is returned:

update_memory(
  fact_id="f8a2bc91",
  content="JWT tokens use 1h expiry for API access tokens; refresh tokens 30d (updated 2026-06-16)",
)

`update_memory` returns `{"success": true, "fact_id": "f8a2bc91", "content": "..."}`.

2. Store a new fact

remember(
  content="Decided to use JWT with 1h expiry for API auth; refresh tokens persist 30 days",
  tags="auth,security,decision",
  project="superlocalmemory",
  importance=8,
  session_id="<sid>",
)

Real response shape:

{
  "success": true,
  "fact_ids": ["c9d4e112"],
  "count": 1,
  "pending": false,
  "message": "Stored (recallable now; enriching async)."
}

When `pending: true`, the daemon was offline at save time; the fact enters a pending queue and becomes recallable once the daemon is back. Do not re-save.

**Never claim "saved" unless `success: true` is in the response.**

3. Parameter reference

remember(
  content: str,       # required — the atomic fact to store
  tags: str = "",     # comma-separated tags, e.g. "auth,security,gotcha"
  project: str = "",  # project scope, e.g. "superlocalmemory"
  importance: int = 5,# 1–10; see scale below
  session_id: str = "",# from session_init; attributes the write to this session
  session_date: str = "",# when the memory is ABOUT, if not today
  scope: str = None,   # v3.6.15 multi-scope: "personal" (default) | "shared" | "global"
  shared_with: str = "",# comma-separated profile_ids for scope="shared"
  idempotency_key: str = "",# replaying the same key will not store a second copy
)

> **Multi-scope (v3.6.15, opt-in):** leave `scope` unset for `personal` (private to > this profile — the default, identical to 3.6.14). `"global"` is visible to every > profile on the machine; `"shared"` is visible to the profiles in `shared_with`. > See [docs/shared-memory.md](../../../docs/shared-memory.md).

**importance scale:**

• 1–3: Low — passing notes, ideas, soft preferences
• 4–6: Normal — patterns, conventions, standard decisions (default: 5)
• 7–8: High — architectural decisions, integration contracts, known gotchas
• 9–10: Critical — security rules, blockers, irreversible decisions

Use 7–10 only for facts that would cause real damage if forgotten.

4. Date a memory to when it happened

`session_date` says **when the memory is about**, as distinct from when you wrote it. Omit it and the memory is dated today.

remember(
  content="The outage on the payments queue was caused by a stale DNS entry",
  tags="incident,payments,postmortem",
  project="platform",
  session_date="2026-08-14",       # YYYY-MM-DD, or a full ISO 8601 timestamp
  session_id="<sid>",
)

Use it whenever you are writing something down after the fact — a postmortem, a decision taken in a meeting last week, a migration that ran on a known date. Time-filtered recall (`window="7d"`, `window="2026-07-01..2026-07-31"`) reads event time, so a mis-dated memory is one a time-scoped question cannot find.

`session_date` does not change what **kind** of memory it is. A memory that describes something planned — "the migration is scheduled for Tuesday", "the certificate expires on 2026-09-01" — is stored as a **prospective** memory, and recall reports it as `"fact_type": "prospective"`. That is inferred from how the content reads, not from the date you pass. Stores written before 4.1.0 spelled this type `"temporal"`; that value still reads correctly and needs nothing from you.

---

5. One fact per call

Store one atomic fact per `remember` call. Do not concatenate multiple unrelated points into a single content string — they will be hard to update individually and harder to retrieve cleanly. If you have three separate decisions, make three calls.

6. Always set tags and project

Untagged, unscoped facts are harder to retrieve and harder to manage. Minimum: set `tags` to one or two