Docs/Overview

Sofuu Documentation: Lightweight Native AI Runtime

Sofuu is a lightweight native runtime for AI applications, tools, and agents (under 10 MB). Written in Rust, QuickJS, and libuv, it unites autonomous agent loops, declarative Kaze routines, on-device vector memory (QTSQ), and native Model Context Protocol (MCP) in a native runtime. Selected local workflows run without a separate Python installation or daemon; other workflows need external services or model files.

Installation

Install Sofuu with one command on macOS (Apple Silicon arm64) and Linux (x86_64 & arm64 / Raspberry Pi 5). Every official release binary is packaged as a single standalone executable under 10 MB with verified SHA-256 checksums:

# Install globally (one line, auto-detects macOS Apple Silicon & Linux x86_64 / arm64)
$ curl -fsSL https://sofuu.xyz/install | sh
# Or install through npm (downloads native platform binary, verifies SHA-256)
$ npm install -g sofuu # or: npx sofuu
# Verify installation & on-device vector memory linkage
$ sofuu doctor

Direct Release Downloads

Pre-compiled release binaries and mobile APKs with bundled QTSQ cognitive vector memory:

Verify checksum: sha256sum -c sofuu-<platform>-<arch>.tar.gz.sha256

AI Coding Agent Skill: SKILL.md

Works with Claude, Cursor, Antigravity, & Copilot

Hand this file to your AI assistant or place it in your project workspace to provide immediate operational mastery over Sofuu: CLI toolchain, in-process APIs (sofuu.memory, sofuu.agent, sofuu.mcp), standalone compilation, and plugin development.

# Download the official Sofuu AI skill for your agent workspace
$ curl -fsSL https://sofuu.xyz/SKILL.md -o SKILL.md

Quickstart Guide

1. Everything in One Process: Memory, Agents & AI

Sofuu collapses vector databases, agent orchestrators, and tool sandboxes into standard JavaScript / TypeScript inside a single lightweight binary (< 10 MB):

// quickstart.js - memory · native tools · agents · zero daemons
const brain = sofuu.memory.open("./brain.qtsq", 768);
brain.remember(sofuu.ai.embedLocal("runtime"), "AI runtime. Under 10 MB.");
// Recall using the same local embedding space
const [hit] = brain.recall(sofuu.ai.embedLocal("speed"), 1);
// Sandboxed native tool executed in-process with policy gates
const sys = sofuu.tools.execute("system_info", {});
// Autonomous agent - define once with memory & tools (0 models needed to test)
const agent = sofuu.agent.define({
name: "assistant", system: "Cite sources.",
tools: ["coding", "memory", "web"],
});
console.log(hit.text, "•", sys.platform || process.platform, "• agent:", agent.name);
// -> AI runtime. Under 10 MB. · darwin · agent: assistant

Execute directly, or compile supported code into a single-file executable:

# 1. Run directly
$ sofuu run quickstart.js
AI runtime. Under 10 MB. · darwin · agent: assistant
# 2. Compile into a native executable
$ sofuu compile quickstart.js -o my-agent
$ ./my-agent

This example defines an agent without running a model. Some workflows require external model files or services.

Local vector memory and selected local tools can work offline. Model-backed agents need a supported local model and backend or a remote provider; remote services require network access.

2. Instant Terminal Testing (No Files Needed)

Evaluate JavaScript and SIMD vector memory directly from any shell:

$ sofuu eval 'const b = sofuu.memory.open("./brain.qtsq", 768); b.remember(sofuu.ai.embedLocal("fast"), "Sofuu starts in <20ms"); console.log(b.recall(sofuu.ai.embedLocal("speed"), 1)[0].text);'

3. Streaming AI Micro-Server

When you are ready to stream tokens from an OpenAI-compatible endpoint or local Ollama server:

