Architecture

LearnOS has one rule: one workspace, three ways in. The web app at learnosapp.com, the hosted MCP server, and the CLI all read and write the same library through the same auth and the same row-level security. There's no "CLI sync" or "web app sync" — every surface sees the canonical state of your library.

                            Your LearnOS workspace
              ┌───────────────────────────────────────────────┐
              │   Courses · Lessons · Notes · Flashcards       │
              │   Reviews · Highlights · Projects · Chats      │
              │   Indexed for keyword + semantic search        │
              └───────────────────────────────────────────────┘
                       ▲                ▲                ▲
                   Web app          Hosted MCP          CLI
              learnosapp.com   learnosapp.com/mcp     `learnos`
                                    (OAuth)        (learnos login)

Citation-grounded retrieval

When you chat with a lesson — or ask a question across your library — LearnOS doesn't just hand the model your raw markdown. It:

1. Splits each lesson into sections scoped by heading (H2–H4). A "section" is the unit a citation points at.
2. Embeds each section with a 1536-dimension vector so semantic search works ("how do promises resolve?" finds a section about microtasks even if the words don't match).
3. Retrieves with both signals. A query runs a keyword search and a semantic search in parallel, then Reciprocal Rank Fusion mixes the rankings — neither signal wins outright, both contribute.
4. Anchors every assistant claim to specific sections. The model emits inline citation markers (cite:LESSON_ID#ANCHOR) which LearnOS resolves into the citation tabs you see in the chat side panel.

The result: every answer is traceable to the lesson sections it came from. Hallucinations are easier to spot because every assertion has a clickable source.

Multi-user, scoped by row-level security

Every read and every write in LearnOS — from the web app, from MCP, from the CLI — runs under the calling user's identity. When you connect with OAuth (the default for MCP clients and learnos login), your session token reaches the database and row-level security clamps every result to your library, exactly as in the web app.

Personal access tokens are the exception. They exist for CI and clients that can't complete a browser flow, and a PAT request runs through a trusted server client that filters by the token owner in application code instead of through row-level security. PATs also carry full access and expire after 90 days.

What the surfaces share, what's unique

• Web app is the primary UI: rich lesson view, side-panel chat, flashcard reviews, study guides, notes editor, highlights, projects, command palette.
• Hosted MCP lets a model client (Claude Code / Desktop / Cursor) call tools against your library — list_courses, search_lessons, get_lesson, create_flashcard, append_note, and more. See the MCP reference.
• CLI wraps the same primitives for shell use: learnos courses, learnos search, learnos ask, learnos course quality, and so on. See the CLI reference.

What's unique to each surface is the user experience, not the data. Any write you make from one surface is visible from every other surface the moment it returns.