passepartout/README.org

OpenCortex: Your Autonomous, Plain-Text Life Assistant

• Meet OpenCortex
• The OpenCortex Experience: What It Actually Does
  • 1. Zero-Friction Capture & Organization
  • 2. Autonomous Task Execution
  • 3. Proactive "Gardening"
  • 4. Uninterrupted Background Research
• The Philosophy: Fixing the Broken AI Agent Ecosystem
  • The Data Silo Problem
  • The Safety and Hallucination Problem
  • The Cloud Dependency Problem
• Quick Start & Installation
• Project Navigation
• License

Meet OpenCortex

Most AI assistants are just chatbots. You ask a question, they answer, you close the tab, and they forget you exist. They trap your conversations in proprietary web apps and silo your data.

OpenCortex is different. It is an AI that lives inside your own text files.

It runs locally on your machine as a background process. It reads the same plain-text notes you do, organizes your life while you sleep, and acts as a permanent, private companion. It doesn't lock you into a database; it manages a folder of text files that you completely own and control.

The OpenCortex Experience: What It Actually Does

OpenCortex acts as the ultimate digital librarian and executor. Here is what it feels like to use it:

1. Zero-Friction Capture & Organization

You don't need to categorize everything perfectly. Just dump your messy, half-finished thoughts, meeting notes, and to-dos into a single "Inbox" text file. In the background, OpenCortex reads your inbox, extracts the actionable tasks into your to-do lists, and distills your random thoughts into permanent, beautifully linked reference notes (your knowledge base).

2. Autonomous Task Execution

OpenCortex isn't just a writer; it's a doer. If you add a task like `=TODO Update the web server packages=`, the agent recognizes it. It opens a secure, hidden terminal, writes the necessary commands, verifies they are safe, runs them, and updates your text file with the result and terminal output.

3. Proactive "Gardening"

OpenCortex runs on a heartbeat. When you step away from your computer, it goes to work. It scans your notes to fix formatting, finds related ideas you forgot to link together, and flags outdated information. You wake up to a cleaner, more connected workspace.

4. Uninterrupted Background Research

You can tell OpenCortex: "Research the history of digital privacy and draft a report." Instead of freezing and making you wait, it spawns a background thread. It silently browses the web and drafts the document in your notes while you continue working on other things.

The Philosophy: Fixing the Broken AI Agent Ecosystem

We built OpenCortex from the ground up because the current generation of AI agents are built on fundamentally flawed architecture. They prioritize quick demos over long-term reliability and user sovereignty.

Here is how we address the three massive issues with modern AI agents:

The Data Silo Problem

The Flaw: Popular agents bury your memories, preferences, and documents inside opaque databases (like SQLite or specialized vector stores). If you want to see your own data, you have to ask the AI to fetch it. If the app shuts down, your data is gone. The OpenCortex Solution: Total plain-text transparency. We use a powerful plain-text format (Org-mode). There is no database. Your entire life is just a folder of text files. You can open them in any basic text editor, sync them anywhere, and they are guaranteed to be readable decades from now.

The Safety and Hallucination Problem

The Flaw: Most agents are built using languages (like Python) that blindly pipe AI-generated text directly into your computer's terminal. If the AI hallucinates or makes a mistake, it can delete files or break your system. The OpenCortex Solution: A "Neurosymbolic" safeguard. OpenCortex splits its brain into two parts:

1. The Creative Brain (AI): Understands your notes and suggests actions.
2. The Strict Guard (Logic): Before the AI is allowed to touch a file or run a command, a mathematically strict set of rules intercepts the proposal. It verifies the action is safe and permitted. If the AI hallucinates, the guard blocks it.

The Cloud Dependency Problem

The Flaw: Most assistants rely entirely on big tech cloud APIs. When your internet drops, or the service goes down, your assistant dies. Worse, your private, personal notes are constantly sent to third-party servers. The OpenCortex Solution: Local-First and Private. OpenCortex is designed to run directly on your own hardware using free, open-source AI models. Your private journals and API keys never leave your laptop. It can intelligently use cloud models for highly complex tasks, but only when you give explicit permission.

Quick Start & Installation

To boot your local assistant, you need a Common Lisp compiler (SBCL) and a cloned repository.

# Clone the repository
git clone https://github.com/your-username/opencortex.git ~/memex/projects/opencortex

# Run the setup wizard
cd ~/memex/projects/opencortex
./opencortex.sh setup

The setup wizard will guide you through connecting your local AI models and initializing your text-based workspace.

Project Navigation

OpenCortex is built using **Literate Programming**—the explanations and the code are woven together in the same files so anyone can understand how the system works.

• The Evolutionary Roadmap: See our detailed plan for reaching State-of-the-Art capabilities.
• Contributing Guidelines: Learn how to teach OpenCortex new skills.
• The Core Engine: Read the code that drives the agent's heartbeat.

License

openCortex is released under the AGPLv3 license. See CLA.org for the Contributor License Agreement.