amr/passepartout
1
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

REFAC: Global rename of org-agent to opencortex

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-14 12:10:11 -04:00
parent b58b780a44
commit 849c078c37
95 changed files with 662 additions and 642 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/deployment.org
View File

@@ -1,19 +1,19 @@
#+TITLE: Deployment Guide: Containerized Org-Agent
#+TITLE: Deployment Guide: Containerized OpenCortex
#+AUTHOR: Amr
#+DATE: [2026-04-11 Sat]
#+FILETAGS: :deployment:docker:infrastructure:
* Overview
The ~org-agent~ is designed to run within a Docker container to ensure system dependencies (SBCL, Quicklisp, signal-cli) are perfectly matched across different host environments.
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/org-agent/~ directory (refer to ~.env.example~).
- A valid ~.env~ file in the ~projects/opencortex/~ directory (refer to ~.env.example~).
* Quick Start
** 1. Build and Start
From the ~projects/org-agent/~ directory:
From the ~projects/opencortex/~ directory:
#+begin_src bash
docker-compose up --build -d
#+end_src

4
docs/marketing-v0.1.0.org
View File

@@ -34,10 +34,10 @@ The narrative: "An autonomous AI agent that doesn't just chat, but lives nativel
- *Hook:* "Own your brain. An AI agent that runs locally on your Markdown/Org files with mathematical security gates."
3. **The AI / Autonomous Agent Hackers:**
- *Channels:* Hacker News (Show HN), Twitter/X (AI tech Twitter).
- *Hook:* "Tired of fragile Python/Playwright agent wrappers? org-agent uses a deterministic Lisp microkernel to formally verify LLM actions before execution."
- *Hook:* "Tired of fragile Python/Playwright agent wrappers? opencortex uses a deterministic Lisp microkernel to formally verify LLM actions before execution."
** Launch Materials
- **Demo Video (2 minutes):** Show the one-liner install, the agent running the `Scribe` skill in the background, and the user querying it via `org-agent chat`.
- **Demo Video (2 minutes):** Show the one-liner install, the agent running the `Scribe` skill in the background, and the user querying it via `opencortex chat`.
- **Blog Post / Essay:** "Why we built an Autonomous Agent in Common Lisp." Discuss the fragility of current SOTA (Devin/SWE-agent) and the necessity of the Bouncer/Policy gates.
* 4. Post-Launch Community Engagement

14
docs/quickstart.org
View File

@@ -4,19 +4,19 @@
#+FILETAGS: :quickstart:onboarding:guide:
* 1. Introduction
Welcome to ~org-agent~, the "Executive Soul" of your personal OS. This guide will help you set up and interact with your first probabilistic-deterministic agent.
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 ~org-agent.el~.
- **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/org-agent.git
cd org-agent
git clone https://github.com/amr/opencortex.git
cd opencortex
#+end_src
** Step 2: Secret Configuration
@@ -36,8 +36,8 @@ docker-compose up --build -d
Once the harness is "Ready", you can interact with it via multiple sensors.
** Gateway A: Emacs (communication protocol)
If you have configured the ~org-agent~ package in Emacs:
1. Open a chat buffer: ~M-x org-agent-chat-open~.
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
@@ -46,7 +46,7 @@ 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 org-agent
docker-compose logs -f opencortex
#+end_src
Look for: ~LOADER: Boot Complete. [Ready: 34] [Failed: 0]~

6
docs/rca/rca-boot-sequence.org
View File

@@ -19,9 +19,9 @@ Skills that depended on functions or variables from other skills would randomly
** Symptoms
Variables or functions with the same name in different skills would silently overwrite each other, causing unpredictable behavior.
** Root Cause
All skills were being evaluated directly into the `org-agent` package.
All skills were being evaluated directly into the `opencortex` package.
** Resolution
**Package-Based Jailing:** Each skill is now evaluated within its own dedicated, shadowed package (e.g., `ORG-AGENT.SKILLS.ORG-SKILL-CHAT`). This ensures logical isolation while still allowing access to kernel exports.
**Package-Based Jailing:** Each skill is now evaluated within its own dedicated, shadowed package (e.g., `OPENCORTEX.SKILLS.ORG-SKILL-CHAT`). This ensures logical isolation while still allowing access to kernel exports.
* 3. Issue: Boot Stall (The Hanging Skill)
** Symptoms
@@ -31,7 +31,7 @@ Skill loading was strictly synchronous and blocking on the main thread.
** Resolution
**Execution Timeouts:** Implemented `load-skill-with-timeout`, which wraps the loader in a monitored thread. If a skill takes longer than 5 seconds to initialize, the loader terminates the thread, jails the failure, and continues with the rest of the boot sequence.
* 4. org-agent Mandate Alignment
* 4. opencortex Mandate Alignment
** Evolutionary Kernel
The boot sequence is now a verifiable, mathematical process rather than a side-effect of filesystem organization.
** Literate Granularity