// app.js — an edge server that streams LLM tokens over Server-Sent Events
const server = sofuu.http.createServer(async (req, res) => {
if (req.url === "/chat") {
const stream = sofuu.ai.stream("Explain quantum mechanics simply.", {
provider: "openai", model: "gpt-4o",
});
res.writeHead(200, { "Content-Type": "text/event-stream" });
for await (const chunk of stream) res.write(chunk.text);
res.end();
} else {
res.writeHead(200);
res.end("AI Edge Runtime Active");
}
});
server.listen(8080, "0.0.0.0");
console.log("Server bound on port 8080.");

Building from Source

Sofuu links the QTSQ cognitive vector memory codec (libqtsq.a) statically as a core runtime dependency. To build from source, compile the QTSQ codec first, then pass its directory via SOFUU_QTSQ_DIR when building Sofuu:

Prerequisites

  • Rust & Cargo: 1.80+ (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh)
  • C/C++ Toolchain: clang or gcc, cmake, make
  • System Headers:
    • macOS: Xcode Command Line Tools (xcode-select --install)
    • Linux (Ubuntu / Debian / AWS Linux): sudo apt-get install -y zlib1g-dev libcurl4-openssl-dev libssl-dev
# 1. Clone and build the QTSQ static archive (libqtsq.a)
$ git clone https://github.com/haruhito2666/qtsq ~/projects/qtsq
$ cd ~/projects/qtsq && make
$ export SOFUU_QTSQ_DIR=$(pwd)
# 2. Clone and build Sofuu
$ git clone https://github.com/sofuu-runtime/sofuu ~/projects/sofuu
$ cd ~/projects/sofuu
$ make deps
$ SOFUU_QTSQ_DIR=$SOFUU_QTSQ_DIR make
# 3. Verify health check & test suite
$ ./sofuu doctor
$ make test

CLI Commands & Cheatsheet

One single binary is the whole toolchain: runtime, compiler, agent supervisor, MCP bridge, and package manager.

CommandArguments & FlagsWhat it does
sofuu run<file.js|ts> [--sandbox <preset>]Executes a JavaScript or TypeScript script directly without a build step using QuickJS and libuv.
sofuu eval"<code>" [-q]Evaluates inline JavaScript expressions directly from the shell (-q to suppress output).
sofuu repl[--sandbox <preset>]Starts an interactive JavaScript/TypeScript evaluation shell.
sofuu chat[-m <model>] [-p <provider>] [--sync off]Interactive AI coding assistant with real-time tool execution, vector memory, and collaborative session mesh.
sofuu compile<entry> [-o <out>] [--profile micro|lean|full] [--embed-brain <path>] [--no-strip]Compiles scripts, agents, or Kaze routines into a standalone single-file native executable (under 10 MB).
sofuu mcp build<server.ts> -o <out>Compiles a supported MCP server into a single-file executable; OS and workflow dependencies may remain.
sofuu mcplist | test <cmd> | inspect <cmd> | link <cursor|claude-desktop>Test protocol handshake, inspect schemas, invoke tools directly, and synchronize MCP configuration into IDEs.
sofuu agent run<name> "<task>" [--json]Headless execution of registered autonomous agents with structured JSON outputs for automation pipelines.
sofuu agentinit <name> | validate <file> | listScaffolds new agent templates to ~/.sofuu/agents/, validates schemas, and lists registered agents.
sofuu scriptrun <file.kaze> | check | compile | replExecutes, syntax-checks, compiles, and evaluates declarative Kaze (.kaze) agent routines.
sofuu logs[show <id>] [--follow] [--last-error]Lists past agent runs, displays step-by-step JSONL event traces, streams live traces, or renders post-mortem crash cards.
sofuu resume<run_id>Resumes an interrupted or failed agent execution from its last durable checkpoint.
sofuu pluginlist | add <pkg> | init <name> | validate <file> | test <tool>Manages plugins and invokes tools. Plugins run in-process and must be trusted as code.
sofuu sessionlist | show <id> | repair | pruneInspects segmented project sessions, repairs corrupted manifests, and prunes stale checkpoints.
sofuu outputslist | search <query> | context <id>Queries, searches, and builds historical task context from archived model and tool execution outputs.
sofuu brainstats | verify <path> | backup | restore | repairOffline administrative operations on encrypted QTSQ cognitive vector memory files.
sofuu serve--brain <path> | --model <path> [--port 7707]Hosts an OpenAI-compatible HTTP server serving vector memory queries or local model completions.
sofuu policycheck | why <action> [args]Validates security policies in .sofuu/policy.json or explains allow/deny decisions.
sofuu capabilities--jsonOutputs the complete runtime capability manifest (SIMD, GPU engines, transports, features) as JSON.
sofuu doctornoneHard system diagnostic: verifies QTSQ memory linkage, round-trip write/recall, and context limits.
sofuu versionnonePrints runtime version, commit revision (with -dirty if modified), QuickJS version, and platform arch.
sofuu licensesnoneDisplays open-source licenses for Sofuu, QuickJS, libuv, and the QTSQ memory engine.
sofuu dev[dir] [--port 3000]Full-stack reactive dev server with streaming JSX/TSX transpiler [Preview].
sofuu droneobserve | status | send | missionMAVLink v2 telemetry codec and hardware safety gates for robotics [Preview].
sofuu infer<model.gguf> [prompt]Built-in GGUF/SafeTensors local CPU inference preview [Preview].
sofuu swarmworker | leaderDistributed transformer layer pipelining over LAN sockets [Preview].

