suemo 0.0.5 → 0.0.7

package/README.md

@@ -5,7 +5,9 @@
 > [!CAUTION]
 > **Bun-only.** This project will not run on Node.js and there are no plans to support it.
 >
-> suemo is experimental software built for the author's personal agent infrastructure. APIs may change without notice. Use at your own risk.
+> suemo is experimental software built for the author's personal agent infrastructure. APIs may change without notice.
+>
+> Most of the code is AI-generated and only tested briefly by a single person. Use at your own risk.
 
 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.
 
@@ -17,7 +19,7 @@ suemo gives AI agents a memory that survives across sessions, models, and runtim
 - **Bi-temporal nodes** — every fact has `valid_from` / `valid_until`; nothing is hard-deleted
 - **Contradiction detection** — calling `believe()` with a conflicting belief automatically invalidates the old one and links them with a `contradicts` edge
 - **Two-phase consolidation** — NREM clusters and compresses redundant observations via LLM; REM integrates new summaries into the broader graph with auto-scored relations
-- **SurrealKV time-travel** — `VERSION d'...'` queries let you inspect any node's state at any past datetime (requires `SURREAL_DATASTORE_RETENTION=90d`)
+- **SurrealKV time-travel** — `VERSION d'...'` queries let you inspect any node's state at any past datetime (requires `SURREAL_DATASTORE_RETENTION=90d` / `0` for infinite)
 - **Namespace isolation** — one SurrealDB instance, multiple agents, zero collision (`namespace` = agent group, `database` = agent identity)
 - **MCP + CLI** — both interfaces are thin shells over the same domain functions; no business logic duplication
 - **Lightweight** — no bundled vector store, no embedded database process, no OpenAI SDK; embedding via `fn::embed()` runs server-side in SurrealDB
@@ -34,12 +36,25 @@ suemo gives AI agents a memory that survives across sessions, models, and runtim
 SurrealDB must be started with SurrealKV and a retention window:
 
 ```sh
-SURREAL_DATASTORE_RETENTION=90d surreal start \
+SURREAL_DATASTORE_VERSIONED=true SURREAL_DATASTORE_RETENTION=90d surreal start \
   --bind 0.0.0.0:8000 \
-  surrealkv:///path/to/data
+  --allow-funcs "*" \
+  -- surrealkv:///path/to/data
 ```
 
-An embedding model must be configured in SurrealDB for `fn::embed()` to work.
+For suemo, the critical capability is allowing custom functions:
+
+- `fn::*`
+- `time::*`
+- `vector::*`
+- `search::*` (for `search::score`)
+- `math::*` (for `math::mean`, `math::min`)
+- `rand::*` (used in `wander` query)
+
+If you run with strict capability mode, use an allowlist like:
+
+- for **openai-compatible/stub**: `fn,time,vector,search,math,rand`
+- for **surreal** provider (with `ml::...` in `fn::embed` wrapper): add `ml`
 
 ---
 
@@ -64,6 +79,69 @@ bun run src/cli/index.ts init config
 
 This writes `~/.suemo/suemo.ts`. Edit it with your SurrealDB URL, credentials, and LLM endpoint.
 