4
docs/rca/rca-formal-verification.org
View File

@@ -17,7 +17,7 @@ System failed to load with `Package STR does not exist`.
** Root Cause
Incorrect assumption about the Quicklisp system name vs. the package name. The library is `cl-str` but the Quicklisp system is `str` and the package is `str`.
** Resolution
1. Updated `org-agent.asd` to depend on `:str`.
1. Updated `opencortex.asd` to depend on `:str`.
2. Updated all source code and literate notes to use the `str:` prefix.
3. Verified via explicit `ql:quickload` in the test runner.
@@ -25,7 +25,7 @@ Incorrect assumption about the Quicklisp system name vs. the package name. The l
- **Path Confinement:** Deterministically proves that any file operation or absolute path in a shell command is strictly within the `/home/user/memex` root.
- **No Network Exfiltration:** Prevents the shell from invoking common exfiltration tools (`nc`, `ssh`, etc.) by inspecting the parsed command structure.
* 4. org-agent Mandate Alignment
* 4. opencortex Mandate Alignment
** Soundness over Heuristics
By moving to formal invariants, we have moved from "blacklisting bad things" to "proving safety." Any action that cannot be proven to satisfy all invariants is denied by default.
** Literate Granularity

4
docs/rca/rca-gateway-matrix.org
View File

@@ -3,7 +3,7 @@
#+FILETAGS: :rca:gateway:matrix:chat:autonomy:
* Executive Summary
Successfully implemented the third and final external communication channel (Matrix) for Org-agent v1.0. Resolved integration issues related to case-sensitivity in JSON keys and strict header requirements in `dexador`.
Successfully implemented the third and final external communication channel (Matrix) for OpenCortex v1.0. Resolved integration issues related to case-sensitivity in JSON keys and strict header requirements in `dexador`.
* 1. Issue: Symbol Casing in JSON Keys
** Symptoms
@@ -30,7 +30,7 @@ I was passing a single string or an incorrectly nested list where `dexador` expe
Standardized all gateway HTTP calls to use proper alist nesting for headers.
* 4. Completion: Communication Track
With Telegram, Signal, and Matrix gateways now verified and passing tests, the Org-agent has achieved full multi-channel parity.
With Telegram, Signal, and Matrix gateways now verified and passing tests, the OpenCortex has achieved full multi-channel parity.
- **Telegram:** Polling via Bot API.
- **Signal:** Wrapping `signal-cli`.
- **Matrix:** Polling via `/sync` Client API.

2
docs/rca/rca-gateway-signal.org
View File

@@ -22,7 +22,7 @@ Unlike Telegram's HTTP API, Signal requires a local binary (`signal-cli`).
** Security
The system uses the pre-configured Signal account `+13322690326` discovered in the user's memex.
* 3. Alignment with org-agent Mandates
* 3. Alignment with opencortex Mandates
** Literate Granularity
Strictly adhered to the "one definition per block" mandate throughout the new `org-skill-gateway-signal.org` file.
** Verification

6
docs/rca/rca-gateway-telegram.org
View File

@@ -9,10 +9,10 @@ Successfully implemented the first external communication channel (Telegram) and
** Symptoms
During compilation, `gateway-telegram.lisp` failed with `UNDEFINED-FUNCTION` for `register-actuator` and `harness-log`.
** Root Cause
Poorly scoped foundational functions. These were defined in `core.lisp` (the loop orchestrator), which was loaded *after* the gateways in `org-agent.asd`. This created a "Circular Intention" where the gateways needed the harness to exist before the harness could load the gateways.
Poorly scoped foundational functions. These were defined in `core.lisp` (the loop orchestrator), which was loaded *after* the gateways in `opencortex.asd`. This created a "Circular Intention" where the gateways needed the harness to exist before the harness could load the gateways.
** Resolution
1. **Relocation:** Moved `*actuator-registry*` and `register-actuator` to `communication.lisp` (the foundation).
2. **Reordering:** Adjusted `org-agent.asd` to load `core.lisp` (containing the stimulus loop) immediately after the deterministic gates but before the physical sensors (gateways).
2. **Reordering:** Adjusted `opencortex.asd` to load `core.lisp` (containing the stimulus loop) immediately after the deterministic gates but before the physical sensors (gateways).
* 2. Issue: Hardcoded Chat UI
** Symptoms
@@ -32,7 +32,7 @@ Misinterpretation of the `UIOP` API. `setenv` is not a standard export; the port
** Resolution
Updated all test environment setup to use the `setf` accessor.
* 4. org-agent Mandate Alignment
* 4. opencortex Mandate Alignment
** Autonomous Boundary
By moving the Telegram API logic to a user-space skill and communicating with the core via standard stimuli, we have respected the microkernel boundary.
** Homoiconic Memory

