From 60f2c152e0131c1df1a566071b8e1f04c5b3caf2 Mon Sep 17 00:00:00 2001 From: Amr Gharbeia Date: Tue, 21 Apr 2026 19:07:32 -0400 Subject: [PATCH] REORG: Apply semantic directory structure and documentation cleanup --- deploy/bare-metal/install.sh | 46 --------- deploy/bare-metal/org-agent.service | 18 ---- deploy/docker/Dockerfile | 44 --------- deploy/docker/docker-compose.yml | 18 ---- deploy/guix/manifest.scm | 14 --- deploy/lxc/setup.org | 33 ------- deploy/vms/debian/Vagrantfile | 22 ----- deploy/vms/fedora/Vagrantfile | 21 ----- CHANGELOG.org => docs/CHANGELOG.org | 0 CLA.org => docs/CLA.org | 0 CONTRIBUTING.org => docs/CONTRIBUTING.org | 0 docs/MVP_SPEC.org | 93 ------------------- USER_MANUAL.org => docs/USER_MANUAL.org | 0 docs/deployment.org | 36 ------- docs/marketing-v0.1.0.org | 46 --------- docs/quickstart.org | 55 ----------- docs/ux.org | 66 ------------- .../system}/state/memory-image.lisp | 0 {literate => harness}/act.org | 0 {literate => harness}/communication.org | 0 {literate => harness}/context.org | 0 {literate => harness}/loop.org | 0 {literate => harness}/manifest.org | 0 {literate => harness}/memory.org | 0 {literate => harness}/package.org | 0 {literate => harness}/perceive.org | 0 {literate => harness}/reason.org | 0 {literate => harness}/setup.org | 0 {literate => harness}/skills.org | 0 {literate => harness}/tui-client.org | 0 .../docker/Dockerfile | 0 .../docker/docker-compose.yml | 0 src/communication-validator.lisp | 2 +- 33 files changed, 1 insertion(+), 513 deletions(-) delete mode 100644 deploy/bare-metal/install.sh delete mode 100644 deploy/bare-metal/org-agent.service delete mode 100644 deploy/docker/Dockerfile delete mode 100644 deploy/docker/docker-compose.yml delete mode 100644 deploy/guix/manifest.scm delete mode 100644 deploy/lxc/setup.org delete mode 100644 deploy/vms/debian/Vagrantfile delete mode 100644 deploy/vms/fedora/Vagrantfile rename CHANGELOG.org => docs/CHANGELOG.org (100%) rename CLA.org => docs/CLA.org (100%) rename CONTRIBUTING.org => docs/CONTRIBUTING.org (100%) delete mode 100644 docs/MVP_SPEC.org rename USER_MANUAL.org => docs/USER_MANUAL.org (100%) delete mode 100644 docs/deployment.org delete mode 100644 docs/marketing-v0.1.0.org delete mode 100644 docs/quickstart.org delete mode 100644 docs/ux.org rename {system => environment/system}/state/memory-image.lisp (100%) rename {literate => harness}/act.org (100%) rename {literate => harness}/communication.org (100%) rename {literate => harness}/context.org (100%) rename {literate => harness}/loop.org (100%) rename {literate => harness}/manifest.org (100%) rename {literate => harness}/memory.org (100%) rename {literate => harness}/package.org (100%) rename {literate => harness}/perceive.org (100%) rename {literate => harness}/reason.org (100%) rename {literate => harness}/setup.org (100%) rename {literate => harness}/skills.org (100%) rename {literate => harness}/tui-client.org (100%) rename Dockerfile => infrastructure/docker/Dockerfile (100%) rename docker-compose.yml => infrastructure/docker/docker-compose.yml (100%) diff --git a/deploy/bare-metal/install.sh b/deploy/bare-metal/install.sh deleted file mode 100644 index 1825bed..0000000 --- a/deploy/bare-metal/install.sh +++ /dev/null @@ -1,46 +0,0 @@ -#!/bin/bash -# opencortex: Bare Metal Installation Script -# This script sets up the opencortex daemon on a Linux host (Debian/Fedora). - -set -e - -echo "--- opencortex: Bare Metal Installation ---" - -# 1. Check Dependencies -echo "[1/4] Checking dependencies..." -for cmd in sbcl curl git ripgrep; do - if ! command -v $cmd &> /dev/null; then - echo "Error: $cmd is not installed. Please install it first." - exit 1 - fi -done - -# 2. Setup Quicklisp -if [ ! -d "$HOME/quicklisp" ]; then - echo "[2/4] Quicklisp not found. Installing..." - curl -O https://beta.quicklisp.org/quicklisp.lisp - sbcl --non-interactive --load quicklisp.lisp --eval '(quicklisp-quickstart:install)' - rm quicklisp.lisp - echo "Quicklisp installed." -else - echo "[2/4] Quicklisp already installed." -fi - -# 3. Build standalone binary -echo "[3/4] Building standalone binary..." -PROJECT_ROOT=$(pwd)/../.. -sbcl --non-interactive \ - --eval "(push \"$PROJECT_ROOT/\" asdf:*central-registry*)" \ - --eval "(ql:quickload :opencortex)" \ - --eval "(asdf:make :opencortex)" - -echo "Binary built: $PROJECT_ROOT/opencortex-server" - -# 4. Instructions for Systemd -echo "[4/4] Installation complete." -echo "" -echo "To run as a systemd service:" -echo "1. Edit opencortex.service to set correct paths." -echo "2. sudo cp opencortex.service /etc/systemd/system/" -echo "3. sudo systemctl daemon-reload" -echo "4. sudo systemctl enable --now opencortex" diff --git a/deploy/bare-metal/org-agent.service b/deploy/bare-metal/org-agent.service deleted file mode 100644 index bf75c18..0000000 --- a/deploy/bare-metal/org-agent.service +++ /dev/null @@ -1,18 +0,0 @@ -[Unit] -Description=opencortex: Probabilistic-Deterministic Lisp Machine Kernel -After=network.target - -[Service] -Type=simple -# Update User and WorkingDirectory to match your local setup -User=amr -WorkingDirectory=/home/amr/.openclaw/workspace/memex/5_projects/opencortex -ExecStart=/home/amr/.openclaw/workspace/memex/5_projects/opencortex/opencortex-server -Restart=always -RestartSec=10 - -# Environment variables can be loaded from the .env file -EnvironmentFile=/home/amr/.openclaw/workspace/memex/5_projects/opencortex/.env - -[Install] -WantedBy=multi-user.target diff --git a/deploy/docker/Dockerfile b/deploy/docker/Dockerfile deleted file mode 100644 index 6e35d6b..0000000 --- a/deploy/docker/Dockerfile +++ /dev/null @@ -1,44 +0,0 @@ -FROM debian:bookworm-slim - -# Install SBCL, ripgrep, and build dependencies -RUN apt-get update && \ - apt-get install -y sbcl build-essential curl git ripgrep libsqlite3-dev lynx python3 python3-pip && \ - apt-get clean && \ - rm -rf /var/lib/apt/lists/* - -# Install Quicklisp globally -RUN curl -O https://beta.quicklisp.org/quicklisp.lisp && \ - sbcl --non-interactive \ - --load quicklisp.lisp \ - --eval '(quicklisp-quickstart:install :path "/opt/quicklisp")' \ - --eval '(ql-util:without-prompting (ql:add-to-init-file))' && \ - rm quicklisp.lisp - -# Set up the working directory -WORKDIR /app - -# Copy source code and system definition -COPY opencortex.asd /app/ -COPY src/ /app/src/ - -# Ensure we aren't using a stale binary from the host -RUN rm -f /app/opencortex-server - -# Build the standalone binary natively inside the container -# This ensures GLIBC compatibility with the runtime environment. -RUN sbcl --non-interactive \ - --eval '(push "/app/" asdf:*central-registry*)' \ - --eval '(ql:quickload :opencortex)' \ - --eval '(asdf:make :opencortex)' - -# Ensure the binary is executable -RUN chmod +x /app/opencortex-server - -# Expose the communication protocol and Web Dashboard ports -EXPOSE 9105 8080 - -# The app expects the memex to be mounted here -VOLUME /memex - -# Run the natively compiled standalone daemon -CMD ["./opencortex-server"] diff --git a/deploy/docker/docker-compose.yml b/deploy/docker/docker-compose.yml deleted file mode 100644 index 9211e04..0000000 --- a/deploy/docker/docker-compose.yml +++ /dev/null @@ -1,18 +0,0 @@ -version: '3.8' - -services: - opencortex: - build: - context: ../.. - dockerfile: deploy/docker/Dockerfile - container_name: opencortex - restart: unless-stopped - ports: - - "${ORG_AGENT_DAEMON_PORT:-9105}:${ORG_AGENT_DAEMON_PORT:-9105}" - - "${ORG_AGENT_WEB_PORT:-8080}:${ORG_AGENT_WEB_PORT:-8080}" - volumes: - - /memex:/memex - -networks: - sandbox-net: - driver: bridge diff --git a/deploy/guix/manifest.scm b/deploy/guix/manifest.scm deleted file mode 100644 index a4e8528..0000000 --- a/deploy/guix/manifest.scm +++ /dev/null @@ -1,14 +0,0 @@ -;; opencortex: Guix Environment Manifest -;; Usage: guix shell -m manifest.scm -- sbcl --eval ... - -(specifications->manifest - '("sbcl" - "sbcl-cl-json" - "sbcl-bordeaux-threads" - "sbcl-usocket" - "sbcl-dexador" - "sbcl-cl-ppcre" - "ripgrep" - "git" - "curl" - "sqlite")) diff --git a/deploy/lxc/setup.org b/deploy/lxc/setup.org deleted file mode 100644 index e4b4a1e..0000000 --- a/deploy/lxc/setup.org +++ /dev/null @@ -1,33 +0,0 @@ -#+TITLE: LXC / Systemd-nspawn Deployment Guide -#+AUTHOR: opencortex - -* Overview -For users who prefer containerization without the overhead or dependency on the Docker daemon, `opencortex` can be run within a standard Linux Container (LXC) or a systemd-nspawn container. - -* Systemd-nspawn Setup (Fastest for Linux users) - -1. **Create the container root:** - #+begin_src bash - sudo debootstrap --arch=amd64 bookworm /var/lib/machines/opencortex - #+end_src - -2. **Start and enter the container:** - #+begin_src bash - sudo systemd-nspawn -D /var/lib/machines/opencortex - #+end_src - -3. **Install dependencies (inside container):** - #+begin_src bash - apt-get update && apt-get install -y sbcl curl git ripgrep libsqlite3-dev build-essential - #+end_src - -4. **Bind mount the Memex directory:** - Add this to your container startup or use the `--bind` flag: - #+begin_src bash - sudo systemd-nspawn -D /var/lib/machines/opencortex --bind /home/amr/.openclaw/workspace/memex - #+end_src - -* Proxmox LXC Setup -1. Create a new LXC container using the Debian 12 template. -2. Ensure the network is bridged so Emacs can reach it. -3. Run the `deploy/bare-metal/install.sh` script inside the container. diff --git a/deploy/vms/debian/Vagrantfile b/deploy/vms/debian/Vagrantfile deleted file mode 100644 index 102d3e4..0000000 --- a/deploy/vms/debian/Vagrantfile +++ /dev/null @@ -1,22 +0,0 @@ -Vagrant.configure("2") do |config| - config.vm.box = "debian/bookworm64" - config.vm.network "forwarded_port", guest: 9105, host: 9105 - - config.vm.provider "virtualbox" do |vb| - vb.memory = "1024" - vb.cpus = 2 - end - - config.vm.provision "shell", inline: <<-SHELL - apt-get update - apt-get install -y sbcl curl git ripgrep libsqlite3-dev build-essential - - # Setup for opencortex - mkdir -p /home/vagrant/opencortex - cp -r /vagrant/* /home/vagrant/opencortex/ - chown -R vagrant:vagrant /home/vagrant/opencortex - - # Build binary natively - sudo -u vagrant bash -c "cd /home/vagrant/opencortex && ./deploy/bare-metal/install.sh" - SHELL -end diff --git a/deploy/vms/fedora/Vagrantfile b/deploy/vms/fedora/Vagrantfile deleted file mode 100644 index f0f5a70..0000000 --- a/deploy/vms/fedora/Vagrantfile +++ /dev/null @@ -1,21 +0,0 @@ -Vagrant.configure("2") do |config| - config.vm.box = "fedora/39-cloud-base" - config.vm.network "forwarded_port", guest: 9105, host: 9105 - - config.vm.provider "virtualbox" do |vb| - vb.memory = "1024" - vb.cpus = 2 - end - - config.vm.provision "shell", inline: <<-SHELL - dnf install -y sbcl curl git ripgrep sqlite-devel make gcc - - # Setup for opencortex - mkdir -p /home/vagrant/opencortex - cp -r /vagrant/* /home/vagrant/opencortex/ - chown -R vagrant:vagrant /home/vagrant/opencortex - - # Build binary natively - sudo -u vagrant bash -c "cd /home/vagrant/opencortex && ./deploy/bare-metal/install.sh" - SHELL -end diff --git a/CHANGELOG.org b/docs/CHANGELOG.org similarity index 100% rename from CHANGELOG.org rename to docs/CHANGELOG.org diff --git a/CLA.org b/docs/CLA.org similarity index 100% rename from CLA.org rename to docs/CLA.org diff --git a/CONTRIBUTING.org b/docs/CONTRIBUTING.org similarity index 100% rename from CONTRIBUTING.org rename to docs/CONTRIBUTING.org diff --git a/docs/MVP_SPEC.org b/docs/MVP_SPEC.org deleted file mode 100644 index 581f299..0000000 --- a/docs/MVP_SPEC.org +++ /dev/null @@ -1,93 +0,0 @@ -#+TITLE: OpenCortex MVP (v0.1.0) Specification & Release Plan -#+STARTUP: content - -* Objective -Define detailed specifications for the OpenCortex MVP (v0.1.0). This MVP establishes the autonomous foundation and introduces a native Common Lisp Terminal User Interface (TUI) for improved UX, alongside a comprehensive release plan. - -* 1. Core Architecture & Environment (Completed) -- *System Harness:* A minimal, un-brittle Common Lisp (SBCL) microkernel that orchestrates the Perceive -> Probabilistic -> Deterministic -> Dispatch pipeline. -- *Dual-Engine Cognition:* - - /Probabilistic Engine:/ The LLM gateway handling semantic translation, multi-modal ingestion, and intent parsing (supporting Anthropic, Gemini, Groq, OpenAI, and Ollama). - - /Deterministic Engine:/ The Lisp logical core that mathematically verifies LLM-proposed actions against system rules prior to execution. -- *Data Stores:* - - /Linguistic Substrate:/ Org-mode plaintext files acting as the universal Abstract Syntax Tree (AST) for both humans and the agent. - - /Lisp Memory:/ A live, threaded graph of Lisp objects representing the Memex in RAM for instant, token-efficient traversal (Sparse Trees). -- *Skill Architecture:* All agent capabilities are encapsulated in single-file Literate Programs (~org-skill-*.org~). They are topologically loaded, dynamically compiled, and hot-reloadable. - -* 2. Mandatory Security & Containment (Completed) -- *Formal Verification Gate:* Evaluates actions before they hit the OS. - - /Path Confinement:/ Guarantees file writes are physically locked to the `~/memex/` root directory. - - /Network Exfiltration:/ Intercepts and blocks unauthorized external generic HTTP or socket requests. -- *System Policy Gate:* Enforces the "Zero-Bloat" and "Autonomy Above All" invariants. -- *Credentials Vault:* API keys and ~.env~ files are stored in a secure, masked Lisp enclave, rendering them invisible to the LLM's context window. - -* 3. Autonomous Background Workers (Completed) -- *The Scribe (~org-skill-scribe.org~):* A distillation engine that periodically reads the chronological logs (e.g., daily journal files) and autonomously extracts concepts into permanent Zettelkasten notes. -- *The Gardener (~org-skill-gardener.org~):* A heartbeat-driven, idle process that continuously walks the memory graph. It automatically repairs broken internal links, infers missing metadata, and flags orphaned ideas for the user. - -* 4. Native Terminal User Interface (UX Target) -- *Objective:* Eliminate raw ~stdout~ shell piping in favor of a rich, structured, and interactive Common Lisp TUI. -- *Library:* ~croatoan~ (A high-level CLOS wrapper for ncurses) will be used for rapid, robust UI development. -- *Layout:* - - /Main Viewport:/ A read-only, scrollable panel that renders Org-mode headlines, syntax-highlighted Lisp/Python code blocks, and system logs. - - /Input Box:/ A fixed, multi-line input area pinned to the bottom of the screen, supporting standard Readline keybindings. - - /Status Bar:/ A persistent bar at the top or bottom displaying the health and current activity of background workers (Scribe/Gardener) and memory usage. -- *Interactive Control (Slash Commands):* - - ~/help~: View system overview and command syntax. - - ~/clear~: Clear the viewport buffer. - - ~/skill-load ~: Dynamically reload a modified Lisp skill into the active image. - - ~/exit~: Gracefully shut down the harness and exit the environment. - - ~/status~: Print diagnostic report (memory, git status, worker uptimes). - - ~/config~: Display active config/env vars (masking secrets). - - ~/search ~: Raw deterministic regex/vector search across the Memex. - - ~/commit~: Trigger Engineering Standard check, stage, and commit Memex state. -- *Refactoring:* Reroute the existing ~:cli~ actuator and inbound gateway to exclusively utilize the new TUI rendering engine. - -* 5. Release & Publication Plan (v0.1.0) -- *Documentation:* - - ~USER_MANUAL.md~: A comprehensive guide on the one-liner installation (~opencortex.sh~), daily workflow, and navigating the Memex directory structure. - - ~CONTRIBUTING.md~: A guide to "Literate Granularity" engineering standards and creating new ~org-skill-*.org~ files. -- *Legal Finalization:* - - Assign the *AGPLv3* open-source license. - - Implement a broad *Contributor License Agreement (CLA)* process for external contributors to license rights back to the core project. - - Update ~LICENSE~ and finalize ~CHANGELOG.org~. -- *End-to-End Walkthrough:* Execute a clean-slate test of the installation script, boot sequence, environment variable parsing, and autonomous background worker triggers. -- *Marketing & Launch:* Migrate the canonical repository to GitHub (configure topics, badges, and issue templates). Record a high-fidelity GIF/video of the new TUI interaction and execute announcements on Hacker News, Reddit, and X/Twitter. - -* 6. User-Centric End-to-End Test Plan - -This section defines the precise workflow and expected user experience for the v0.1.0 MVP. It serves as the definitive manual testing script before release. - -** Phase 1: The One-Liner Installation & Boot -- *Action:* The user executes the canonical curl-bash script: ~curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/opencortex.sh | bash~ -- *Expected Experience:* - 1. The script detects the OS and installs any missing system dependencies (e.g., Docker, SBCL, Quicklisp). - 2. It interactively prompts the user to enter as many LLM API keys as they choose to (e.g., Gemini, Anthropic, OpenAI). The user can skip this step and configure them later. - 3. It asks the user for their existing folder structure and fills in the corresponding values (INBOX_DIR, DAILY_DIR, etc.) in ~.env.example~ to generate a valid ~.env~ file. - 4. It compiles and launches the ~opencortex-server~ daemon in the background. - 5. The user is greeted with a success message instructing them to run ~opencortex tui~. - -** Phase 2: First Contact (The TUI Experience) -- *Action:* The user types ~opencortex tui~ in their terminal. -- *Expected Experience:* - 1. The terminal clears and launches the Croatoan UI. - 2. The *Status Bar* appears at the bottom, indicating: ~[Scribe: Idle] [Gardener: Sleeping]~. - 3. The user types a natural language message in the input box: "Hello, what is my current Memex structure?" and presses Enter. - 4. The input box clears, and the user's message appears in the main viewport. - 5. A few seconds later, the agent responds with a formatted Org-mode list of the directories, demonstrating successful Lisp s-expression communication over the TCP socket and valid probabilistic reasoning. - -** Phase 3: The Autonomous Subroutines -- *Action:* The user creates a messy text file in ~/memex/daily/YYYY-MM-DD.org~ with a scattered thought about a new project, then waits. -- *Expected Experience:* - 1. Without any user prompting, the *Status Bar* updates to ~[Scribe: Distilling...]~. - 2. A quiet log message appears in the TUI viewport: ~*System*: Scribe extracted 1 new Zettelkasten note.~ - 3. The user inspects ~/memex/notes/~ and finds a cleanly formatted, semantically tagged Org node containing the distilled thought. - 4. The user intentionally breaks an Org-roam link in one of their notes. Minutes later, the Gardener awakens (~[Gardener: Auditing]~), and a log message appears indicating the link was repaired or flagged. - -** Phase 4: Deterministic Actuation (Slash Commands) -- *Action:* The user types ~/status~ in the TUI. -- *Expected Experience:* The TUI instantly prints a diagnostic report showing memory usage, uptime, and git status, bypassing the LLM entirely. -- *Action:* The user types ~/commit~. -- *Expected Experience:* The system runs the Engineering Standard gate, stages all changes in ~/memex~, and creates a git commit. The TUI confirms success. -- *Action:* The user types ~/exit~. -- *Expected Experience:* The TUI client gracefully disconnects and closes, returning the user to their standard bash prompt. The ~opencortex-server~ continues running safely in the background. diff --git a/USER_MANUAL.org b/docs/USER_MANUAL.org similarity index 100% rename from USER_MANUAL.org rename to docs/USER_MANUAL.org 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/marketing-v0.1.0.org b/docs/marketing-v0.1.0.org deleted file mode 100644 index 85466cc..0000000 --- a/docs/marketing-v0.1.0.org +++ /dev/null @@ -1,46 +0,0 @@ -#+TITLE: v0.1.0 Launch & Marketing Plan -#+AUTHOR: Amr -#+FILETAGS: :marketing:release:autonomy: -#+STARTUP: content - -* Overview -With the v0.1.0 "Autonomous MVP" released, the goal is to leverage GitHub's social graph to build a community of early adopters, contributors, and power users who resonate with the "Thin Harness, Fat Skills" and "Local-First" philosophy. - -* 1. Licensing Strategy -Before wide promotion, the project's license must align with its goals. -- **MIT License (Current):** Maximum adoption, frictionless for developers to embed in their own tools. Good for rapid growth. -- **GPLv3 / AGPLv3:** Enforces copyleft. Ensures any modifications or integrations by corporations must remain open-source. Protects the "Autonomous" ethos from proprietary enclosure. -- **Dual Licensing:** Open-source for individuals, commercial license for enterprise usage (if monetization is a future goal). - -*Decision Needed:* Do we stick with MIT, or switch to a copyleft license (AGPL) to protect the autonomous nature of the project? - -* 2. The GitHub Migration & Setup -To maximize visibility, the repository must be optimized for GitHub's ecosystem. -- [ ] **Mirror/Migrate to GitHub:** Move the primary remote from the self-hosted Gitea to GitHub. -- [ ] **README Optimization:** Add badges (License, Build Status, Version). Ensure the "Zero-to-One" curl command is prominent. Add an architecture diagram (mermaid). -- [ ] **Repository Topics:** Add tags like `common-lisp`, `autonomous-agents`, `org-mode`, `pkm`, `zettelkasten`, `llm`, `local-first`. -- [ ] **Contributing Guide:** Add `CONTRIBUTING.md` to explain the Literate Programming standard and how to add new "Skills". -- [ ] **Issue Templates:** Create templates for "Bug Report" and "Skill Proposal". - -* 3. The PR & Social Media Campaign -The narrative: "An autonomous AI agent that doesn't just chat, but lives natively in your Org-mode Memex. No Python glue code, no cloud lock-in—just pure, homoiconic Common Lisp." - -** Target Audiences & Channels -1. **The Emacs / Org-mode Community:** - - *Channels:* `r/emacs`, `r/orgmode`, Hacker News (`/r/lisp`), Emacs News. - - *Hook:* "A background daemon that autonomously distills your daily logs into a Zettelkasten using LLMs." -2. **The Local-First / PKM Community:** - - *Channels:* `r/Zettelkasten`, `r/PKM`, Obsidian/Logseq diaspora looking for more power. - - *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? 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 `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 -- Encourage "Show and Tell" in GitHub Discussions. -- Create a "Skill Directory" where users can share their custom `.org` skills. -- Actively solicit feedback for the v0.2.0 (Lisp TUI) roadmap. 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/docs/ux.org b/docs/ux.org deleted file mode 100644 index eb64c02..0000000 --- a/docs/ux.org +++ /dev/null @@ -1,66 +0,0 @@ -#+TITLE: User Experience (UX) Journey -#+AUTHOR: Amr -#+FILETAGS: :ux:design:autonomy: -#+STARTUP: content - -* Overview -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 -A user should be able to go from discovering the project to having a running, calibrated agent in under 3 minutes, with zero prerequisite knowledge of Lisp. - -** The Appliance Paradigm (Primary Path) -The user runs a single command in their terminal: -#+begin_src bash -curl -fsSL https://raw.githubusercontent.com/gharbeia/opencortex/main/scripts/install.sh | bash -#+end_src - -** The Interactive Wizard -The script verifies Docker presence and then launches an interactive prompt before booting the container: -1. *Identity:* "What is your name?" -> Configures ~$MEMEX_USER~ -2. *Assistant:* "What shall we name your Assistant?" -> Configures ~$MEMEX_ASSISTANT~ -3. *Neural Provider:* "Select your primary neural provider [Gemini/OpenRouter/Anthropic/OpenAI]" -> Configures API Keys. -4. *Data Gravity:* "Where is your Memex located?" -> Maps the host directory to the Docker container. - -*Outcome:* The `.env` is generated, core skills are seeded into the user's Memex, and `docker-compose up -d` launches the daemon in the background. The user sees: /"Booting your autonomous brain in the background..."/ - -* 2. The First Contact (The CLI Gateway) -** Goal -Immediately after boot, the user needs a way to verify the agent is alive and capable of answering questions about their Memex without configuring complex third-party integrations (like Telegram bots). - -** The Interaction -The user types a local client command to connect to the background daemon: -#+begin_src bash -opencortex chat -#+end_src - -This opens a slick, colorful interactive terminal session: -#+begin_example -> User: Hello, what are my active projects? -> Agent: [Thinking...] -> Agent: You currently have 3 active projects: -> 1. OpenCortex v1.0 -> 2. Home Renovation -> 3. Read 'The Autonomous Individual' -#+end_example - -** Behind the Scenes -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. -5. The Deterministic Engine (Bouncer) verifies it is a safe read-only action. -6. The ~:cli~ Actuator formats the Lisp response into Markdown and sends it back over the socket. - -* 3. The Interactive Refinement (v0.2.0) -** Goal -Transition from a "Verified Wrapper" around netcat to a high-fidelity, native Common Lisp TUI that rivals the experience of ~gemini-cli~. - -** Features -- *Homoiconic UI:* The TUI is rendered directly by the Lisp kernel, allowing for live introspection of the agent's thoughts. -- *Rich Formatting:* ANSI colors, bold headers, and syntax-highlighted code blocks. -- *Command Palette:* Slash commands for system control without leaving the chat. - -* 4. The Continuous Loop (Daily Usage) -(To be defined as the agent's capabilities expand into Scribe, Gardener, and Emacs-native interactions). diff --git a/system/state/memory-image.lisp b/environment/system/state/memory-image.lisp similarity index 100% rename from system/state/memory-image.lisp rename to environment/system/state/memory-image.lisp diff --git a/literate/act.org b/harness/act.org similarity index 100% rename from literate/act.org rename to harness/act.org diff --git a/literate/communication.org b/harness/communication.org similarity index 100% rename from literate/communication.org rename to harness/communication.org diff --git a/literate/context.org b/harness/context.org similarity index 100% rename from literate/context.org rename to harness/context.org diff --git a/literate/loop.org b/harness/loop.org similarity index 100% rename from literate/loop.org rename to harness/loop.org diff --git a/literate/manifest.org b/harness/manifest.org similarity index 100% rename from literate/manifest.org rename to harness/manifest.org diff --git a/literate/memory.org b/harness/memory.org similarity index 100% rename from literate/memory.org rename to harness/memory.org diff --git a/literate/package.org b/harness/package.org similarity index 100% rename from literate/package.org rename to harness/package.org diff --git a/literate/perceive.org b/harness/perceive.org similarity index 100% rename from literate/perceive.org rename to harness/perceive.org diff --git a/literate/reason.org b/harness/reason.org similarity index 100% rename from literate/reason.org rename to harness/reason.org diff --git a/literate/setup.org b/harness/setup.org similarity index 100% rename from literate/setup.org rename to harness/setup.org diff --git a/literate/skills.org b/harness/skills.org similarity index 100% rename from literate/skills.org rename to harness/skills.org diff --git a/literate/tui-client.org b/harness/tui-client.org similarity index 100% rename from literate/tui-client.org rename to harness/tui-client.org diff --git a/Dockerfile b/infrastructure/docker/Dockerfile similarity index 100% rename from Dockerfile rename to infrastructure/docker/Dockerfile diff --git a/docker-compose.yml b/infrastructure/docker/docker-compose.yml similarity index 100% rename from docker-compose.yml rename to infrastructure/docker/docker-compose.yml 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