Standalone Compiler & Minimum Size Profiles

sofuu compile packages supported JavaScript, TypeScript, or Kaze programs as a single executable. A separate Node.js or Python installation is not required for supported code; system libraries and workflow-specific models or services may be required.

Compiler Profiles Comparison

Choose the target profile to optimize between binary footprint and available runtime capabilities:

ProfileCLI FlagBase BinaryTarget SizeIncluded SubsystemsRecommended Use Cases
Micro--profile microsofuu-micro~2.0–2.5 MBMinimal QuickJS + libuv + MCP stream parser. Strips agent loop, inference engine, TUI, and SQLite.Single-purpose tools, microservices, MCP servers (sofuu mcp build).
Lean (Default)--leansofuu-agent~5.4 MBFull QuickJS, libuv, vector memory (sofuu.memory), sandboxed tools, policy gates, and agent loop (sofuu.agent). Drops local GGUF engine and chat TUI.Autonomous agents, background daemons, CLI tools, edge workers.
Full--full / --with-inferencesofuu~6.8 MBEntire engine: local GGUF/SafeTensors CPU inference, MAVLink robotics, JSX transpiler, and full CLI.Completely offline, self-contained local AI applications with embedded weights.

Compiler CLI Examples

# 1. Compile with the default lean profile (full agents, memory, tools — under 10 MB):
$ sofuu compile agent.js -o dist/my-agent
# 2. Compile an MCP server with the micro profile:
$ sofuu mcp build server.ts -o dist/my-mcp-server
# (Or equivalently: sofuu compile server.ts --profile micro -o dist/my-mcp-server)
# 3. Embed encrypted vector cognitive memory directly inside the binary trailer:
$ sofuu compile agent.js --embed-brain ./brain.qtsq -o dist/agent-with-memory
# 4. Compile a declarative Kaze agent routine into a standalone executable:
$ sofuu compile agent.kaze -o dist/kaze-agent

Compiler Flags & Options

FlagDescription
-o <path>Specifies the output binary path (defaults to entry name without extension).
--profile <micro|lean|full>Selects the compiler profile and base runtime binary.
--embed-brain <path.qtsq>Embeds an encrypted QTSQ cognitive vector memory container directly inside the executable.
--no-stripPreserves debugging symbols in the output binary (useful during development).
--target <triple>Selects cross-compilation target (e.g. x86_64-unknown-linux-musl).

Model Context Protocol (MCP)