10
docs/rca/rca-infrastructure-docker.org
View File

@@ -3,14 +3,14 @@
#+FILETAGS: :rca:docker:deployment:infrastructure:autonomy:
* Executive Summary
Standardized the `org-agent` execution environment by creating a production-grade Docker infrastructure. This ensures that all system dependencies, including the Lisp runtime and external binaries like `signal-cli`, are locked down and portable.
Standardized the `opencortex` execution environment by creating a production-grade Docker infrastructure. This ensures that all system dependencies, including the Lisp runtime and external binaries like `signal-cli`, are locked down and portable.
* 1. Architectural Intent: The "Clean Room" Model
** Problem
The `org-agent` was relying on host-local binaries (`sbcl`, `signal-cli`) and manually configured Quicklisp dists. This made deployment to other environments (e.g., a VPS or a Autonomous Home Server) fragile and prone to version drift.
The `opencortex` was relying on host-local binaries (`sbcl`, `signal-cli`) and manually configured Quicklisp dists. This made deployment to other environments (e.g., a VPS or a Autonomous Home Server) fragile and prone to version drift.
** Solution
1. **Dockerfile:** Created a multi-step build process that installs Debian Bookworm, SBCL, Java, and `signal-cli 0.14.0`.
2. **Pre-Caching:** The build process triggers a `ql:quickload` of the `:org-agent` system, ensuring all Lisp dependencies are pre-downloaded and stored in the image layer, drastically reducing startup time.
2. **Pre-Caching:** The build process triggers a `ql:quickload` of the `:opencortex` system, ensuring all Lisp dependencies are pre-downloaded and stored in the image layer, drastically reducing startup time.
3. **Compose Orchestration:** Standardized the runtime via `docker-compose.yml`, which handles volume mounting of the user's `memex` directory and injection of `.env` secrets.
* 2. Volume Mapping & Persistence
@@ -19,7 +19,7 @@ To maintain the "Autonomous" mandate, the agent's code is isolated, but its memo
- **Mapping:** `../..` (host) -> `/memex` (container).
- **State:** Created a named Docker volume `signal-state` to ensure that `signal-cli` identities and cryptographic keys survive container restarts and image updates.
* 3. Alignment with org-agent Mandates
* 3. Alignment with opencortex Mandates
** Evolutionary Completion
By moving to Docker, we have achieved "Evolutionary Completion" for the deployment track. The system is no longer a collection of scripts; it is a deployable appliance.
** Documentation
@@ -27,4 +27,4 @@ A new `Deployment Guide` was added to `docs/deployment.org` to ensure standard o
* 4. Permanent Learnings
- **Lisp Build Layers:** Always push the system to the ASDF registry and quickload during Docker build to bake dependencies into the image.
- **Compose Locality:** Placing the `docker-compose.yml` inside the `projects/org-agent/` folder keeps infrastructure code close to the implementation logic.
- **Compose Locality:** Placing the `docker-compose.yml` inside the `projects/opencortex/` folder keeps infrastructure code close to the implementation logic.

2
docs/rca/rca-lisp-repair-async.org
View File

