Amr Gharbeia
41de20d3f1
Some checks failed
Deploy (Gitea) / deploy (push) Failing after 11s
- Secret Exposure Gate + Privacy Filter (Bouncer) - Shell actuator safety harness (timeout, blocked patterns) - REPL-first enforcement (lisp validation gate, system-prompt-augment) - Engineering Standards lifecycle (two-track Org-first + REPL-first) - Literate Programming discipline (one function per block, reflect-back) - AGENTS.md: thin routing layer, skills are authoritative - SKILLS_DIR removed, ~/notes fallback eliminated - opencortex.sh: multi-distro (Debian+Fedora), configure, install service, backup, restore, help - infrastructure/opencortex.service (systemd user unit) - Docker: updated to debian:trixie, fixed build context - GitHub CI: lint + test workflows fixed, trigger on tags only - Gitea CI: deploy workflow paths fixed - README: one-line curl install, badges - USER_MANUAL: Deployment section (bare metal, Docker, backup) - .gitignore: skills/*.lisp and tests/*.lisp as generated artifacts - Prose/block refactor across all 35 org files - Test suite Tier 1: 43/45 pass (env-dependent failures isolated)
124 lines
3.8 KiB
Org Mode
124 lines
3.8 KiB
Org Mode
#+TITLE: OpenCortex User Manual
|
|
#+AUTHOR: OpenCortex Contributors
|
|
#+STARTUP: content
|
|
#+FILETAGS: :docs:manual:
|
|
|
|
* 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 (curl)
|
|
|
|
#+begin_src bash
|
|
curl -fsSL https://raw.githubusercontent.com/amrgharbeia/opencortex/main/opencortex.sh | bash -s configure
|
|
#+end_src
|
|
|
|
** From a clone
|
|
|
|
#+begin_src bash
|
|
git clone https://github.com/amrgharbeia/opencortex.git ~/projects/opencortex
|
|
~/projects/opencortex/opencortex.sh configure
|
|
#+end_src
|
|
|
|
Both methods will:
|
|
1. Install system dependencies (SBCL, Emacs, git, curl, socat — detected for Debian or Fedora)
|
|
2. Install Quicklisp (Common Lisp package manager)
|
|
3. Tangle literate Org sources into runnable Lisp
|
|
4. Launch the interactive setup wizard (LLM providers, gateways)
|
|
|
|
If you already have Emacs installed, the installer skips it and uses your existing installation.
|
|
|
|
* Configuration
|
|
The system is configured via a `.env` file in the project root. Essential 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`).
|
|
|
|
* 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
|
|
|
|
** Terminal User Interface (TUI)
|
|
For a rich, split-pane terminal experience:
|
|
#+begin_src bash
|
|
./opencortex.sh tui
|
|
#+end_src
|
|
|
|
** Command Line Interface (CLI)
|
|
For raw, pipe-friendly interaction:
|
|
#+begin_src bash
|
|
./opencortex.sh 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.
|
|
|
|
* Deployment
|
|
|
|
** Bare metal (Debian / Fedora)
|
|
|
|
The ~configure~ command supports both Debian-based (Ubuntu, Pop, Mint) and Fedora-based (RHEL, Rocky) distributions. It detects your distro automatically and installs the correct packages.
|
|
|
|
#+begin_src bash
|
|
./opencortex.sh configure # interactive
|
|
./opencortex.sh configure --non-interactive # headless
|
|
./opencortex.sh configure --with-firewall # also open port 9105
|
|
#+end_src
|
|
|
|
After configuration, you can re-run ~configure~ any time to add providers or link gateways.
|
|
|
|
** systemd service (auto-start on boot)
|
|
|
|
#+begin_src bash
|
|
./opencortex.sh install service
|
|
#+end_src
|
|
|
|
Installs a user-level systemd unit that starts the daemon on login. Logs are available via ~journalctl --user -u opencortex.service -f~.
|
|
|
|
To remove:
|
|
|
|
#+begin_src bash
|
|
./opencortex.sh uninstall service
|
|
#+end_src
|
|
|
|
** Docker
|
|
|
|
A Debian-based Docker image is provided for containerized deployment.
|
|
|
|
#+begin_src bash
|
|
cd infrastructure/docker
|
|
docker-compose up -d
|
|
#+end_src
|
|
|
|
This builds an image from ~debian:trixie-slim~ with all dependencies pre-installed. The memex directory is mounted from the host.
|
|
|
|
** Backup
|
|
|
|
#+begin_src bash
|
|
./opencortex.sh backup ~/my-backup.tar.gz
|
|
#+end_src
|
|
|
|
Backs up the config, data, and memex directories.
|
|
|
|
** Restore
|
|
|
|
#+begin_src bash
|
|
./opencortex.sh restore ~/my-backup.tar.gz
|
|
#+end_src
|
|
|
|
Restores from a backup file. Run ~opencortex doctor~ afterward to verify integrity. |