suemo 0.1.4 → 0.1.7

package/README.md

@@ -11,6 +11,8 @@
 
 suemo gives AI agents a memory that survives across sessions, models, and runtimes. Write observations from a Telegram bot, query them from OpenCode, consolidate overnight — all agents share one source of truth in SurrealDB.
 
+Canonical behavioral specification: **[`SPEC.md`](./SPEC.md)**.
+
 ---
 
 ## Features
@@ -170,6 +172,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
@@ -189,25 +225,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:
+
+- `~/.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:
 
-- MCP config snippet (`command: suemo`, `args: ["serve", "--stdio", ...]`)
-- minimal AGENTS.md guidance snippet
+```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.
 
 ---
 
@@ -405,6 +447,27 @@ This prints your active target (`url`, `namespace`, `database`) and step-by-step
 
 Agents never supply temporal fields (`valid_from`, `valid_until`). These are system-managed.
 
+### Memory field semantics (quick reference)
+
+- `content`: canonical memory payload.
+- `summary`: optional condensed text for compact retrieval/consolidation. It does **not** replace `content`.
+- `source`: optional provenance label (free-form string), e.g. `prompt-capture`, `consolidation:nrem`.
+- `prompt_source`: optional pointer to the prompt memory record that originated a derived memory.
+- `fsrs_next_review`: optional review timestamp; currently set on `recall()` (not on every ingest).
+
+### Episode `memory_ids`
+
+`episode.memory_ids` stores memory IDs attached to an open session, used for session reconstruction.
+
+If you rarely see it populated, the typical reason is missing `sessionId` on write calls.
+Current behavior: only write paths invoked with `sessionId` append to `memory_ids`.
+`believe` now supports session linkage too:
+
+- CLI: `suemo believe "..." --session <sessionId>`
+- MCP: `believe({ content, sessionId, ... })`
+
+See `SPEC.md` for full normative semantics and hardening targets.
+
 ### Scope and longevity notes
 
 - Default inferred project scope now uses nearest `<projectDir>/suemo.json` with `main.projectDir` defaulting to `.ua`.

package/package.json

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

package/skills/suemo/SKILL.md

@@ -3,13 +3,38 @@ 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.4
+version: 0.1.7
 ---
 
 # suemo skill
 
 Use suemo to persist technical context across sessions with minimal, project-scoped memory.
 
+## Strict defaults (v0.1.7)
+
+- Always run pre-checks before implementation:
+  - `goal_list({ scope })`
+  - `query({ input: "recent work on <topic>", scope })`
+  - `context({ scope, limit: 20 })`
+- `observe.kind` accepts only: `observation | belief | question | hypothesis | goal`
+- For non-trivial writes, prefer structured content:
+  - `**What**`, `**Why**`, `**Where**`, `**Learned**`
+- End meaningful tasks with:
+  - `episode_end({ sessionId, summary, goal, discoveries, accomplished, files_changed })`
+  - `goal_resolve({ goalId })` when done
+  - `query({ input: "most recent observations", scope })`
+  - `health()`
+
+## OpenCode plugin support
+
+`suemo init opencode` now installs three things:
+
+1. MCP config entry for suemo
+2. AGENTS.md suemo block
+3. OpenCode plugin at `~/.config/opencode/plugins/suemo.ts`
+
+The plugin injects strict suemo protocol into system prompt and adds compaction checkpoint reminders.
+
 ## Quick use
 
 - CLI latest skill: `suemo skill`

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

@@ -1,17 +1,25 @@
 ---
 name: agents-snippet
 description: AGENTS.md snippet optimized for suemo skill discovery and usage.
