suemo 0.0.6 → 0.0.8

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
@@ -36,13 +38,23 @@ SurrealDB must be started with SurrealKV and a retention window:
 ```sh
 SURREAL_DATASTORE_VERSIONED=true SURREAL_DATASTORE_RETENTION=90d surreal start \
   --bind 0.0.0.0:8000 \
-  --allow-funcs "fn::*" \
+  --allow-funcs "*" \
   -- surrealkv:///path/to/data
 ```
 
-For suemo, the critical capability is allowing custom functions (`fn::embed`) via `--allow-funcs "fn::*"`.
+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:
 
-An embedding model must be configured in SurrealDB for `fn::embed()` to work.
+- for **openai-compatible/stub**: `fn,time,vector,search,math,rand`
+- for **surreal** provider (with `ml::...` in `fn::embed` wrapper): add `ml`
 
 ---
 
@@ -80,6 +92,56 @@ export default defineConfig({
 
 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:
@@ -155,10 +217,12 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "suemo",
-	"version": "0.0.6",
+	"version": "0.0.8",
 	"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", "LICENSE", "README.md", "tsconfig.json"],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
@@ -44,9 +44,9 @@
 	},
 	"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/init.ts

@@ -1,13 +1,17 @@
 import { confirm } from '@crustjs/prompts'
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve as resolvePath } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join, resolve as resolvePath } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import packageJson from '../../../package.json' with { type: 'json' }
 import { loadConfig } from '../../config.ts'
 import { connect, disconnect } from '../../db/client.ts'
 import { checkCompatibility } from '../../db/preflight.ts'
 import { runSchema } from '../../db/schema.ts'
 import { getLogger } from '../../logger.ts'
-import { app, initCliCommand, resolveOutputModeOrExit } from '../shared.ts'
+import { app, initCliCommand, printCliJson, resolveOutputModeOrExit } from '../shared.ts'
 
 import template from '../../config.template.ts' with { type: 'text' }
 
@@ -25,6 +29,541 @@ const log = getLogger(['suemo', 'cli', 'init'])
 const init = app.sub('init')
 	.meta({ description: 'Initialize suemo config and/or database schema' })
 
