superlocalmemory 3.6.22 → 3.7.0

package/plugin-src/skills/slm-recall/SKILL.md

@@ -1,204 +0,0 @@
----
-name: slm-recall
-description: Search and retrieve facts, decisions, and past context from SuperLocalMemory. Use when the user asks to recall, find, search, or "what did we decide/say about X". Triggers multi-channel semantic retrieval with reranking; always call before storing anything new.
-when_to_use: |
-  - "What did we decide about X?"
-  - "Recall anything about Y"
-  - "Do we have context on the Z feature?"
-  - "Find stored information about authentication / the database / error handling"
-  - "Search for what I said about Y"
-  - Automatically before any non-trivial task, to surface prior context
-allowed-tools: recall, search, fetch, list_recent, Bash
----
-
-# slm-recall — Search & Retrieve Memory
-
-Retrieve stored facts, decisions, and past context from SuperLocalMemory using
-multi-channel retrieval. The golden rule: **recall before you remember**.
-
----
-
-## When to use recall vs search vs fetch vs list_recent
-
-| Situation | Tool |
-|-----------|------|
-| Conceptual or paraphrase query ("what did we agree on for auth?") | `recall` — full multi-channel retrieval + rerank |
-| Exact keyword match needed ("find facts containing BM25") | `search` — FTS5 BM25 only, lower latency |
-| You have a specific `fact_id` from a prior result | `fetch` — exact lookup, full detail |
-| Browse newest entries without a query | `list_recent` |
-
-Use `recall` as the default. `search` is a fallback for zero-result recall on a
-known exact term. `fetch` is for when you already know the ID.
-
----
-
-## Recall-before-remember discipline
-
-Before storing anything new, always call `recall` first. If a near-duplicate
-fact already exists, call `update_memory(fact_id, content)` to refine it
-rather than creating a duplicate. Duplicates degrade retrieval quality for
-every future session.
-
----
-
-## MCP-first workflow
-
-### 1. Standard recall
-
-```
-recall(
-  query="authentication strategy decision",
-  limit=20,            # default 20; reduce to 5 for quick pre-task checks
-  session_id="<sid>",  # pass the session_id returned by session_init
-  fast=False,          # default False; True skips SpreadingActivation channel
-)
-```
-
-Real response shape (`--json` equivalent):
-```json
-{
-  "success": true,
-  "results": [
-    {
-      "fact_id": "f8a2bc91",
-      "content": "Decided to use JWT with 1h expiry for API auth (2026-06-10)",
-      "score": 0.87,
-      "confidence": 0.91,
-      "trust_score": 0.84,
-      "fact_type": "decision",
-      "channel_scores": {
-        "semantic": 0.88,
-        "lexical": 0.61,
-        "temporal": 0.72,
-        "structural": 0.55
-      }
-    }
-  ],
-  "count": 1,
-  "query_type": "semantic",
-  "channel_weights": {
-    "semantic": 0.4,
-    "lexical": 0.2,
-    "temporal": 0.2,
-    "structural": 0.2
-  },
-  "retrieval_time_ms": 134,
-  "no_confident_match": false
-}
-```
-
-**Always check `no_confident_match`.** When `true`, no result cleared the
-evidence floor. Do not invent a memory — tell the user nothing was found and
-offer to search more broadly or store a new fact.
-
-### 2. Passing session_id
-
-Pass the `session_id` returned by `session_init`. It threads engagement signals
-through to the ranker so each recall contributes to improving retrieval for
-your project over time. Omitting it degrades the learning loop — recall works
-correctly, but feedback is not attributed to the session.
-
-### 3. Fast mode
-
-Use `fast=True` for pre-tool-call checks where sub-second response matters.
-This skips the SpreadingActivation channel. The remaining channels — semantic,
-lexical, temporal, and structural — still run.
-
-```
-recall(query="rate limiting approach", limit=5, session_id="<sid>", fast=True)
-```
-
-### 4. Keyword fallback via search
-
-When `recall` returns zero results on a specific term, try `search`:
-
-```
-search(query="BM25 indexing", limit=10, profile_id="")
-```
-
-`profile_id=""` uses the active profile. Response has `success`, `results`,
-and `count` but no `channel_scores` or `query_type`.
-
-### 5. Pull full detail for a known fact
-
-```
-fetch(fact_ids="f8a2bc91,d4c1e203")
-```
-
-Returns the full record for each ID: `entities`, `lifecycle`, `access_count`,
-`importance`, `observation_date`, `referenced_date`. Use this when the recall
-summary (120-char truncation in `list_recent`) is not enough.
-
-### 6. Browse recent memories
-
-```
-list_recent(limit=20, profile_id="")
-```
-
-Returns facts newest-first. Content is truncated to 120 chars. Use `fetch`
-once you have the `fact_id` for full content.
-
----
-
-## How multi-channel retrieval works
-
-`recall` runs four channels in parallel — semantic vector similarity, lexical
-BM25, temporal recency, and structural/graph — then fuses them with Reciprocal
-Rank Fusion (RRF) and applies a reranker. The `channel_weights` field in the
-response shows how each channel contributed for that query. Weights adapt over
-time based on engagement signals attributed via `session_id`.
-
-To inspect per-channel scores for a real query against your own data:
-
-```bash
-slm trace "<query>" [--limit N] [--json]
-```
-
-No benchmark numbers are cited here; performance is workload-dependent.
-
----
-
-## CLI fallback (when MCP is unavailable)
-
-```bash
-# Multi-channel semantic recall
-slm recall "<query>" [--limit N] [--fast] [--json]
-
-# Opt into shared/global facts for one query (v3.6.15 — off by default)
-slm recall "<query>" --include-global --include-shared
-
-# Keyword/FTS5 search (alias: slm search)
-slm search "<query>" [--limit N] [--json]
-
-# Per-channel score breakdown
-slm trace "<query>" [--limit N] [--json]
-
-# Browse recent memories
-slm list [--limit N] [--json]
-```
-
-Flags verified in source (main.py):
-- `slm recall`: `--limit`, `--fast`, `--json`, `--include-global` / `--no-global`, `--include-shared` / `--no-shared`
-- `slm search`: `--limit`, `--json`
-- `slm trace`: `--limit`, `--json`
-- `slm list`: `--limit` / `-n`, `--json`
-
-> **Multi-scope (v3.6.15, opt-in):** recall is shared-OFF by default — it returns only
-> this profile's facts. Pass `--include-global` / `--include-shared` (or the MCP
-> `include_global` / `include_shared` args) to opt in for a query, or set the defaults in
-> your `mode_a/b/c.json` config. See [docs/shared-memory.md](../../../docs/shared-memory.md).
-
-**Flags that do NOT exist** (fabricated in old skills — never write these):
-`--min-score`, `--format`, `--project`, `--tags` on recall or search.
-
----
-
-## Never fabricate a memory
-
-If `results` is empty or `no_confident_match` is `true`, report it plainly.
-Never construct a response as if a memory was found when it was not. The user
-trusts that what you surface came from the store.
-
----
-
-*SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-remember/SKILL.md