Sofuu supports MCP client and server features for protocol versions 2025-06-18 and 2024-11-05, with stdio, HTTP, legacy SSE, and direct client transports. Stdio resource and prompt handlers must be synchronous. An external server such as an npx server has its own dependencies.

1. MCP Client

Connect to local or remote MCP servers to discover tools, read resources, and execute actions:

// Connect to an MCP server via stdio, Streamable HTTP, or legacy SSE
const client = await sofuu.mcp.connect("npx -y @modelcontextprotocol/server-filesystem /tmp");
// or HTTP: await sofuu.mcp.connect({ url: "http://127.0.0.1:9000/mcp", transport: "http" });
// Inspect tools and execute calls
const tools = await client.listTools();
const result = await client.call("read_file", { path: "/tmp/data.txt" });
console.log(result.text);
client.disconnect();
  • Transports Supported: stdio (command spawning with newline-delimited JSON-RPC), http (Streamable HTTP with session handling), sse (HTTP+SSE), and direct (in-memory).
  • Configuration & Policy (~/.sofuu/mcp.json): Configure persistent servers with per-server tool allow/deny filters (tools: { allow: ["read_file"], deny: ["write_file"] }) and secret store resolution.

2. MCP Server

Build standalone or in-process MCP servers in TypeScript or JavaScript:

// server.ts — Standalone MCP Server in pure TypeScript
const server = sofuu.mcp.serve({ name: "math-service", version: "1.0.0" });
// Register a tool with typed parameter schema
server.tool("fibonacci", {
description: "Calculate the nth Fibonacci number",
schema: { type: "object", properties: { n: { type: "number" } }, required: ["n"] }
}, async ({ n }) => ({
result: n <= 1 ? n : n * 2 // computation
}));
// Register resources and prompts
server.resource("system://metrics", { mimeType: "application/json" }, async () => ({
cpu: process.cpuUsage(), memory: process.memoryUsage()
}));
// Spawns over stdio for Cursor, Claude Desktop, or custom clients
server.start();

3. Direct In-Memory Transport for Agents

Connect an in-process MCP server directly to an autonomous agent without process spawning or serialization overhead:

const directClient = await sofuu.mcp.connect(server, { transport: "direct" });
const agent = sofuu.agent.define({ name: "calc-agent", tools: [directClient] });

4. Standalone MCP Micro-Binary Compilation

Compile any TypeScript MCP server into a standalone single-file micro-binary (~2 MB):

$ sofuu mcp build server.ts -o dist/my-mcp-server
$ ./dist/my-mcp-server   # OS libraries and workflow dependencies may apply

5. MCP CLI Utilities & IDE Linking

CommandPurpose
sofuu mcp listLists configured MCP servers from ~/.sofuu/mcp.json.
sofuu mcp test "<cmd>"Tests handshake, protocol negotiation, and tool count.
sofuu mcp inspect "<cmd>" --call <t> --args '{...}'Inspects tool schemas and invokes a tool directly from the terminal.
sofuu mcp link cursorSynchronizes server configurations directly into Cursor IDE settings.
sofuu mcp link claude-desktopSynchronizes server configurations into Claude Desktop settings.

Kaze Agent Language (.kaze)

Kaze is a domain-specific language for agent and device routines. The embedded host can return synthetic AI, tool and memory results; the real model-and-authorized-tool journey remains an open milestone.

Read the standalone Kaze 1.0 language reference → for its tagged syntax, values, capabilities, errors, limits, and configuration. The standalone and embedded engines differ.

# agent.kaze — pure computation
action add(a, b):
return a + b

Sofuu-compiled agent configuration

The Sofuu-compiled agent source resolves parameters in the following order. The standalone kaze CLI has different configuration support; see the reference for its current limits.

  1. CLI arguments: --arg name=value or positional values (highest priority).
  2. Environment Variables: AGENT_<PARAM> or SOFUU_*.
  3. Configuration File: --config <path> or ./agent.config.json.

Kaze CLI Workflow