+const SURREAL_PROFILES_DIR = '/opt/suemo/surrealdb'
+const SURREAL_LOCAL_ENV_PATH = '/opt/suemo/surrealdb/local.env'
+const SURREAL_SYSTEMD_UNIT_PATH = '/etc/systemd/system/suemo-surrealdb@.service'
+const SURREAL_DATA_DIR = '/var/lib/surrealdb'
+const FASTEMBED_INSTALL_DIR = '/opt/suemo'
+const FASTEMBED_LOCAL_ENV_DIR = '/opt/fastembed'
+const FASTEMBED_SCRIPT_TARGET = '/opt/suemo/fastembed-server.py'
+const FASTEMBED_CACHE_DIR = '/var/cache/fastembed'
+const FASTEMBED_SERVICE_PATH = '/etc/systemd/system/suemo-fastembed.service'
+const FASTEMBED_USER_HOME = '/var/lib/fastembed'
+
+const SURREAL_TEMPLATE_UNIT = `# Generated by suemo init surreal
+[Unit]
+Description=SurrealDB (%i profile)
+Documentation=https://surrealdb.com/docs/surrealdb
+After=network.target
+Wants=network-online.target
+
+ [Service]
+Type=simple
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+User=surrealdb
+Group=surrealdb
+EnvironmentFile=/opt/suemo/surrealdb/common.env
+EnvironmentFile=/opt/suemo/surrealdb/%i.env
+EnvironmentFile=-/opt/suemo/surrealdb/local.env
+ExecStart=/usr/bin/surreal start
+ExecStop=/bin/kill -s SIGTERM $MAINPID
+Restart=on-failure
+RestartSec=5s
+TimeoutStartSec=30s
+TimeoutStopSec=30s
+LimitNOFILE=65536
+LimitNPROC=4096
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictRealtime=true
+RestrictNamespaces=true
+StateDirectory=surrealdb
+StateDirectoryMode=0750
+WorkingDirectory=/var/lib/surrealdb
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=suemo-surrealdb-%i
+
+[Install]
+WantedBy=multi-user.target
+`
+
+const SURREAL_COMMON_ENV_TEMPLATE = `# Generated by suemo init surreal
+# DO NOT edit - managed by suemo
+
+# Root auth (rotate regularly via local.env)
+SURREAL_USER=root
+SURREAL_PASS=__SURREAL_PASS__
+
+# Network
+SURREAL_BIND=127.0.0.1:8000
+
+# Datastore
+SURREAL_PATH=surrealkv:///var/lib/surrealdb/db
+SURREAL_DATASTORE_VERSIONED=true
+SURREAL_DATASTORE_RETENTION=90d
+SURREAL_DATASTORE_SYNC_DATA=every
+
+# SurrealKV storage tuning
+SURREAL_SURREALKV_ENABLE_VLOG=true
+SURREAL_SURREALKV_VLOG_THRESHOLD=4096
+SURREAL_SURREALKV_VERSIONED_INDEX=false
+
+# Grouped commit batching
+SURREAL_SURREALKV_GROUPED_COMMIT_TIMEOUT=5000000
+SURREAL_SURREALKV_GROUPED_COMMIT_WAIT_THRESHOLD=12
+SURREAL_SURREALKV_GROUPED_COMMIT_MAX_BATCH_SIZE=4096
+
+# Changefeed GC
+SURREAL_CHANGEFEED_GC_INTERVAL=60s
+
+# Timeouts
+SURREAL_QUERY_TIMEOUT=30s
+SURREAL_TRANSACTION_TIMEOUT=15s
+
+# Capability allowlist (required for suemo workflows)
+SURREAL_CAPS_DENY_ALL=true
+SURREAL_CAPS_ALLOW_FUNC=fn,time,vector,search,math,rand,ml
+
+# Logging
+SURREAL_LOG=warn
+SURREAL_NO_BANNER=true
+`
+
+const SURREAL_LOCAL_ENV_TEMPLATE = `# User overrides - edit this file to customize credentials
+# This file is NOT overwritten by suemo init surreal
+# Uncomment and set values to override defaults from common.env
+
+#SURREAL_USER=root
+#SURREAL_PASS=your-password-here
+#SURREAL_BIND=127.0.0.1:8000
+#SURREAL_PATH=surrealkv:///var/lib/surrealdb/db
+`
+
+const SURREAL_PROFILE_2GB_ENV = `# Generated by suemo init surreal 2gb
+SURREAL_SURREALKV_BLOCK_CACHE_CAPACITY=67108864
+SURREAL_SURREALKV_VLOG_MAX_FILE_SIZE=67108864
+SURREAL_TRANSACTION_CACHE_SIZE=2000
+SURREAL_DATASTORE_CACHE_SIZE=500
+SURREAL_HNSW_CACHE_SIZE=16777216
+SURREAL_RUNTIME_WORKER_THREADS=2
+SURREAL_RUNTIME_MAX_BLOCKING_THREADS=64
+SURREAL_NET_MAX_CONCURRENT_REQUESTS=1024
+SURREAL_WEBSOCKET_READ_BUFFER_SIZE=65536
+SURREAL_WEBSOCKET_WRITE_BUFFER_SIZE=65536
+SURREAL_EXTERNAL_SORTING_BUFFER_LIMIT=10000
+SURREAL_MEMORY_THRESHOLD=256m
+`
+
+const SURREAL_PROFILE_6GB_ENV = `# Generated by suemo init surreal 6gb
+SURREAL_SURREALKV_BLOCK_CACHE_CAPACITY=1073741824
+SURREAL_SURREALKV_VLOG_MAX_FILE_SIZE=134217728
+SURREAL_TRANSACTION_CACHE_SIZE=5000
+SURREAL_DATASTORE_CACHE_SIZE=1000
+SURREAL_HNSW_CACHE_SIZE=67108864
+SURREAL_RUNTIME_WORKER_THREADS=4
+SURREAL_RUNTIME_MAX_BLOCKING_THREADS=128
+SURREAL_NET_MAX_CONCURRENT_REQUESTS=4096
+SURREAL_WEBSOCKET_READ_BUFFER_SIZE=131072
+SURREAL_WEBSOCKET_WRITE_BUFFER_SIZE=131072
+SURREAL_EXTERNAL_SORTING_BUFFER_LIMIT=25000
+SURREAL_MEMORY_THRESHOLD=512m
+`
+
+const FASTEMBED_LOCAL_ENV_PATH = '/opt/fastembed/local.env'
+
+const FASTEMBED_LOCAL_ENV_TEMPLATE = `# User overrides - edit this file to customize settings
+# This file is NOT overwritten by suemo init fastembed
+# Uncomment and set values to override defaults
+
+#FASTEMBED_HOST=127.0.0.1
+#FASTEMBED_PORT=8080
+#FASTEMBED_MODEL=sentence-transformers/all-MiniLM-L6-v2
+#FASTEMBED_CACHE_DIR=/var/cache/fastembed
+`
+
+const FASTEMBED_SYSTEMD_SERVICE = `# Generated by suemo init fastembed
+[Unit]
+Description=FastEmbed OpenAI-compatible embedding service
+After=network.target
+
+[Service]
+Type=simple
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+User=fastembed
+Group=fastembed
+WorkingDirectory=/opt/suemo
+Environment=FASTEMBED_HOST=127.0.0.1
+Environment=FASTEMBED_PORT=8080
+Environment=FASTEMBED_MODEL=sentence-transformers/all-MiniLM-L6-v2
+Environment=FASTEMBED_CACHE_DIR=/var/cache/fastembed
+EnvironmentFile=-/opt/fastembed/local.env
+ExecStart=/usr/bin/python /opt/suemo/fastembed-server.py
+Restart=on-failure
+RestartSec=5s
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/cache/fastembed
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=suemo-fastembed
+
+[Install]
+WantedBy=multi-user.target
+`
+
+type InitAction =
+	| {
+		kind: 'mkdir'
+		path: string
+		mode: number
+	}
+	| {
+		kind: 'write'
+		path: string
+		mode: number
+		content: string
+	}
+	| {
+		kind: 'run'
+		command: string
+		args: string[]
+		requireRoot?: boolean
+	}
+
+type CredentialStatus = 'preserved' | 'generated'
+
+interface SurrealInitResult {
+	actions: InitAction[]
+	credentialStatus: CredentialStatus
+}
+
+function modeText(mode: number): string {
+	return mode.toString(8)
+}
+
+function hasRoot(): boolean {
+	return typeof process.getuid === 'function' ? process.getuid() === 0 : false
+}
+
+function runCommand(command: string, args: string[], options?: { requireRoot?: boolean; quiet?: boolean }): void {
+	const requireRoot = options?.requireRoot ?? false
+	const quiet = options?.quiet ?? false
+	if (requireRoot && !hasRoot()) {
+		throw new Error(
+			`Root privileges required for ${command}. Run init commands as root (e.g. sudo suemo init ... or sudo bunx suemo init ...).`,
+		)
+	}
+	const result = spawnSync(command, args, {
+		stdio: quiet ? 'ignore' : 'inherit',
+	})
+	if ((result.status ?? 1) !== 0) {
+		throw new Error(`Command failed: ${[command, ...args].join(' ')}`)
+	}
+}
+
+function requireRootForInit(subcommand: string): void {
+	if (hasRoot()) return
+	throw new Error(
+		`\`suemo ${subcommand}\` must be run as root. Try: \`sudo suemo ${subcommand}\` (or \`sudo bunx suemo ${subcommand}\` if suemo is not on root PATH).`,
+	)
+}
+
+function packageInstalled(pkg: string): boolean {
+	const result = spawnSync('pacman', ['-Q', pkg], { stdio: 'ignore' })
+	return (result.status ?? 1) === 0
+}
+
+function requireArchPackages(packages: string[]): void {
+	const pacmanProbe = spawnSync('pacman', ['--version'], { stdio: 'ignore' })
+	if ((pacmanProbe.status ?? 1) !== 0) {
+		throw new Error('pacman not found. `suemo init surreal/fastembed` currently supports Arch Linux systems.')
+	}
+
+	const missing = packages.filter((pkg) => !packageInstalled(pkg))
+	if (missing.length > 0) {
+		throw new Error(
+			`Missing required Arch package(s): ${missing.join(', ')}. Install with: sudo pacman -S ${missing.join(' ')}`,
+		)
+	}
+}
+
+function commandExists(command: string): boolean {
+	const result = spawnSync('sh', ['-lc', `command -v ${command}`], { stdio: 'ignore' })
+	return (result.status ?? 1) === 0
+}
+
+function requireCommands(commands: string[]): void {
+	const missing = commands.filter((command) => !commandExists(command))
+	if (missing.length > 0) {
+		throw new Error(`Missing required command(s): ${missing.join(', ')}`)
+	}
+}
+
+function systemUserExists(user: string): boolean {
+	const result = spawnSync('id', ['-u', user], { stdio: 'ignore' })
+	return (result.status ?? 1) === 0
+}
+
+function ensureDir(path: string, mode: number): void {
+	if (hasRoot()) {
+		mkdirSync(path, { recursive: true })
+		chmodSync(path, mode)
+		return
+	}
+	runCommand('install', ['-d', '-m', modeText(mode), path], { requireRoot: true })
+}
+
+function writeRootFile(path: string, content: string, mode: number): void {
+	if (hasRoot()) {
+		mkdirSync(dirname(path), { recursive: true })
+		writeFileSync(path, content, 'utf-8')
+		chmodSync(path, mode)
+		return
+	}
+
+	const tempDir = mkdtempSync(join(tmpdir(), 'suemo-init-'))
+	const tempFile = join(tempDir, basename(path))
+	try {
+		writeFileSync(tempFile, content, 'utf-8')
+		runCommand('install', ['-D', '-m', modeText(mode), tempFile, path], { requireRoot: true })
+	} finally {
+		rmSync(tempDir, { recursive: true, force: true })
+	}
+}
+
+function generatePassword(): string {
+	return randomBytes(20).toString('base64url')
+}
+
+function printDryRunActions(actions: InitAction[]): void {
+	for (const action of actions) {
+		if (action.kind === 'mkdir') {
+			console.log(`[dry-run] mkdir ${action.path} (mode ${modeText(action.mode)})`)
+			continue
+		}
+		if (action.kind === 'run') {
+			console.log(`[dry-run] run ${action.command} ${action.args.join(' ')}`.trim())
+			continue
+		}
+		console.log(`[dry-run] write ${action.path} (mode ${modeText(action.mode)})`)
+		console.log('-----8<-----')
+		console.log(action.content.trimEnd())
+		console.log('----->8-----')
+	}
+}
+
+function applyActions(actions: InitAction[]): void {
+	for (const action of actions) {
+		if (action.kind === 'mkdir') {
+			ensureDir(action.path, action.mode)
+			continue
+		}
+		if (action.kind === 'write') {
+			writeRootFile(action.path, action.content, action.mode)
+			continue
+		}
+		if (action.requireRoot === true) {
+			runCommand(action.command, action.args, { requireRoot: true })
+		} else {
+			runCommand(action.command, action.args)
+		}
+	}
+}
+
+function readEnvFile(path: string): string | null {
+	try {
+		const content = readFileSync(path, 'utf-8')
+		log.debug(`readEnvFile: successfully read file`, { path, length: content.length })
+		return content
+	} catch (error) {
+		const errorCode = error && typeof error === 'object' && 'code' in error
+			? (error as { code: string }).code
+			: 'UNKNOWN'
+
+		if (errorCode === 'ENOENT') {
+			log.debug(`readEnvFile: file does not exist`, { path })
+			return null
+		}
+
+		throw new Error(`Failed to read ${path}: ${error instanceof Error ? error.message : String(error)}`)
+	}
+}
+
+function extractEnvValue(content: string, key: string): string | null {
+	const match = new RegExp(`^${key}\\s*=\\s*(.+)$`, 'm').exec(content)
+	if (!match || !match[1]) return null
+	return match[1].trim()
+}
+
+function readFastembedScriptSource(): string {
+	const path = fileURLToPath(new URL('../../../data/fastembed-server.py', import.meta.url))
+	return readFileSync(path, 'utf-8')
+}
+
+function buildSurrealActions(
+	profile: '2gb' | '6gb',
+	existingPassword: string | null,
+	force: boolean,
+): SurrealInitResult {
+	const commonEnvPath = join(SURREAL_PROFILES_DIR, 'common.env')
+	const profileEnvPath = join(SURREAL_PROFILES_DIR, `${profile}.env`)
+	const localEnvPath = SURREAL_LOCAL_ENV_PATH
+	const actions: InitAction[] = []
+
+	log.debug('buildSurrealActions: start', { profile, existingPassword: existingPassword ? '***' : null, force })
+
+	if (!systemUserExists('surrealdb')) {
+		actions.push({
+			kind: 'run',
+			command: 'useradd',
+			args: [
+				'--system',
+				'--home-dir',
+				'/var/lib/surrealdb',
+				'--shell',
+				'/usr/bin/nologin',
+				'--create-home',
+				'surrealdb',
+			],
+			requireRoot: true,
+		})
+	}
+
+	const credentialStatus: CredentialStatus = existingPassword && !force ? 'preserved' : 'generated'
+	log.debug('buildSurrealActions: credential decision', { credentialStatus })
+
+	const password = credentialStatus === 'preserved' ? existingPassword! : generatePassword()
+	log.debug('buildSurrealActions: password determined', { passwordSet: !!password })
+
+	let commonEnv = SURREAL_COMMON_ENV_TEMPLATE.replace('__SURREAL_PASS__', password)
+	const existingCommonEnv = readEnvFile(commonEnvPath)
+	if (existingCommonEnv && !force) {
+		const existingUser = extractEnvValue(existingCommonEnv, 'SURREAL_USER')
+		const existingPass = extractEnvValue(existingCommonEnv, 'SURREAL_PASS')
+		if (existingUser && existingPass) {
+			log.debug('buildSurrealActions: preserving existing user and pass from common.env')
+			const lines = commonEnv.split('\n')
+			const preservedLines = lines.map((line) => {
+				if (line.startsWith('SURREAL_USER=')) {
+					return `SURREAL_USER=${existingUser}`
+				}
+				if (line.startsWith('SURREAL_PASS=')) {
+					return `SURREAL_PASS=${existingPass}`
+				}
+				return line
+			})
+			commonEnv = preservedLines.join('\n')
+		}
+	}
+
+	let profileEnv = profile === '2gb' ? SURREAL_PROFILE_2GB_ENV : SURREAL_PROFILE_6GB_ENV
+	const existingProfileEnv = readEnvFile(profileEnvPath)
+	if (existingProfileEnv && !force) {
+		log.debug('buildSurrealActions: preserving existing profile env')
+		profileEnv = existingProfileEnv
+	}
+
+	const localEnvExists = existsSync(localEnvPath)
+
+	actions.push(
+		{ kind: 'mkdir', path: SURREAL_PROFILES_DIR, mode: 0o750 },
+		{ kind: 'mkdir', path: SURREAL_DATA_DIR, mode: 0o750 },
+		{ kind: 'write', path: commonEnvPath, mode: 0o640, content: commonEnv },
+		{ kind: 'write', path: profileEnvPath, mode: 0o640, content: profileEnv },
+		...(!localEnvExists
+			? [{ kind: 'write' as const, path: localEnvPath, mode: 0o644, content: SURREAL_LOCAL_ENV_TEMPLATE }]
+			: []),
+		{ kind: 'write', path: SURREAL_SYSTEMD_UNIT_PATH, mode: 0o644, content: SURREAL_TEMPLATE_UNIT },
+		{ kind: 'run', command: 'chown', args: ['-R', 'surrealdb:surrealdb', SURREAL_DATA_DIR], requireRoot: true },
+		{
+			kind: 'run',
+			command: 'chown',
+			args: ['root:surrealdb', commonEnvPath],
+			requireRoot: true,
+		},
+		{
+			kind: 'run',
+			command: 'chown',
+			args: ['root:surrealdb', profileEnvPath],
+			requireRoot: true,
+		},
+		{ kind: 'run', command: 'systemctl', args: ['daemon-reload'], requireRoot: true },
+		{
+			kind: 'run',
+			command: 'systemctl',
+			args: ['enable', '--now', `suemo-surrealdb@${profile}.service`],
+			requireRoot: true,
+		},
+	)
+
+	log.debug('buildSurrealActions: complete', { actionCount: actions.length })
+	return { actions, credentialStatus }
+}
+
+function buildFastembedActions(scriptContent: string): InitAction[] {
+	const actions: InitAction[] = []
+	const localEnvExists = existsSync(FASTEMBED_LOCAL_ENV_PATH)
+
+	if (!systemUserExists('fastembed')) {
+		actions.push({
+			kind: 'run',
+			command: 'useradd',
+			args: [
+				'--system',
+				'--home-dir',
+				FASTEMBED_USER_HOME,
+				'--shell',
+				'/usr/bin/nologin',
+				'--create-home',
+				'fastembed',
+			],
+			requireRoot: true,
+		})
+	}
+
+	actions.push(
+		{ kind: 'mkdir', path: FASTEMBED_INSTALL_DIR, mode: 0o755 },
+		{ kind: 'mkdir', path: FASTEMBED_LOCAL_ENV_DIR, mode: 0o755 },
+		{ kind: 'mkdir', path: FASTEMBED_CACHE_DIR, mode: 0o755 },
+		{ kind: 'write', path: FASTEMBED_SCRIPT_TARGET, mode: 0o755, content: scriptContent },
+		...(!localEnvExists
+			? [{ kind: 'write' as const, path: FASTEMBED_LOCAL_ENV_PATH, mode: 0o644, content: FASTEMBED_LOCAL_ENV_TEMPLATE }]
+			: []),
+		{ kind: 'write', path: FASTEMBED_SERVICE_PATH, mode: 0o644, content: FASTEMBED_SYSTEMD_SERVICE },
+		{ kind: 'run', command: 'chown', args: ['-R', 'fastembed:fastembed', FASTEMBED_INSTALL_DIR], requireRoot: true },
+		{ kind: 'run', command: 'chown', args: ['root:root', FASTEMBED_LOCAL_ENV_DIR], requireRoot: true },
+		{ kind: 'run', command: 'chown', args: ['root:root', FASTEMBED_LOCAL_ENV_PATH], requireRoot: true },
+		{ kind: 'run', command: 'chown', args: ['-R', 'fastembed:fastembed', FASTEMBED_CACHE_DIR], requireRoot: true },
+		{ kind: 'run', command: 'systemctl', args: ['daemon-reload'], requireRoot: true },
+		{ kind: 'run', command: 'systemctl', args: ['enable', '--now', 'suemo-fastembed.service'], requireRoot: true },
+	)
+
+	return actions
+}
+
+function printInitSystemSummary(kind: 'surreal' | 'fastembed', dryRun: boolean, profile?: '2gb' | '6gb'): void {
+	if (kind === 'surreal') {
+		if (dryRun) {
+			console.log('Dry-run complete for SurrealDB setup.')
+		} else {
+			console.log('✓ SurrealDB setup complete.')
+		}
+		if (profile) {
+			console.log(`Service: suemo-surrealdb@${profile}.service`)
+			console.log(`Status: systemctl status suemo-surrealdb@${profile}.service`)
+			console.log(`Logs: journalctl -u suemo-surrealdb@${profile}.service -f`)
+		}
+		return
+	}
+
+	if (dryRun) {
+		console.log('Dry-run complete for fastembed setup.')
+	} else {
+		console.log('✓ fastembed setup complete.')
+	}
+	console.log('Service: suemo-fastembed.service')
+	console.log('Status: systemctl status suemo-fastembed.service')
+	console.log('Logs: journalctl -u suemo-fastembed.service -f')
+}
+
 function homeConfigPath(): string {
 	const home = process.env.HOME ?? process.env.USERPROFILE
 	if (!home) throw new Error('HOME/USERPROFILE is not set; cannot resolve ~/.suemo path')
@@ -241,10 +780,137 @@ const initOpenCodeCmd = init.sub('opencode')
 		console.log(`Installed suemo version: ${npmVersion}`)
 	})
 
