suemo 0.1.6 → 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
@@ -445,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.6",
+	"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.6
+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.6
+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.6
+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.6
+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.6
+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.6
+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.6
+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.6
+version: 0.1.7
 ---
 
 # Local ↔ VPS sync scenario

package/src/AGENTS.md

@@ -1,150 +1,130 @@
-# Working with suemo
+**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.
 
-suemo is your persistent memory. Use it to store what you learn, remember what matters, and build on past work.
+## 1) Pre-Session Checklist (required)
 
-## Before anything else
+Before implementation:
 
-**Load the skill doc first.** It is versioned and may contain updated workflows, references, and tool signatures that supersede this file.
+- [ ] `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
 
-- CLI: `suemo skill`
-- MCP: `skill({})`
+Proceed only after all checks pass.
 
-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`
+## 2) Strict schema rules (required)
 
-Do not proceed until the skill doc is loaded.
+### `suemo_observe` kind is strict
 
-## Session protocol
+Valid `kind` values only:
 
-These steps are **mandatory**, not suggested.
+- `observation`
+- `belief`
+- `question`
+- `hypothesis`
+- `goal`
 
-### On session start
+### `suemo_episode_end` payload shape
 
-```
-goal_list(scope: "<active-scope>")
-query("recent work on [topic]", scope: "<active-scope>")
-```
+Minimum schema requirement: `sessionId`.
 
-Read relevant results before touching any code. Do not re-derive what is already stored.
+Required by protocol when finishing meaningful work:
 
-### While working
+- `summary`
+- `goal`
+- `discoveries` (array)
+- `accomplished` (array)
+- `files_changed` (array)
 
-Store anything that would save time next session:
+Use exact field names above.
 
-```
-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.
+## 3) During work
 
-### Before ending (or if interrupted)
+Persist important information immediately (not only at the end).
 
-Call this **before** your final tool invocation, not after — sessions can be cut off without warning:
+Use this structure for non-trivial observations:
 
+```md
+**What**: <what changed>
+**Why**: <reason>
+**Where**: <files/paths>
+**Learned**: <gotchas/decisions>
 ```
-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.
+Guidance:
 
-**Observe:** `"[tool] requires [flag] — without it, [failure mode]"`\
-**Believe:** `"[tool] behaviour is likely a bug — worth retrying after an upgrade"`
+- Facts → `suemo_observe`
+- Interpretations/uncertainty → `suemo_believe`
+- Longer tasks → `suemo_goal_set`
 
-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.
+## 4) After completion
 
-## What to observe
+Run in order:
 
-Observe your **experience**, not documentation:
+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()`
 
-- 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
+## 5) Querying best practices
 
-## 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:
+Prefer specific, scoped queries:
 
-```
-query("what approaches did we try for N+1 query issue", scope: "<active-scope>")
-query("past decisions about auth middleware", scope: "<active-scope>")
+```ts
+suemo_query({
+	input: 'past decisions about auth middleware',
+	scope: '<project-id>',
+})
+suemo_query({
+	input: '"SURREAL_CAPS_ALLOW_FUNC" init fix',
+	scope: '<project-id>',
+})
 ```
 
-For exact strings (error codes, env var names, flag spellings), quote them:
+When weak ranking is suspected, run `--explain` from CLI to inspect scoring.
 
-```
-query('"SURREAL_CAPS_ALLOW_FUNC" init fix', scope: "<active-scope>")
-```
+---
 
-If ranking looks weak, inspect scoring directly:
+## 6) Anti-patterns
 
-```
-suemo query "<your query>" --scope <active-scope> --explain
-suemo query "<your query>" --scope <active-scope> --explain --min-score 0.25 --relative-floor 0.8
-```
+- ❌ 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
 
-- 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.
+## 7) Compaction/reset handling
 
-## Using recall vs query
+Immediately:
 
-- 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
+1. `suemo_session_context_set({ sessionId, summary: "<compacted summary>" })`
+2. `suemo_context({ scope: "<project-id>", limit: 20 })`
+3. Continue work
 
-`recall()` also ticks the spaced-repetition clock on that node, marking it as "actively used".
+---
 
-## Goals
+## 8) Documentation shortcuts
 
-Set a goal at the start of any multi-step task:
-
-```
-goal_set("<description of task>", scope: "<active-scope>")
+```bash
+suemo skill
+suemo skill core-workflow
+suemo skill mcp-reference
+suemo skill manual-test-plan
 ```
 
