DOCS: Refine roadmap and expand Anatomy. RENAM: Rename Emacs package to opencortex.el. CLEAN: Purge legacy scripts.
Some checks failed
Deploy-Agent-V15-Stdin / JOB-V15-STDIN (push) Failing after 4s
Some checks failed
Deploy-Agent-V15-Stdin / JOB-V15-STDIN (push) Failing after 4s
This commit is contained in:
@@ -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.
|
||||
|
||||
38
README.org
38
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.
|
||||
|
||||
@@ -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.
|
||||
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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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"
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user