diff --git a/CONTRIBUTING.org b/CONTRIBUTING.org index f276af1..77b518f 100644 --- a/CONTRIBUTING.org +++ b/CONTRIBUTING.org @@ -31,7 +31,7 @@ Example Registration: #+end_src * The Unified Envelope (Communication Protocol) -All inter-process communication occurs via the Unified Envelope. Do not use legacy specific types like `:CHAT`. +All inter-process communication occurs via the Unified Envelope. - Always use semantic types: `:REQUEST`, `:EVENT`, `:RESPONSE`, `:STATUS`, `:LOG`. - Include routing metadata in the `:META` block (e.g., `(:SOURCE :TUI)`). - Ensure generated `:REQUEST` messages include a mandatory `:TARGET` field. diff --git a/README.org b/README.org index b5efb0a..c761ffc 100644 --- a/README.org +++ b/README.org @@ -43,15 +43,16 @@ The Lisp microkernel is a thin, unbreakable harness strictly responsible for: In opencortex, a Skill is simply a *single .org file* containing everything: the documentation, the AI instructions, and the deterministic Lisp code. When the system boots, it compiles these skills directly into the live Lisp image. ** The Anatomy: Three Data Stores -1. *The Linguistic Substrate (Plaintext Files):* The human-readable Source of Truth on your hard drive. -2. *The Lisp Memory (RAM):* The "Active Brain," a live, threaded graph of Lisp objects representing your Memex. -3. *The Telemetry Store (External):* A high-volume database for sub-deterministic sensory data. +1. *The Linguistic Substrate (The Memex):* A collection of plain-text Org-mode files on your local disk. This is the ultimate Source of Truth. Because it is plaintext, it is human-editable, version-controllable, and platform-independent. In OpenCortex, your notes, tasks, and code aren't just "data"—they are the agent's actual configuration and memory. +2. *The Lisp Memory (RAM):* A live, homoiconic graph of Lisp objects. Upon boot, OpenCortex ingests your Memex files and transforms them into a high-performance in-memory graph. + - *Why RAM?* Traditional databases require expensive joins and context-switching to traverse complex associations. By keeping the entire graph in RAM, OpenCortex can perform semantic traversals and logical inferences at native Lisp speeds. + - *Homoiconicity:* Since the program (Lisp) and the data (Lisp objects) share the same structure, the agent can manipulate its own memory as easily as it manipulates its own code. +3. *The Telemetry Store (External):* A high-volume database for sub-deterministic sensory data (system metrics, sensor logs) that the agent monitors and distills into Org-mode "insights." ** The Psychology: The 2x2 Cognitive Matrix -| | Probabilistic (Neural/Intuitive) | Deterministic (Deterministic/Logical) | -| :--- | :--- | :--- | -| Foreground (Active) | *The Interface:* Fast AI models for conversation and multimodal ingestion. | *The Steward:* Lisp engine that safely retrieves data and enforces security rules. | -| Background (Passive) | *The Editor:* Deep AI models finding patterns while you sleep. | *The Librarian:* Lisp engine maintaining data integrity and filing notes. | +| | Probabilistic (Neural/Intuitive) | Deterministic (Deterministic/Logical) | +| Foreground (Active) | *The Interface:* Fast AI models for conversation and multimodal ingestion. | *The Steward:* Lisp engine that safely retrieves data and enforces security rules. | +| Background (Passive) | *The Editor:* Deep AI models finding patterns while you sleep. | *The Librarian:* Lisp engine maintaining data integrity and filing notes. | ** The Physiology: Five Core Processes 1. *Perception:* Automatically vectorizes your input and sets the "Foreground Focus." @@ -81,17 +82,26 @@ opencortex cli * The Evolutionary Roadmap ** v0.1.0: The Autonomous Foundation (Current Release) -The initial MVP establishing a secure, auditable Lisp kernel. Features a robust metabolic pipeline, mandatory skill enforcement, and background distillation. +The initial MVP establishing a secure, auditable Lisp kernel. Features a robust metabolic pipeline, mandatory skill enforcement, and background distillation (The Scribe). -** v1.0.0: The Verified Wrapper (Current Target) +** v0.2.0: Interactive Refinement & Self-Editing +Elevating the user interface and granting the kernel the physical capability to edit its own source code. +- *Autonomous Self-Editing:* Implementation of File I/O cognitive tools (`:read-file`, `:write-file`, `:replace-string`) and whitelisting `emacs` for autonomous `org-babel-tangle` operations. +- *High-Fidelity TUI:* Transitioning to a rich, native Lisp TUI via `croatoan` with scrollable history and multi-line input. +- *Skill Hot-Reloading:* A dedicated mechanism to safely swap compiled Lisp code into the live image without severing client connections. +- *Automated PATH Handling:* Zero-config installation where the `opencortex` binary is automatically injected into the user's environment. + +** v1.0.0: The Verified Wrapper (Next Major Target) Achieving feature parity with SOTA autonomous agents but with Lisp-grade mathematical security. -- *The Tools are External:* Standard 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. +- *The Tools are External:* Standard bash shell, headless browser (via Playwright), and standard file I/O. +- *The Safety is Internal:* The Bouncer and Formal Verification gates mathematically prove actions are safe before they touch the OS. ** v2.0.0: The Cannibalization -Replacing string-based tool wrappers with native Lisp data structures. -- *Cannibalizing the Browser:* Ingesting the DOM as a native Lisp AST. -- *Cannibalizing the Shell:* Moving from bash execution to native OS API bindings. +Replacing string-based tool wrappers with native Lisp data structures to eliminate LLM fragility. +- *Cannibalizing the Browser:* Ingesting the DOM as a native Lisp AST rather than fighting with Playwright scripts. +- *Cannibalizing the Shell:* Moving from bash execution to native OS API bindings. Emacs becomes a viewport for the live AST, not a master. ** v3.0.0: True Symbolic Determinism The great inversion. The Lisp engine takes the wheel, and the LLM is relegated to a mere semantic translation layer for the messy outside world. +- *Deterministic Planning:* The core reasoning engine uses formal logic and graph traversal to plan and execute workflows. +- *Self-Correcting Syntax:* The Lisp engine catches and repairs hallucinated syntax errors without consulting the LLM. diff --git a/USER_MANUAL.org b/USER_MANUAL.org index d1790c1..4f4ad21 100644 --- a/USER_MANUAL.org +++ b/USER_MANUAL.org @@ -6,51 +6,46 @@ * Introduction Welcome to OpenCortex v0.1.0 (The Autonomous Foundation). OpenCortex is a neurosymbolic AI agent and a Lisp Machine operating system designed to autonomously maintain your Memex (knowledge base) and interact with you via multiple, equal-citizen interfaces. -* Installation -OpenCortex is bootstrapped via a single shell script. +* Quick Start Installation +OpenCortex can be installed and booted with a single command: #+begin_src bash -git clone ssh://git@10.10.10.201:2222/amr/opencortex.git -cd opencortex -./opencortex.sh setup +curl -sSL https://raw.githubusercontent.com/gharbeia/opencortex/main/opencortex.sh | bash -s -- setup #+end_src -This process will install SBCL, Quicklisp, and prompt you to create a `.env` file for your API keys. +This command will: +1. Bootstrap the OpenCortex repository into \`~/.opencortex\`. +2. Install system dependencies (SBCL, Quicklisp, etc.). +3. Interactively guide you through the initial configuration. +4. Tangle the literate source code. +5. Awaken the background daemon. * Configuration -The system is configured via a `.env` file in the project root. Essential variables include: +The system is configured via a \`.env\` file in the project root. Key variables include: -- `OPENROUTER_API_KEY`: Your LLM provider key. -- `PROVIDER_CASCADE`: The fallback order for LLM providers (e.g., `openrouter,ollama,anthropic`). -- `MEMEX_DIR`: The absolute path to your knowledge base (defaults to `~/memex`). +- \`LLM_API_KEY\`: Your provider key (e.g., \`OPENROUTER_API_KEY\`, \`OPENAI_API_KEY\`). +- \`PROVIDER_CASCADE\`: The fallback order for LLM providers (e.g., \`openrouter,ollama,anthropic\`). +- \`MEMEX_DIR\`: The absolute path to your knowledge base (defaults to \`~/memex\`). * Interacting with OpenCortex -Because of the Unified Envelope Architecture, the kernel treats all clients as interchangeable. You must first boot the background daemon: - -#+begin_src bash -./opencortex.sh --boot & -#+end_src +Once the daemon is running, you can connect via any supported client. ** Terminal User Interface (TUI) -For a rich, split-pane terminal experience: +For a rich terminal experience with history and background worker status: #+begin_src bash -./opencortex.sh tui +opencortex tui #+end_src ** Command Line Interface (CLI) For raw, pipe-friendly interaction: #+begin_src bash -./opencortex.sh cli +opencortex cli #+end_src -** Emacs Integration -OpenCortex functions as your "foveal vision" inside Emacs. -1. Ensure `org-agent.el` is loaded. -2. Run `M-x opencortex-connect`. -3. Interact via the `*opencortex-chat*` buffer. - * The Memex Structure -OpenCortex assumes a local folder structure representing your "Memex". -- Core memories and identities are mapped to Org-mode files. -- The `Scribe` background worker distills chronological logs into structured Zettelkasten notes. -- The `Gardener` continuously repairs broken links and flags orphaned nodes. \ No newline at end of file +OpenCortex manages a local folder structure representing your "Memex". +- *Nodes:* Every Org-mode headline is a "node" in the agent's memory graph. +- *Source of Truth:* Plaintext files are the definitive state. +- *Autonomous Workers:* + - The \`Scribe\` distills chronological logs into structured Zettelkasten notes. + - The \`Gardener\` repairs links and flags orphaned nodes. diff --git a/docs/deployment.org b/docs/deployment.org deleted file mode 100644 index f2a3119..0000000 --- a/docs/deployment.org +++ /dev/null @@ -1,36 +0,0 @@ -#+TITLE: Deployment Guide: Containerized OpenCortex -#+AUTHOR: Amr -#+DATE: [2026-04-11 Sat] -#+FILETAGS: :deployment:docker:infrastructure: - -* Overview -The ~opencortex~ is designed to run within a Docker container to ensure system dependencies (SBCL, Quicklisp, signal-cli) are perfectly matched across different host environments. - -* Prerequisites -- Docker Engine -- Docker Compose -- A valid ~.env~ file in the ~projects/opencortex/~ directory (refer to ~.env.example~). - -* Quick Start -** 1. Build and Start -From the ~projects/opencortex/~ directory: -#+begin_src bash -docker-compose up --build -d -#+end_src - -** 2. Check Logs -#+begin_src bash -docker-compose logs -f -#+end_src - -* Volume Mapping -The ~docker-compose.yml~ file automatically mounts your host's ~memex~ directory to ~/memex~ inside the container. This allows the agent to: -1. Read/Write to your Zettelkasten and GTD files. -2. Maintain its local state (Memory, snapshots). - -* Troubleshooting -** signal-cli Identity -If using the Signal gateway, ensure you have registered your number via the host's ~signal-cli~ or within the container. The state is preserved in the ~signal-state~ Docker volume. - -** Re-loading Skills -The container pre-caches dependencies during the build. If you modify core Lisp logic, you must rebuild the image (~--build~). If you only modify ~.org~ skills in your memex, the agent can reload them dynamically if they are part of the startup scan. diff --git a/docs/quickstart.org b/docs/quickstart.org deleted file mode 100644 index 942bf2a..0000000 --- a/docs/quickstart.org +++ /dev/null @@ -1,55 +0,0 @@ -#+TITLE: Quickstart Guide: The Road to Autonomousty -#+AUTHOR: Amr -#+DATE: [2026-04-11 Sat] -#+FILETAGS: :quickstart:onboarding:guide: - -* 1. Introduction -Welcome to ~opencortex~, the "Executive Soul" of your personal OS. This guide will help you set up and interact with your first probabilistic-deterministic agent. - -* 2. Prerequisites -Before launching the harness, ensure your host environment has: -- **Docker & Docker Compose**: The primary enclosure for the Lisp Machine. -- **LLM API Keys**: At least one key for Gemini, Anthropic, or OpenAI. -- **Emacs (Optional)**: For the full literate experience via ~opencortex.el~. - -* 3. Installation & Enclosure -** Step 1: Clone the Autonomousty -#+begin_src bash -git clone https://github.com/amr/opencortex.git -cd opencortex -#+end_src - -** Step 2: Secret Configuration -Copy the example environment file and add your keys. -#+begin_src bash -cp .env.example .env -# Edit .env with your favorite editor -#+end_src - -** Step 3: Launch the Image -This will build the SBCL environment and start the Micro-Loader. -#+begin_src bash -docker-compose up --build -d -#+end_src - -* 4. Interaction Gateways -Once the harness is "Ready", you can interact with it via multiple sensors. - -** Gateway A: Emacs (communication protocol) -If you have configured the ~opencortex~ package in Emacs: -1. Open a chat buffer: ~M-x opencortex-chat-open~. -2. Send: "Are you online, agent?" - -** Gateway B: External Sensors -If you enabled Signal or Telegram in ~.env~, send a message directly to your bot. - -* 5. Verification (The Chaos Check) -To ensure the harness is fully healthy, check the logs for the Micro-Loader summary: -#+begin_src bash -docker-compose logs -f opencortex -#+end_src -Look for: ~LOADER: Boot Complete. [Ready: 34] [Failed: 0]~ - -* 6. Next Steps -- **Extend the Brain**: Read the [[file:skill-creation.org][Skill Creation Guide]] to add custom Lisp skills. -- **Deep Dive**: Explore the [[file:../literate/][literate/]] directory to understand the harness's architecture. diff --git a/scripts/onboard-baremetal.sh b/scripts/onboard-baremetal.sh deleted file mode 100755 index 91bc040..0000000 --- a/scripts/onboard-baremetal.sh +++ /dev/null @@ -1,59 +0,0 @@ -#!/bin/bash -# OpenCortex Final-Mile Installer -RED='\033[0;31m'; GREEN='\033[0;32m'; BLUE='\033[0;34m'; YELLOW='\033[0;33m'; NC='\033[0m' -echo -e "${BLUE}=== OpenCortex: Baremetal Power-User Setup ===${NC}" - -prompt_user() { - local prompt="$1" - local default="$2" - local var_name="$3" - local result="" - echo -n -e "${YELLOW}$prompt (default: $default): ${NC}" >&2 - if read -t 5 result; then :; else result="$default"; echo -e "${BLUE} [Auto-Selected: $default]${NC}" >&2; fi - val=${result:-$default} - eval "$var_name=\"$val\"" -} - -# 1. Dependencies -if ! command -v sbcl >/dev/null 2>&1; then - echo -e "${BLUE}Installing dependencies...${NC}" - sudo apt-get update && sudo apt-get install -y sbcl emacs git curl socat || true -fi - -# 2. Quicklisp -if [ ! -d "$HOME/quicklisp" ]; then - curl -O https://beta.quicklisp.org/quicklisp.lisp - sbcl --non-interactive --load quicklisp.lisp --eval "(quicklisp-quickstart:install)" --eval "(ql-util:without-prompting (ql:add-to-init-file))" - rm quicklisp.lisp -fi - -# 3. Tangling -echo -e "${BLUE}Tangling source files...${NC}" -mkdir -p src -for f in literate/*.org; do - echo " - Tangling $f" - emacs --batch --eval "(require 'org)" --eval "(org-babel-tangle-file \"$f\")" >/dev/null 2>&1 -done - -# 4. Config -if [ ! -f .env ]; then cp .env.example .env; fi -prompt_user "What is your name?" "User" "USER_NAME" -prompt_user "What shall we name your Assistant?" "OpenCortex" "AGENT_NAME" -prompt_user "Select provider (1:Gemini, 2:OpenRouter)" "1" "LLM_CHOICE" - -sed -i "s/MEMEX_USER=.*/MEMEX_USER=\"$USER_NAME\"/g" .env -sed -i "s/MEMEX_ASSISTANT=.*/MEMEX_ASSISTANT=\"$AGENT_NAME\"/g" .env - -# 5. Path Alignment -INSTALL_DIR="$(cd "$(dirname "$0")/.." && pwd)" -sed -i "s|MEMEX_DIR=.*|MEMEX_DIR=\"$(dirname "$INSTALL_DIR")\"|g" .env -sed -i "s|SKILLS_DIR=.*|SKILLS_DIR=\"$INSTALL_DIR/skills\"|g" .env - -mkdir -p "$HOME/.local/bin" -ln -sf "$INSTALL_DIR/opencortex.sh" "$HOME/.local/bin/opencortex" -echo -e "${GREEN}✓ Installed 'opencortex' command to ~/.local/bin${NC}" - -echo -e "\n${GREEN}==============================================${NC}" -echo -e " OpenCortex Installation Complete! " -echo -e "==============================================${NC}" -echo -e "To start: opencortex" diff --git a/scripts/org-agent-chat.sh b/scripts/org-agent-chat.sh deleted file mode 100755 index eee422a..0000000 --- a/scripts/org-agent-chat.sh +++ /dev/null @@ -1,20 +0,0 @@ -#!/bin/bash -# opencortex-chat: The terminal mouthpiece for the Autonomous Brain. -PORT=9105 -HOST=${1:-localhost} - -# Check for socat (preferred) -if command -v socat >/dev/null 2>&1; then - # Use socat with READLINE for history and arrow-key support. - # It establishes a persistent bidirectional connection. - socat READLINE,history=$HOME/.org_agent_history TCP:$HOST:$PORT -else - # Fallback to nc (netcat) for a single-shot connection if socat is missing. - # Note: This is less robust for agents with long-thinking times. - echo "WARNING: socat not found. Falling back to nc (no line-editing support)." - while true; do - read -p "User: " MESSAGE - if [ -z "$MESSAGE" ]; then continue; fi - echo "$MESSAGE" | nc -N $HOST $PORT - done -fi diff --git a/src/communication-validator.lisp b/src/communication-validator.lisp index 66ff0d8..329df45 100644 --- a/src/communication-validator.lisp +++ b/src/communication-validator.lisp @@ -6,7 +6,7 @@ (error "Communication Protocol Schema Error: Message must be a property list (got ~s)" (type-of msg))) (let ((type (let ((raw (proto-get msg :type))) (if (keywordp raw) (intern (string-upcase (string raw)) :keyword) raw)))) - (unless (member type '(:REQUEST :EVENT :RESPONSE :LOG :STATUS :CHAT)) + (unless (member type '(:REQUEST :EVENT :RESPONSE :LOG :STATUS)) (progn (harness-log "REJECTED MSG: ~s" msg) (error "Communication Protocol Schema Error: Invalid message type '~a'" type))) (case type diff --git a/src/org-agent.el b/src/opencortex.el similarity index 100% rename from src/org-agent.el rename to src/opencortex.el