-version: 0.1.4
+version: 0.1.7
 ---
 
 # AGENTS.md snippet
 
 ```md
-## suemo-first memory workflow
+## suemo-first memory workflow (strict)
 
 Before significant work:
 
-- query("what do I know about <topic>")
+- suemo_goal_list({ scope: "<active-scope>" })
+- suemo_query({ input: "recent work on <topic>", scope: "<active-scope>" })
+- suemo_context({ scope: "<active-scope>", limit: 20 })
+- suemo_episode_start({ sessionId: "<session-id>" }) for new tasks
+
+Schema guardrails:
+
+- suemo_observe.kind must be one of: observation | belief | question | hypothesis | goal
+- Never use discovery/architecture/bugfix as kind
 
 If you need latest usage docs:
 
@@ -21,16 +29,19 @@ If you need latest usage docs:
 
 During work:
 
-- observe("...") for concrete facts
-- believe("...") for conclusions
-- goal_set("...") for long tasks
+- suemo_observe({ content: "**What**: ...\n**Why**: ...\n**Where**: ...\n**Learned**: ...", kind: "observation" })
+- suemo_believe("...") for uncertain interpretations
+- suemo_goal_set("...") for long tasks
 
 After completion:
 
-- goal_resolve("...") if applicable
-- episode_end(sessionId, summary="...")
+- suemo_episode_end({ sessionId, summary, goal, discoveries, accomplished, files_changed })
+- suemo_goal_resolve({ goalId }) if applicable
+- suemo_query({ input: "most recent observations", scope: "<active-scope>" })
+- suemo_health()
 
 After compaction/reset:
 
-- context({ scope: "<project-id>", limit: 20 })
+- suemo_session_context_set({ sessionId, summary: "<compacted summary>" })
+- suemo_context({ scope: "<project-id>", limit: 20 })
 ```

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.4
+version: 0.1.7
 ---
 
 # CLI reference
@@ -14,10 +14,15 @@ Core:
 - `suemo serve [--stdio|--dev]`
 - `suemo skill [reference]`
 
+Aliases (deprecated, still accepted with warning):
+
+- `suemo skills` → use `suemo skill`
+- `suemo init surrealdb` → use `suemo init surreal`
+
 Memory:
 
 - `suemo observe <content>`
-- `suemo believe <content>`
+- `suemo believe <content> [--session <sessionId>]`
 - `suemo query <input>`
 - `suemo recall <nodeId>`
 - `suemo wander`

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

@@ -1,40 +1,68 @@
 ---
 name: core-workflow
 description: Canonical suemo operating loop for OpenCode agents.
-version: 0.1.4
+version: 0.1.7
 ---
 
 # Core workflow
 
-1. Start with memory lookup:
+1. Start with strict pre-check:
 
 ```ts
-query('what do I know about <topic>')
+goal_list({ scope: '<project-scope>' })
+query({ input: 'recent work on <topic>', scope: '<project-scope>' })
+context({ scope: '<project-scope>', limit: 20 })
+episode_start({ sessionId: '<session-id>' }) // when beginning new task
 ```
 
 2. During work, persist concrete discoveries:
 
 ```ts
-observe('...')
-believe('...')
+observe({
+	content: '**What**: ...\n**Why**: ...\n**Where**: ...\n**Learned**: ...',
+	kind: 'observation',
+	scope: '<project-scope>',
+})
+believe({ content: '...', scope: '<project-scope>' })
 ```
 
-3. For long tasks:
+3. Kind schema is strict:
 
 ```ts
-goal_set('...')
+// valid only:
+// observation | belief | question | hypothesis | goal
 ```
 
-4. If compaction/reset happened:
+4. For long tasks:
 
 ```ts
+goal_set({ content: '...', scope: '<project-scope>' })
+```
+
+5. If compaction/reset happened:
+
+```ts
+session_context_set({
+	sessionId: '<session-id>',
+	summary: '<compacted summary>',
+})
 context({ scope: '<project-id>', limit: 20 })
 ```
 
