superlocalmemory 4.2.4 → 4.2.6

package/cursor-plugin/cursor-skills/slm-governance/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: slm-governance
+description: Governed-workspace behavior for SuperLocalMemory. Covers roles (admin/member/viewer) and company mode, who administers a company-mode workspace (a signed-in admin, or `slm team` on the SLM computer), `slm token show` in strict mode, what remote web apps can never see or change, retention and lifecycle settings, the audit trail, GDPR export and erasure, and how agents must behave when operating under workspace governance. The audit and retention tools need the power MCP profile. Agents must never bypass governance controls.
+when_to_use: |
+  - "What can I do in this workspace?" (role check)
+  - "Move cold memories to archive after 60 days"
+  - "Show the audit trail for recent memory operations"
+  - "Export my data for GDPR compliance"
+  - "Delete all memories about user X (right to erasure)"
+  - "Turn on require-login for this workspace", "I'm locked out of company mode", slm team status
+  - "The dashboard asks for a key" (slm token show)
+  - Enterprise deployment with multi-team shared SLM
+  - Compliance, audit, or data governance task
+allowed-tools: audit_trail, set_retention_policy, get_retention_stats, get_lifecycle_status, compact_memories, consistency_check, recall, search, remember, Bash
+---
+
+# slm-governance — Governed Workspace Behavior
+
+SuperLocalMemory can run with named users and roles per workspace (company
+mode), keeps a compliance audit trail, applies a retention lifecycle, and ships
+GDPR export and erasure commands. This skill documents how an agent must behave
+in a governed workspace and what the governance tools really do. The MCP audit
+and retention tools are in the `power` tool set, not the default: if they are
+missing, tell the user to run `slm tools set power` and restart this app (see
+`slm-profile`). The `slm gdpr` and `slm team` commands work either way.
+
+---
+
+## Role model
+
+By default SLM is single-user: whoever runs it is the owner and nothing asks for
+a login. Company mode adds named users, each with one role per workspace
+(profile). A role in one workspace grants nothing in another.
+
+| Role | Read | Write | Share (`shared`/`global` writes) | Delete | Manage users and settings |
+|------|------|-------|-------|--------|-----------------|
+| `viewer` | Yes | No | No | No | No |
+| `member` | Yes | Yes | Yes | No | No |
+| `admin` | Yes | Yes | Yes | Yes | Yes |
+
+**Agent behavior by role:**
+
+- **Viewer**: Only call `recall`, `search`, `fetch`, `list_recent` and other
+  reads. Never call `remember`, `update_memory`, `delete_memory` or any write
+  tool. If a write is refused, say so: "This workspace is read-only for my role."
+- **Member**: May write memories, including `scope="shared"` and `scope="global"`
+  when the user explicitly asks for them. May not delete memories or change
+  users, roles or settings.
+- **Admin**: Everything above plus deletion and user administration.
+
+No MCP tool or `slm` command reports your role (only a signed-in dashboard session can ask the daemon, at `GET /api/rbac/whoami`). Do not guess it: attempt
+what the user asked and treat a permission refusal as final. Setting up users,
+roles and "Require login" is done in the dashboard under **Settings → Access**;
+there is no `slm user` or `slm role` command. The only company-mode commands
+are `slm team status` and `slm team policy` (next section).
+
+Roles apply to every route that touches data, not only to `remember` and
+`recall`. That includes pictures, documents, connected folders and
+turning features on: reading a file by path, connecting a folder
+(`slm sources add`), turning on pictures and documents and cleaning up with
+`slm media gc --apply` or `slm media repair` need the owner or an admin. SLM's
+own data folder can never be named as a path or a source. With login
+required, every page of data (export, compliance records, profiles, learning
+and trust details) needs a signed-in user; a test walks every route so a new
+one cannot slip through.
+
+---
+
+## Who administers a company-mode workspace
+
+While users are enrolled and login is required, the install token or an API
+key alone no longer administers the workspace: any local program can fetch the
+install token, so it would let anyone switch company mode off. Administration
+needs one of these:
+
+- **A signed-in admin** (a user with the `admin` role on that workspace),
+  through the dashboard.
+- **`slm team` on the SLM computer**, which uses a private capability file that
+  only the user running SLM can read, so the owner can never be locked out
+  even if every admin is:
+
+```bash
+slm team status                          # "Require login: on. Users: N."  (read-only, safe)
+slm team policy --require-login on       # every user signs in
+slm team policy --require-login off      # the machine owner is the user again
+```
+
+Run them as the same user that runs SLM, with the daemon running. Otherwise the
+daemon refuses them. Users, roles and sessions are kept when login is turned
+off. Switching the requirement off lowers protection for everyone, so do it
+only when the user asks for it in this conversation; `slm team status` first.
+With no users enrolled yet, the machine owner can still create the first
+administrator.
+
+### Strict mode: `slm token show`
+
+With `SLM_REQUIRE_CREDENTIALS=1`, the dashboard is not handed the SLM key; the
+person pastes it into a one-time box. `slm token show` prints that key. It is a
+secret that opens write access: do not run it on your own, never paste it into
+chat, a memory or a log, and tell the user to run it in their own terminal.
+`slm rotate-token` replaces it (then `slm restart`).
+
+### What remote web apps can never do
+
+A connected web app (see `slm-web-access`) cannot correct, delete, share or
+switch profile, cannot read another profile, and cannot change, delete, pin or
+replace a memory it is not allowed to see: it is answered as if that memory did
+not exist. It never sees memories that came from a connected folder, and sees
+a picture or page only when its text held no secret or personal data.
+
+---
+
+## require-login
+
+When login is required, every operation on memories needs a signed-in user,
+including the connection your assistant uses. SLM handles this at the daemon
+level; agents do not pass credentials in tool calls. If a tool call returns an
+authentication or permission error, you must:
+
+1. Stop the current operation immediately.
+2. Report the requirement to the user.
+3. Never cache, retry, or work around the block.
+
+In this mode, `include_global=True` and `include_shared=True` on `recall` are
+quietly turned off while the recall policy forbids cross-profile reads (the
+default), so an opt-in recall can come back with only personal facts. Do not try
+to work around it. See `slm-scope`.
+
+---
+
+## Retention and lifecycle
+
+Every memory moves through lifecycle states as it goes unused: active, warm, cold,
+archived. Two tools set and inspect that, and a third runs the forgetting cycle.
+They need the `power` tool set.
+
+### Set the thresholds
+
+```
+set_retention_policy(
+  cold_after_days: int = 30,      # days of inactivity before a memory goes cold
+  archive_after_days: int = 90,   # days before it is archived
+)
+```
+
+It sets two thresholds and returns them. There is no `profile_id` argument and
+there are no named retention zones or per-tag policies; tagging a memory does not
+route it to a different policy.
+
+### Look at the state
+
+```
+get_retention_stats(profile_id="")
+get_lifecycle_status(limit=50, profile_id="")
+```
+
+`get_retention_stats` reports, from the retention table, the count and average
+retention score per Ebbinghaus zone (`active`, `warm`, `cold`, `archive`,
+`forgotten`) and the totals. `get_lifecycle_status` counts the active, warm, cold
+and archived state of up to `limit` memories and returns up to ten short
+samples of each. Neither says when the next cycle runs.
+
+### Apply it
+
+```
+forget(dry_run=True)          # preview the decay cycle for the active profile
+compact_memories(dry_run=True) # preview lifecycle-state transitions
+```
+
+The MCP `forget` tool is not a delete: it recomputes retention scores and moves
+memories between zones. `compact_memories` moves memories whose lifecycle state
+has become due (for example cold to archived); it does not merge duplicates. Both
+default to a dry run. Run the preview first, show it to the user, and only then
+pass `dry_run=False`. Do not run either without the user's say-so.
+
+---
+
+## Audit trail
+
+```
+audit_trail(limit: int = 50)
+```
+
+Returns the newest `limit` rows of the compliance audit for the active profile,
+as `{"success", "entries", "count"}`. Each entry has `audit_id`, `profile_id`,
+`action`, `target_type`, `target_id`, `details` and `timestamp`. There are no
+filter arguments. Entries are compliance actions (store, retrieve, delete, export
+and the like).
+
+Use it for compliance reviews, for investigating an unexpected change, and for
+audit reports to a data controller.
+
+---
+
+## GDPR
+
+```bash
+slm gdpr status [--profile P] [--json]            # posture: receipts, audit counts, known gaps; read-only
+slm gdpr export --profile P [--output FILE] [--json]   # Art. 15/20 access and portability
+slm gdpr erase --profile P --dry-run [--json]     # preview an erasure
+slm gdpr erase --profile P --yes [--json]         # Art. 17 erasure, IRREVERSIBLE
+slm gdpr verify --receipt-id ID [--profile P]     # check an erasure receipt (exit 0 ok, 1 tampered, 2 not found)
+```
+
+`slm gdpr erase` erases a **profile**. It refuses to run without both `--profile`
+and `--yes`, and without them it only previews. It is the only irreversible
+operation here, so confirm the subject, the profile and the authority to erase
+with the user before running it. `slm gdpr status` lists the known gaps (for
+example backups and the code graph) rather than claiming completeness.
+
+To remove individual memories rather than a whole profile, use the deletion
+commands from `slm-remember`:
+
+```bash
+slm forget "<subject or project name>" --dry-run --json   # ALWAYS first
+slm forget "<subject or project name>" --yes --json
+slm delete <fact_id> --yes --json
+```
+
+Memories that belong to a reviewed correction cannot be deleted this way; the
+refusal names the case. After an erasure, confirm with `slm recall "<content>"`
+that nothing comes back, and never try to re-derive erased content from other
+stored facts.
+
+---
+
+## Scope enforcement in governed workspaces
+
+- **Viewers** cannot write anything, whatever the `scope` argument.
+- **Members and admins** can write `shared` and `global` facts; writing either
+  scope needs the share permission, which both roles hold.
+- Agents must not split a `global` fact into several `shared` facts, or otherwise
+  accumulate visibility the user did not ask for.
+
+---
+
+## Integrity checks
+
+```
+consistency_check(limit: int = 100)
+```
+
+Runs a sheaf-consistency check over up to `limit` memories and returns pairs of
+facts that contradict each other, with a severity (`fact_a`, `fact_b`,
+`severity`, `content_a`), plus `facts_checked`, `facts_errored` and
+`total_contradictions`. If the checker is disabled it says so in `note`. For the
+health of the store itself (orphan rows, erased words left behind, unfinished
+deletes) use `slm db integrity` and `slm db repair`; see `slm-status`.
+
+---
+
+## Agent checklist for governed workspaces
+
+Before each write operation:
+- [ ] The user asked for it, and a refusal from the workspace is respected
+- [ ] Scope is `personal` unless the user explicitly asked to share
+- [ ] Pass `session_id` so the write is attributed
+
+Before running any destructive or state-changing operation (`forget`,
+`compact_memories`, `slm forget --yes`, `slm gdpr erase --yes`):
+- [ ] The user authorized it in this conversation
+- [ ] Ran the dry run or preview and showed it to the user
+- [ ] GDPR: confirmed the subject or controller authorized the erasure
+
+---
+
+## Related skills
+
+- `slm-scope` — scope model details (personal/shared/global)
+- `slm-profile` — memory profiles and tool sets
+- `slm-remember` — fact storage, corrections and deletion
+- `slm-recall` — retrieval reference (includes scope read flags)
+- `slm-mesh` — mesh tools
+- `slm-media` — pictures, documents and folders, and the roles that gate them
+- To use this memory from a web assistant or another computer, see the slm-web-access skill.
+
+---
+
+*SuperLocalMemory v4.2.6 · Qualixar · AGPL-3.0-or-later*