+const initSurrealCmd = init.sub('surreal')
+	.meta({ description: 'Install SurrealDB systemd profile (2gb|6gb) with VERSIONED + allowlist config' })
+	.args([{ name: 'profile', type: 'string', required: true }])
+	.flags({
+		force: { type: 'boolean', description: 'Overwrite existing env files' },
+		'dry-run': { type: 'boolean', description: 'Print generated files and planned commands', default: false },
+		json: { type: 'boolean', description: 'Machine-readable output mode' },
+		'verbose-json': { type: 'boolean', description: 'Include embeddings in JSON output (implies --json)' },
+		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
+	})
+	.run(async ({ args, flags }) => {
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('init surreal', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
+		requireRootForInit('init surreal <2gb|6gb>')
+
+		requireCommands(['pacman', 'systemctl', 'install', 'chown', 'id'])
+		requireArchPackages(['surrealdb'])
+
+		const profileRaw = (args as { profile: string }).profile.trim().toLowerCase()
+		if (profileRaw !== '2gb' && profileRaw !== '6gb') {
+			throw new Error('Profile must be 2gb or 6gb')
+		}
+		const profile = profileRaw as '2gb' | '6gb'
+
+		const commonEnvPath = join(SURREAL_PROFILES_DIR, 'common.env')
+		const existingCommonEnv = readEnvFile(commonEnvPath)
+		const existingPassword = existingCommonEnv ? extractEnvValue(existingCommonEnv, 'SURREAL_PASS') : null
+		const force = Boolean(flags.force)
+		const dryRun = Boolean(flags['dry-run'])
+
+		log.debug('init surreal: reading existing password', {
+			commonEnvExists: existsSync(commonEnvPath),
+			existingPasswordFound: !!existingPassword,
+			force,
+		})
+
+		if (dryRun) {
+			if (outputMode === 'json') {
+				printCliJson({
+					ok: true,
+					dryRun: true,
+					profile,
+					existingPassword: existingPassword ?? 'none (not set)',
+					actions: [],
+				}, flags)
+				return
+			}
+			printInitSystemSummary('surreal', true, profile)
+			console.log(`Existing SURREAL_PASS preview: ${existingPassword ?? 'none (not set)'}`)
+			return
+		}
+
+		const result = buildSurrealActions(profile, existingPassword, force)
+		applyActions(result.actions)
+		printInitSystemSummary('surreal', false, profile)
+
+		if (result.credentialStatus === 'preserved') {
+			console.log(
+				`Existing SURREAL_USER and SURREAL_PASS have been preserved in ${commonEnvPath}. Use --force to regenerate password.`,
+			)
+		} else {
+			console.log(`Generated new SURREAL_PASS and wrote ${commonEnvPath} (rotate if needed).`)
+		}
+
+		if (outputMode === 'json') {
+			printCliJson({
+				ok: true,
+				dryRun: false,
+				profile,
+				service: `suemo-surrealdb@${profile}.service`,
+				credentialStatus: result.credentialStatus,
+			}, flags)
+			return
+		}
+	})
+
+const initFastembedCmd = init.sub('fastembed')
+	.meta({ description: 'Install fastembed systemd service from data/fastembed.py' })
+	.flags({
+		'dry-run': { type: 'boolean', description: 'Print generated files and planned commands', default: false },
+		json: { type: 'boolean', description: 'Machine-readable output mode' },
+		'verbose-json': { type: 'boolean', description: 'Include embeddings in JSON output (implies --json)' },
+		pretty: { type: 'boolean', description: 'Human-readable output (default)' },
+	})
+	.run(async ({ flags }) => {
+		const outputMode = resolveOutputModeOrExit(flags)
+		await initCliCommand('init fastembed', {
+			debug: flags.debug,
+			config: flags.config,
+			json: outputMode === 'json',
+			quiet: flags.quiet,
+		})
+		requireRootForInit('init fastembed')
+
+		requireCommands(['pacman', 'systemctl', 'install', 'chown', 'id'])
+		requireArchPackages(['python-fastembed', 'python-fastapi', 'uvicorn'])
+
+		const scriptContent = readFastembedScriptSource()
+		const actions = buildFastembedActions(scriptContent)
+		const dryRun = Boolean(flags['dry-run'])
+
+		if (dryRun) {
+			if (outputMode === 'json') {
+				printCliJson({ ok: true, dryRun: true, actions }, flags)
+				return
+			}
+			printDryRunActions(actions)
+			printInitSystemSummary('fastembed', true)
+			return
+		}
+
+		applyActions(actions)
+		printInitSystemSummary('fastembed', false)
+
+		if (outputMode === 'json') {
+			printCliJson({ ok: true, dryRun: false, service: 'suemo-fastembed.service' }, flags)
+			return
+		}
+	})
+
 export const initCmd = init
 	.command(initConfigCmd)
 	.command(initSchemaCmd)
 	.command(initOpenCodeCmd)
+	.command(initSurrealCmd)
+	.command(initFastembedCmd)
 	.flags({
 		json: { type: 'boolean', description: 'Machine-readable output mode' },
 		'verbose-json': { type: 'boolean', description: 'Include embeddings in JSON output (implies --json)' },
@@ -262,6 +928,8 @@ export const initCmd = init
 		console.log('  suemo init config [--force]')
 		console.log('  suemo init schema [--yes]')
 		console.log('  suemo init opencode')
+		console.log('  suemo init surreal <2gb|6gb> [--force] [--dry-run]')
+		console.log('  suemo init fastembed [--dry-run]')
 		console.log('  suemo skill [reference]')
 		console.log('\nRun `suemo init --help` for full details.')
 	})

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"]
+}