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.
Quickstart
Run the 30-second offline demo with zero models and zero API keys needed.
Open Quickstart →CLI Reference
Complete cheatsheet of every command, argument, and toolchain flag.
Open CLI Reference →Standalone Compiler
Compile agents and MCP servers into single-file binaries with micro and lean profiles.
Open Compiler Guide →Model Context Protocol
Native client, server, direct in-memory transport, and IDE linking.
Open MCP Guide →Kaze Language
Explore standalone Kaze 1.0 syntax, capabilities, errors, limits, and configuration.
Open Kaze Reference →Plugin System
Zero-build extensibility: tools, providers, stores, and background services.
Open Plugins Guide →Memory (QTSQ)
Local vector memory, encrypted by default, with SIMD search.
Open Memory Reference →Build from Source
Step-by-step instructions for building both QTSQ and Sofuu from source.
Open Build Guide →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, & CopilotHand 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 daemonsconst brain = sofuu.memory.open("./brain.qtsq", 768);brain.remember(sofuu.ai.embedLocal("runtime"), "AI runtime. Under 10 MB.");// Recall using the same local embedding spaceconst [hit] = brain.recall(sofuu.ai.embedLocal("speed"), 1);// Sandboxed native tool executed in-process with policy gatesconst 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.jsAI 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:
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 Eventsconst 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:
clangorgcc,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
- macOS: Xcode Command Line Tools (
# 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.
| Command | Arguments & Flags | What 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 mcp | list | 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 agent | init <name> | validate <file> | list | Scaffolds new agent templates to ~/.sofuu/agents/, validates schemas, and lists registered agents. |
sofuu script | run <file.kaze> | check | compile | repl | Executes, 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 plugin | list | add <pkg> | init <name> | validate <file> | test <tool> | Manages plugins and invokes tools. Plugins run in-process and must be trusted as code. |
sofuu session | list | show <id> | repair | prune | Inspects segmented project sessions, repairs corrupted manifests, and prunes stale checkpoints. |
sofuu outputs | list | search <query> | context <id> | Queries, searches, and builds historical task context from archived model and tool execution outputs. |
sofuu brain | stats | verify <path> | backup | restore | repair | Offline 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 policy | check | why <action> [args] | Validates security policies in .sofuu/policy.json or explains allow/deny decisions. |
sofuu capabilities | --json | Outputs the complete runtime capability manifest (SIMD, GPU engines, transports, features) as JSON. |
sofuu doctor | none | Hard system diagnostic: verifies QTSQ memory linkage, round-trip write/recall, and context limits. |
sofuu version | none | Prints runtime version, commit revision (with -dirty if modified), QuickJS version, and platform arch. |
sofuu licenses | none | Displays 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 drone | observe | status | send | mission | MAVLink 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 swarm | worker | leader | Distributed 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:
| Profile | CLI Flag | Base Binary | Target Size | Included Subsystems | Recommended Use Cases |
|---|---|---|---|---|---|
| Micro | --profile micro | sofuu-micro | ~2.0–2.5 MB | Minimal QuickJS + libuv + MCP stream parser. Strips agent loop, inference engine, TUI, and SQLite. | Single-purpose tools, microservices, MCP servers (sofuu mcp build). |
| Lean (Default) | --lean | sofuu-agent | ~5.4 MB | Full 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-inference | sofuu | ~6.8 MB | Entire 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
| Flag | Description |
|---|---|
-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-strip | Preserves 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 SSEconst 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 callsconst 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), anddirect(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 TypeScriptconst server = sofuu.mcp.serve({ name: "math-service", version: "1.0.0" });// Register a tool with typed parameter schemaserver.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 promptsserver.resource("system://metrics", { mimeType: "application/json" }, async () => ({cpu: process.cpuUsage(), memory: process.memoryUsage()}));// Spawns over stdio for Cursor, Claude Desktop, or custom clientsserver.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 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):
$ ./dist/my-mcp-server # OS libraries and workflow dependencies may apply
5. MCP CLI Utilities & IDE Linking
| Command | Purpose |
|---|---|
sofuu mcp list | Lists 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 cursor | Synchronizes server configurations directly into Cursor IDE settings. |
sofuu mcp link claude-desktop | Synchronizes 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 computationaction 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.
- CLI arguments:
--arg name=valueor positional values (highest priority). - Environment Variables:
AGENT_<PARAM>orSOFUU_*. - Configuration File:
--config <path>or./agent.config.json.
Kaze CLI Workflow
| Command | Purpose |
|---|---|
sofuu script run agent.kaze | Executes a Kaze agent routine directly in the linear arena VM. |
sofuu script check agent.kaze | Parses and checks the routine without executing it. |
sofuu script compile agent.kaze -o agent.kazebc | Compiles the routine into embedded-engine bytecode. |
sofuu compile agent.kaze -o agent | Packages a supported routine as a standalone executable. |
sofuu script repl | Interactive 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:
| Command | Purpose |
|---|---|
/work <task> | Broadcasts your active task to the project session mesh so other sessions avoid conflicting work. |
/done | Marks 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. |
/compact | Compacts conversation history when the context window fills up, preserving questions and decisions. |
/ctx · /cost | Live context-window and spend meters. Accepts 1m, 128k, or raw token counts. |
/effort <lvl> | Sets reasoning effort level (low, medium, high, max). |
/provider · /model | Switches LLM backend or model (local or cloud). |
/tools | Toggles the active tool belt on or off. |
/sessions · /resume | Lists past project sessions and resumes any run by ID. |
/help | Displays 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
| Command | Behavior |
|---|---|
sofuu logs | Lists 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 --follow | Live-streams streaming tokens and tool calls from an active background agent worker. |
sofuu logs --last-error | Extracts 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 discoveryimport { 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 allowlistcircuitBreaker: { 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();},});
| Command | Purpose |
|---|---|
sofuu plugin init <name> | Scaffolds a plugin in ./plugins/. Use --category=tool|provider|store|vectorstore|service|openapi. |
sofuu plugin list | Discovers 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.
| Binding | Behavior |
|---|---|
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.env | Command-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 / Module | Supported Primitives & APIs |
|---|---|
Web Standards | TextEncoder, TextDecoder, URL, URLSearchParams, atob, btoa, Headers, Request, Response |
Web platform globals | structuredClone, Blob/File/FormData, Event/EventTarget/CustomEvent, MessageChannel/MessagePort, navigator, and persistent localStorage (backed by .sofuu/localStorage.json). |
Web Crypto | crypto.randomUUID() (OS urandom RFC 4122 v4), crypto.getRandomValues(), crypto.subtle.digest("SHA-256") |
Streams | ReadableStream, WritableStream, TransformStream, TextDecoderStream, TextEncoderStream; Response.body is a stable ReadableStream. |
node:fs / fs | readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, unlinkSync, statSync, promises |
node:path / path | join, resolve, normalize, isAbsolute, relative, dirname, basename, extname, parse, format, sep |
node:buffer · Buffer | Buffer.from, alloc, concat, isBuffer, byteLength, toString('utf8'|'hex'|'base64'), copy, slice |
node:events | EventEmitter (on, once, off, emit, listeners, listenerCount, setMaxListeners) |
node:process / process | process.nextTick, process.version ('0.3.0-beta'), process.platform, process.arch, process.versions |
AI SDK Compatibility | OpenAI (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.
| Export | Behavior |
|---|---|
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
| Export | Behavior |
|---|---|
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
| Export | Behavior |
|---|---|
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.
| Export | Behavior |
|---|---|
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 vectorsconst brain = sofuu.memory.open("./brain.qtsq", 768);// Explicit remote adapter: same remember/recall contract, asyncconst remote = sofuu.memory.open("https://...", {adapter: "qdrant", // qdrant | pinecone | pgvector | customdimensions: 768, collection: "notes",apiKeyEnv: "QDRANT_API_KEY",});await remote.remember("hello", { tags: ["note"] });const hits = await remote.recall({ query: "hello", limit: 5 });
| Export | Behavior |
|---|---|
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 toolpackssofuu.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)
| Pack | Tools Included | Description |
|---|---|---|
coding | read_file, write_file, edit_file, apply_patch, grep, glob, list_dir, bash, code_eval | Filesystem and execution tools jailed to the project directory. Strip shell with SOFUU_NO_SHELL=1. |
web | web_search, web_open | Keyless web searching and reader-friendly page fetching. |
memory | memory_search, memory_remember | Direct natural language recall and persistence in local .qtsq cognitive vector memory. |
system | system_info | Runtime 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 realmconst result = await sofuu.sandbox.run(source, {fuel: 50_000_000, // deterministic instruction budgettimeoutMs: 5_000, // wall-clock deadlinemaxMemoryMB: 64, // realm memory ceilingpreset: "standard" // strict | standard | compute | worker}); // { success, result, errorType, code, fuelUsed, logs }
Realm Presets
| Preset | Workload | Deadline | Fuel | Memory |
|---|---|---|---|---|
strict | Untrusted LLM-generated code | 2 s | 5M instructions | 32 MB |
standard | Developer scripting | 10 s | 20M instructions | 64 MB |
compute | Math, simulations, ETL | 300 s | unlimited | 512 MB |
worker | Long-running background tasks | none | unlimited | 256 MB |
In-Process Local Inference [Preview]
llamacpp provider plugin or remote cloud endpoints.Sofuu runs local models directly in-process with zero-copy mmap:
$ sofuu serve --infer -m ./model.gguf
Micro-Server
Host an OpenAI-compatible endpoint with zero external daemons:
$ 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 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):
| Export | Behavior |
|---|---|
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 Sofuulet sofuu = try Sofuu()let brain = try Brain.openDefault(sofuu: sofuu) // encrypted local storagetry 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.