suemo 0.1.3 → 0.1.6

package/README.md

@@ -52,6 +52,7 @@ For suemo, the critical capability is allowing custom functions:
 - `search::*` (for `search::score`)
 - `math::*` (for `math::mean`, `math::min`)
 - `rand::*` (used in `wander` query)
+- `array::*` (used in `recall` query)
 
 If you run with strict capability mode, use an allowlist like:
 
@@ -138,7 +139,7 @@ What these commands do:
 - `suemo init fastembed`
   - checks `python-fastembed`, `python-fastapi`, `python-uvicorn` via `pacman -Q`
   - installs `data/fastembed-server.py` to `/opt/suemo/fastembed-server.py`
-  - creates `/opt/fastembed/local.env` once (user override file; not overwritten)
+  - creates `/opt/suemo/fastembed/local.env` once (user override file; not overwritten)
   - writes `/etc/systemd/system/suemo-fastembed.service`
   - enables + starts `suemo-fastembed.service`
 
@@ -169,6 +170,40 @@ suemo observe "Bun is significantly faster than Node for CLI tools" \
 suemo query "which JS runtime is faster"
 ```
 
+To inspect ranking/scoring internals:
+
+```sh
+suemo query "which JS runtime is faster" --explain
+suemo query "which JS runtime is faster" --explain --min-score 0.15 --relative-floor 0.75
+```
+
+`--explain` shows per-strategy contributions (vector/BM25/graph), final score, and applied thresholds.
+
+### How query scoring works
+
+`suemo query` computes a hybrid score per candidate and then applies score gates.
+
+1. **Per-strategy raw scores**
+   - vector: cosine similarity between memory embedding and query embedding
+   - bm25: `search::score(1)` from full-text index
+   - graph: anchor-weighted relation strength from top vector anchors
+
+2. **Normalization**
+   - `vector_norm = clamp((cosine - 0.2) / 0.8, 0, 1)`
+   - `bm25_norm = log1p(raw_bm25) / log1p(max_bm25_in_query)`
+   - `graph_norm = clamp(raw_graph, 0, 1)`
+
+3. **Final score**
+   - `final = 0.5*vector_norm + 0.25*bm25_norm + 0.15*graph_norm + agreement_bonus`
+   - `agreement_bonus = 0.05` when a node matches at least two strategies
+
+4. **Default gates (to reduce false positives)**
+   - `final >= 0.08` (`--min-score`)
+   - `final >= topScore * 0.65` (`--relative-floor`)
+   - `max(vector_norm, bm25_norm) >= 0.08` (primary evidence floor)
+
+Use `--explain` to inspect all these values per result.
+
 **5. Start the MCP server**
 
 ```sh
@@ -188,25 +223,31 @@ suemo serve --dev
 
 ## OpenCode setup (only integration target)
 
-Print copy-paste setup snippets:
+Create/update integration files automatically:
 
 ```sh
 suemo init opencode
 ```
 
-This prints:
+This updates:
 
-- MCP config snippet (`command: suemo`, `args: ["serve", "--stdio", ...]`)
-- minimal AGENTS.md guidance snippet
+- `~/.config/opencode/opencode.jsonc` (preferred) or `.json` fallback with `mcp.suemo`
+- `~/.config/opencode/AGENTS.md` with managed `<!-- SUEMO:START --> ... <!-- SUEMO:END -->` block
+
+Preview changes without writing files:
+
+```sh
+suemo init opencode --dry-run
+```
 
-To fetch the latest skill docs directly from your local checkout:
+To fetch latest skill docs directly from your local checkout:
 
 ```sh
 suemo skill
 suemo skill core-workflow
 ```
 
