README.md

# FELON Cortex — Local Cognitive Runtime

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0.0-blue?style=flat-square" alt="Version">
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/python-3.10+-blue?style=flat-square" alt="Python">
  <img src="https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20android-lightgrey?style=flat-square" alt="Platform">
  <img src="https://img.shields.io/badge/privacy-100%25%20local-purple?style=flat-square" alt="Privacy">
  <img src="https://img.shields.io/badge/offline-ready-orange?style=flat-square" alt="Offline">
</p>

**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

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

Or via pip:

```bash
pip install felon-cortex
```

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

---

## Usage

```bash
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.
```python
# 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

```bash
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

- [x] DNA Memory (BM25 retrieval)
- [x] Knowledge Library (22 textbooks)
- [x] Veritas 6-check verifier
- [x] Nanobot swarm (8 tools)
- [x] Confidence scoring
- [x] Offline session journaling
- [x] 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](https://github.com/AnonymousNomad)
- HuggingFace: [FerrellSyntheticIntelligence](https://huggingface.co/FerrellSyntheticIntelligence)

---

## License

MIT License — free for personal and commercial use.

---

<p align="center">
  <b>FELON Cortex</b> — <i>Every model deserves a brain.</i>
</p>