+Set project scope discovery in config (recommended):
+
+```ts
+export default defineConfig({
+	main: {
+		projectDir: '.ua',
+	},
+	// ...
+})
+```
+
+With this, suemo resolves default scope from nearest `.ua/suemo.json` (auto-created if missing).
+
+### Optional: one-command local service setup (Arch Linux)
+
+**NOTE:** These init commands are Arch Linux–specific (author's primary development environment). They rely on `pacman` package checks and systemd paths matching Arch Linux layouts.
+
+For local host deployments, suemo can install systemd service assets directly.
+
+These commands **must be run as root**:
+
+```sh
+sudo suemo init surreal 2gb --dry-run
+sudo suemo init surreal 6gb --dry-run
+sudo suemo init fastembed --dry-run
+```
+
+If `suemo` is not on root PATH, use `sudo bunx suemo ...`.
+
+Drop `--dry-run` to apply changes.
+
+`suemo init surreal` also creates `/opt/suemo/surrealdb/local.env` with commented overrides and does not overwrite it if it already exists. If defined in `local.env`, these values override `common.env`:
+
+- `SURREAL_USER`
+- `SURREAL_PASS`
+- `SURREAL_BIND`
+- `SURREAL_PATH`
+
+Add `--force` to regenerate managed env files (`common.env` and profile env).
+
+What these commands do:
+
+- `suemo init surreal <2gb|6gb>`
+  - checks `surrealdb` package via `pacman -Q`
+  - creates `/opt/suemo/surrealdb/common.env` + profile env (`2gb.env` or `6gb.env`)
+  - creates `/opt/suemo/surrealdb/local.env` once (user override file; not overwritten)
+  - writes `/etc/systemd/system/suemo-surrealdb@.service`
+  - enables + starts `suemo-surrealdb@<profile>.service`
+  - includes `VERSIONED` + retention config and strict capability allowlist:
+    - `SURREAL_DATASTORE_VERSIONED=true`
+    - `SURREAL_DATASTORE_RETENTION=90d`
+    - `SURREAL_CAPS_DENY_ALL=true`
+    - `SURREAL_CAPS_ALLOW_FUNC=fn,time,vector,search,math,rand,ml`
+
+- `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)
+  - writes `/etc/systemd/system/suemo-fastembed.service`
+  - enables + starts `suemo-fastembed.service`
+
+`--dry-run` prints all generated file content and planned commands to stdout without writing anything.
+
 **2. Apply schema**
 
 Apply schema after you set/edit namespace/database:
@@ -106,6 +184,30 @@ suemo serve --dev
 
 ---
 
+## OpenCode setup (only integration target)
+
+Print copy-paste setup snippets:
+
+```sh
+suemo init opencode
+```
+
+This prints:
+
+- MCP config snippet (`command: suemo`, `args: ["serve", "--stdio", ...]`)
+- minimal AGENTS.md guidance snippet
+
+To fetch the latest skill docs directly from your local checkout:
+
+```sh
+suemo skill
+suemo skill core-workflow
+```
+
+No files are auto-written by this command.
+
+---
+
 ## CLI Reference
 
 ```
@@ -115,10 +217,13 @@ Global flags (inherited by all commands):
   -c, --config <path>   Path to config file
   -d, --debug           Verbose debug logging
 
-Commands:
-  init                  Show init subcommands and usage guidance
-  init config           Create/update ~/.suemo/suemo.ts
-  init schema           Apply DB schema from current config (with confirm)
+ Commands:
+   init                  Show init subcommands and usage guidance
+   init config           Create/update ~/.suemo/suemo.ts
+   init schema           Apply DB schema from current config (with confirm)
+   init surreal          Install systemd SurrealDB profile (2gb/6gb) with VERSIONED + allowlist config
+   init fastembed        Install systemd fastembed service
+  skill                 Print suemo skill docs (or specific reference)
   serve                 Start the MCP server (HTTP or stdio)
   observe <content>     Store an observation
   believe <content>     Store a belief (triggers contradiction detection)
@@ -277,12 +382,16 @@ This prints your active target (`url`, `namespace`, `database`) and step-by-step
 | `recall`              | Fetch a node and its 1-hop neighbourhood; ticks FSRS                |
 | `wander`              | Spreading-activation walk through the graph                         |
 | `timeline`            | Chronological memory slice with optional date range                 |
+| `context`             | Recover recent session context for current/default scope            |
 | `episode_start`       | Begin a bounded session window                                      |
 | `episode_end`         | Close a session, optionally with a summary                          |
 | `goal_set`            | Create a goal node                                                  |
 | `goal_resolve`        | Mark a goal achieved                                                |
 | `goal_list`           | List active (or all) goals                                          |
 | `upsert_by_key`       | Upsert a memory node by stable topic key                            |
+| `update`              | Update an existing memory node by ID (re-embeds if content changed) |
+| `suggest_topic_key`   | Suggest deterministic canonical topic key from free text            |
+| `skill`               | Return current suemo skill docs or one named reference              |
 | `capture_prompt`      | Capture raw prompt and link derived observations                    |
 | `session_context_get` | Fetch open episode summary/context by session ID                    |
 | `session_context_set` | Update open episode summary/context by session ID                   |
@@ -293,6 +402,13 @@ 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.
 
+### Scope and longevity notes
+
+- Default inferred project scope now uses nearest `<projectDir>/suemo.json` with `main.projectDir` defaulting to `.ua`.
+- Semantic operations are scope-aware (dedup, contradiction detection, upsert-by-key, consolidation).
+- Retention probe is fail-closed on unexpected probe errors.
+- Episode records are included in sync and export/import flows.
+
 ---
 
 ## Architecture

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "suemo",
-	"version": "0.0.5",
+	"version": "0.0.7",
 	"description": "Persistent semantic memory for AI agents — backed by SurrealDB.",
 	"author": {
 		"name": "Umar Alfarouk",
@@ -37,13 +37,16 @@
 	"scripts": {
 		"dev": "bun run src/cli/index.ts",
 		"start": "bun run src/cli/index.ts",
-		"check": "bun tsc --noEmit"
+		"ssot:check": "bun run scripts/ssot.ts check",
+		"ssot:sync": "bun run scripts/ssot.ts sync",
+		"check": "bun tsc --noEmit && bun run ssot:check",
+		"sync": "bun run ssot:sync"
 	},
 	"dependencies": {
 		"@crustjs/core": "^0.0.15",
-		"@crustjs/plugins": "^0.0.19",
-		"@crustjs/prompts": "^0.0.9",
-		"@crustjs/style": "^0.0.5",
+		"@crustjs/plugins": "^0.0.20",
+		"@crustjs/prompts": "^0.0.10",
+		"@crustjs/style": "^0.0.6",
 		"@logtape/file": "^2.0.4",
 		"@logtape/logtape": "^2.0.4",
 		"@surrealdb/node": "^3.0.3",

package/src/cli/commands/believe.ts

@@ -2,7 +2,7 @@ import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { getLogger } from '../../logger.ts'
 import { believe } from '../../memory/write.ts'
-import { app, initCliCommand, printCliJson, resolveOutputModeOrExit } from '../shared.ts'
+import { app, initCliCommand, printCliJson, resolveOutputModeOrExit, resolveScopeLabel } from '../shared.ts'
 
 const log = getLogger(['suemo', 'cli', 'believe'])
 
@@ -24,16 +24,19 @@ export const believeCmd = app.sub('believe')
 			quiet: flags.quiet,
 		})
 		const config = await loadConfig(process.cwd(), flags.config)
+		const resolvedScope = resolveScopeLabel(flags.scope, config)
+		log.debug('Resolved believe scope', { scope: resolvedScope, explicit: flags.scope ?? null })
 		const db = await connect(config.surreal)
 		try {
 			log.debug('Running believe command', {
-				hasScope: Boolean(flags.scope),
+				hasScope: Boolean(resolvedScope),
+				scope: resolvedScope,
 				confidence: flags.confidence,
 				contentLength: args.content.length,
 			})
 			const { node, contradicted } = await believe(db, {
 				content: args.content,
-				scope: flags.scope,
+				scope: resolvedScope,
 				confidence: flags.confidence,
 			}, config)
 			if (outputMode === 'json') {

package/src/cli/commands/consolidate.ts

@@ -2,7 +2,7 @@ import { consolidate } from '../../cognitive/consolidate.ts'
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { getLogger } from '../../logger.ts'
-import { app, initCliCommand, printCliJson, resolveOutputModeOrExit } from '../shared.ts'
+import { app, initCliCommand, printCliJson, resolveOutputModeOrExit, resolveScopeLabel } from '../shared.ts'
 
 const log = getLogger(['suemo', 'cli', 'consolidate'])
 
@@ -10,6 +10,7 @@ export const consolidateCmd = app.sub('consolidate')
 	.meta({ description: 'Manually trigger memory consolidation (NREM + REM)' })
 	.flags({
 		'nrem-only': { type: 'boolean', description: 'Run only NREM (compression) phase', default: false },
+		scope: { type: 'string', short: 's', description: 'Scope label (defaults to inferred project scope)' },
 		json: { type: 'boolean', description: 'Output full JSON' },
 		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
 	})
@@ -23,6 +24,7 @@ export const consolidateCmd = app.sub('consolidate')
 		})
 		log.debug('Running consolidate command', { nremOnly: flags['nrem-only'] })
 		const config = await loadConfig(process.cwd(), flags.config)
+		const scope = resolveScopeLabel(flags.scope, config)
 		const db = await connect(config.surreal)
 		try {
 			const run = await consolidate(db, {
@@ -31,6 +33,7 @@ export const consolidateCmd = app.sub('consolidate')
 				remRelationThreshold: config.consolidation.remRelationThreshold,
 				llm: config.consolidation.llm,
 				embedding: config.embedding,
+				...(scope ? { scope } : {}),
 			})
 			if (outputMode === 'json') {
 				printCliJson(run, flags)

package/src/cli/commands/doctor.ts

@@ -104,6 +104,8 @@ const doctorEmbedCmd = doctor.sub('embed')
 			console.log('\nHow to set up fn::embed() (step-by-step):')
 			console.log('\n1) Ensure SurrealDB CLI exposes ML commands:')
 			console.log('   surreal ml --help')
+			console.log('\n   and start SurrealDB with custom function capability:')
+			console.log('   surreal start --allow-funcs "fn::*" ...')
 			console.log('\n2) Import a .surml embedding model into this exact NS/DB:')
 			console.log(
 				`   surreal ml import --conn ${endpoint} --user <USER> --pass <PASS> --ns ${config.surreal.namespace} --db ${config.surreal.database} path/to/your-model.surml`,

package/src/cli/commands/export-import.ts

@@ -4,7 +4,7 @@ import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { getLogger } from '../../logger.ts'
 import type { MemoryNode, Relation } from '../../types.ts'
-import { app, initCliCommand, printCliJson, resolveOutputModeOrExit } from '../shared.ts'
+import { app, initCliCommand, printCliJson, resolveOutputModeOrExit, resolveScopeLabel } from '../shared.ts'
 
 const log = getLogger(['suemo', 'cli', 'export-import'])
 
@@ -30,19 +30,25 @@ export const exportCmd = app.sub('export')
 			includeInvalidated: Boolean(flags.all),
 		})
 		const config = await loadConfig(process.cwd(), flags.config)
+		const resolvedScope = resolveScopeLabel(flags.scope, config)
+		log.debug('Resolved export scope', { scope: resolvedScope, explicit: flags.scope ?? null })
 		const db = await connect(config.surreal)
 		try {
 			const activeFilter = flags.all ? 'true' : '(valid_until = NONE OR valid_until > time::now())'
 			const scopeFilter = '($scope = NONE OR scope = $scope)'
 
-			const [nodesResult, relationsResult] = await Promise.all([
+			const [nodesResult, relationsResult, episodesResult] = await Promise.all([
 				db.query<[MemoryNode[]]>(
 					`
         SELECT * FROM memory WHERE ${activeFilter} AND ${scopeFilter} ORDER BY created_at ASC
       `,
-					{ scope: flags.scope ?? null },
+					{ scope: resolvedScope },
 				),
 				db.query<[Relation[]]>('SELECT * FROM relates_to ORDER BY created_at ASC'),
+				db.query<[Record<string, unknown>[]]>(
+					`SELECT * FROM episode WHERE ($scope = NONE OR session_id = $scope) ORDER BY started_at ASC`,
+					{ scope: resolvedScope },
+				),
 			])
 
 			for (const node of nodesResult[0] ?? []) {
@@ -51,6 +57,9 @@ export const exportCmd = app.sub('export')
 			for (const rel of relationsResult[0] ?? []) {
 				process.stdout.write(JSON.stringify({ _type: 'relation', ...rel }) + '\n')
 			}
+			for (const ep of episodesResult[0] ?? []) {
+				process.stdout.write(JSON.stringify({ _type: 'episode', ...ep }) + '\n')
+			}
 		} finally {
 			await disconnect()
 		}
@@ -79,6 +88,7 @@ export const importCmd = app.sub('import')
 		const rl = createInterface({ input: createReadStream(args.file) })
 		let lineNum = 0
 		let imported = 0
+		let importedEpisode = 0
 		let skipped = 0
 		let errors = 0
 
@@ -129,6 +139,13 @@ export const importCmd = app.sub('import')
 							},
 						)
 						imported++
+					} else if (type === 'episode') {
+						await db.query('UPSERT <record<episode>>$id CONTENT $row', {
+							id: row['id'],
+							row,
+						})
+						importedEpisode++
+						imported++
 					} else {
 						skipped++
 					}
@@ -142,8 +159,10 @@ export const importCmd = app.sub('import')
 			await disconnect()
 		}
 		if (outputMode === 'json') {
-			printCliJson({ imported, skipped, errors, lines: lineNum }, flags)
+			printCliJson({ imported, importedEpisode, skipped, errors, lines: lineNum }, flags)
 		} else {
-			console.log(`import done: imported=${imported} skipped=${skipped} errors=${errors} lines=${lineNum}`)
+			console.log(
+				`import done: imported=${imported} (episodes=${importedEpisode}) skipped=${skipped} errors=${errors} lines=${lineNum}`,
+			)
 		}
 	})

