passepartout/docs/USER_MANUAL.org

OpenCortex User Manual

• Introduction
• Installation
  • Quick start (curl)
  • From a clone
• Configuration
• Interacting with OpenCortex
  • Terminal User Interface (TUI)
  • Command Line Interface (CLI)
  • Emacs Integration
• The Memex Structure
• Deployment
  • Bare metal (Debian / Fedora)
  • systemd service (auto-start on boot)
  • Docker
  • Backup
  • Restore

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)

curl -fsSL https://raw.githubusercontent.com/amrgharbeia/opencortex/main/opencortex.sh | bash -s configure

From a clone

git clone https://github.com/amrgharbeia/opencortex.git ~/projects/opencortex
~/projects/opencortex/opencortex.sh configure

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:

./opencortex.sh --boot &

Terminal User Interface (TUI)

For a rich, split-pane terminal experience:

./opencortex.sh tui

Command Line Interface (CLI)

For raw, pipe-friendly interaction:

./opencortex.sh cli

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.

./opencortex.sh configure              # interactive
./opencortex.sh configure --non-interactive  # headless
./opencortex.sh configure --with-firewall    # also open port 9105

After configuration, you can re-run configure any time to add providers or link gateways.

systemd service (auto-start on boot)

./opencortex.sh install service

Installs a user-level systemd unit that starts the daemon on login. Logs are available via journalctl --user -u opencortex.service -f.

To remove:

./opencortex.sh uninstall service

Docker

A Debian-based Docker image is provided for containerized deployment.

cd infrastructure/docker
docker-compose up -d

This builds an image from debian:trixie-slim with all dependencies pre-installed. The memex directory is mounted from the host.

Backup

./opencortex.sh backup ~/my-backup.tar.gz

Backs up the config, data, and memex directories.

Restore

./opencortex.sh restore ~/my-backup.tar.gz

Restores from a backup file. Run opencortex doctor afterward to verify integrity.