/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. "/Users/me/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": {
    "feedback_signals": 37,
    "phase": 1,
    "status": "collecting"
  }
}

**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.

---

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.

---

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 heal