CortexOS — Your Thinking Engine

A context, memory, and prioritisation engine for ambitious builders and AI agents

Note

CortexOS turns scattered inputs (RSS feeds, notes, digests) into grounded daily actions — answering "What should I focus on today?" using your personal goals, projects, and reading history as context. Works fully offline; LLM is optional.

---

Install

Requirements: Python 3.11+, macOS 14+ / iOS 17+ (native apps), Xcode 15+ (Swift)

git clone git@github.com:CortexMindSystem/Cortex-Thinking-Engine.git
cd Cortex-Thinking-Engine
make install        # creates .venv and installs deps

Or manually:

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

---

Usage

# Run the full pipeline (ingest → score → focus brief)
.venv/bin/python -m cortex_core pipeline

# Start the API server (http://localhost:8420, docs at /docs)
.venv/bin/python -m cortex_core serve

# Other CLI commands
.venv/bin/python -m cortex_core status     # system info
.venv/bin/python -m cortex_core notes      # list knowledge notes
.venv/bin/python -m cortex_core pipeline --llm  # LLM-enhanced summaries

Native app (iOS + macOS):

brew install xcodegen
./generate_xcode_project.sh
open CortexOSApp/CortexOS.xcodeproj
# Requires the API server to be running

---

What Makes It Work

Feature	Detail
4-Layer Memory	Identity → Project → Research → Working memory persist your full context
4-Dimension Scoring	project_relevance, ai_relevance, novelty, actionability per article
Focus Brief	Ranked daily items with why it matters + next action, shaped by your profile
Signal Detection	Emerging topics appearing across multiple sources are surfaced automatically
Decision Engine	Priorities, what to ignore, what changed since yesterday
Hybrid Retrieval	Metadata filters → keyword match → recency weighting
Self-Improvement	Reading history enriches context → scoring improves over time
Why Engine	Per-item evaluation: why it matters, project impact, contradiction detection, recommended action
Offline-First	All scoring and focus generation are rule-based; no API key required
Spaced Repetition	Leitner-style review intervals (1, 3, 7, 14, 30 days)

---

API

Server runs on port 8420. Key endpoints:

Method	Endpoint	Description
GET	/focus/today	Today's focus brief
POST	/focus/generate	Generate a new focus brief
GET/PATCH	/profile/	View or update user profile
POST	/digest/evaluate	Score a digest against your context
GET	/notes/	List / search knowledge notes
POST	/pipeline/run	Run the full pipeline
GET	/context/goals	Active goals (agent context API)
GET	/context/signals	Detected signals
POST	/context/retrieve	Hybrid search across notes + insights
POST	/why/evaluate	Per-item decision: why it matters, impact, action, ignore/watch

Full interactive docs at http://localhost:8420/docs.

---

LLM (Optional)

export OPENAI_API_KEY="sk-..."      # or ANTHROPIC_API_KEY

Configure model in ~/.cortexos/config.json:

{ "llm": { "provider": "openai", "model": "gpt-4o", "temperature": 0.4 } }

---

Deploy to TestFlight

Requires Fastlane and an App Store Connect API key (.p8).

cd CortexOSApp
fastlane ios testflight_release   # iOS
fastlane mac testflight_release   # macOS
fastlane all_testflight           # both

---

Tests

make test          # all Python + Swift tests
make test-python   # Python only (276 tests)
make test-swift    # Swift only (47 tests)
make lint          # ruff + security

---

👨‍🍳 The Cook

Designed & coded with passion by Pierre-Henry Soria — a SUPER passionate Belgian Software Engineer 🍫🍺

Open to exciting opportunities — let's chat.