suemo 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "suemo",
-	"version": "0.0.7",
+	"version": "0.0.9",
 	"description": "Persistent semantic memory for AI agents — backed by SurrealDB.",
 	"author": {
 		"name": "Umar Alfarouk",
@@ -27,7 +27,7 @@
 	"bin": {
 		"suemo": "./src/cli/index.ts"
 	},
-	"files": ["src", "LICENSE", "README.md"],
+	"files": ["src", "skills", "LICENSE", "README.md", "tsconfig.json"],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",

package/skills/suemo/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: suemo
+description: OpenCode-focused persistent memory workflow for suemo with CLI/MCP parity and versioned references.
+version: 0.0.8
+---
+
+# suemo skill
+
+Use suemo to persist technical context across sessions with minimal, project-scoped memory.
+
+## Quick use
+
+- CLI latest skill: `suemo skill`
+- CLI specific reference: `suemo skill <reference-name>`
+- MCP latest skill: `skill({})`
+- MCP specific reference: `skill({ reference: "<reference-name>" })`
+
+## Reference names
+
+- `agents-snippet`
+- `cli-reference`
+- `core-workflow`
+- `manual-test-plan`
+- `mcp-reference`
+- `schema-retention-longevity`
+- `sync-local-vps`
+
+## Operating model
+
+1. Query first: reuse prior knowledge before implementation.
+2. Observe/believe during work (not only at the end).
+3. Use episode + context for session continuity.
+4. Keep scope project-bound via inferred scope unless explicitly overridden.
+
+For full details, read references via `suemo skill <reference-name>`.

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

@@ -0,0 +1,36 @@
+---
+name: agents-snippet
+description: AGENTS.md snippet optimized for suemo skill discovery and usage.
+version: 0.0.8
+---
+
+# AGENTS.md snippet
+
+```md
+## suemo-first memory workflow
+
+Before significant work:
+
+- query("what do I know about <topic>")
+
+If you need latest usage docs:
+
+- suemo skill
+- suemo skill core-workflow
+- suemo skill mcp-reference
+
+During work:
+
+- observe("...") for concrete facts
+- believe("...") for conclusions
+- goal_set("...") for long tasks
+
+After completion:
+
+- goal_resolve("...") if applicable
+- episode_end(sessionId, summary="...")
+
+After compaction/reset:
+
+- context({ scope: "<project-id>", limit: 20 })
+```

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

@@ -0,0 +1,44 @@
+---
+name: cli-reference
+description: CLI command reference for suemo v0.0.6 including skill access.
+version: 0.0.8
+---
+
+# CLI reference
+
+Core:
+
+- `suemo init config`
+- `suemo init schema`
+- `suemo init opencode`
+- `suemo serve [--stdio|--dev]`
+- `suemo skill [reference]`
+
+Memory:
+
+- `suemo observe <content>`
+- `suemo believe <content>`
+- `suemo query <input>`
+- `suemo recall <nodeId>`
+- `suemo wander`
+- `suemo timeline`
+- `suemo consolidate [--nrem-only]`
+
+Goals:
+
+- `suemo goal set <content>`
+- `suemo goal list`
+- `suemo goal resolve <id>`
+
+Ops:
+
+- `suemo sync --direction push|pull|both [--remote <name>] [--dry-run]`
+- `suemo export`
+- `suemo import <file>`
+- `suemo health|health vitals|health stats`
+
+JSON modes:
+
+- `--json`
+- `--pretty`
+- `--verbose-json` (implies `--json`, includes embeddings)

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

@@ -0,0 +1,40 @@
+---
+name: core-workflow
+description: Canonical suemo operating loop for OpenCode agents.
+version: 0.0.8
+---
+
+# Core workflow
+
+1. Start with memory lookup:
+
+```ts
+query('what do I know about <topic>')
+```
+
+2. During work, persist concrete discoveries:
+
+```ts
+observe('...')
+believe('...')
+```
+
+3. For long tasks:
+
+```ts
+goal_set('...')
+```
+
+4. If compaction/reset happened:
+
+```ts
+context({ scope: '<project-id>', limit: 20 })
+```
+
+5. Close session:
+
+```ts
+episode_end(sessionId, summary = '...')
+```
+
+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

@@ -0,0 +1,77 @@
+---
+name: manual-test-plan
+description: Comprehensive manual test matrix for suemo features and commands.
+version: 0.0.8
+---
+
+# Manual test plan
+
+## A. Setup and compatibility
+
+1. `suemo init config`
+2. `suemo init schema`
+3. `suemo health`
+4. `suemo doctor embed` (informational when embeddings unavailable)
+
+Expected:
+
+- clean startup, schema idempotent, health/stats readable
+
+## B. Scope inference
+
+1. Ensure `.ua/suemo.json` exists (or let suemo create)
+2. Run `observe`, `query`, `goal list` without `--scope`
+3. Verify records are in inferred scope
+
+## C. Memory lifecycle
+
+1. `observe`
+2. duplicate `observe` (dedup merge expected in same scope)
+3. `believe` then conflicting `believe` (invalidation + relation)
+4. `recall`, `timeline`, `wander`
+5. `update` by node id and re-query
+
+## D. Session/episode/context
+
+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
+
+## E. Goals
+
+1. `goal set`
+2. `goal list`
+3. `goal resolve`
+4. `goal list --resolved`
+
+## F. Consolidation
+
+1. seed enough unconsolidated memories
+2. run `consolidate --nrem-only`
+3. run full `consolidate`
+4. verify derived nodes/relations and no cross-scope contamination
+
+## G. Sync/export/import
+
+1. `export` and `import` roundtrip (memory + relation + episode)
+2. `sync` push/pull/both with cursor sanity
+3. auto-sync with write trigger and timer
+
+## H. Skill docs access
+
+1. `suemo skill`
+2. `suemo skill core-workflow`
+3. MCP `skill({})`, `skill({ reference: "cli-reference" })`
+
+## I. Output modes
+
+Repeat representative commands under:
+
+- `--pretty`
+- `--json`
+- `--verbose-json`
+
+Verify embeddings are hidden in `--json` and visible in `--verbose-json`.

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

@@ -0,0 +1,46 @@
+---
+name: mcp-reference
+description: MCP tool reference for suemo v0.0.6.
+version: 0.0.8
+---
+
+# MCP tools
+
+Write/mutate:
+
+- `observe`
+- `believe`
+- `invalidate`
+- `upsert_by_key`
+- `update`
+- `capture_prompt`
+- `goal_set`
+- `goal_resolve`
+- `episode_start`
+- `episode_end`
+- `session_context_set`
+
+Read/retrieve:
+
+- `query`
+- `recall`
+- `wander`
+- `timeline`
+- `context`
+- `goal_list`
+- `session_context_get`
+- `health`
+- `vitals`
+- `stats`
+- `suggest_topic_key`
+- `skill`
+
+Maintenance:
+
+- `consolidate` (supports optional `scope`)
+
+Notes:
+
+- Optional `scope` defaults to inferred project id.
+- `update` re-embeds when `content` changes.
+- `episode_end` accepts structured fields (`goal`, `discoveries`, `accomplished`, `files_changed`).

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

@@ -0,0 +1,31 @@
+---
+name: schema-retention-longevity
+description: Long-term schema and retention design expectations for suemo.
+version: 0.0.8
+---
+
+# Schema + retention longevity
+
+## Required invariants
+
+1. Scope isolation for semantic operations (dedup, contradiction, upsert-by-key, consolidation).
+2. Retention checks fail closed when probe cannot prove ≥90d time-travel reach.
+3. Sync/export/import cover `memory`, `relates_to`, and `episode`.
+4. Cursor advancement only after successful sync batch completion.
+5. Additive schema changes preferred; idempotent `DEFINE ... OVERWRITE` remains stable.
+
+## Index baseline
+
+- `memory(embedding)` HNSW
+- `memory(content)` + `memory(summary)` fulltext
+- `memory(scope, created_at)`, `memory(kind, valid_until)`, `memory(salience)`, `memory(topic_key)`
+- `memory(updated_at)`
+- `relates_to(updated_at)`
+- `episode(session_id, ended_at, started_at)`
+- `episode(updated_at)`
+
+## Operational checks
+
+- Run schema repeatedly (idempotence check).
+- Validate retention probe against deployed Surreal flags.
+- Verify scoped operations do not mutate or merge cross-project data.

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

@@ -0,0 +1,26 @@
+---
+name: sync-local-vps
+description: Two-way sync manual scenario for local and VPS SurrealDB.
+version: 0.0.8
+---
+
+# Local ↔ VPS sync scenario
+
+Use this as canonical two-way sync validation.
+
+1. Prepare isolated scope (`sync-smoke-<timestamp>`)
+2. Local write → `sync --direction push`
+3. VPS write → `sync --direction pull`
+4. Conflict smoke: update same memory both sides, run `sync --direction both`
+5. Invalidation propagation smoke
+6. Auto-sync smoke with `serve --stdio` and write-trigger
+7. Cursor sanity (two immediate sync runs)
+
+Expected outcomes:
+
+- no data loss
+- LWW behavior consistent
+- invalidation propagates
+- cursor advances only on successful syncs
+
+Detailed command walkthrough remains available at `data/scenarios/sync-local-vps.md`.

package/src/cli/commands/init.ts

@@ -394,7 +394,7 @@ function extractEnvValue(content: string, key: string): string | null {
 }
 
 function readFastembedScriptSource(): string {
-	const path = fileURLToPath(new URL('../../../data/fastembed-server.py', import.meta.url))
+	const path = fileURLToPath(new URL('../embedding/fastembed-server.py', import.meta.url))
 	return readFileSync(path, 'utf-8')
 }
 

package/src/embedding/fastembed-server.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+# fastembed.py
+# Run: pacman -S python-fastembed python-fastapi python-uvicorn
+# Start: python fastembed.py
+
+from contextlib import asynccontextmanager
+import os
+from pathlib import Path
+from fastapi import FastAPI
+from fastembed import TextEmbedding
+from pydantic import BaseModel
+import uvicorn
+
+MODEL_NAME = os.getenv("FASTEMBED_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
+CACHE_DIR = Path(
+    os.getenv("FASTEMBED_CACHE_DIR", str(Path.home() / ".cache" / "fastembed"))
+)
+HOST = os.getenv("FASTEMBED_HOST", "127.0.0.1")
+PORT = int(os.getenv("FASTEMBED_PORT", "8080"))
+_model: TextEmbedding | None = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global _model
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    print(f"Loading {MODEL_NAME} (cache: {CACHE_DIR})...")
+    _model = TextEmbedding(model_name=MODEL_NAME, cache_dir=str(CACHE_DIR))
+    print("Model ready.")
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+class EmbedRequest(BaseModel):
+    input: str | list[str]  # OpenAI-compatible field name
+    model: str = MODEL_NAME
+
+
+class EmbedResponse(BaseModel):
+    object: str = "list"
+    data: list[dict]
+    model: str
+    usage: dict
+
+
+@app.post("/v1/embeddings")
+def embed(req: EmbedRequest) -> EmbedResponse:
+    texts = [req.input] if isinstance(req.input, str) else req.input
+    vectors = list(_model.embed(texts))  # type: ignore
+    return EmbedResponse(
+        data=[
+            {"object": "embedding", "index": i, "embedding": v.tolist()}
+            for i, v in enumerate(vectors)
+        ],
+        model=MODEL_NAME,
+        usage={"prompt_tokens": sum(len(t.split()) for t in texts), "total_tokens": 0},
+    )
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "model": MODEL_NAME, "dimension": 384}
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host=HOST, port=PORT)

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+	"compilerOptions": {
+		"lib": ["ESNext"],
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"moduleDetection": "force",
+		"resolveJsonModule": true,
+
+		"target": "ESNext",
+		"noEmit": true,
+		"isolatedModules": true,
+
+		"rewriteRelativeImportExtensions": true,
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+
+		"strict": true,
+		"noUncheckedIndexedAccess": true,
+		"exactOptionalPropertyTypes": true,
+		"noUnusedLocals": true,
+
+		"skipLibCheck": true,
+
+		"paths": {
+			"@/*": ["./*"]
+		}
+	},
+	"include": ["src/**/*", "suemo.config.ts"]
+}