-Check open goals at session start (already covered above). Resolve when done:
-
-```
-goal_resolve(<id>)
-```
+Load docs once per session unless requirements changed.
 
-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.
+_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 }

package/src/cli/commands/init.ts

@@ -16,6 +16,8 @@ import OPENCODE_AGENTS_SNIPPET_TEXT from '@/src/AGENTS.md' with { type: 'text' }
 import template from '@/src/config.template' with { type: 'text' }
 import FASTEMBED_SCRIPT_TEXT from '@/src/embedding/fastembed-server.py' with { type: 'text' }
 
+const OPENCODE_PLUGIN_TEXT = readFileSync(new URL('../../opencode/plugin.ts', import.meta.url), 'utf-8')
+
 interface InitFlags {
 	debug?: boolean | undefined
 	config?: string | undefined
@@ -253,6 +255,7 @@ type ServiceManager =
 type OpenCodeConfigMode = 'mcp'
 type OpenCodeConfigStatus = 'added' | 'already-present' | 'unchanged'
 type OpenCodeAgentsStatus = 'added' | 'updated' | 'unchanged'
+type OpenCodePluginStatus = 'added' | 'updated' | 'unchanged'
 
 interface OpenCodeConfigResolution {
 	path: string
@@ -268,6 +271,8 @@ interface OpenCodeInitResult {
 	configMode: OpenCodeConfigMode
 	agentsPath: string
 	agentsStatus: OpenCodeAgentsStatus
+	pluginPath: string
+	pluginStatus: OpenCodePluginStatus
 	dryRun: boolean
 }
 
@@ -594,6 +599,18 @@ function initOpenCodeFiles(configPath: string, dryRun: boolean): OpenCodeInitRes
 	const existingAgents = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf-8') : ''
 	const agentsResult = upsertAgentsSnippet(existingAgents)
 
+	const pluginsDir = join(openCodeDir, 'plugins')
+	const pluginPath = join(pluginsDir, 'suemo.ts')
+	const nextPluginText = `${OPENCODE_PLUGIN_TEXT.trimEnd()}\n`
+	const pluginExists = existsSync(pluginPath)
+	const existingPlugin = pluginExists ? readFileSync(pluginPath, 'utf-8') : ''
+	let pluginStatus: OpenCodePluginStatus = 'unchanged'
+	if (!pluginExists) {
+		pluginStatus = 'added'
+	} else if (existingPlugin !== nextPluginText) {
+		pluginStatus = 'updated'
+	}
+
 	if (!dryRun) {
 		mkdirSync(openCodeDir, { recursive: true })
 		if (!configResolution.existed || configWriteResult.changed) {
@@ -602,6 +619,10 @@ function initOpenCodeFiles(configPath: string, dryRun: boolean): OpenCodeInitRes
 		if (!existsSync(agentsPath) || agentsResult.content !== existingAgents) {
 			writeFileSync(agentsPath, agentsResult.content, 'utf-8')
 		}
+		mkdirSync(pluginsDir, { recursive: true })
+		if (pluginStatus !== 'unchanged') {
+			writeFileSync(pluginPath, nextPluginText, 'utf-8')
+		}
 	}
 
 	return {
@@ -612,6 +633,8 @@ function initOpenCodeFiles(configPath: string, dryRun: boolean): OpenCodeInitRes
 		configMode: configWriteResult.mode,
 		agentsPath,
 		agentsStatus: agentsResult.status,
+		pluginPath,
+		pluginStatus,
 		dryRun,
 	}
 }
@@ -1129,7 +1152,7 @@ const initSchemaCmd = init.sub('schema')
 	})
 
 const initOpenCodeCmd = init.sub('opencode')