package/src/cli/commands/goal.ts

@@ -3,7 +3,7 @@ import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { goalList, goalResolve, goalSet } from '../../goal.ts'
 import { getLogger } from '../../logger.ts'
-import { app, initCliCommand, printCliJson, resolveOutputModeOrExit } from '../shared.ts'
+import { app, initCliCommand, printCliJson, resolveOutputModeOrExit, resolveScopeLabel } from '../shared.ts'
 
 const log = getLogger(['suemo', 'cli', 'goal'])
 
@@ -34,11 +34,13 @@ const setCmd = goal.sub('set')
 			contentLength: args.content.length,
 		})
 		const config = await loadConfig(process.cwd(), flags.config)
+		const resolvedScope = resolveScopeLabel(flags.scope, config)
+		log.debug('Resolved goal set scope', { scope: resolvedScope, explicit: flags.scope ?? null })
 		let db: Surreal | undefined
 		try {
 			db = await connect(config.surreal)
 			const node = await goalSet(db, args.content, config, {
-				...(flags.scope ? { scope: flags.scope } : {}),
+				scope: resolvedScope,
 				tags: flags.tags ? flags.tags.split(',').map((t) => t.trim()) : [],
 			})
 			if (outputMode === 'json') {
@@ -69,16 +71,19 @@ const listCmd = goal.sub('list')
 			json: outputMode === 'json',
 			quiet: flags.quiet,
 		})
+		const config = await loadConfig(process.cwd(), flags.config)
+		const resolvedScope = resolveScopeLabel(flags.scope, config)
+		log.debug('Resolved goal list scope', { scope: resolvedScope, explicit: flags.scope ?? null })
 		log.debug('Running goal list command', {
-			hasScope: Boolean(flags.scope),
+			hasScope: Boolean(resolvedScope),
+			scope: resolvedScope,
 			includeResolved: Boolean(flags.resolved),
 		})
-		const config = await loadConfig(process.cwd(), flags.config)
 		let db: Surreal | undefined
 		try {
 			db = await connect(config.surreal)
 			const goals = await goalList(db, {
-				...(flags.scope ? { scope: flags.scope } : {}),
+				scope: resolvedScope,
 				includeResolved: flags.resolved,
 			})
 			if (outputMode === 'json') {