@@ -1,194 +0,0 @@
----
-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:
-```json
-{
-  "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
-  scope: str = None,   # v3.6.15 multi-scope: "personal" (default) | "shared" | "global"
-  shared_with: str = "",# comma-separated profile_ids for scope="shared"
-)
-```
-
-> **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. 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.
-
-### 5. Always set tags and project
-
-Untagged, unscoped facts are harder to retrieve and harder to manage. Minimum:
-set `tags` to one or two relevant terms and `project` to the repo/product name.
-
----
-
-## Deleting stale facts via CLI
-
-For deletion, the CLI is the authoritative surface. The MCP `forget` tool in
-v3.6.14 runs an Ebbinghaus decay cycle — it does NOT delete by query. For
-targeted deletion, use the CLI:
-
-```bash
-# Preview what would be deleted (always do this first)
-slm forget "<query>" --dry-run [--json]
-
-# Execute deletion after confirming the preview
-slm forget "<query>" --yes [--json]
-
-# Delete a specific fact by exact ID (use when you have the fact_id)
-slm delete <fact_id> --yes [--json]
-```
-
-Flags verified in source (main.py):
-- `slm forget`: positional `query`, `--dry-run`, `--yes` / `-y`, `--json`
-- `slm delete`: positional `fact_id`, `--yes` / `-y`, `--json`
-
-Always run `--dry-run` first and review the preview before passing `--yes`.
-
----
-
-## CLI fallback (when MCP is unavailable)
-
-```bash
-# Store a fact
-slm remember "<content>" [--tags a,b,c] [--json]
-
-# Store a shared/global fact (v3.6.15, opt-in)
-slm remember "<content>" --scope global
-slm remember "<content>" --scope shared --shared-with alice,bob
-
-# Flags verified in source (main.py): --tags, --json, --sync, --scope, --shared-with
-# --sync: wait for full enrichment before returning (default is async)
-# --scope: personal (default) | shared | global ; --shared-with: profile ids for shared
-```
-
-**Flags that do NOT exist** on `slm remember`:
-`--importance`, `--project`, `--format` — these are MCP-only params or fabricated.
-
----
-
-## Update vs forget discipline
-
-| Scenario | Action |
-|----------|--------|
-| Fact is still true but needs refinement | `update_memory(fact_id, new_content)` |
-| Fact is superseded or wrong | `slm forget "<query>" --dry-run` then `--yes` |
-| Duplicate found that matches recall result | `update_memory` on the existing one |
-| Fact has a known ID and is clearly obsolete | `slm delete <fact_id> --yes` |
-
----
-
-*SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-session/SKILL.md

@@ -1,207 +0,0 @@
----
-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 6-channel via daemon (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
-
-```json
-{
-  "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
-
-```json
-{
-  "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 health and
-`slm recall` / `slm remember` directly. Session attribution will not be
-available in degraded CLI-only mode.
-
-```bash
-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 | Always pass the stored `session_id` |
-| 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` |
-
----
-
-*SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later*