Karakeep — Roadmap
current version 0.32.0
8 directions
open milestone 0.33.0 (15 open)
state re-verified live via gh
Self-hostable "bookmark everything" — save links, notes, images, PDFs; crawl,
archive, AI-tag, embed, full-text-index, then search, read & organize across
web, mobile, browser extension, CLI and an agent-facing MCP server. Directions are
hypotheses (shabda) until the maintainer confirms them.
Next 3 moves
- Land the committed 0.33.0 milestone (D8). 15 open / 17 total. Gating items:
the maintainer-authored DB-lock fix #2669
(pri/high, size/XL) and chat/semantic-search (#863,
#441). Quick wins:
PR #2785 and
PR #2864 are MERGEABLE/CLEAN today.
- Decide the offline-mobile theme (D1).
#1077 "Offline cache on Mobile app."
has 51 reactions (most-reacted open issue in the repo, full-set of 588) and is in no milestone. Schedule it
or mark it deferred openly — don't let it stay silently un-owned.
- Give the stability cluster an owner (D5). The pinned memory-leak report
#2344 (54 comments) has
no PR. It sits on the worker-fleet spine every flow uses.
What this product is today — the verified ground, each line cited
Subsystems (real module boundaries)
Web app (Next.js)apps/web/ — app router, tRPC, NextAuth
Worker fleet (background jobs)apps/workers/workers/; queues.ts (11 queues)
AI / inferenceinference/, embeddingsWorker.ts; INFERENCE_*/EMBEDDING_*/OLLAMA_*
Crawler / archivalcrawlerWorker.ts, videoWorker.ts; CRAWLER_*/BROWSER_*
SearchsearchWorker.ts; Meilisearch; SEARCH_*
Data / persistencepackages/db/schema.ts — Drizzle / SQLite
API surface (tRPC + REST + SDK)packages/trpc/routers/, open-api, sdk; 0.32.0 granular API keys
Mobile app (React Native)apps/mobile/; 0.32.0 mobile revamp
Capture clients (ext + CLI + MCP)apps/browser-extension/, apps/cli/, apps/mcp/src/
Automation (RSS + rules + webhooks)feedWorker.ts, ruleEngineWorker.ts, webhookWorker.ts
Core capabilities
Full-text search (Meilisearch)searchWorker.ts; SEARCH_*
Vector embeddings / auto-indexingembeddingsWorker.ts; EMBEDDING_ENABLE_AUTO_INDEXING
LLM auto-tagginginferenceWorker.ts; INFERENCE_ENABLE_AUTO_TAGGING
LLM summarizationINFERENCE_ENABLE_AUTO_SUMMARIZATION; queues.ts type=summarize
OCR (image text extraction)OCR_*; tesseract.js
Link crawling & metadata fetchcrawlerWorker.ts (link_crawler_queue); CRAWLER_*
Full-page archival (monolith)CRAWLER_FULL_PAGE_ARCHIVE / CRAWLER_MONOLITH_*
Video archival (yt-dlp)videoWorker.ts; CRAWLER_VIDEO_DOWNLOAD
RSS auto-importfeedWorker.ts (feed_queue)
Rule-based automation engineruleEngineWorker.ts (rule_engine_queue)
Outbound webhookswebhookWorker.ts; schema webhooksTable
Bookmark importersimportWorker.ts; schema importSessions
Reader view + reading progressschema userReadingProgress/highlights; 0.32.0 reader
Collaborative & shared listsschema listCollaborators; trpc publicBookmarks.ts
Auth & SSO (NextAuth + OAuth)OAUTH_*; 0.32.0 granular API keys
Public REST API + SDK + API keyspackages/open-api + sdk; 0.32.0
MCP server (agent-facing)apps/mcp/src/; 0.32.0 official skill
CLIapps/cli/; 0.32.0 revamped CLI
Browser extensions (Chrome/FF/Safari)apps/browser-extension/; 0.32.0 Safari + SingleFile
Native mobile apps (iOS/Android)apps/mobile/; 0.32.0 mobile revamp
Bulk actions & multi-language UIREADME bulk/i18n/dark mode; 0.32.0 shortcuts
Domain entities: Bookmark · List · Tag · Highlight ·
Asset · User & account · RSS feed · Rule · Custom prompt — all in packages/db/schema.ts.
How it works today — one core estafeta, traced over the Bookmark lifecycle
Save bookmark (capture) user saves link/note/file (web/mobile/extension/CLI/MCP)
→ Bookmark row created, crawl job enqueued [trpc bookmarks.create; mcp create-bookmark]
↓
Crawl & enrich link crawler fetches title/description/image/screenshot, optional archive/video
→ stores Assets → enqueues AI + index jobs [crawlerWorker.ts / link_crawler_queue]
↓
AI tag, summarize & embed inference + embeddings workers call OpenAI/Ollama → attach Tags + summary,
produce embedding vector [inferenceWorker.ts / openai_queue; embeddingsWorker.ts]
↓
Index for search search-indexing writes Meilisearch full-text index; embeddings persist the vector
[searchWorker.ts / searching_indexing]
↓
Search & retrieve user/agent queries → full-text Meilisearch search → returns Bookmarks
[trpc bookmarks search; mcp search-bookmarks]
↓
Read & highlight user reads in reader view → reading progress persisted → Highlights stored
[schema userReadingProgress/highlights]
The whole chain runs on the Worker fleet over the shared
SQLite substrate — which is why the stability cluster (D5) sits under every direction.
Directions — in anantara order
D8 — The 0.33.0 release ships committed
Extends cross-cuts all subsystems — a scheduled release slice, not a single capability.
Telos the committed next-release milestone lands.
Karta Lead maintainer (@MohamedBassem, OWNER) — committed.
| # | Title (verbatim) | Author | State |
|---|
| #2882 | Add title and favourites button to browser extension | @shannonr | open |
| #2817 | Screenshot previewer does not show scroll bar | @Summon528 | open · fix PR #2864 CLEAN |
| #2798 | [bug][ux] Autosaving tags can autoclose the edit window when in the removed tag's feed | @NotaInutilis | open |
| #2752 | RSS downstream should return full content | @wesamjabali | open |
| #2694 | feat: Introduce bookmark "trash" and undo deletion button | @esimkowitz | open |
| #2669 | bug: removing accounts with large number of bookmarks can lock the database for a long period of time (aka background reaping support) | @MohamedBassem | open · pri/high, size/XL · also D5 |
| #2667 | feat: allow previewing rule engine rules | @MohamedBassem | open |
| #2660 | feat: Agentic interaction improvements for search and content extraction | @MohamedBassem | open · also D2 |
| #2594 | Links from collaborators are not visible in public lists | @karabays | open · pri/high |
| #2591 | [FR] Basic article TTS | @zblesk | open |
| #2502 | Saving a page that was previously saved fails | @Garrett-R | open |
| #2172 | Uncertain origin of alpine chrome image | @MemQu | open · pri/high |
| #1592 | Share single bookmark to anyone | @Draky50110 | open · 8 reactions |
| #863 | Chat about your bookmarks | @sherry-ummen-zalando | open · 15 reactions · also D2 |
| #441 | [Feature request] Selfhosted semantic search | @JojiiOfficial | open · 7 reactions · also D2 |
Honest scope: telos is "the milestone lands", not "every issue resolved".
15 open + 2 closed = 17 total; several items also drive D2/D5 and progress there.
Next: merge
PR #2864 (CLEAN); land #2669; decide chat/semantic scope.
D1 — Mobile becomes offline-first ready
Extends Native mobile apps (iOS/Android) — apps/mobile/; 0.32.0 mobile revamp.
Telos usable on the phone without a live server — saves queue offline, content caches for offline reading, Android share/save stops dropping items.
Karta Mobile maintainer (@esimkowitz, MEMBER) + contributor community.
| # | Title (verbatim) | Author | Live engagement |
|---|
| #1077 | Offline cache on Mobile app. | @venci1ty | 51 reactions / 8 comments — most-reacted open issue in the repo (full-set, 588 open); no milestone |
| #274 | Feature Request: Cache Hoards while away from server. | @hockeygoalie35 | 20 reactions / 3 comments; no milestone |
| #2401 | "Offline" mode for mobile app to store links until it's connected again | @alexlucasdev | 18 reactions / 14 comments; no milestone |
| #237 | Mobile app: don't open after hoarding | @DominikBritz | 12 reactions, pri/high; no milestone |
| #880 | SSO on android | @jakob1379 | open (shared with D6) |
| #2781 | Add swipe actions on mobile apps | @jibe-b | open, Backlog milestone |
Carrier PRs (mobile polish under the revamp) — all currently
CONFLICTING, need a rebase:
#2538,
#2733,
#2306,
#2282.
Already merged: #2837, #2788, #2794.
Open risks: offline-first needs a conflict/sync design (queued saves vs server
state), not yet modeled; four mobile reliability bugs (Android share-menu save, frequent hoard
failures, a crash, action-bar whitespace — pri/high) must be fixed before any offline path is trusted.
anantara none — client-side offline queueing does not block on backend work.
D3 — AI tagging becomes provider-flexible and operator-tunable ready
Extends LLM auto-tagging — inferenceWorker.ts; INFERENCE_ENABLE_AUTO_TAGGING.
Telos the AI subsystem becomes model-agnostic + operator-controllable — native Anthropic provider, configurable temperature/reasoning, richer custom prompts, an eval harness.
Karta Contributor community + Lead maintainer (@MohamedBassem).
| # | Title (verbatim) | Author | Live state |
|---|
| #2189 | Feature Request: Enhanced Prompt Customization for Advanced Tagging Workflows | @DaveG7 | open · 28 reactions / 0 comments |
| #2612 | Feature Request: Allow configuring reasoning behavior (e.g. disable reasoning) for LLM calls | @dennisvanderpool | open |
| #185 | How to verify hoarder app is working with the local ollama | @lihw | open (support question) |
| PR #2785 | feat(inference): make it possible to configure llm temp and default to 0 | @MohamedBassem | MERGEABLE/CLEAN — ready |
| PR #2890 | feat(inference): add native Anthropic (Claude) provider | @johnford2002 | MERGEABLE, CI UNSTABLE — get CI green |
| PR #2888 | Fix headers timeout for AI interference jobs. | @eriktews | MERGEABLE, CI UNSTABLE |
| PR #2876 | fix(inference): add OpenAI request timeout config | @optix2000 | merged |
#2189 (28 reactions) asks to
improve custom prompts, which already ship (schema
customPrompts; trpc
routers/prompts.ts) —
a
delta on an existing capability, not a new one.
anantara none inbound; D2 is sequenced heuristically after this.
D4 — Crawler becomes resilient on hostile pages ready
Extends Link crawling & metadata fetch — crawlerWorker.ts (link_crawler_queue); CRAWLER_*.
Telos archival becomes dependable on the pages it currently fails — GDPR/cookie walls, Reddit, Twitter/X, content-type detection, image-download failures stop breaking the whole crawl; archive.org fallback.
Karta Contributor community.
| # | Title (verbatim) | Author | Live state |
|---|
| #414 | Bypassing cookie and GDPR banner | @TurbulenceDeterministe | open · 40 reactions / 63 comments, pri/high, v0.27.0 (never shipped) — top crawler pain |
| #739 | Reddit full page archiving. | @nicktheone | open · 15 reactions / 31 comments |
| #1652 | [FR] Option to enable archive.org as a middle-man | @MelanieTanaka | open · 15 reactions |
| #1468 | [Request] Save Twitter/x.com thread | @AlejandroAkbal | open · 11 reactions |
| #329 | [FR] Support uploading SingleFile `.html` files from local filesystem. | @huyz | open · 12 reactions, v0.27.0 |
| #815 | Failed to determine the content-type for the url | @GreenMonito | open (bug) |
| PR #2675 | fix(crawler): strip Twitter/X reply articles before Readability extraction | @howwohmm | MERGEABLE/CLEAN — ready |
| PR #2804 | feat(crawler): add ability to screenshot precrawled archives | @MohamedBassem | MERGEABLE/CLEAN — ready |
| PR #2887 | feat(workers): implement Reddit OAuth client credentials flow to bypass restrictions | @kunal-rathore-111 | MERGEABLE, CI UNSTABLE |
| PR #2488 | feat: Add content quality assessment and platform-specific renderers | @MohamedBassem | DRAFT + CONFLICTING — cannot merge |
Open risks: #414
(GDPR, 40 reactions) is the most-reacted
crawler item but is
unscheduled (never-shipped
v0.27.0 milestone) — top pain, no committed fix. Also: full-page archives broken after CSP blocklist;
a single image-download failure failing the whole crawl.
anantara none.
D5 — The server becomes stable under load deferred-but-real
Extends Link crawling / Worker fleet — apps/workers/workers/, queues.ts (the shared spine).
Telos a self-hosted instance becomes trustworthy on a small box over time — memory growth, CPU spikes, idle-Chromium burn, large-image grid lag, DB locks resolved.
Karta community-requested & maintainer-owned but UNCOMMITTED — no PR carriers yet (the explicit deferred-but-real direction).
| # | Title (verbatim) | Author | Live engagement |
|---|
| #2344 | [BUG] Memory leak in 0.30 (with Pangolin) - RAM usage continuously growing over time | @nkkfs | open · 54 comments, pinned; no PR — loudest stability signal, unowned |
| #1748 | Bug: High memory usage on karakeep worker during large imports (and crawlings in general) | @Garrett-R | open · 15 comments, pri/high, Backlog |
| #517 | [Bug] Degraded performance when rendering large images in the bookmarkgrid | @Antebios | open · 22 comments |
| #2669 | bug: removing accounts with large number of bookmarks can lock the database for a long period of time (aka background reaping support) | @MohamedBassem | open · 0.33.0, pri/high, size/XL — the one committed stability item |
| #902 | Loading main page makes server CPU max out | @freakshock88 | open · 16 comments |
| #674 | Failed to connect to the browser instance, will retry in 5 secs | @snowdream | open (browser-instance retry loop) |
Open risks: the whole direction is risk-carried. The pinned
#2344 (54 comments) has no PR — the loudest
stability signal is unowned. These sit on the shared spine (see Reading of the field → S1).
anantara none formally; in practice instability undercuts every other direction's runtime.
D6 — Auth re-platforms to better-auth ready
Extends Auth & SSO (NextAuth + OAuth) — config OAUTH_*; 0.32.0 granular API keys.
Telos auth moves off next-auth onto better-auth — configurable OAuth signing, reverse-proxy header auth, consistent SSO across web + Android.
Karta Lead maintainer (@MohamedBassem), contributor-supported.
| # | Title (verbatim) | Author | Live state |
|---|
| #511 | [FR] Add support for authentication proxy headers | @cyruz-git | open (icebox) |
| #880 | SSO on android | @jakob1379 | open (shared with D1) |
| PR #2057 | feat: Migrate from next-auth to better-auth | @MohamedBassem | CONFLICTING/DIRTY — rebase before merge (large) |
| PR #2850 | feat: Add support for configurable ID token signing algorithm in OAuth | @CertStone | MERGEABLE, CI UNSTABLE |
| PR #2546 | fix: disable password change when password auth is disabled | @xingzihai | MERGEABLE/CLEAN — ready |
| PR #2630 | fix(browser-extension): API login error when server address includes /api/v1 | @xingzihai | MERGEABLE/CLEAN — ready |
Open question (graph): does the better-auth migration preserve existing
OAuth/SSO sessions and password logins? Answer before cutover.
Next: rebase
#2057 (do not merge while DIRTY); merge the clean
fixes
#2546 and
#2630 now.
anantara none.
D7 — Backup and portability become round-trip ready
Extends Bookmark importers — importWorker.ts; schema importSessions.
Telos the library becomes fully portable — import + export round-trip bookmarks plus list membership and nested structure, so self-hosters back up / migrate without loss.
Karta Contributor community.
| # | Title (verbatim) | Author | Live state |
|---|
| #75 | Feature: Import / Export for backup purposes | @georgzoeller | open · 14 reactions / 20 comments, pri/high, v0.27.0 (never shipped) |
| #2214 | Feature Request: Include Bookmark Lists When Exporting Bookmarks | @a21ns1g4ts | open · pri/high |
| #329 | [FR] Support uploading SingleFile `.html` files from local filesystem. | @huyz | open · 12 reactions, v0.27.0 (shared with D4) |
| PR #2746 | fix: Netscape to export nested structures | @california-gnatcatcher | MERGEABLE/CLEAN — ready |
Open question (graph): what must a full export include to be a true round-trip
(lists, nesting, assets)? Bookmarks-only export is not a true backup;
#75 has sat since v0.27.0 without shipping.
Next: merge
#2746 (clean); settle export scope.
anantara none.
D2 — Search becomes semantic and conversational sequenced after D3 (heuristic)
Extends Vector embeddings / auto-indexing — embeddingsWorker.ts; EMBEDDING_ENABLE_AUTO_INDEXING.
Telos retrieval becomes meaning-based and conversational — the embeddings substrate grows into self-hosted semantic search + chat/RAG over the user's bookmarks.
Karta Lead maintainer (@MohamedBassem) — both flagship asks are in the 0.33.0 milestone.
| # | Title (verbatim) | Author | Live state |
|---|
| #863 | Chat about your bookmarks | @sherry-ummen-zalando | open · 15 reactions, milestone 0.33.0 |
| #441 | [Feature request] Selfhosted semantic search | @JojiiOfficial | open · 7 reactions, milestone 0.33.0 |
| #2660 | feat: Agentic interaction improvements for search and content extraction | @MohamedBassem | open · milestone 0.33.0 |
Carrier PRs (embeddings substrate, shipping):
#2857 bookmark embedding support,
#2858 embeddings-based relevant tags in LLM context,
#2861 AI assistant component prep — all merged (@MohamedBassem).
anantara — HEURISTIC (kalpita, hypothesis, not fact): sequenced after D3.
No issue or PR states this dependency; the inference is architectural — chat/RAG reuses the
inference-provider layer, so it lands cleaner once AI tagging is provider-flexible. Both can progress
in parallel; D3 is not a hard blocker.
Open risks: "self-hosted" semantic search and chat lean on the under-anchored
MCP/embeddings spine and the REST/MCP surface — capabilities with no modeled flow (structural risk S1).
Deferred-but-real — high-signal items not yet on a direction deferred-but-real
Two of the repo's top-signal open issues don't cleanly fit any direction above.
They are not dropped — explicitly parked so the strongest community signal stays visible.
| # | Title (verbatim) | Author | Live engagement / where it lands |
|---|
| #1782 | Support for external databases (like Postgres) | @Mrtenz | 32 reactions / 5 comments — 3rd-most-reacted open issue, milestone Backlog. A SQLite→Postgres re-platform on the Data/persistence substrate under D5; own architectural bet, no carrier PR. Decide before chat/agentic load grows the DB. |
| #1166 | Feature request: provide a VNC client to log in user websites on the Hoarder puppeteer instance | @nicktheone | 0 reactions / 39 comments — 3rd-most-commented open issue. An authenticated-crawl / login-wall ask adjacent to D4; candidate to fold into D4's hostile-page scope. |
Reading of the field — the methodology view
Driving kartas (who owns each direction)
• Maintainer-led & committed: D8 0.33.0, D2 search/chat (0.33.0-milestoned), D6 auth (PR #2057), D5's one committed item #2669 — all Lead maintainer @MohamedBassem.
• Contributor-led & needs-review: D3 AI tagging, D4 crawler, D7 backup — carriers split between MERGEABLE/CLEAN and CONFLICTING; several need a rebase.
• Mobile-maintainer-led: D1 offline-first (@esimkowitz) + community.
• Community-requested & largely UNOWNED: D5 server-stability (pinned leak #2344, 54 comments, no PR); D1's offline-cache theme is community-loud (#1077, 51 reactions) but unscheduled.
The real constraint is @MohamedBassem's finite attention: he already carries D8 + D2 + D6 + the one committed stability fix. D1 has a second owner; D3/D4/D7 are contributor-carried and need review bandwidth, not authoring.
Structural risks (from the graph's own tensions lens)
S1 — Five shipped capabilities have no producing/consuming flow ("dead-recipe").
OCR, RSS auto-import, outbound webhooks, the public REST API + SDK, and the agent-facing MCP server
are marked as shipped but no modeled flow exercises them. This matters because four of the eight
directions lean on exactly this under-anchored spine: D2 (chat/semantic) on MCP + embeddings; D8's
agentic item (#2660) and chat (#863) on the REST/MCP surface; the RSS-full-content ask (#2752) on the
webhook/RSS corner. Either Step 2 under-modeled these (seed the missing flows) or they are genuinely
passive surfaces — worth knowing before building chat/agentic on top of MCP/REST.
Core-spine backlog risks with structural weight (they sit on the estafeta every flow
passes through): #2344 memory leak (54 comments, pinned) degrades the Worker fleet; #2669 DB lock sits on
the SQLite substrate (the only committed stability item, 0.33.0); #902 / #674 CPU/idle-Chromium exhaustion
make the box unusable regardless of feature work. These drive D5.
Figure-on-ground map (each direction → the capability it consumes)
| Direction | Extends (shipped capability) | Primitive |
|---|
| D1 Mobile offline-first | Native mobile apps (iOS/Android) | apps/mobile/ |
| D2 Search semantic & conversational | Vector embeddings / auto-indexing | embeddingsWorker.ts |
| D3 AI tagging provider-flexible | LLM auto-tagging | inferenceWorker.ts |
| D4 Crawler resilient on hostile pages | Link crawling & metadata fetch | crawlerWorker.ts |
| D5 Server stable under load | Link crawling / Worker fleet (shared spine) | apps/workers/workers/, queues.ts |
| D6 Auth re-platforms to better-auth | Auth & SSO (NextAuth + OAuth) | config OAUTH_* |
| D7 Backup & portability round-trip | Bookmark importers | importWorker.ts |
| D8 0.33.0 release ships | cross-cuts all subsystems — a release slice | milestone 0.33.0 |
Every direction transforms something that already exists — none is a free-floating wish.
The two whose ground is under-anchored (D2 on MCP/embeddings; any chat/agentic work on REST/MCP)
are flagged by S1 — the one place where building forward outruns the modeled product.