Optimal Engine CLI, SDKs and MCP

Every interface below talks to the same HTTP API, so a workspace looks the same from each. All of them install from a checkout of Miosa-osa/OptimalEngine.

The optimal CLI

A single shell script that needs sh, curl 7.55 or newer, and awk. It sends the key to curl on standard input, so the key never shows in a process list, and it never prints the key.

apps/cli/install.sh            # installs optimal and oe into /usr/local/bin or ~/.local/bin
optimal --version

Point it at an Engine

Settings are read in this order, first match wins:

1. Flags: --api <url>, --key-file <path>, -w <workspace>, --profile <name>.
2. A named profile, from --profile or OPTIMAL_PROFILE.
3. Environment: OPTIMAL_ENGINE_URL, OPTIMAL_ENGINE_API_KEY or OPTIMAL_ENGINE_API_KEY_FILE, OPTIMAL_WORKSPACE.
4. The default profile, ~/.config/optimal/profile.
5. http://127.0.0.1:4200.

A profile file holds the same settings:

url=http://127.0.0.1:4200
key_file=/home/me/.config/optimal/key
workspace=default:notes

optimal doctor reports where each setting came from and whether the Engine answers. On MIOSA, miosa engine connect writes this profile for you; see Optimal Engine on MIOSA.

Commands

optimal capture "Decided: annual plans get two months free." -w default:notes --title "Pricing"
optimal search "annual plans" -w default:notes -n 5
optimal ask "What did we decide about pricing?" -w default:notes
optimal api GET /api/version

Common options: -n for a limit, --as-of for a point in time, --mode lexical|hybrid|auto, --field a.b to print one field, and --raw for unformatted JSON.

MCP server

A stdio MCP server over the same API, for agent clients. It needs Node 20 or newer.

cd apps/mcp
npm ci && npm run build

It reads the same settings as the CLI, from the environment or a profile, once when it starts. Restart it after the key changes.

Register it with Claude Code:

claude mcp add --scope user 
  --env OPTIMAL_ENGINE_URL=http://127.0.0.1:4200 
  --env OPTIMAL_ENGINE_API_KEY_FILE=/home/me/.config/optimal/key 
  --env OPTIMAL_WORKSPACE=default:notes 
  optimal-engine -- node /path/to/OptimalEngine/apps/mcp/dist/index.js

Give it a key with only what its agent needs, for example read and write on one workspace.

Mix tasks

On the Engine’s own machine, a checkout has mix optimal.* tasks that work on the store directly. Useful ones:

docs/guides/mix-tasks.md in the repository lists all of them.

TypeScript client

cd sdks/typescript
npm install && npm run build

import { OptimalEngine } from "@optimal-engine/client";

const engine = new OptimalEngine({
  baseUrl: "http://127.0.0.1:4200",
  apiKey: process.env.OPTIMAL_ENGINE_API_KEY,
  workspace: "default:notes",
});

await engine.ingest("Decided: annual plans get two months free.", { title: "Pricing" });
const hits = await engine.search("annual plans");
const context = await engine.ask("What did we decide about pricing?");
console.log(context.envelope.body, context.envelope.sources);

It also has grep, assemble, profile, createNode, and sub-clients for memory, workspaces, wiki, recall, subscriptions, surface, and render. Adapters for the Vercel AI SDK and the OpenAI Agents SDK are at @optimal-engine/client/adapters/ai-sdk and /adapters/openai-agents.

Python client

pip install ./sdks/python

from optimal_engine import OptimalEngine

engine = OptimalEngine(base_url="http://127.0.0.1:4200", workspace="default:notes", api_key="oe_...")
results = engine.search("annual plans")
memory = engine.memory.create(content="Customer Example Co renews in March.")

It needs Python 3.10 or newer, and has a sync OptimalEngine and an async AsyncOptimalEngine. It covers search, grep, recall, memory, and workspaces.