-5. Close session:
+6. Close session with structured fields:
 
 ```ts
-episode_end(sessionId, summary = '...')
+episode_end({
+	sessionId: '<session-id>',
+	summary: '...',
+	goal: '...',
+	discoveries: ['...'],
+	accomplished: ['...'],
+	files_changed: ['path/to/file'],
+})
+goal_resolve({ goalId: '<goal-id>' }) // if completed
+query({ input: 'most recent observations', scope: '<project-scope>' })
+health()
 ```
 
 Prefer project-scoped memory. Let suemo infer scope from nearest `{projectDir}/suemo.json` (recommended `main.projectDir = '.ua'`).

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.4
+version: 0.1.7
 ---
 
 # Manual test plan
@@ -35,10 +35,11 @@ Expected:
 
 1. `episode_start`
 2. add observations with `sessionId`
-3. `session_context_set`
-4. `context`
-5. `episode_end` with structured fields
-6. verify episode fields persisted
+3. add belief with `sessionId` (`suemo believe "..." --session <id>` or MCP `believe({ sessionId })`)
+4. `session_context_set`
+5. `context`
+6. `episode_end` with structured fields
+7. verify episode fields persisted
 
 ## E. Goals
 
@@ -66,7 +67,17 @@ Expected:
 2. `suemo skill core-workflow`
 3. MCP `skill({})`, `skill({ reference: "cli-reference" })`
 
-## I. Output modes
+## I. OpenCode init + plugin install
+
+1. `suemo init opencode --dry-run`
+2. `suemo init opencode`
+3. Verify files:
+   - `~/.config/opencode/opencode.jsonc` or `.json` contains `mcp.suemo`
+   - `~/.config/opencode/AGENTS.md` has `<!-- SUEMO:START --> ... <!-- SUEMO:END -->`
+   - `~/.config/opencode/plugins/suemo.ts` exists
+4. Validate plugin appears under OpenCode loaded plugins
+
+## J. Output modes
 
 Repeat representative commands under:
 

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

@@ -1,11 +1,17 @@
 ---
 name: mcp-reference
 description: MCP tool reference for suemo v0.0.6.
-version: 0.1.4
+version: 0.1.7
 ---
 
 # MCP tools
 
+Strictness notes (v0.1.7):
+
+- `observe.kind` is strict enum: `observation | belief | question | hypothesis | goal`
+- `episode_end` supports optional structured fields: `summary`, `goal`, `discoveries`, `accomplished`, `files_changed`
+- For reliable agent adoption, pair `episode_end` with `goal_resolve` and post-check `query("most recent observations")`
+
 Write/mutate:
 
 - `observe`
@@ -42,5 +48,7 @@ Maintenance:
 Notes:
 
 - Optional `scope` defaults to inferred project id.
+- `believe` accepts optional `sessionId` to attach created belief memories to an open episode.
 - `update` re-embeds when `content` changes.
 - `episode_end` accepts structured fields (`goal`, `discoveries`, `accomplished`, `files_changed`).
+- `skill` returns inline references; use `skill({ reference: "core-workflow" })` for canonical loop.

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.4
+version: 0.1.7
 ---
 
 # 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.4
+version: 0.1.7
 ---
 
 # Local ↔ VPS sync scenario

package/src/AGENTS.md

