🧠 KnowledgeOS

Your personal AI-powered knowledge management system.
Save anything from the web. Let AI score, summarize, and organize it — based on your profile, not generic algorithms.

---

📖 What is KnowledgeOS?

KnowledgeOS is a self-hosted knowledge vault — a place where everything you find on the internet lands, gets evaluated by AI, and either gets archived or filtered out.

Instead of mindlessly saving bookmarks you never revisit, KnowledgeOS uses a personalized AI scoring pipeline to decide how relevant each piece of content is to you — based on your hobbies, professional context, and learning goals.

Core flow

URL saved by user
      │
      ▼
[Ingestion Job] ──► Fetch metadata (title, image, description)
      │               YouTube API / Reddit JSON / OpenGraph
      ▼
[AI Analysis Job] ──► Score 0–100, verdict, summary, tags
      │                Based on your personal profile
      ▼
[Inbox] ──► Review ──► [Vault] (permanent archive)
                  └──► [Trash]

---

✨ Features

🤖 AI-Powered Inbox

• Every saved resource is scored 0–100 based on your personal profile
• AI generates a verdict, summary, and tags
• Scoring uses a two-axis system: Intrinsic Quality × Relevance to your profile
• Protects against keyword hallucination — "AI" in title ≠ match if content is a gimmick

📥 Inbox & 🏛️ Vault

• Inbox — staging area for new resources, shows AI score and verdict
• Vault — permanent curated archive with categories, notes, and detailed AI summaries
• One-click promotion from Inbox → Vault with automatic re-analysis
• Smart Mix — surfaces forgotten Vault items across different categories

🌐 Multi-source ingestion

Source	What gets fetched
YouTube	Title, channel, duration, views, transcript excerpt
Articles / Websites	Title, description, author, og:image, favicon fallback

🗂️ Categories & Tags

• User-defined categories for Vault organization
• AI suggests category based on existing ones (or proposes new)
• Auto-tagging with niche, profile-relevant vocabulary

👤 User Profile

• ProfessionalContext — who you are, what you do
• LearningGoals — what you want to learn
• Hobbies — your interests (genuinely used for scoring, not decoration)
• TopicsToAvoid — hard filter, caps score at 0–10

⚙️ Background Jobs

• Hangfire-powered async processing pipeline
• Automatic retry with error recovery job
• ErrorRecoveryJob — periodically rescues stuck resources

---

🏗️ Architecture

Backend

KnowledgeOS.Backend/
├── Controllers/          # REST API endpoints
├── Services/
│   ├── Ai/               # OpenRouter provider, AI service, prompt builder
│   ├── Content/          # YouTube, Reddit, Website content fetchers
│   ├── Processors/       # Resource processors
│   └── Abstractions/     # Interfaces
├── Jobs/                 # Hangfire background jobs (Ingestion, AI Analysis, Error Recovery)
├── Entities/
│   ├── Resources/        # Resource (base), VideoResource, ArticleResource, RedditResource
│   │   ├── InboxMetadata # AI score, verdict, inbox summary
│   │   └── VaultMetadata # Detailed summary, category, user notes
│   ├── Tagging/          # Tag, Category
│   └── Users/            # ApplicationUser, UserPreference
├── DTOs/                 # Data Transfer Objects
├── Data/                 # AppDbContext, EF Core (TPT strategy)
└── Migrations/           # EF Core migrations

Frontend

knowledgeos-frontend/
├── app/
│   ├── (auth)/
│   │   ├── login/        # Login page
│   │   └── register/     # Registration page
│   └── dashboard/
│       ├── inbox/        # Inbox view — scored resources awaiting review
│       ├── vault/        # Vault view — curated archive with filters
│       ├── add/          # Add new resource by URL
│       ├── settings/     # User preferences & account settings
│       └── layout.tsx    # Dashboard shell with navigation
├── components/
│   ├── InboxCard.tsx     # Resource card for inbox (score, verdict, tags)
│   ├── InboxDetailModal.tsx  # Full resource detail view for inbox
│   ├── VaultCard.tsx     # Resource card for vault (category, notes)
│   └── VaultDetailModal.tsx  # Full resource detail view for vault
└── lib/
    ├── api.ts            # All API calls (typed fetch wrappers)
    ├── types.ts          # Shared TypeScript types
    ├── categoryColor.ts  # Category color mapping utility
    └── ThemeProvider.tsx # Dark/light theme context

Key design decisions

• Table Per Type (TPT) — VideoResource, ArticleResource, RedditResource each have their own table, sharing the base Resources table
• 1:1 Metadata composition — InboxMetadata and VaultMetadata are separate tables linked by FK, not flat columns on Resource
• Global query filters — all queries are automatically scoped to CurrentUser.UserId
• AI provider abstraction — multiple models registered as IAiProvider, AiService tries them in order with fallback
• Next.js App Router — full server/client component split, JWT stored in localStorage, all API calls typed via shared lib/types.ts

---

🚀 Getting Started

Prerequisites

• .NET 10 SDK
• Node.js 20+
• PostgreSQL
• OpenRouter API key (free tier works)

Backend setup