CommandPurpose
sofuu script run agent.kazeExecutes a Kaze agent routine directly in the linear arena VM.
sofuu script check agent.kazeParses and checks the routine without executing it.
sofuu script compile agent.kaze -o agent.kazebcCompiles the routine into embedded-engine bytecode.
sofuu compile agent.kaze -o agentPackages a supported routine as a standalone executable.
sofuu script replInteractive Kaze expression and policy evaluation REPL.

Chat & Project Session Mesh

sofuu chat is a full autonomous coding agent in your terminal with real-time streaming answers, built-in tools (read_file, write_file, edit_file, grep, glob, list_dir, bash), and persistent encrypted cognitive memory.

Real-Time Session Mesh: When running multiple terminal sessions on the same project, sofuu chat automatically synchronizes tasks, notes, critical alerts, and shared context via bounded project storage. Use --sync off to run in standalone isolation.

# Start interactive coding assistant in terminal
$ sofuu chat
# Real-time streaming answers, built-in tool belt,
# encrypted QTSQ cognitive memory, and project session mesh.

Essential slash commands:

CommandPurpose
/work <task>Broadcasts your active task to the project session mesh so other sessions avoid conflicting work.
/doneMarks your active task completed and clears work status across the mesh.
/note <msg>Saves an instant note visible to all sessions on the current project.
/notify <msg>Emits a high-priority banner notification to all connected peer sessions.
/context [id]Inspects or attaches shared context across project sessions.
/remember <fact>Pins durable facts and architecture rules into the local encrypted QTSQ brain.
/compactCompacts conversation history when the context window fills up, preserving questions and decisions.
/ctx · /costLive context-window and spend meters. Accepts 1m, 128k, or raw token counts.
/effort <lvl>Sets reasoning effort level (low, medium, high, max).
/provider · /modelSwitches LLM backend or model (local or cloud).
/toolsToggles the active tool belt on or off.
/sessions · /resumeLists past project sessions and resumes any run by ID.
/helpDisplays full interactive command documentation.

Agent Observability & Crash Recovery

Agent tracing can record events and checkpoints. Redaction recognizes certain patterns, crash cards are best-effort, and resume requires a usable checkpoint; redacted or truncated checkpoints can be refused.

# 1. Inspect recent autonomous agent runs
$ sofuu logs
# 2. Render complete event trace transcript
$ sofuu logs show run_1730000000
# 3. Resume an interrupted or crashed run from last checkpoint
$ sofuu resume run_1730000000
# 4. View diagnostic post-mortem card for the newest failure
$ sofuu logs --last-error
CommandBehavior
sofuu logsLists recent runs with run ID, start time, step count, and exit status (DONE, ERROR, CANCELLED).
sofuu logs show <id>Renders human-readable event traces for model calls, tool executions, and step summaries.
sofuu logs --followLive-streams streaming tokens and tool calls from an active background agent worker.
sofuu logs --last-errorExtracts the exact failure context, stack trace, and post-mortem card for immediate debugging.
sofuu resume <id>Attempts to resume from a usable checkpoint; some checkpoints are refused.

Universal Plugin System

Extend Sofuu with plugins in five categories — tools (defineTool), inference providers (defineProvider), stores and vector stores(defineStorage/defineVectorStore), and lifecycle services(defineService) — plus zero-code bridging (useOpenAPI/ingestMcp). Plugin tools provide schema checks, guarded context helpers, circuit breakers, and watchdogs. Plugins run in-process and must be trusted as code; these controls are not an OS sandbox and cannot contain all failures.