@@ -22,7 +22,7 @@ Mismatched expectations of signal nesting. The skill expected the code at `(getf
** Resolution
Updated the deterministic logic to correctly traverse the nested signal structure: `(getf (getf context :candidate) :payload)`.
* 3. org-agent Mandate Alignment
* 3. opencortex Mandate Alignment
** Autonomous Boundary
The core is now strictly a parser. Repair is an optional, user-space service.
** Reactive Signal Pipeline

4
docs/rca/rca-playwright-bridge.org
View File

@@ -3,7 +3,7 @@
#+FILETAGS: :rca:intelligence:browsing:automation:autonomy:
* Executive Summary
Successfully implemented a high-fidelity browsing bridge using Playwright and Python. This allows the `org-agent` to interact with modern, JavaScript-rendered web applications that were previously inaccessible via simple HTTP clients.
Successfully implemented a high-fidelity browsing bridge using Playwright and Python. This allows the `opencortex` to interact with modern, JavaScript-rendered web applications that were previously inaccessible via simple HTTP clients.
* 1. Architectural Strategy: The I/O Bridge
** Problem
@@ -28,7 +28,7 @@ Created the `:browser` cognitive tool, which exposes three primary capabilities
- **Extraction:** Targeted text retrieval via CSS selectors.
- **Vision:** Base64-encoded screenshot capture for future multimodal processing.
* 4. org-agent Mandate Alignment
* 4. opencortex Mandate Alignment
** Zero-Bloat (Managed)
While adding Playwright increases the image size, it is a "Complexity Earned" trade-off that dramatically expands the agent's capability frontier.
** Literate Granularity

6
docs/rca/rca-provider-verification.org
View File

@@ -17,9 +17,9 @@ Implemented a robust `get-nested` helper function that safely traverses both nes
** Symptoms
Provider logic was present in the codebase but inaccessible during tests and runtime.
** Root Cause
The `credentials-vault.lisp` and `llm-gateway.lisp` files (consolidated in a previous session) were never added to the `org-agent.asd` system definition. Furthermore, an incorrect loading order caused `UNDEFINED-FUNCTION` errors for `register-probabilistic-backend`.
The `credentials-vault.lisp` and `llm-gateway.lisp` files (consolidated in a previous session) were never added to the `opencortex.asd` system definition. Furthermore, an incorrect loading order caused `UNDEFINED-FUNCTION` errors for `register-probabilistic-backend`.
** Resolution
1. Added both files to `org-agent.asd`.
1. Added both files to `opencortex.asd`.
2. Enforced strict loading order: `probabilistic` (defines registry) -> `credentials-vault` -> `llm-gateway` (uses registry).
* 3. Issue: Credential Key Mismatch
@@ -30,7 +30,7 @@ Gemini requests failed with "API Key missing" even when environment variables we
** Resolution
Updated `vault-get-secret` to map both `:gemini` and `:gemini-api` to the same `GEMINI_API_KEY` environment variable.
* 4. org-agent Mandate Alignment
* 4. opencortex Mandate Alignment
** Invariant Check
- *High-Integrity Memory:* All individual provider tracks are now backed by automated unit tests (`llm-gateway-tests.lisp`).
- *Literate Programming:* Updated `org-skill-llm-gateway.org` to reflect the improved `get-nested` utility.

6
docs/rca/rca-self-fix-loop.org
View File

@@ -22,14 +22,14 @@ Created `self-fix-tests.lisp` which:
** Symptoms
Repeated `LOAD-SYSTEM-DEFINITION-ERROR` and "unmatched close parenthesis" errors during test integration.
** Root Cause
Complexity in the `:components` nesting of `org-agent.asd` led to repeated syntax errors when using automated editing tools. The deep nesting made manual paren counting prone to "off-by-one" errors.
Complexity in the `:components` nesting of `opencortex.asd` led to repeated syntax errors when using automated editing tools. The deep nesting made manual paren counting prone to "off-by-one" errors.
** Resolution
Refactored `org-agent.asd` to use a **Flat Component Structure**.
Refactored `opencortex.asd` to use a **Flat Component Structure**.
- *Before:* `:components ((:module "src" :components (...)))`
- *After:* `:components ((:file "src/package") ...)`
This eliminates unnecessary nesting levels and drastically reduces the surface area for syntax errors.
* 3. org-agent Mandate Alignment
* 3. opencortex Mandate Alignment
** Invariant Check
- *Lisp Machine Autonomousty:* Verification utilized hot-reloading (`load-skill-from-org`) without restarting the SBCL image.
- *Literate Programming:* Updated `org-skill-self-fix.org` to match the finalized `self-fix.lisp` logic.

4
docs/rca/rca-shell-hardening.org
View File

@@ -19,11 +19,11 @@ The `execute-shell-safely` function only checked the first space-delimited word
** Symptoms
`UNDEFINED-FUNCTION EXECUTE-SHELL-SAFELY` during unit tests.
** Root Cause
`src/shell-logic.lisp` was missing an `(in-package :org-agent)` declaration, causing symbols to be defined in the default `COMMON-LISP-USER` package instead of the harness package.
`src/shell-logic.lisp` was missing an `(in-package :opencortex)` declaration, causing symbols to be defined in the default `COMMON-LISP-USER` package instead of the harness package.
** Resolution
Added the `in-package` header to `shell-logic.lisp`.
* 3. org-agent Mandate Alignment
* 3. opencortex Mandate Alignment
** Invariant Check
- *High-Integrity Memory:* The shell actuator is now formally verified with 4 new unit tests covering whitelist enforcement and injection blocking.
- *Literate Programming:* Updated `org-skill-shell-actuator.org` Phase A and Build sections to reflect the hardened logic.

6
docs/rca/rca-task-orchestrator.org
View File

@@ -23,7 +23,7 @@ Selected "Majority Rules" over "First-to-Finish".
- *Pros:* Higher accuracy, mathematically consistent.
- *Cons:* Slower (latency limited by the slowest provider).
** Invariant Alignment
Aligns with org-agent Mandate 4 (Radical Transparency) and Invariant 2 (Technical Mastery) by ensuring decisions are auditable and consistent across multiple brains.
Aligns with opencortex Mandate 4 (Radical Transparency) and Invariant 2 (Technical Mastery) by ensuring decisions are auditable and consistent across multiple brains.
* 3. Design Decision: Task Integrity Gate
** Requirement
@@ -33,7 +33,7 @@ Added `task-integrity-check` in `deterministic.lisp`.
** Invariant Alignment
Enforces the "High-Integrity Memory" mandate by ensuring the Org-mode AST remains semantically valid according to GTD rules (e.g., no orphaned active tasks).
* 4. org-agent Mandate Violations during Session (Corrected)
* 4. opencortex Mandate Violations during Session (Corrected)
** Violations
1. Editing without prior commit.
2. Direct `.lisp` edits vs Literate Org tangling.
@@ -45,4 +45,4 @@ Enforces the "High-Integrity Memory" mandate by ensuring the Org-mode AST remain
* 5. Permanent Learnings
- *Check Exports:* Always verify that symbols exported in `package.lisp` have a corresponding definition in the literate source.
- *Strict org-agent Mode:* Enable a pre-save hook or agent check to ensure all edits are performed within `#+begin_src` blocks in Literate Org files to avoid synchronization debt.
- *Strict opencortex Mode:* Enable a pre-save hook or agent check to ensure all edits are performed within `#+begin_src` blocks in Literate Org files to avoid synchronization debt.