-	.meta({ description: 'Initialize OpenCode MCP config + AGENTS.md suemo snippet' })
+	.meta({ description: 'Initialize OpenCode MCP config + AGENTS.md snippet + suemo plugin' })
 	.flags({
 		'dry-run': { type: 'boolean', description: 'Show changes without writing files', default: false },
 		json: { type: 'boolean', description: 'Machine-readable output mode' },
@@ -1160,6 +1183,8 @@ const initOpenCodeCmd = init.sub('opencode')
 						configMode: result.configMode,
 						agentsPath: result.agentsPath,
 						agentsStatus: result.agentsStatus,
+						pluginPath: result.pluginPath,
+						pluginStatus: result.pluginStatus,
 						dryRun: result.dryRun,
 					},
 					suemoVersion: npmVersion,
@@ -1173,6 +1198,7 @@ const initOpenCodeCmd = init.sub('opencode')
 		console.log(`OpenCode config: ${result.configPath} (${result.configFormat})`)
 		console.log(`MCP entry: ${result.configStatus} (${result.configMode})`)
 		console.log(`AGENTS.md: ${result.agentsStatus} at ${result.agentsPath}`)
+		console.log(`Plugin: ${result.pluginStatus} at ${result.pluginPath}`)
 		if (dryRun) {
 			console.log('Dry-run mode: no files were written.')
 		}

package/src/cli/index.ts

@@ -20,6 +20,26 @@ import { helpPlugin, versionPlugin } from '@crustjs/plugins'
 
 import packageJson from '@/package.json' with { type: 'json' }
 
+function applyDeprecatedAliases(argv: string[]): string[] {
+	const next = [...argv]
+
+	if (next[0] === 'skills') {
+		next[0] = 'skill'
+		console.warn('[suemo] Deprecated alias `skills` detected. Use `skill` instead.')
+		return next
+	}
+
+	if (next[0] === 'init' && next[1] === 'surrealdb') {
+		next[1] = 'surreal'
+		console.warn('[suemo] Deprecated alias `init surrealdb` detected. Use `init surreal` instead.')
+		return next
+	}
+
+	return next
+}
+
+process.argv = [...process.argv.slice(0, 2), ...applyDeprecatedAliases(process.argv.slice(2))]
+
 await app
 	.use(versionPlugin(packageJson.version ?? '0.0.0'))
 	.use(helpPlugin())

package/src/mcp/dispatch.ts

@@ -16,7 +16,7 @@ import {
 	upsertByKey,
 } from '@/src/memory/write.ts'
 import { listSkillReferences, readSkillDoc, readSkillReference } from '@/src/skill/catalog.ts'
-import { ObserveInputSchema, QueryInputSchema } from '@/src/types.ts'
+import { MemoryKindSchema, ObserveInputSchema, QueryInputSchema } from '@/src/types.ts'
 import type { Surreal } from 'surrealdb'
 import { z } from 'zod'
 
@@ -49,6 +49,7 @@ export async function handleToolCall(
 ): Promise<unknown> {
 	log.debug('Dispatching MCP tool call', { method, paramKeys: Object.keys(params) })
 	const inferredScope = inferProjectScope(process.cwd(), config)
+	const validKinds = MemoryKindSchema.options.join(', ')
 
 	const maybeTriggerMutationSync = (): void => {
 		if (!MUTATING_TOOLS.has(method) || !opts.onMutation) return
@@ -59,7 +60,15 @@ export async function handleToolCall(
 
 	switch (method) {
 		case 'observe': {
-			const parsed = ObserveInputSchema.parse(params)
+			const parsedObserve = ObserveInputSchema.safeParse(params)
+			if (!parsedObserve.success) {
+				const invalidKindIssue = parsedObserve.error.issues.find((issue) => issue.path[0] === 'kind')
+				if (invalidKindIssue && typeof params.kind === 'string') {
+					throw new Error(`Invalid observe.kind "${params.kind}". Valid kinds: ${validKinds}`)
+				}
+				throw parsedObserve.error
+			}
+			const parsed = parsedObserve.data
 			const result = await observe(db, {
 				...parsed,
 				scope: parsed.scope?.trim() || inferredScope,
@@ -74,6 +83,7 @@ export async function handleToolCall(
 					content: z.string(),
 					scope: z.string().optional(),
 					confidence: z.number().optional(),
+					sessionId: z.string().optional(),
 				})
 				.parse(params)
 			const result = await believe(db, {
@@ -225,7 +235,7 @@ export async function handleToolCall(
 					confidence: z.number().optional(),
 					source: z.string().optional(),
 					sessionId: z.string().optional(),
-					kind: z.enum(['observation', 'belief', 'question', 'hypothesis', 'goal']).optional(),
+					kind: MemoryKindSchema.optional(),
 				})
 				.parse(params)
 			const result = await upsertByKey(db, config, parsed.topicKey, parsed.content, {
@@ -262,7 +272,7 @@ export async function handleToolCall(
 				.object({
 					nodeId: z.string(),
 					content: z.string().optional(),
-					kind: z.enum(['observation', 'belief', 'question', 'hypothesis', 'goal']).optional(),
+					kind: MemoryKindSchema.optional(),
 					tags: z.array(z.string()).optional(),
 					scope: z.string().nullable().optional(),
 					source: z.string().nullable().optional(),

package/src/mcp/stdio.ts

@@ -31,12 +31,12 @@ interface StdioServerOptions {
 const MCP_TOOLS: McpToolDefinition[] = [
 	{
 		name: 'observe',
-		description: 'Store an observation/belief/question/hypothesis/goal memory node',
+		description: 'Store memory node (kind must be observation|belief|question|hypothesis|goal)',
 		inputSchema: {
 			type: 'object',
 			properties: {
 				content: { type: 'string' },
-				kind: { type: 'string' },
+				kind: { type: 'string', enum: ['observation', 'belief', 'question', 'hypothesis', 'goal'] },
 				tags: { type: 'array', items: { type: 'string' } },
 				scope: { type: 'string' },
 				source: { type: 'string' },
@@ -55,6 +55,7 @@ const MCP_TOOLS: McpToolDefinition[] = [
 				content: { type: 'string' },
 				scope: { type: 'string' },
 				confidence: { type: 'number' },
+				sessionId: { type: 'string' },
 			},
 			required: ['content'],
 		},

package/src/opencode/plugin.ts

@@ -0,0 +1,105 @@
+/**
+ * suemo OpenCode plugin (v0.1.7)
+ *
+ * Purpose:
+ * - Inject strict, always-on suemo memory workflow instructions.
+ * - Preserve compacted-session signal by requiring immediate suemo checkpointing.
+ *
+ * This module is copied by `suemo init opencode` to:
+ *   ~/.config/opencode/plugins/suemo.ts
+ */
+
+interface SystemTransformOutput {
+	system: string[]
+}
+
+interface SessionCompactingInput {
+	sessionID?: string
+}
+
+interface SessionCompactingOutput {
+	context: string[]
+}
+
+const MEMORY_INSTRUCTIONS = `## Suemo Persistent Memory — Protocol (v0.1.7)
+
+You have access to suemo persistent memory tools (commonly prefixed as \`suemo_*\`).
+
+### REQUIRED START-OF-TASK CHECKLIST
+
+Before implementation:
+1. \`suemo_goal_list({ scope })\`
+2. \`suemo_query({ input: "recent work on <topic>", scope })\`
+3. \`suemo_context({ scope, limit: 20 })\`
+4. If task is new: \`suemo_episode_start({ sessionId })\`
+
+### REQUIRED WRITE TRIGGERS
+
+Call \`suemo_observe\` immediately after:
+- bug fix completed
+- architecture/design decision made
+- non-obvious discovery
+- config/environment change
+- user preference/constraint discovered
+
+Use this strict content template for non-trivial writes:
+
+\`\`\`
+**What**: ...
+**Why**: ...
+**Where**: path/to/file
+**Learned**: ...
+\`\`\`
+
+### SCHEMA GUARDRAILS
+
+For \`suemo_observe\`, \`kind\` MUST be one of:
+- \`observation\`
+- \`belief\`
+- \`question\`
+- \`hypothesis\`
+- \`goal\`
+
+### END-OF-TASK CHECKLIST
+
+Before declaring done:
+1. \`suemo_episode_end({ sessionId, summary, goal, discoveries, accomplished, files_changed })\`
+2. \`suemo_goal_resolve({ goalId })\` for completed goals
+3. \`suemo_query({ input: "most recent observations", scope })\`
+4. \`suemo_health()\`
+
+### COMPACTION/RESET RULE
+
+If context is compacted/reset, FIRST:
+1. Save checkpoint with \`suemo_session_context_set({ sessionId, summary })\`
+2. Recover via \`suemo_context({ scope, limit: 20 })\`
+3. Then continue work
+`
+
+export const Suemo = async () => {
+	return {
+		'experimental.chat.system.transform': async (_input: unknown, output: SystemTransformOutput) => {
+			if (output.system.length > 0) {
+				output.system[output.system.length - 1] += `\n\n${MEMORY_INSTRUCTIONS}`
+				return
+			}
+			output.system.push(MEMORY_INSTRUCTIONS)
+		},
+
+		'experimental.session.compacting': async (
+			input: SessionCompactingInput,
+			output: SessionCompactingOutput,
+		) => {
+			const sessionId = input.sessionID ?? '<current-session-id>'
+			output.context.push(
+				[
+					'FIRST ACTION REQUIRED:',
+					`Call suemo_session_context_set({ sessionId: "${sessionId}", summary: "<compacted summary>" }) before any other work.`,
+					'Then call suemo_context({ scope: "<project-scope>", limit: 20 }) to recover continuity.',
+				].join(' '),
+			)
+		},
+	}
+}
+
+export default Suemo