// plugins/weather.ts — Drop into ./plugins/ for zero-build discovery
import { defineTool, z } from "sofuu";
export default defineTool({
name: "weather",
description: "Get current weather for a city",
schema: z.object({ city: z.string() }),
timeoutMs: 5000,
permissions: { net: ["api.weatherapi.com"] }, // Network allowlist
circuitBreaker: { failureThreshold: 5, resetTimeoutMs: 30000 },
async run({ city }, ctx) {
const res = await ctx.fetch(`https://api.weatherapi.com/v1/current.json?q=${city}`);
return res.json();
},
});
CommandPurpose
sofuu plugin init <name>Scaffolds a plugin in ./plugins/. Use --category=tool|provider|store|vectorstore|service|openapi.
sofuu plugin listDiscovers and lists all installed plugins across ./plugins/ and sofuu.json, with per-plugin circuit state.
sofuu plugin validate <file.ts|js>Parses, type-strips, and registers a plugin source file, reporting registered exports or validation refusals.
sofuu plugin test <tool> [<json-args>]Invokes an in-process plugin tool with the given inputs and prints the result envelope.
sofuu plugin add <name>Installs provider plugins from the official catalog (e.g., sofuu plugin add llamacpp).

Global Sandbox

Primitives injected into the root scope of every script — no import needed.

BindingBehavior
setTimeout(cb, ms)Schedules the callback on the native event loop. Cancel with clearTimeout(id).
setInterval(cb, ms)Repeating background scheduler. Cancel with clearInterval(id).
sleep(ms)Synchronous halt of the entire event loop — useful in embedded scripts, avoid in servers.
console.log()Standard output; console.time(id) / timeEnd(id) for high-resolution timing.
process.argv · process.envCommand-line arguments and the process environment block.
process.cwd()Current working directory.
process.exit(code)Terminates the runtime immediately.
process.stdout.write(s)Raw write to standard output.

Node.js & Web Standards Compatibility

Eliminates the QuickJS compatibility wall. Run standard modern TypeScript and JavaScript using familiar Node.js built-ins and Web Standard APIs without third-party polyfills. TypeScript is transformed in-process — types erased, enums and constructor parameter properties lowered to plain JS — so sofuu run app.ts requires no tsc step.

Standard / ModuleSupported Primitives & APIs
Web StandardsTextEncoder, TextDecoder, URL, URLSearchParams, atob, btoa, Headers, Request, Response
Web platform globalsstructuredClone, Blob/File/FormData, Event/EventTarget/CustomEvent, MessageChannel/MessagePort, navigator, and persistent localStorage (backed by .sofuu/localStorage.json).
Web Cryptocrypto.randomUUID() (OS urandom RFC 4122 v4), crypto.getRandomValues(), crypto.subtle.digest("SHA-256")
StreamsReadableStream, WritableStream, TransformStream, TextDecoderStream, TextEncoderStream; Response.body is a stable ReadableStream.
node:fs / fsreadFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, unlinkSync, statSync, promises
node:path / pathjoin, resolve, normalize, isAbsolute, relative, dirname, basename, extname, parse, format, sep
node:buffer · BufferBuffer.from, alloc, concat, isBuffer, byteLength, toString('utf8'|'hex'|'base64'), copy, slice
node:eventsEventEmitter (on, once, off, emit, listeners, listenerCount, setMaxListeners)
node:process / processprocess.nextTick, process.version ('0.3.0-beta'), process.platform, process.arch, process.versions
AI SDK CompatibilityOpenAI (openai), Anthropic (@anthropic-ai/sdk), MCP (@modelcontextprotocol/sdk), Zod (zod)

sofuu.ai

The AI bridge: talk to local models, a llama.cpp server, or cloud providers (OpenAI, Anthropic, or any OpenAI-compatible endpoint) through one API. Streaming and SSE parsing happen in native code — libcurl's multi interface polled by libuv — not as a JavaScript parser loop.

