slm-session

name	slm-session
description	Manage SuperLocalMemory session lifecycle — call session_init once at the start of every fresh session to load relevant project context and get a session_id; call close_session when work is meaningfully complete to commit temporal summaries. Correct lifecycle hygiene is what makes SLM's learning loop work.
when_to_use	- At the start of every session (auto-trigger on first user message in a project context) - When the user says "start a new session" or "initialize memory" - When meaningful work completes and context should be committed - When the user says "close session" or "end session"
allowed-tools	session_init, close_session, Bash

slm-session — Session Lifecycle Hygiene

Session lifecycle is the mechanism that makes SuperLocalMemory's learning loop work. Without it, recall signals are not attributed and temporal summaries are not written. This is not optional housekeeping — it is load-bearing.

---

The lifecycle in one diagram

Session starts
     |
     v
session_init(project_path, query)
     |--- returns session_id, context, memories
     |
     v
Use session_id in every recall() and remember() call
     |
     v
Work completes
     |
     v
close_session(session_id)
     |--- writes temporal summaries to DB

---

session_init — call once per fresh session

When to call

Call session_init exactly once at the start of every fresh session, before any recall or remember. Never call it twice in a session — the second call would generate a new session_id and break signal attribution for any prior recalls or remembers in that session.

Signature

session_init(
  project_path: str = "",  # working directory path, e.g. "~/projects/foo"
  query: str = "",         # topic override; if omitted, derived from project_path
  max_results: int = 10,   # max memories to return (default: 10)
  max_age_days: int = 30,  # suppress memories older than N days unless score >= 0.7
                           # set to 0 to disable the age gate entirely
)

What it does

1. Derives a search query from project_path (or uses your explicit query).
2. Runs a 2-tier recall: full daemon retrieval (primary) or FTS5 BM25 (emergency fallback if daemon is unreachable).
3. Merges any pinned "core memory" facts with the recall results.
4. Applies an age gate — memories older than max_age_days are suppressed unless their relevance score is 0.70 or above (architectural decisions that remain permanently relevant still surface).
5. Returns a pre-formatted context block and a structured memories array for your session.
6. Generates a stable session_id (slm-YYYYMMDD-<8hex>) and returns it.

Real response shape

{
  "success": true,
  "session_id": "slm-20260616-a3f8c1d2",
  "context": "# Relevant Memory Context\n\n- JWT tokens use 1h expiry ...",
  "memories": [
    {
      "fact_id": "f8a2bc91",
      "content": "JWT tokens use 1h expiry for API auth (2026-06-10)",
      "score": 0.87,
      "is_core": false
    }
  ],
  "memory_count": 3,
  "core_memory": [],
  "degraded_mode": false,
  "retrieval_mode": "full_6_channel",
  "learning": 
     
     
     
  

Check degraded_mode. When true, the daemon was unreachable and only FTS5 BM25 was used — semantic, graph, temporal, and structural channels were unavailable. The context is still usable; note the degradation if relevant.

Check learning.phase:

• Phase 1 (< 50 signals): collecting baseline feedback
• Phase 2 (50–199 signals): active learning
• Phase 3 (≥ 200 signals): full ML-driven ranking

How to use the returned session_id

Store it and thread it into every recall and remember call in this session:

session_id = "<value from session_init>"

recall(query="auth strategy", session_id=session_id, limit=10)
remember(content="...", session_id=session_id, tags="auth,decision", project="myapp")

This attribution is what allows the ranker to learn which recalls led to useful outcomes for this project. It also gives the session a small working set, so successive recalls in one conversation build on what the earlier ones surfaced instead of each starting cold.

Do not synthesise a session id. An id beginning http:, mcp:, cli: or probe: is read as a synthetic per-request label rather than a conversation and is deliberately excluded from that working set. Use the one session_init returned, unchanged, for the whole session.

---

close_session — call when work is meaningfully complete

When to call

Call close_session when a meaningful unit of work is done — end of a coding session, after shipping a feature, after a design review. You do not need to call it after every small interaction. The signal is "this session's work is committed and should be summarised."

Do not call it at the start of a new session as a cleanup step — session_init is the correct opener and it does not require a prior close.

Signature

close_session(
  session_id: str = "",  # the session_id from session_init; if omitted,
                         # the system queries the DB for the most recent session
)

What it does

Aggregates facts written during the session into per-entity temporal summary events. These summaries enable future queries like "what happened during session X?" and contribute to the temporal channel in retrieval.

Real response shape

{
  "success": true,
  "session_id": "slm-20260616-a3f8c1d2",
  "summary_events_created": 4
}

summary_events_created: 0 is normal for short sessions where no new facts were written. It is not an error.

---

Why this matters

Every recall call with a session_id enqueues engagement signals — which results were shown, which were acted on. The learning ranker processes these signals to gradually up-weight channels and facts that prove useful for your project. Without session_id, signals land on a fallback identifier and are never attributed to a project or agent. Over many sessions this compounds: projects where lifecycle is respected have measurably better retrieval quality than projects where session_init is skipped.

Within a single session it compounds faster. The session's working set holds the memories its recalls have already surfaced, and later recalls rank those higher, so a long conversation converges on the material it is actually about.

Closing the loop explicitly

Engagement signals say a memory was shown. report_outcome says it was right:

report_outcome(memory_ids="<ids you actually used>", outcome="success")

Send it when a recalled memory changed what you did, and send failure when a confidently-returned memory turned out to be wrong — that is the only signal that stops a stale memory from being promoted. See the slm-recall skill.

---

CLI fallback (when MCP is unavailable)

There are no direct session_init or close_session CLI subcommands. When MCP is unavailable, use slm status to check system health and slm recall / slm remember directly. Session attribution will not be available in degraded CLI-only mode.

slm status [--json]    # check mode, profile, DB size, fact count
slm doctor [--json]    # preflight check including daemon and embedding worker

---

Common mistakes

Mistake	Consequence	Fix
Calling session_init twice in one session	Two session IDs; signals split across them	Call once; store the returned ID
Omitting session_id from recall / remember	No learning attribution, and every turn starts cold	Always pass the stored session_id
Inventing a session_id such as mcp:agent or http:1234	Read as synthetic, excluded from the working set	Use the id session_init returned
Never reporting an outcome	Ranking cannot tell a useful memory from a merely returned one	report_outcome after a recall that changed what you did
Never calling close_session	Temporal summaries not written	Call at end of each meaningful work unit
Calling close_session without a session_id when no prior writes exist	Returns error "No session_id found"	Pass the explicit session_id from session_init

---

Profile context (v3.8.0+)

session_init operates on the currently active profile. If you need to start a session on a different workspace, call switch_profile (requires code, full, or power MCP profile) before session_init, then call session_init for that workspace. See slm-profile for workspace switching.

The returned memories array reflects facts stored in the active profile only. To also surface shared or global facts in the initial context, pass the query explicitly and call recall with include_global/include_shared after session_init. See slm-scope for the sharing model.

---

Related skills

• slm-recall — multi-channel retrieval during the session
• slm-remember — store durable facts during the session
• slm-profile — workspace isolation and profile switching
• slm-scope — multi-scope sharing model

---

SuperLocalMemory v4.1.11 · Qualixar · AGPL-3.0-or-later