FerrellSyntheticIntelligence/felon-cortex

FELON Cortex — Local Cognitive Runtime

Give ANY AI model a brain. Memory. Knowledge. Tools. Verification. Confidence. All running locally. No cloud. No API keys required. Works offline.

┌─────────────────────────────────────────────────────────┐
│                    FELON CORTEX                          │
│                                                          │
│   You ──→  FELON  ──→  Claude / OpenAI / opencode /     │
│                         any local model                  │
│                                                          │
│   FELON wraps EVERY interaction with:                   │
│   🧬 DNA Memory     → Never forgets                     │
│   📚 Knowledge Lib   → 22 SE textbooks                  │
│   🔍 Veritas        → 6 security + syntax checks        │
│   🤖 Nanobot Swarm  → 8 local tools                     │
│   🎯 Confidence     → Tells you when it's guessing      │
│   📝 Session Journal → Works offline, syncs later       │
└─────────────────────────────────────────────────────────┘

---

What It Solves

Problem	FELON Solution
AI forgets between sessions	DNA Memory persists everything — picks up where you left off
Can't code without internet	Offline mode — local model + 22 textbooks + cached knowledge
Models lie confidently	Confidence score on every response: "I'm sure" / "experimental" / "guessing"
No code verification	Veritas runs 6 checks: syntax, security, imports, logic, tests, edge cases
Blank slate every chat	22 SE textbooks injected into context automatically
API downtime = dead project	Session journal records everything offline, syncs when internet returns

---

Install

git clone https://github.com/AnonymousNomad/felon-cortex.git
cd felon-cortex
./install.sh

Or via pip:

pip install felon-cortex

Dependencies: Python 3.10+ only. Zero external packages required for core operation.

---

Usage

felon start                    # Start proxy on http://localhost:8080
felon start --port 9090       # Custom port
felon status                   # View memory, sessions, knowledge
felon sync                     # Upload offline sessions when internet returns

Then point any tool at http://localhost:8080:

Tool	Configuration
Claude Desktop	Settings → Proxy → http://localhost:8080
opencode	--api-base http://localhost:8080
Continue.dev	apiBase: "http://localhost:8080" in config
Any OpenAI client	Set OPENAI_BASE_URL=http://localhost:8080
Local GGUF model	felon start --model ./my-model.gguf

---

Architecture

┌──────────────────────────────────────────────────────────┐
│                    FELON CORTEX                           │
│                                                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐               │
│  │   DNA    │  │ KNOWLEDGE│  │ VERITAS  │               │
│  │  MEMORY  │  │ LIBRARY  │  │ 6-CHECK  │               │
│  │          │  │ 22 books │  │ VERIFIER │               │
│  │ Remembers│  │ Works    │  │ Catches  │               │
│  │ every    │  │ offline  │  │ mistakes │               │
│  │ session  │  │          │  │          │               │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘               │
│       │              │             │                     │
│       └──────────────┼─────────────┘                     │
│                      │                                   │
│  ┌───────────────────┴────────────────────┐              │
│  │            PROMPT ENRICHMENT            │              │
│  │  Memory context + Knowledge + Context   │              │
│  └───────────────────┬────────────────────┘              │
│                      │                                   │
│                      ▼                                   │
│  ┌────────────────────────────────────────┐              │
│  │           TARGET MODEL                  │              │
│  │  Claude / OpenAI / opencode / local    │              │
│  └───────────────────┬────────────────────┘              │
│                      │                                   │
│  ┌───────────────────┴────────────────────┐              │
│  │         RESPONSE PROCESSING             │              │
│  │  Veritas checks + Confidence scoring    │              │
│  └───────────────────┬────────────────────┘              │
│                      │                                   │
│  ┌───────────────────┴────────────────────┐              │
│  │  🤖 NANOBOT SWARM (8 tools)            │              │
│  │  fs • git • compile • test • search    │              │
│  │  shell • library • web_search          │              │
│  └────────────────────────────────────────┘              │
│                      │                                   │
│  ┌───────────────────┴────────────────────┐              │
│  │  📝 SESSION JOURNAL                     │              │
│  │  Offline → logs → syncs when online    │              │
│  └────────────────────────────────────────┘              │
│                      │                                   │
│                      ▼                                   │
│              VERIFIED + SCORED + TOOL-EXECUTED OUTPUT    │
└──────────────────────────────────────────────────────────┘