ExportBehavior
sofuu.ai.complete(prompt, config?)Returns Promise<{ text, usage, raw }>; usage is { promptTokens, completionTokens }. Messages accept an images array.
sofuu.ai.stream(prompt, config?)Returns an AsyncIterator of chunks as they arrive from the model.
sofuu.ai.embed(text, config?)Defaults to the local sem2-64 space (64 dimensions). embedLocal defaults to the 768-dimensional trigram hash. Query and stored vectors must use the same space and dimension; explicit providers may require network access.
sofuu.ai.embedBatch(texts[], config?)Local-only vectorized batch — one call, one Float32Array per input.
sofuu.ai.embedImage(bytes)Image bytes (Uint8Array) → 64-dim unit vector in joint text-image space.
sofuu.ai.embedLocal(text)Bundled offline embeddings, sync, zero network: 768-dim hash vector.
sofuu.ai.similarity(a, b)Cosine similarity of two vectors on hardware SIMD registers (AVX2 / NEON).
sofuu.ai.dot(a, b) · sofuu.ai.l2(a, b)Raw dot product and L2 distance over the same native SIMD kernels.
sofuu.ai.estimateTokens(text)Fast token-count estimate for prompt budgeting.

sofuu.http & fetch

ExportBehavior
sofuu.http.createServer(cb)Binds a non-blocking HTTP server directly over OS sockets. Callback receives req and res.
server.listen(port, host)Refs the handle and keeps the process alive while listening (Node semantics). Opt out with server.unref().
res.writeHead(status, hdrs)Sends the response status code and headers.
res.end(data)Flushes the body and finishes the response.
sofuu.fetch(url, opts?)HTTP(S) client over statically linked curl — runs on background polling, resolves to response with .text() / .json().

sofuu.fs & processes

ExportBehavior
sofuu.fs.readFile(path)Reads a file from disk.
sofuu.fs.writeFile(path, data)Writes (overwrites) a file.
sofuu.fs.appendFile(path, data)Appends to a file — useful for local logs.
sofuu.fs.readdir(path)Lists a directory as an array of entries.
sofuu.fs.mkdir(path) · sofuu.fs.rm(path) · sofuu.fs.exists(path)Directory creation, removal, and existence checks.
sofuu.spawn()Launches a child process with an argument list and returns its output.

sofuu.web

Web access for scripts and agents — keyless web search and reader-friendly content extraction.

ExportBehavior
sofuu.web.search(text)Searches the web and returns ranked result snippets.
sofuu.web.open(url)Fetches a webpage and returns cleaned, reader-friendly text.

sofuu.memory (QTSQ / CMA v2) & sofuu.storage

Durable persistence is backed by the QTSQ Continuous Memory Architecture: bounded .store segments with write journals, torn-segment quarantine, and AES-256-GCM encryption with a machine-local key (~/.sofuu/brain.key or SOFUU_BRAIN_KEY). Encrypted by default; explicit plaintext mode and unencrypted exports exist. Logs and providers have separate data handling. Search latency varies by workload. Remote adapters (qdrant, pinecone, pgvector) are supported via memory.open options.

// Embedded QTSQ with 768-dimensional vectors
const brain = sofuu.memory.open("./brain.qtsq", 768);
// Explicit remote adapter: same remember/recall contract, async
const remote = sofuu.memory.open("https://...", {
adapter: "qdrant", // qdrant | pinecone | pgvector | custom
dimensions: 768, collection: "notes",
apiKeyEnv: "QDRANT_API_KEY",
});
await remote.remember("hello", { tags: ["note"] });
const hits = await remote.recall({ query: "hello", limit: 5 });
ExportBehavior
sofuu.memory.open(path, vecDim, options?)Opens an encrypted QTSQ container (e.g. ./brain.qtsq). Pass adapter: "qdrant" | "pinecone" | "pgvector" to route to a remote backend.
mem.remember(vectorOrText, text?, role?, turn?)Stores a record with a vector, timestamp, and text; a plain string is automatically embedded.
mem.recall(queryVectorOrText, k)Returns top k nearest records. Includes distance (0 = exact match) and similarity.
mem.count() · mem.stats()Total records, active segments, and capacity metrics.
sofuu.storage.open(path)Opens structured store: .messages, .traces, and key-value facade at .kv.

sofuu.agent & Domain Toolpacks

Sofuu provides a first-class autonomous agent execution loop with prompt sovereignty (the runtime never injects hidden prompt prefixes or rules), modular domain toolpacks, and structured session persistence.

