Slm Session

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",
  "calibration_status": "uncalibrated",
  "calibration_id": null,
  "answer_confidence": null,
  "abstained": false,
  "abstention_reason": null,
  "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 abstained. If true, the memories returned in context and memories do not answer the query that seeded this session — say so, or ask, rather than presenting them as settled fact. This is most relevant when you passed an explicit query; the default project-context query rarely has a single "right answer" for a judge to evaluate. answer_confidence is a measurement, not a guarantee. calibration_status: "uncalibrated" means no judge is configured, and abstained then only reflects the older "nothing found" signal. See slm-recall for the full rule, which applies identically here.

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.