suemo 0.1.6 → 0.1.8

package/README.md

@@ -11,6 +11,26 @@
 
 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.
 
+Specifications:
+
+- Index: **[`specs/SPEC.md`](./specs/SPEC.md)**
+- Technical/runtime contract: **[`specs/SPEC-technical.md`](./specs/SPEC-technical.md)**
+- Psychological/critique framing: **[`specs/SPEC-psychological.md`](./specs/SPEC-psychological.md)**
+
+## For professional critique authors (longevity-focused)
+
+If you're designing high-quality external critiques for suemo, evaluate it as **persistent coding-agent memory infrastructure**, not as a general AGI cognition claim.
+
+Use this framing:
+
+1. **Psychological intent** — what memory quality should hold over time?
+2. **Technical mechanism** — what exact table/field/tool enforces that quality?
+3. **Operational evidence** — what logs/tests/metrics prove it under drift and contradiction?
+
+Questions are most useful when they stress long-horizon behavior (30–180 day operation), contradiction handling, consolidation quality, retrieval interference, and scope/session isolation.
+
+For rigorous critique language and category framing, start from **[`specs/SPEC-psychological.md`](./specs/SPEC-psychological.md)**.
+
 ---
 
 ## Features
@@ -445,6 +465,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 `specs/SPEC-technical.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.8",
 	"description": "Persistent semantic memory for AI agents — backed by SurrealDB.",
 	"author": {
 		"name": "Umar Alfarouk",
@@ -37,10 +37,11 @@
 	"scripts": {
 		"dev": "bun run src/cli/index.ts",
 		"start": "bun run src/cli/index.ts",
+		"test": "bun test",
 		"ssot:check": "bun run scripts/ssot.ts check",
 		"ssot:sync": "bun run scripts/ssot.ts sync",
 		"fmt": "dprint fmt",
-		"check": "bun run fmt && bun tsc --noEmit && bun run ssot:check",
+		"check": "bun run fmt && bun tsc --noEmit && bun test && bun run ssot:check",
 		"sync": "bun run ssot:sync"
 	},
 	"dependencies": {
@@ -56,6 +57,7 @@
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
+		"@opencode-ai/plugin": "^1.3.0",
 		"@types/bun": "^1.3.11",
 		"typescript": "^5.9.3"
 	}

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.8
 ---
 
 # suemo skill
 
 Use suemo to persist technical context across sessions with minimal, project-scoped memory.
 
+## Strict defaults (v0.1.8)
+
+- 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.8
 ---
 
 # 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.8
 ---
 
 # 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.8
 ---
 
 # 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.8
 ---
 
 # 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.8
 ---
 
 # 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.8
 ---
 
 # 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.8
 ---
 
 # 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.8 | Updated: 2026-03-24 | 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/health.ts

@@ -29,7 +29,7 @@ const reportCmd = health.sub('report')
 		let db: Surreal | undefined
 		try {
 			db = await connect(config.surreal)
-			const report = await healthReport(db)
+			const report = await healthReport(db, { embeddingProvider: config.embedding.provider })
 			if (outputMode === 'json') {
 				printCliJson(report, flags)
 			} else {
@@ -129,7 +129,7 @@ export const healthCmd = health
 		let db: Surreal | undefined
 		try {
 			db = await connect(config.surreal)
-			const report = await healthReport(db)
+			const report = await healthReport(db, { embeddingProvider: config.embedding.provider })
 			if (outputMode === 'json') {
 				printCliJson(report, flags)
 			} else {