@@ -0,0 +1,130 @@
+**CRITICAL:** This protocol is mandatory. Start each new task with the checklist below. End each completed task with `suemo_episode_end` + `suemo_goal_resolve` (if applicable). Do not skip.
+
+## 1) Pre-Session Checklist (required)
+
+Before implementation:
+
+- [ ] `suemo_goal_list({ scope: "<active-scope>" })`
+- [ ] `suemo_query({ input: "recent work on <topic>", scope: "<active-scope>" })`
+- [ ] `suemo_context({ scope: "<active-scope>", limit: 20 })`
+- [ ] Resolve abandoned goals if any
+- [ ] `suemo_episode_start({ sessionId: "<session-id>" })` for new tasks
+
+Proceed only after all checks pass.
+
+---
+
+## 2) Strict schema rules (required)
+
+### `suemo_observe` kind is strict
+
+Valid `kind` values only:
+
+- `observation`
+- `belief`
+- `question`
+- `hypothesis`
+- `goal`
+
+### `suemo_episode_end` payload shape
+
+Minimum schema requirement: `sessionId`.
+
+Required by protocol when finishing meaningful work:
+
+- `summary`
+- `goal`
+- `discoveries` (array)
+- `accomplished` (array)
+- `files_changed` (array)
+
+Use exact field names above.
+
+---
+
+## 3) During work
+
+Persist important information immediately (not only at the end).
+
+Use this structure for non-trivial observations:
+
+```md
+**What**: <what changed>
+**Why**: <reason>
+**Where**: <files/paths>
+**Learned**: <gotchas/decisions>
+```
+
+Guidance:
+
+- Facts → `suemo_observe`
+- Interpretations/uncertainty → `suemo_believe`
+- Longer tasks → `suemo_goal_set`
+
+---
+
+## 4) After completion
+
+Run in order:
+
+1. `suemo_episode_end({ sessionId, summary, goal, discoveries, accomplished, files_changed })`
+2. `suemo_goal_resolve({ goalId })` when done
+3. `suemo_query({ input: "most recent observations", scope })`
+4. `suemo_health()`
+
+---
+
+## 5) Querying best practices
+
+Prefer specific, scoped queries:
+
+```ts
+suemo_query({
+	input: 'past decisions about auth middleware',
+	scope: '<project-id>',
+})
+suemo_query({
+	input: '"SURREAL_CAPS_ALLOW_FUNC" init fix',
+	scope: '<project-id>',
+})
+```
+
+When weak ranking is suspected, run `--explain` from CLI to inspect scoring.
+
+---
+
+## 6) Anti-patterns
+
+- ❌ Storing transient state (cursor position, temporary thoughts)
+- ❌ Storing raw code snippets instead of distilled understanding
+- ❌ Querying on every small step
+- ❌ Skipping `suemo_episode_end`
+- ❌ Forgetting `suemo_goal_resolve`
+- ❌ Using non-schema `kind` values
+
+---
+
+## 7) Compaction/reset handling
+
+Immediately:
+
+1. `suemo_session_context_set({ sessionId, summary: "<compacted summary>" })`
+2. `suemo_context({ scope: "<project-id>", limit: 20 })`
+3. Continue work
+
+---
+
+## 8) Documentation shortcuts
+
+```bash
+suemo skill
+suemo skill core-workflow
+suemo skill mcp-reference
+suemo skill manual-test-plan
+```
+
+Load docs once per session unless requirements changed.
+
+---
+
+_Version: 0.1.7 | Updated: 2026-03-23 | Summary: stricter schema + explicit completion contract_

package/src/cli/commands/believe.ts

@@ -12,6 +12,7 @@ export const believeCmd = app.sub('believe')
 	.flags({
 		scope: { type: 'string', short: 's', description: 'Scope label' },
 		confidence: { type: 'number', description: 'Confidence 0.0–1.0', default: 1.0 },
+		session: { type: 'string', description: 'Session ID (attach to open episode)' },
 		json: { type: 'boolean', description: 'Output JSON result' },
 		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
 	})
@@ -32,12 +33,14 @@ export const believeCmd = app.sub('believe')
 				hasScope: Boolean(resolvedScope),
 				scope: resolvedScope,
 				confidence: flags.confidence,
+				hasSession: Boolean(flags.session),
 				contentLength: args.content.length,
 			})
 			const { node, contradicted } = await believe(db, {
 				content: args.content,
 				scope: resolvedScope,
 				confidence: flags.confidence,
+				sessionId: flags.session,
 			}, config)
 			if (outputMode === 'json') {
 				const out: Record<string, unknown> = { id: node.id, valid_from: node.valid_from }