10
docs/ux.org
View File

@@ -4,7 +4,7 @@
#+STARTUP: content
* Overview
This document traces the intended User Experience (UX) journey for the ~org-agent~. It serves as a living design document to ensure that architectural decisions align with a frictionless, autonomous, and intuitive user interaction model.
This document traces the intended User Experience (UX) journey for the ~opencortex~. It serves as a living design document to ensure that architectural decisions align with a frictionless, autonomous, and intuitive user interaction model.
* 1. The Zero-to-One Experience (Onboarding)
** Goal
@@ -13,7 +13,7 @@ A user should be able to go from discovering the project to having a running, ca
** The Appliance Paradigm (Primary Path)
The user runs a single command in their terminal:
#+begin_src bash
curl -fsSL https://raw.githubusercontent.com/gharbeia/org-agent/main/scripts/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/scripts/install.sh | bash
#+end_src
** The Interactive Wizard
@@ -32,7 +32,7 @@ Immediately after boot, the user needs a way to verify the agent is alive and ca
** The Interaction
The user types a local client command to connect to the background daemon:
#+begin_src bash
org-agent chat
opencortex chat
#+end_src
This opens a slick, colorful interactive terminal session:
@@ -40,13 +40,13 @@ This opens a slick, colorful interactive terminal session:
> User: Hello, what are my active projects?
> Agent: [Thinking...]
> Agent: You currently have 3 active projects:
> 1. Org-agent v1.0
> 1. OpenCortex v1.0
> 2. Home Renovation
> 3. Read 'The Autonomous Individual'
#+end_example
** Behind the Scenes
1. The ~org-agent chat~ client connects to the daemon's local port (e.g., 9105).
1. The ~opencortex chat~ client connects to the daemon's local port (e.g., 9105).
2. It sends a ~:chat-message~ signal.
3. The core harness routes this to the Probabilistic Engine.
4. The Context Manager retrieves active projects from the Memex AST.