Slm Remember

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.

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.