// Define an autonomous agent with prompt sovereignty & domain toolpacks
sofuu.agent.define({
name: "researcher",
system: "You research accurately. Cite sources with URLs.",
tools: ["web", "memory", "system"],
memory: "agent",
budget: { maxSteps: 12, maxWallMs: 120_000 },
);
const result = await sofuu.agent.run("researcher", "Compare ARM NEON and AVX2");
console.log(result.answer);

Domain Toolpacks (sofuu.tools.PACKS)

PackTools IncludedDescription
codingread_file, write_file, edit_file, apply_patch, grep, glob, list_dir, bash, code_evalFilesystem and execution tools jailed to the project directory. Strip shell with SOFUU_NO_SHELL=1.
webweb_search, web_openKeyless web searching and reader-friendly page fetching.
memorymemory_search, memory_rememberDirect natural language recall and persistence in local .qtsq cognitive vector memory.
systemsystem_infoRuntime version, host OS, CPU architecture, GPU engine, memory, and active capabilities.

Sandbox v2 & Policy Enforcement

sofuu.sandbox runs untrusted code in a separate hermetic realm with no host filesystem, network, or process access unless explicitly bridged:

// Execute untrusted code in an isolated, hermetic realm
const result = await sofuu.sandbox.run(source, {
fuel: 50_000_000, // deterministic instruction budget
timeoutMs: 5_000, // wall-clock deadline
maxMemoryMB: 64, // realm memory ceiling
preset: "standard" // strict | standard | compute | worker
}); // { success, result, errorType, code, fuelUsed, logs }

Realm Presets

PresetWorkloadDeadlineFuelMemory
strictUntrusted LLM-generated code2 s5M instructions32 MB
standardDeveloper scripting10 s20M instructions64 MB
computeMath, simulations, ETL300 sunlimited512 MB
workerLong-running background tasksnoneunlimited256 MB

In-Process Local Inference [Preview]

Experimental Preview. The built-in GGUF/SafeTensors inference engine is an experimental preview decoupled from the production launch gate. For production workloads, use llama.cpp or another inference backend through the llamacpp provider plugin or remote cloud endpoints.

Sofuu runs local models directly in-process with zero-copy mmap:

$ sofuu infer ./model.gguf "Hello"
$ sofuu serve --infer -m ./model.gguf

Micro-Server

Host an OpenAI-compatible endpoint with zero external daemons:

$ sofuu serve --model ./model --port 8080
$ sofuu serve --brain ./brain.qtsq   # Serves QTSQ vector memory over HTTP

Distributed Edge Swarms (Preview)

Pipeline transformer layers across local network nodes over sockets:

$ sofuu swarm worker --model ./model.gguf --listen 0.0.0.0:9001 --layers 16..32
$ sofuu swarm leader --model ./model.gguf --workers 192.168.1.50:9001 "Hello"

Advanced: RLM & Context ML

Recursive long-context reader loops (RLM) and five on-device context-economy advisory gates (freshness, relevance, supervisor, compaction, alloc):

ExportBehavior
sofuu.rlm.query(text, q, opts?)Recursive long-context reader loop — decomposes queries across documents far exceeding model context windows.
sofuu.ml.info()Inspects status of the 5 on-device context-economy gates (66,821 parameters total, deterministic, zero API calls).

Embed the Runtime in Your App (libsofuu)

Ship Sofuu inside iOS, macOS, Android, and native C/C++ applications with an embeddable C ABI library and Swift/Kotlin bindings:

// Swift (iOS / macOS)
import Sofuu
let sofuu = try Sofuu()
let brain = try Brain.openDefault(sofuu: sofuu) // encrypted local storage
try brain.remember("user prefers dark mode")
let hits = try brain.recall("theme preference", k: 1)
print(hits.first?.text ?? "")

For complete Swift, Kotlin, and C ABI documentation, visit sofuu.xyz/embed.