-No files are auto-written by this command.
+This command is idempotent and avoids duplicate `mcp.suemo` entries.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "suemo",
-	"version": "0.1.3",
+	"version": "0.1.6",
 	"description": "Persistent semantic memory for AI agents — backed by SurrealDB.",
 	"author": {
 		"name": "Umar Alfarouk",

package/skills/suemo/SKILL.md

@@ -3,7 +3,7 @@ name: suemo
 description: OpenCode-focused persistent memory workflow for suemo with CLI/MCP parity and versioned references.
 license: GPL-3.0-only
 compatibility: opencode
-version: 0.1.2
+version: 0.1.6
 ---
 
 # suemo skill

package/skills/suemo/references/agents-snippet.md

@@ -1,7 +1,7 @@
 ---
 name: agents-snippet
 description: AGENTS.md snippet optimized for suemo skill discovery and usage.
-version: 0.1.2
+version: 0.1.6
 ---
 
 # AGENTS.md snippet

package/skills/suemo/references/cli-reference.md

@@ -1,7 +1,7 @@
 ---
 name: cli-reference
 description: CLI command reference for suemo v0.0.6 including skill access.
-version: 0.1.2
+version: 0.1.6
 ---
 
 # CLI reference

package/skills/suemo/references/core-workflow.md

@@ -1,7 +1,7 @@
 ---
 name: core-workflow
 description: Canonical suemo operating loop for OpenCode agents.
-version: 0.1.2
+version: 0.1.6
 ---
 
 # Core workflow

package/skills/suemo/references/manual-test-plan.md

@@ -1,7 +1,7 @@
 ---
 name: manual-test-plan
 description: Comprehensive manual test matrix for suemo features and commands.
-version: 0.1.2
+version: 0.1.6
 ---
 
 # Manual test plan

package/skills/suemo/references/mcp-reference.md

@@ -1,7 +1,7 @@
 ---
 name: mcp-reference
 description: MCP tool reference for suemo v0.0.6.
-version: 0.1.2
+version: 0.1.6
 ---
 
 # MCP tools

package/skills/suemo/references/schema-retention-longevity.md

@@ -1,7 +1,7 @@
 ---
 name: schema-retention-longevity
 description: Long-term schema and retention design expectations for suemo.
-version: 0.1.2
+version: 0.1.6
 ---
 
 # Schema + retention longevity

package/skills/suemo/references/sync-local-vps.md

@@ -1,7 +1,7 @@
 ---
 name: sync-local-vps
 description: Two-way sync manual scenario for local and VPS SurrealDB.
-version: 0.1.2
+version: 0.1.6
 ---
 
 # Local ↔ VPS sync scenario

package/src/AGENTS.md

@@ -0,0 +1,150 @@
+# Working with suemo
+
+suemo is your persistent memory. Use it to store what you learn, remember what matters, and build on past work.
+
+## Before anything else
+
+**Load the skill doc first.** It is versioned and may contain updated workflows, references, and tool signatures that supersede this file.
+
+- CLI: `suemo skill`
+- MCP: `skill({})`
+
+For a specific reference: `suemo skill <reference-name>` / `skill({ reference: "<reference-name>" })`
+
+Available references: `agents-snippet`, `cli-reference`, `core-workflow`, `manual-test-plan`, `mcp-reference`, `schema-retention-longevity`, `sync-local-vps`
+
+Do not proceed until the skill doc is loaded.
+
+## Session protocol
+
+These steps are **mandatory**, not suggested.
+
+### On session start
+
+```
+goal_list(scope: "<active-scope>")
+query("recent work on [topic]", scope: "<active-scope>")
+```
+
+Read relevant results before touching any code. Do not re-derive what is already stored.
+
+### While working
+
+Store anything that would save time next session:
+
+```
+observe("[fact you learned or confirmed]")
+believe("[interpretation or conclusion that might change]")
+```
+
+Query only when you are **genuinely blocked** or starting a distinct new subtask. Do not query on every step — it burns context and adds noise.
+
+### Before ending (or if interrupted)
+
+Call this **before** your final tool invocation, not after — sessions can be cut off without warning:
+
+```
+episode_end(<session_id>, summary="<one sentence of what was accomplished>")
+goal_resolve(<goal_id>)   # only if the goal is fully done
+```
+
+If the session is interrupted and you never reach this step, that is acceptable. Incomplete episodes are better than missing observations mid-session.
+
+## observe vs believe
+
+Use `observe()` for facts. Use `believe()` for interpretations that could be wrong or change.
+
+**Observe:** `"[tool] requires [flag] — without it, [failure mode]"`\
+**Believe:** `"[tool] behaviour is likely a bug — worth retrying after an upgrade"`
+
+Beliefs trigger contradiction detection. If you later believe the opposite, the old belief is invalidated and both are linked — useful for tracing why you changed your mind.
+
+For uncertain things, prefer `kind: "question"` or `kind: "hypothesis"` over stating them as facts.
+
+## What to observe
+
+Observe your **experience**, not documentation:
+
+- Approaches tried and whether they worked
+- Config or flags that took effort to figure out
+- Errors encountered and how they were resolved
+- Decisions made and the reasoning behind them
+- Constraints or preferences the user stated
+
+**Good:** `"[library] [method] runs before [other step] — caused [bug] in [context]"`\
+**Skip:** `"[library] supports [feature]"` ← already in the docs
+
+## What not to store
+
+- Transient state: current cursor position, open file, in-progress thought
+- Exact code snippets from files — observe your _understanding_ of them instead
+- Timestamps — suemo sets `valid_from` automatically
+- Uncertain things stated as facts — use `kind: "hypothesis"` instead
+
+## Querying
+
+suemo uses hybrid retrieval (vector + BM25 + graph) with score gates.
+Natural language often works, but broad prompts can still be noisy.
+
+Use scoped, specific queries first:
+
+```
+query("what approaches did we try for N+1 query issue", scope: "<active-scope>")
+query("past decisions about auth middleware", scope: "<active-scope>")
+```
+
+For exact strings (error codes, env var names, flag spellings), quote them:
+
+```
+query('"SURREAL_CAPS_ALLOW_FUNC" init fix', scope: "<active-scope>")
+```
+
+If ranking looks weak, inspect scoring directly:
+
+```
+suemo query "<your query>" --scope <active-scope> --explain
+suemo query "<your query>" --scope <active-scope> --explain --min-score 0.25 --relative-floor 0.8
+```
+
+- Use `query()` when searching — you don't know which node you want
+- Use `recall(<nodeId>)` when you have a node ID and want it plus neighbours
+
+`recall()` also ticks the spaced-repetition clock on that node.
+
+## Using recall vs query
+
+- Use `query()` when you don't know _which_ memory you want — you're searching
+- Use `recall(nodeId)` when you have a specific node ID and want it plus its neighbours — you're inspecting
+
+`recall()` also ticks the spaced-repetition clock on that node, marking it as "actively used".
+
+## Goals
+
+Set a goal at the start of any multi-step task:
+
+```
+goal_set("<description of task>", scope: "<active-scope>")
+```
+
+Check open goals at session start (already covered above). Resolve when done:
+
+```
+goal_resolve(<id>)
+```
+
+Goals are a record of intent. Abandoned goals show up in health reports as a signal something was left incomplete.
+
+## What suemo handles automatically
+
+- **Timestamps** — `valid_from` on write, `valid_until` on contradiction or invalidation
+- **Deduplication** — identical writes merge; near-duplicates create a new linked node
+- **Consolidation** — runs on a schedule; no manual trigger needed
+- **Embeddings** — computed server-side via `fn::embed()`; never pass vectors yourself
+
+## Health check
+
+```
+suemo health
+```
+
+Signs things are working: recent consolidation run, goals resolved not abandoned, queries returning relevant results without heavy tuning.