superlocalmemory 3.6.13 → 3.6.15

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

@@ -0,0 +1,194 @@
+---
+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.15 · Qualixar · AGPL-3.0-or-later*

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

@@ -0,0 +1,207 @@
+---
+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.15 · Qualixar · AGPL-3.0-or-later*

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

@@ -0,0 +1,149 @@
+---
+name: slm-status
+description: Health and optimization stats for SuperLocalMemory — call slm_optimize_stats() for live compression and cache counters (compress_runs, tokens_saved_compress, cache_proxy_hits, cache_proxy_misses, cache_kv_hits, cache_kv_misses); run slm status [--json] for system state (mode, profile, DB size, fact/entity/edge counts) and slm doctor [--json] for preflight including the "Optimize (Surface B)" health line; use together to confirm optimization is actually saving tokens.
+when_to_use: "check slm status, health check, is slm working, optimize stats, tokens saved, cache hits, compress runs, slm doctor, preflight, db size, slm info, diagnose slm"
+allowed-tools: slm_optimize_stats, Bash
+---
+
+# slm-status — Health and Optimize Stats
+
+## Purpose
+
+Use this skill to answer: "Is SLM healthy?", "Is compression/caching actually saving tokens?", and "What does the system look like right now?" It covers three surfaces: the MCP stats tool, the `slm status` CLI, and the `slm doctor` preflight.
+
+## Primary MCP Tool: slm_optimize_stats
+
+```
+slm_optimize_stats() -> dict
+```
+
+No arguments. Returns counters from the current daemon and MCP process session.
+
+### Return dict (all keys always present)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| `ok` | bool | `True` on success; `False` on internal error |
+| `compress_runs` | int | Total compress calls recorded by the daemon (persisted across restarts) |
+| `tokens_saved_compress` | int | Cumulative tokens saved by compression (daemon-persisted) |
+| `cache_proxy_hits` | int | Proxy-layer cache hits (daemon-persisted) |
+| `cache_proxy_misses` | int | Proxy-layer cache misses (daemon-persisted) |
+| `cache_kv_hits` | int | MCP KV cache hits — **this MCP process session only**, resets on restart |
+| `cache_kv_misses` | int | MCP KV cache misses — **this MCP process session only**, resets on restart |
+| `ccr_note` | str \| None | Note about CCR entry count (not tracked per-session; see daemon `/api/v1/metrics`) |
+| `note` | str \| None | Scope clarification or error detail |
+
+### Important scope distinction
+
+`compress_runs`, `tokens_saved_compress`, `cache_proxy_hits`, and `cache_proxy_misses` are **daemon-persisted** — they survive MCP restarts and accumulate over the full install lifetime.
+
+`cache_kv_hits` and `cache_kv_misses` are **in-process counters** — they reset to 0 each time the MCP server starts. Use them to gauge cache effectiveness within the current session only.
+
+### Reading whether optimization is saving tokens
+
+```python
+stats = await slm_optimize_stats()
+if stats["ok"]:
+    savings = stats["tokens_saved_compress"]
+    kv_hit_rate = (
+        stats["cache_kv_hits"] / max(stats["cache_kv_hits"] + stats["cache_kv_misses"], 1)
+    )
+    # savings > 0 and kv_hit_rate > 0.5 means Surface B is actively reducing costs
+```
+
+If `compress_runs` is 0 after several sessions, compression is not being triggered — check daemon config and whether `slm_compress` is being called.
+
+If `cache_kv_hits` is 0 after repeated work, verify key naming consistency (the same key string must be used for set and get).
+
+## Secondary CLI: slm status
+
+```bash
+slm status [--json] [--verbose]
+```
+
+Reports system-level state — not optimization counters. Canonical fields (WP-02):
+
+- **mode** — active operation mode (e.g. `local`)
+- **profile** — current memory profile name
+- **DB size** — database file size on disk
+- **fact count** — number of stored memory facts
+- **entity count** — entity graph node count
+- **edge count** — entity graph edge count
+
+`--verbose` / `-v` adds: migration log, daemon port, disabled marker, last version.
+
+`--json` outputs a machine-readable dict with the same fields — preferred for agent consumption.
+
+Example agent-native invocation:
+
+```bash
+slm status --json
+```
+
+Typical JSON shape (exact field names depend on runtime; use `--json` and read what arrives):
+
+```json
+{
+  "mode": "local",
+  "profile": "code",
+  "db_size_mb": 12.4,
+  "facts": 384,
+  "entities": 201,
+  "edges": 519
+}
+```
+
+Do not rely on the human-readable format for parsing — always use `--json` when the output feeds another tool.
+
+## Secondary CLI: slm doctor
+
+```bash
+slm doctor [--json] [--quick]
+```
+
+Preflight check covering dependencies, embedding worker, daemon connectivity, and Surface B health. The **"Optimize (Surface B)"** line (WP-03) confirms whether the compression and cache subsystem initialised correctly.
+
+`--quick` skips the daemon and embedding probes — runs only dependency and config checks; faster but incomplete.
+
+`--json` outputs structured results per check — use this in automated health pipelines.
+
+A passing doctor output confirms:
+- Python deps present
+- Embedding worker reachable
+- Daemon responding
+- Surface B (Optimize) initialised
+
+A failing "Optimize (Surface B)" line means `slm_compress`, `slm_cache_set`, and `slm_cache_get` may not function correctly — investigate daemon config before relying on those tools.
+
+## Secondary CLI: slm optimize status
+
+```bash
+slm optimize status [--json]
+```
+
+Shows whether the Optimize module (cache + compress) is currently enabled or disabled at the daemon level. Available subcommands also include `optimize on`, `optimize off`, and `optimize savings`.
+
+The `optimize savings` subcommand accepts:
+
+```bash
+slm optimize savings [--since <days>] [--provider anthropic|openai|gemini] [--json]
+```
+
+`--since` defaults to 7 days. `--provider` filters by the target AI provider.
+
+Note: the `slm optimize` subcommands have known pre-existing parse-test failures — if a subcommand errors, use `slm_optimize_stats()` via MCP as the authoritative source.
+
+## Recommended Health Workflow
+
+1. Run `slm doctor --json` at session start to confirm all subsystems are up.
+2. Call `slm_optimize_stats()` after a batch of work to check token savings.
+3. Run `slm status --json` when you need DB size or memory counts.
+4. If `ok: false` on any MCP tool — check `note` field, then run `slm doctor` to isolate the failure.
+
+## Fail-Open
+
+`slm_optimize_stats()` never raises. On internal error it returns `ok: false` with all counters at 0. Continue the session — stats unavailability does not affect compression or caching operations.
+
+---
+
+SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.6.13"
+version = "3.6.15"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}
@@ -48,6 +48,10 @@ dependencies = [
     "zeroconf>=0.140",
     "lightgbm==4.6.0",
     "orjson==3.11.9",
+    # TOML writer for portable-kit IDE config (codex uses .codex/config.toml).
+    # stdlib tomllib is read-only; without this, connect_ide('codex') silently
+    # fails to write the MCP server block.
+    "tomli-w==1.2.0",
     "tree-sitter==0.25.2",
     "tree-sitter-language-pack==0.13.0",
     "rustworkx==0.17.1",
@@ -137,7 +141,7 @@ build-backend = "setuptools.build_meta"
 where = ["src"]
 
 [tool.setuptools.package-data]
-superlocalmemory = ["ui/**/*", "skills/**/*"]
+superlocalmemory = ["ui/**/*"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]