CognitiveOS

A local-first cognitive operating system for capturing, evolving, and querying your personal knowledge graph.

Version 1.0.0 — Production Release

---

Architecture

┌─────────────────┐     ┌───────────────────┐     ┌──────────────┐
│  Chrome Extension│────▶│  FastAPI Backend   │────▶│   Neo4j      │
│  (Plasmo)       │     │  (Python 3.11)     │     │   (Graph DB) │
└─────────────────┘     │                   │     └──────────────┘
                        │  Embedding Model  │
┌─────────────────┐     │  (BGE-Small 384d) │     ┌──────────────┐
│  Next.js 15     │◀───▶│                   │────▶│   LanceDB    │
│  (React 19)     │     │  12-Layer Evolution│     │   (Vector DB)│
└─────────────────┘     └───────────────────┘     └──────────────┘

Component	Technology	Purpose
Backend	FastAPI + Uvicorn	API server, embedding, graph sync
Frontend	Next.js 15, React 19, D3.js	Dashboard, graph visualization
Graph DB	Neo4j 5.x + APOC	Knowledge graph, relationships
Vector DB	LanceDB	Semantic search, embeddings
Extension	Plasmo (Chrome)	Browser capture, highlights
Embedding	BAAI/bge-small-en-v1.5	384-dim local embeddings

---

Quick Start (Local Development)

Prerequisites

• Python 3.11+
• Node.js 20+
• Neo4j 5.x (Community or Enterprise) — Download
• Git

1. Clone and configure

git clone <repo-url> CognitiveOS
cd CognitiveOS
cp .env.example .env
# Edit .env with your Neo4j password and desired settings

2. Start Neo4j

Start your Neo4j instance and ensure it's accessible at the URI in your .env file (default: bolt://localhost:7687).

3. Backend

cd backend
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

The first startup downloads the BGE-Small embedding model (~130 MB). Subsequent starts are instant.

4. Frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000 in your browser.

5. Browser Extension (optional)

cd extension
npm install
npm run dev

Then load the unpacked extension from extension/build/chrome-mv3-dev in chrome://extensions.

---

Docker Deployment

# Start all services (Neo4j + Backend + Frontend)
docker compose up --build

# Stop
docker compose down

The docker-compose.yml includes healthchecks — the frontend waits for the backend, and the backend waits for Neo4j.

Environment Variables

Variable	Default	Description
NEO4J_URI	bolt://localhost:7687	Neo4j Bolt endpoint
NEO4J_USER	neo4j	Neo4j username
NEO4J_PASSWORD	strongpassword123	Neo4j password
LANCEDB_URI	./data/lancedb	LanceDB storage path
BACKEND_CORS_ORIGINS	http://localhost:3000,http://127.0.0.1:3000	Comma-separated allowed origins
NEXT_PUBLIC_API_URL	http://localhost:8000	Backend URL for browser requests
REQUIRE_API_KEY	true	Enforce X-API-Key header
TRANSFORMERS_OFFLINE	0	Set to 1 after first model download

See .env.example for the complete list.

---

API Reference

The backend serves interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Key Endpoints

Method	Path	Description
GET	/health	Health check (embedding + DBs)
GET	/api/v1/status	System status
POST	/api/v1/memories	Store a new memory
GET	/api/v1/memories	List memories (paginated)
POST	/api/v1/memories/search	Semantic search
GET	/api/v1/graph	Knowledge graph data
POST	/api/v1/reasoning/query	Ask a question
GET	/api/v1/evolution/status	Evolution engine status
GET	/api/v1/timeline/events	Semantic timeline events
POST	/api/v1/auth/key	Generate API key

---

Knowledge Evolution Engine

The 12-layer autonomous evolution engine continuously improves graph quality:

Layer	Name	Schedule	Purpose
L1	Duplicate Merge	Fast (15m)	Merge near-duplicate nodes
L2	Abstraction	Daily	Abstract clusters into concepts
L3	Decay	Daily	Age-based relevance scoring
L4	Relevance Filter	Fast (15m)	Remove low-value noise
L5	Cluster Refresh	Daily	Re-cluster related nodes
L6	Relationship Prune	Daily	Remove stale edges
L7	Core Protection	Fast (15m)	Guard high-value nodes
L8	Budget Enforcement	Daily	Cap active node count
L9	Quality Snapshot	Daily	Record graph quality metrics
L10	Full Reindex	Weekly	Complete graph maintenance
L11	Lifecycle Promoter	Fast (15m)	Promote nodes through lifecycle
L12	Semantic Enricher	Daily	Replace generic with typed edges

Node Lifecycle

Source → Concept → KnowledgeCluster → AbstractConcept → CoreMemory

CoreMemory nodes are immutable — never pruned, archived, or demoted.

---

Project Structure

CognitiveOS/
├── backend/
│   ├── app/
│   │   ├── api/v1/endpoints/   # FastAPI route handlers
│   │   ├── core/               # Config, database manager
│   │   ├── models/             # Pydantic data models
│   │   ├── repositories/       # Neo4j & LanceDB data access
│   │   ├── schemas/            # API request/response schemas
│   │   ├── services/           # Business logic layer
│   │   ├── workflows/          # Scheduler, engine, definitions
│   │   └── main.py             # FastAPI application entry
│   ├── tests/                  # pytest test suite
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/                # Next.js pages
│   │   ├── components/         # React components
│   │   └── lib/                # API clients, utilities
│   ├── Dockerfile
│   └── package.json
├── extension/                  # Chrome extension (Plasmo)
├── docker-compose.yml
├── render.yaml                 # Render cloud deployment
├── Makefile
└── .env.example

---

Running Tests

cd backend
pip install pytest pytest-asyncio
python -m pytest tests/ -v

Tests are offline-safe — they run without Neo4j using graceful degradation patterns.

---

Deployment

Render

The render.yaml defines all services:

• cognitiveos-api — FastAPI backend with persistent disk
• cognitiveos-frontend — Next.js frontend
• cognitiveos-worker — Background job worker
• Cron jobs — Memory compression (daily) and consolidation (weekly)

Vercel (Frontend only)

cd frontend
npx vercel
# Set NEXT_PUBLIC_API_URL to your backend's production URL

Docker (Self-hosted)

docker compose up -d

---

Troubleshooting

Issue	Solution
Neo4j won't connect	Check NEO4J_URI, ensure Neo4j is running, verify credentials
Embedding model fails to load	Ensure internet access on first run; set TRANSFORMERS_OFFLINE=1 after download
Extension can't reach backend	Check PLASMO_PUBLIC_BACKEND_URL in extension/.env.chrome
CORS errors in browser	Add your frontend URL to BACKEND_CORS_ORIGINS
Graph shows no data	Capture some memories first; check /api/v1/memories/stats
Health endpoint shows "degraded"	One or more services (Neo4j, LanceDB, embedding) are offline

---

License

See LICENSE for details.