1. Clone the repository

   git clone https://github.com/your-username/KnowledgeOS.git
   cd KnowledgeOS/KnowledgeOS.Backend

2. Configure environment
   Create a .env file in KnowledgeOS.Backend/:

   JWT_KEY=your_super_secret_jwt_key_min_32_chars
   OPENROUTER_API_KEY=sk-or-...

3. Configure appsettings.json

   {
     "ConnectionStrings": {
       "DefaultConnection": "Host=localhost;Port=5432;Database=knowledge_os;Username=postgres;Password=yourpassword"
     },
     "Ai": {
       "Model_1": "google/gemini-2.0-flash-exp:free",
       "Model_2": "meta-llama/llama-3.3-70b-instruct:free",
       "Model_3": "mistralai/mistral-small-3.1-24b-instruct:free"
     }
   }

4. Run migrations & start

   dotnet ef database update
   dotnet run

Frontend setup

cd KnowledgeOS/knowledgeos-frontend
npm install
npm run dev

Frontend runs on http://localhost:3000, backend on https://localhost:5001.

Docker — full stack

The entire stack (PostgreSQL, backend, frontend) can be run with a single command.

1. Copy and configure the environment file

   cp .env.example .env

   Open .env and set your values. The most important one is NEXT_PUBLIC_API_URL — this is the address the browser uses to reach the backend, so it must be your machine's actual IP (not localhost) if you want to access it from other devices on the network or expose it externally:

   # Local network (phone, tablet, other PC on the same WiFi)
   NEXT_PUBLIC_API_URL=http://192.168.1.100:5000/api
   
   # VPS / public server
   NEXT_PUBLIC_API_URL=https://api.yourdomain.com/api
   
   # Ports (change if you have conflicts)
   FRONTEND_PORT=3000
   BACKEND_PORT=5000
   
   # Secrets
   JWT_KEY=your_min_32_char_secret_here
   OPENROUTER_API_KEY=sk-or-...

2. Run

   docker compose up -d --build

3. Run database migrations (first time only)

   docker compose exec backend dotnet ef database update

   Service	Default address
   Frontend	http://localhost:3000
   Backend API	http://localhost:5000
   Swagger	http://localhost:5000/swagger
   Adminer (DB UI)	http://localhost:8080

   Tip: To find your local IP on Linux run ip route get 1 | awk '{print $7}'

---

📡 API Overview

Method	Endpoint	Description
POST	/api/auth/register	Register new user
POST	/api/auth/login	Login, returns JWT
GET	/api/auth/me	Get display name
PUT	/api/auth/me/password	Change password
PUT	/api/auth/me/display-name	Change display name
GET	/api/preferences	Get user preferences
PUT	/api/preferences	Update user preferences
POST	/api/resources	Save new resource (URL)
GET	/api/inbox	Get inbox resources (paged)
GET	/api/inbox/mix	Get smart mix (high/mid/low score)
GET	/api/vault	Get vault resources (paged, filterable)
GET	/api/vault/mix	Get vault rediscovery mix
PUT	/api/resources/{id}/status	Promote / trash resource
PUT	/api/resources/{id}/category	Assign category
DELETE	/api/resources/{id}	Two-step delete (Trash → permanent)
GET	/api/categories	List categories
POST	/api/categories	Create category
DELETE	/api/categories/{id}	Delete category

---

🛣️ Roadmap

🔧 In Progress

• Browser extension — save to KnowledgeOS directly from any webpage with one click
• Extension for Shortcut app for iOS — add to KnowledgeOS from iPhone share sheet

📋 Planned

Core Features

• PWA (Progressive Web App) — installable mobile/desktop app with offline support and home screen shortcut
• Vector search — semantic similarity search across saved resources using embeddings
• Reddit as a source — support saving Reddit posts and comments with appropriate metadata and AI analysis

AI & Intelligence

• AI re-analysis — manually trigger re-analysis after updating your profile
• Duplicate detection — warn when saving content already in vault (semantic, not just URL match)
• Trend surfacing — detect recurring themes across saved resources

Organization

• Nested categories — subcategories for deeper organization
• Collections / reading lists — group resources manually across categories
• Resource relations — link related resources together

UX & Settings

• Settings page — manage account, preferences, AI model choice, and danger zone
• Admin panel — user management, job queue monitoring, system health
• Password reset via email — forgot password flow with email token
• Email verification — verify email on registration

Integrations

• Pocket / Readwise import — migrate existing bookmarks
• Obsidian export — export vault as Obsidian-compatible Markdown vault
• RSS / Atom feed ingestion — auto-import from feeds

---

🖼️ Screenshots

---

🧰 Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript, Tailwind CSS 4
Backend	ASP.NET Core 10, C#
Database	PostgreSQL + EF Core 10 (TPT)
Auth	ASP.NET Core Identity + JWT
AI	OpenRouter API (multi-model with fallback)
Background Jobs	Hangfire + PostgreSQL storage
Content Fetching	YoutubeExplode, HtmlAgilityPack, Reddit JSON API
API Docs	Swagger / OpenAPI

---

📄 License

MIT License — see LICENSE for details.

---

_{Built with curiosity, need and too many saved tabs. Also with a dash of AI (especially frontend ^^)}