passepartout/README.org

OpenCortex: The Conductor of your Life Stack

• The Problem with Current AI Agents
• The Vision: A Modern, Homoiconic Memex
  • 1. Org-mode: The Universal Language
  • 2. Common Lisp: The Engine of Self-Modification
  • 3. The Probabilistic-Deterministic Loop
• Architecture: Thin Harness, Fat Skills
  • The Minimalist Harness
  • Literate, Single-File Skills
• Quick Start (The Zero-to-One Experience)
• The Evolutionary Roadmap (v0.1.0 to v1.0.0+)
  • v0.1.0: The Autonomous Foundation (Current Release)
  • v1.0.0 (Phase 2.5): The Verified Wrapper (Current Target)

opencortex is a minimalist, extensible AI agent framework designed to manage and continuously organize your personal knowledge base. It transforms a static collection of plaintext notes into a live, programmable Memex—an automated, personalized memory system where humans and AI collaborate in the exact same workspace.

The Problem with Current AI Agents

The current ecosystem of AI agents (typically built in Python or TypeScript) is overwhelmingly built on architectural choices that prioritize rapid prototyping over long-term reliability, security, and self-modification:

1. The Format Trap (Markdown & JSON): Most agents force a painful translation layer. Humans write in Markdown, which lacks a strict Abstract Syntax Tree (AST). Machines output JSON, which is hostile for human note-taking. The result is a fractured workspace where the agent's memory and the human's memory are incompatible.
2. The Language Trap (Python & TypeScript): Poorly suited for an agent that needs to safely read, write, and execute its own code at runtime.
3. The Probabilistic Trap: Almost all modern agents rely entirely on probabilistic reasoning without a rigorous, deterministic layer to formally verify proposals before execution.

The Vision: A Modern, Homoiconic Memex

opencortex abandons these fragile paradigms by returning to first principles and embracing two historically powerful technologies: Org-mode and Common Lisp.

1. Org-mode: The Universal Language

Instead of wrestling with Markdown parsers, opencortex mandates that Org-mode is the native AST for both humans and machines.

2. Common Lisp: The Engine of Self-Modification

Lisp possesses a unique property called Homoiconicity: the primary representation of the program is also a data structure (nested lists). Because Lisp code is Lisp data, it is trivially easy for an AI to manipulate and safely evaluate new tools at runtime.

3. The Probabilistic-Deterministic Loop

opencortex does not let AI models touch your system directly. Instead, it splits cognition into two distinct engines:

• The Probabilistic Engine (Neural/Dynamic): Provides semantic understanding and dynamic reasoning. It utilizes a Dynamic LLM Cascade (OpenRouter, Ollama, Anthropic, etc.) to ensure the agent always has a brain.
• The Deterministic Engine (Logic/Safety): Intercepts proposals and formally verifies them against your security rules (the "Bouncer" pattern) before execution.

Architecture: Thin Harness, Fat Skills

The Minimalist Harness

The Lisp microkernel is a thin, unbreakable harness strictly responsible for:

1. The Memory: Maintaining the live graph of your Memex in RAM.
2. The Unified Envelope: A protocol-agnostic communication layer (TUI, CLI, Signal, Telegram).
3. The Metabolic Cycle: Moving signals through the Perceive -> Reason -> Act pipeline.

Literate, Single-File Skills

In opencortex, a Skill is simply a single .org file containing documentation, AI instructions, and deterministic Lisp code.

Quick Start (The Zero-to-One Experience)

OpenCortex can be installed and booted with a single command.

curl -sSL https://raw.githubusercontent.com/gharbeia/opencortex/main/opencortex.sh | bash -s -- setup

After installation, the background daemon is automatically awakened. Start interacting immediately:

# Start the rich Terminal UI
opencortex tui

# Or use the raw CLI
opencortex cli

The Evolutionary Roadmap (v0.1.0 to v1.0.0+)

v0.1.0: The Autonomous Foundation (Current Release)

Initial MVP establishing a secure, auditable Lisp kernel. Features a robust metabolic pipeline, mandatory skill enforcement, and background distillation (The Scribe).

v1.0.0 (Phase 2.5): The Verified Wrapper (Current Target)

Achieving feature parity with SOTA autonomous agents but with Lisp-grade mathematical security.

• The Tools are External: bash shell, headless browser (Playwright), and standard file I/O.
• The Safety is Internal: The Bouncer and Formal Verification gates mathematically prove actions are safe.