---

Offline Mode

When the API is unreachable, FELON Cortex:

1. DNA Memory — pulls from past sessions (continuity)
2. Knowledge Library — answers from 22 SE textbooks
3. Local Model — falls back to bundled GGUF model (optional)
4. Session Journal — records every prompt, decision, file change
5. Auto-Sync — when internet returns, uploads journal → model is instantly caught up

No internet?
  ✓ You keep coding
  ✓ FELON remembers everything
  ✓ Knowledge library fills gaps
  ✓ When internet returns: one sync → model caught up

---

Sub-Systems

🧬 DNA Memory

BM25-ranked retrieval across all past sessions. Gives the model continuity.

# FELON automatically adds to every prompt:
[FELON DNA MEMORY — relevant context from past sessions]
Past interactions:
  (0.87) "Build REST API with Flask" → "Use Flask blueprints for modular routes..."
  (0.72) "Add JWT auth" → "Use flask-jwt-extended with token refresh..."
[END MEMORY]

📚 Knowledge Library

22 software engineering textbook entries. Topics: Python, algorithms, data structures, testing, git, security, design patterns, web, concurrency. BM25 retrieval with tag-based boosting. Works completely offline.

🔍 Veritas (6-Check Verifier)

Every code block in every response gets checked:

1. Syntax — compile() check
2. Imports — resolves every import
3. Security — blocks eval, exec, subprocess, pickle
4. Logic — has def/class/return/control flow
5. Tests — has assert statements
6. Edge Cases — has try/except or if/else

🎯 Confidence Scoring

Every response gets a confidence label:

• ✅ 90%+ — High confidence, I'm sure
• 📊 70-89% — Moderate confidence
• 🔬 50-69% — Experimental, verify
• ⚠️ 30-49% — Low confidence, I'm guessing
• 🚫 <30% — I have no idea

🤖 Nanobot Swarm

8 local tools the model can use:

Tool	Actions
fs	read, write, list, exists, delete, mkdir
git	init, add, commit, status, diff, log
compile	Syntax-check any Python file
test	Run pytest on any directory
search	Search codebase for patterns
shell	Run safe shell commands
library	Query knowledge library
web_search	Search allowlisted sites (docs.python.org, stackoverflow, etc.)

📝 Session Journal

• Records every interaction during offline sessions
• Tracks: prompts, responses, decisions, file changes, tool use
• Builds sync summary when internet returns
• Model instantly catches up on everything that happened offline

---

Benchmarks

Metric	Value
Prompt enrichment latency	< 50ms
DNA Memory retrieval	< 10ms (BM25)
Knowledge Library query	< 5ms
Veritas 6-check	< 20ms per code block
Offline fallback latency	< 100ms
Memory: 1000 sessions stored	< 5MB disk

---

Development

git clone https://github.com/AnonymousNomad/felon-cortex.git
cd felon-cortex
pip install -e .

# Run tests
python -m pytest tests/

# Start dev proxy
felon start --port 8080

---

Roadmap

• DNA Memory (BM25 retrieval)
• Knowledge Library (22 textbooks)
• Veritas 6-check verifier
• Nanobot swarm (8 tools)
• Confidence scoring
• Offline session journaling
• Auto-sync on internet restore
• Bundled local GGUF model
• ChromaDB/FAISS for large-scale memory
• Web dashboard
• VSCode extension
• Multi-user memory isolation

---

Project Status

Beta — actively developed. The core proxy, memory, knowledge library, and veritas layer are built and tested. Nanobot tools and offline sync are functional. Currently expanding the knowledge library and adding bundled local model support.

---

Author

FerrellSyntheticIntelligence (James Ferrell) — built on a tablet with zero VC funding.

• GitHub: AnonymousNomad
• HuggingFace: FerrellSyntheticIntelligence

---

License

MIT License — free for personal and commercial use.

---

FELON Cortex — Every model deserves a brain.