package/cursor-plugin/cursor-skills/slm-graph/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: slm-graph
+description: >
+  Index and query a codebase as a structural graph — build the code graph, trace blast radius of a
+  change, find callers/callees/inheritors, semantic code search by meaning, assemble PR review
+  context, and detect what changed since last index. Use when the user asks how code connects, what
+  breaks if X changes, what calls a function, what a class inherits from, how to navigate an
+  unfamiliar codebase, or to understand risk before editing.
+when_to_use: |
+  - what calls X
+  - what breaks if I change Y
+  - what does Z inherit from
+  - find code that handles authentication
+  - impact analysis before editing
+  - code navigation in unfamiliar repos
+  - blast radius before a PR
+  - pre-commit change detection
+allowed-tools: build_code_graph, query_graph, get_blast_radius, semantic_search_code, get_review_context, detect_changes, Bash
+---
+
+# slm-graph — Code Intelligence Skill
+
+Index any repo as a code knowledge graph and answer structural questions about it: callers, callees, impact radius, semantic search, and review context. These tools are not in the default tool set: they need `slm tools set code` (or `whole`); see "Tool set requirement" below.
+
+**Prerequisite rule:** every tool except `build_code_graph` self-guards — if the graph is not built it returns `{"success": false, "error": "Code graph not built. Run build_code_graph first."}`. Always index first.
+
+---
+
+## Tool Reference
+
+### 1. `build_code_graph` — index a repository
+
+```
+build_code_graph(
+    repo_path: str,
+    languages: str = "",
+    exclude_patterns: str = "",
+) -> {success, files_parsed, nodes, edges, flows, communities, duration_ms}
+```
+
+Parses all supported source files, extracts functions/classes/imports, builds the call graph, detects execution flows, and identifies code communities. Replaces any previous index for the same repo.
+
+- `repo_path` — absolute path to the repository root. Must exist and sit under your home directory; a path outside it is refused with `Invalid repo_path`.
+- `languages` — comma-separated language filter, e.g. `"python,typescript"`. Empty string = index all supported languages.
+- `exclude_patterns` — comma-separated glob patterns to exclude, e.g. `"**/node_modules/**,**/.venv/**"`. Empty = no exclusions.
+
+When to (re)build:
+- Before using any other graph tool for the first time on a repo.
+- After significant changes to the codebase (pull, merge, large refactor).
+- When `detect_changes` or `query_graph` returns stale/unexpected results.
+- Rebuild is safe and idempotent — it replaces the previous index atomically per file.
+
+```
+# Index the full repo
+build_code_graph(repo_path="/abs/path/to/myrepo")
+
+# Index only Python, skip tests and generated code
+build_code_graph(
+    repo_path="/abs/path/to/myrepo",
+    languages="python",
+    exclude_patterns="**/tests/**,**/generated/**"
+)
+```
+
+---
+
+### 2. `query_graph` — traverse relationships
+
+```
+query_graph(
+    pattern: str,
+    target: str = "",
+    limit: int = 20,
+) -> {success, pattern, target, results: [{qualified_name, kind, file_path, name}]}
+```
+
+Query the graph for structural relationships. `pattern` is required and must be one of the eight valid values below. `target` is a qualified name, partial name, or node ID — matched with exact-then-LIKE fallback.
+
+Valid patterns:
+
+| pattern | returns |
+|---|---|
+| `callers_of` | functions/methods that call `target` |
+| `callees_of` | functions/methods that `target` calls |
+| `imports_of` | modules/symbols that `target` imports |
+| `imported_by` | who imports `target` |
+| `tests_for` | test nodes associated with `target` |
+| `inherits_from` | base classes of `target` |
+| `inherited_by` | subclasses of `target` |
+| `contains` | symbols defined inside `target` (e.g. methods in a class) |
+
+```
+# Who calls the auth handler?
+query_graph(pattern="callers_of", target="authenticate_user")
+
+# What does the payment processor import?
+query_graph(pattern="imports_of", target="PaymentProcessor", limit=30)
+
+# What classes inherit from BaseModel?
+query_graph(pattern="inherited_by", target="BaseModel")
+```
+
+---
+
+### 3. `get_blast_radius` — impact analysis
+
+```
+get_blast_radius(
+    changed_files: str,
+    max_depth: int = 2,
+    max_nodes: int = 500,
+) -> {success, changed_nodes, impacted_nodes, impacted_files, edges, depth_reached, truncated}
+```
+
+Computes the full impact radius for one or more changed files using bidirectional BFS (callers and callees). Returns every node and file reachable within `max_depth` hops. Use this before editing to understand risk surface.
+
+- `changed_files` — comma-separated file paths relative to the repo root, e.g. `"src/auth/handler.py,src/auth/models.py"`.
+- `max_depth` — BFS depth. Default 2. Increase to 3–4 for deep call chains; lower to 1 for a quick first-degree check.
+- `max_nodes` — caps the result set. If `truncated=true` in the response, the real blast radius is larger.
+
+```
+# What breaks if I change the auth handler?
+get_blast_radius(changed_files="src/auth/handler.py")
+
+# Deeper analysis across two files
+get_blast_radius(
+    changed_files="src/payments/gateway.py,src/payments/models.py",
+    max_depth=3,
+    max_nodes=200
+)
+```
+
+If `truncated` is `true`, narrow the scope with `max_nodes` or reduce `max_depth` to get a reliable result.
+
+---
+
+### 4. `semantic_search_code` — find code by meaning
+
+```
+semantic_search_code(
+    query: str,
+    kind: str = "",
+    limit: int = 20,
+) -> {success, results: [{qualified_name, kind, file_path, score, line_start, name}]}
+```
+
+Hybrid FTS5 + vector search over all indexed code entities. Use when you know what the code *does* but not what it's *called*.
+
+- `query` — natural language description, e.g. `"retry logic for HTTP requests"` or `"parse JWT token from header"`.
+- `kind` — optional filter: `"Function"`, `"Class"`, `"File"`, or `"Test"`. Empty = all kinds. Case-insensitive match in the engine.
+- `limit` — max results. Default 20.
+
+Results include a `score` field (higher = more relevant).
+
+```
+# Find where authentication is handled
+semantic_search_code(query="authenticate user from request token")
+
+# Find only test functions that cover database writes
+semantic_search_code(query="database write transaction rollback", kind="Test")
+
+# Find the rate limiter class
+semantic_search_code(query="rate limiting middleware", kind="Class", limit=5)
+```
+
+---
+
+### 5. `get_review_context` — assemble PR review context
+
+```
+get_review_context(
+    changed_files: str,
+    include_source: bool = True,
+) -> {success, summary, review_items, test_gaps, risk_score}
+```
+
+Produces a token-optimized review package for a set of changed files: a plain-language summary, a ranked list of review items with per-node risk scores, and a list of changed symbols that have no associated test coverage.
+
+- `changed_files` — comma-separated file paths relative to the repo root.
+- `include_source` — whether to include source code snippets in the context (default `True`). Set `False` to reduce token usage when you only need the risk analysis.
+
+`risk_score` is a float 0–1 on the overall changeset. `review_items[].risk_score` is per-node.
+
+```
+# Get review context for a PR touching two files
+get_review_context(changed_files="src/auth/handler.py,src/auth/utils.py")
+
+# Risk summary only, no source snippets
+get_review_context(
+    changed_files="src/payments/gateway.py",
+    include_source=False
+)
+```
+
+---
+
+### 6. `detect_changes` — what changed since last index
+
+```
+detect_changes(
+    base: str = "HEAD~1",
+) -> {success, summary, risk_score, changed_functions, test_gaps, review_priorities}
+```
+
+Runs `git diff` against `base`, maps the changed hunks to graph nodes, and returns a risk-scored list of changed functions, test gaps, and review priorities. Requires the repo to be a git repository.
+
+- `base` — git ref to diff against. Default `"HEAD~1"` (one commit back). Any valid git ref works: `"main"`, `"v1.4.0"`, a commit SHA, etc.
+
+```
+# What changed in the last commit?
+detect_changes()
+
+# What changed since the release branch?
+detect_changes(base="release/1.4")
+
+# What changed relative to main?
+detect_changes(base="main")
+```
+
+Returns `error` if the repo root is not a git repository or if git is not available.
+
+---
+
+## Realistic Workflow
+
+### Explore an unfamiliar codebase
+
+```
+# 1. Index it
+build_code_graph(repo_path="/abs/path/to/repo")
+
+# 2. Find the entry point by meaning
+semantic_search_code(query="request router entry point", kind="Function")
+
+# 3. Trace what it calls
+query_graph(pattern="callees_of", target="handle_request")
+
+# 4. See who else calls the same core function
+query_graph(pattern="callers_of", target="authenticate_user")
+```
+
+### Before editing a function
+
+```
+# 1. Know what you are touching
+semantic_search_code(query="retry HTTP requests with backoff")
+
+# 2. Understand blast radius before making the change
+get_blast_radius(changed_files="src/http/client.py")
+
+# 3. Check test gaps
+get_review_context(changed_files="src/http/client.py")
+```
+
+### Pre-commit / PR review
+
+```
+# 1. What changed in this branch vs main?
+detect_changes(base="main")
+
+# 2. Full impact analysis for the changed files
+get_blast_radius(changed_files="src/auth/handler.py,src/auth/models.py")
+
+# 3. Assemble review context
+get_review_context(changed_files="src/auth/handler.py,src/auth/models.py")
+```
+
+---
+
+## Error Handling
+
+All tools return `{"success": false, "error": "<message>"}` on failure — they never raise.
+
+| Error message | Cause | Fix |
+|---|---|---|
+| `Code graph not built. Run build_code_graph first.` | No index exists | Call `build_code_graph(repo_path=...)` first |
+| `Repository path does not exist: <path>` | Bad `repo_path` in build | Pass an absolute path that exists |
+| `Git not available or not a git repository: ...` | `detect_changes` needs git | Only works in git repos with git installed |
+| `Invalid pattern '...'` | Wrong `pattern` in `query_graph` | Use one of the 8 valid pattern strings |
+| `No node found matching '<target>'` | Target not in index. Returned as `success: true` with an empty `results` and this `message`, not as an error | Rebuild or check the qualified name via `semantic_search_code` |
+| `Invalid repo_path: ...` | `repo_path` is outside your home directory | Index a repository under your home directory |
+
+If `build_code_graph` returns `files_parsed: 0`, no supported source files were found — check `repo_path` and `exclude_patterns`.
+
+---
+
+## Tool set requirement
+
+The six tools above are registered only when the MCP server runs the `code` tool
+set, or with `SLM_MCP_ALL_TOOLS=1` / `SLM_MCP_PROFILE=whole`, or when
+`SLM_MCP_TOOLS` names them. They are **not** in `core`, `full`, `power` or the
+default every app gets, so there the tools do not exist and a call fails as an
+unknown tool. If the user asks for graph work and the tools are missing, tell
+them: "Code-graph tools are off by default. Run `slm tools set code` (graph
+without mesh) or `slm tools set whole` (every tool), then restart this app."
+Let them choose; it changes the tools every connected app sees.
+
+`switch_profile` does not change the tool set; it changes the active memory
+profile. See `slm-profile`. The `code` set leaves out the mesh and several
+administration tools, so ask the user before changing their tool set.
+
+With `SLM_MCP_ALL_TOOLS=1` more graph tools appear: `update_code_graph` (refresh
+for `changed_files` without a full rebuild), `list_graph_stats`,
+`get_architecture_overview`, `list_communities`, `get_community`, `list_flows`,
+`get_flow`, `get_affected_flows`, `find_large_functions`, `enrich_blast_radius`,
+`refactor_preview`, and the code-to-memory tools `link_memory_to_code`,
+`code_memory_search`, `code_entity_history` and `code_stale_check`. The memory
+links need `"bridge_enabled": true` in `code_graph_config.json` and a rebuild.
+All are host-only: a remote caller cannot use them.
+
+---
+
+## Related skills
+
+- `slm-profile` — memory profiles and the tool sets that decide which tools exist
+- `slm-recall` — retrieve architectural decisions before graph queries
+- `slm-status` — confirm the active profile and graph index health
+
+---
+
+SuperLocalMemory v4.2.6 · Qualixar · AGPL-3.0-or-later