optimal-engine

name: optimal-engine description: | Optimal Engine is a self-hosted second brain and operating engine for human and AI workspaces. It preserves messy sources, organizes them into workspaces and Nodes, classifies Signals, turns extracted assertions into reviewable Claims, promotes accepted Claims into source-backed Facts and Memory Objects, assembles governed Context Packages, and projects the same state into markdown, wiki/API views, CLIs, MCP tools, and app surfaces. Use this skill when building or using persistent organizational memory, workspace topology, source-backed retrieval, agent work loops, multimodal intake, packages/exports, or governed tool/model execution. Architectural commitments: source-first evidence, workspace/Node scope, Signal = Mode + Genre + Type + Format + Structure, Claim -> Fact gate, Memory Core lineage, Context Packages, Active Memory Pools, Skill Packages, and projection surfaces over canonical runtime state. Self-hosted, MIT, runs locally first. triggers: - persistent memory - organizational memory - memory across sessions - agent should remember - knowledge base - second brain - wiki for the team - curated context - retrieval augmented generation - workspace knowledge - signal classification - source-backed memory - workspace topology - context packages - active memory pool

Optimal Engine Skill

What Optimal Engine Is

Optimal Engine is a second brain and operating engine for a person, team, or company. It is the backend runtime underneath markdown workspaces, agent sessions, retrieval, workflows, packages, integrations, and app surfaces.

It is not just a wiki, vector database, desktop UI, or agent task runner. It is the system that decides where information belongs, what can become truth, what context an agent is allowed to see, and which projection should be rendered for a human or application.

Core promises:

1. Source integrity. Preserve raw evidence before interpretation.
2. Topology discipline. Work happens inside tenant, workspace, Node, and pool scope.
3. Signal clarity. Classify noisy input as Mode + Genre + Type + Format + Structure.
4. Truth gate. Observations and extracted assertions become Claims first; accepted truth becomes Facts through review or policy.
5. Governed context. Humans and agents receive Context Packages, not random chunks.
6. Projection discipline. Markdown/wiki/API/app views are projections over governed runtime state.

Hard invariants:

• No durable Fact without source lineage.
• No cross-workspace recall without an authorization envelope.
• No agent observation becomes truth silently.
• No connector/tool/model output bypasses Source Package, Claim, audit, or governance when it affects memory.
• No package/export is written outside the owning workspace/Node projection unless it is a receiver-level export job.

When to Use This Skill

Activate when the user says or implies:

• "I need persistent context across sessions"
• "My agent should remember what happened last week"
• "I want a knowledge base the whole team can query"
• "Build me a second brain / company wiki"
• "I need memory that survives conversation resets"
• "My agent needs to know who owns X / what Y decided"
• "I want to search all our documents semantically"
• "I want RAG with citations I can trust"
• "Multi-tenant / workspace-isolated knowledge"
• "Help me organize a messy company or personal workspace"
• "My agent needs authorized context before doing work"
• "Turn repeated work into workflows or skills"
• "Connect tools, CLIs, MCP servers, or scripts without bypassing governance"

Core Capabilities

1. Workspace / Topology

Create an organization/workspace, define Nodes, attach aliases, set relationships, and keep projects as one Node type inside a workspace.

mix optimal.setup company-os --name "Company OS"
mix optimal.initiate company-os --name "Company OS" --dump setup.md
mix optimal.topology --workspace default:company-os

2. Source-First Memory Core

Preserve source evidence, extract Claims, review/promote Facts, build Memory Objects, and keep derivation lineage.

# Ingest a workspace projection or source dump
mix optimal.ingest_workspace sample-workspace

# Ask through governed retrieval
mix optimal.rag "what changed before the weekly review?"

Truth lifecycle:

Source Package -> Signal -> Claim -> Fact -> Memory Object

3. Retrieval / Context Packages

Retrieve scoped context with evidence links and authorization metadata.

# Keyword + semantic search
GET /api/search?q=pricing+negotiation&workspace=sales

# Contextual answer
POST /api/rag  {"query": "what's the pricing decision?", "workspace": "sales", "format": "markdown"}

# Grep-style inspection
GET /api/grep?q=pricing&workspace=sales&intent=record_fact&scale=paragraph

4. Agent Work Loops

Agents should load a Context Package, work inside an Active Memory Pool, call governed tools, record observations, and promote only reviewed knowledge.

Task -> Context Package -> Active Memory Pool -> Tool/model calls
     -> Observations -> pending Claims -> reviewed Facts

5. Projections And Packages

Markdown/wiki/API/app views are projections. Packages are receiver/channel bundles, usually owned by a Node, such as proposals, contracts, SOP bundles, requirements packets, reports, or handoff bundles.

Quick Integration Examples

TypeScript — Vercel AI SDK

import Anthropic from '@anthropic-ai/sdk';

const ENGINE = process.env.OPTIMAL_ENGINE_URL ?? 'http://localhost:4200';

async function getContext(query: string, workspace: string): Promise<string> {
  const res = await fetch(`${ENGINE}/api/rag`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, workspace, format: 'claude', bandwidth: 'medium' }),
  });
  const data = await res.json() as { answer?: string; context?: string };
  return data.answer ?? data.context ?? '';
}

// Use with Vercel AI SDK
import { streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

export async function POST(req: Request) {
  const { messages, workspace = 'default' } = await req.json();
  const lastMessage = messages[messages.length - 1].content as string;
  const memory = await getContext(lastMessage, workspace);

  return streamText({
    model: anthropic('claude-opus-4-5'),
    system: `You have access to organizational memory:\n\n${memory}`,
    messages,
  }).toDataStreamResponse();
}

Python — OpenAI Agents SDK

import os, requests
from agents import Agent, Runner, function_tool

ENGINE = os.getenv("OPTIMAL_ENGINE_URL", "http://localhost:4200")

@function_tool
def recall(query: str, workspace: str = "default") -> str:
    """Retrieve organizational memory for a query."""
    r = requests.post(f"{ENGINE}/api/rag", json={
        "query": query,
        "workspace": workspace,
        "format": "markdown",
        "bandwidth": "medium",
    })
    r.raise_for_status()
    return r.json().get("answer", "")

agent = Agent(
    name="Company Brain",
    instructions="You are a company assistant. Use recall() before answering any question about company decisions, people, or projects.",
    tools=[recall],
)

result = Runner.run_sync(agent, "What did Alice decide about Q4 pricing?")
print(result.final_output)

MCP — Claude Desktop / Cursor / Windsurf

{
  "mcpServers": {
    "optimal-engine": {
      "command": "npx",
      "args": ["-y", "@optimal-engine/mcp-server"],
      "env": {
        "OPTIMAL_ENGINE_URL": "http://localhost:4200",
        "OPTIMAL_WORKSPACE": "default"
      }
    }
  }
}

curl — raw HTTP

ENGINE=http://localhost:4200

# Ask the wiki
curl -s -X POST $ENGINE/api/rag \
  -H 'Content-Type: application/json' \
  -d '{"query":"current pricing strategy","workspace":"sales","format":"markdown"}' \
  | jq '.answer'

# Store a memory
curl -s -X POST $ENGINE/api/memory \
  -H 'Content-Type: application/json' \
  -d '{"content":"Alice confirmed $2K/seat pricing on 2026-04-28","workspace":"sales"}' \
  | jq '.id'

# Recall who owns something
curl -s "$ENGINE/api/recall/who?topic=pricing&workspace=sales" | jq '.answer'

Key Concepts Cheat Sheet

References