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`
                                  (Bearer PAT)       (LEARNOS_TOKEN)

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. The database itself enforces who can see what; the application code never has to remember to filter by user. This is true for the hosted MCP and CLI just as much as the web app — a personal access token attributes every call to its owner, and row-level security clamps results to that user's library.

Lesson writes are searchable immediately

Whether you add a course from the web, the CLI, or the MCP, the lesson is chunked and embedded inline with the write. Keyword search and semantic search are both live the moment the write returns — there's no separate indexing step you have to wait for. Notes are the one exception: they persist immediately but enter semantic search asynchronously.

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 ~20 tools against your library — list_courses, search_lessons, add_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.