"Reach into your pocket and pull out exactly what you need."

Self-hosted, AI-powered personal knowledge base
Save content from 17+ platforms. AI auto-tags, summarizes, and connects it. Find anything instantly.

GitHub · onllm.dev · Chrome Web Store · Support 4DPocket

Everyone saves things — bookmarks, articles, videos, code snippets, social posts — across dozens of platforms. Then can never find them again.

4DPocket is not a bookmark manager. It's a knowledge base that thinks. Paste a URL — the system extracts the full content, auto-tags it, generates a summary, connects it to what you already know, and makes it instantly searchable. Notes, highlights, collections, reading lists, RSS feeds, and automation rules turn it into a second brain.

Inspired by Doraemon's 4D Pocket — a magical, bottomless pocket where anything you've ever saved is instantly retrievable.

Pull the image from GitHub Container Registry:

docker pull ghcr.io/onllm-dev/4dpocket:latest
# or a specific version:
docker pull ghcr.io/onllm-dev/4dpocket:0.2.0

One-liner (SQLite, no external services):

docker run -d --name 4dpocket -p 4040:4040 -v 4dp-data:/data \
  ghcr.io/onllm-dev/4dpocket:latest

Open http://localhost:4040 — no login needed in single-user mode.

Full stack (PostgreSQL + background worker):

# Clone or download config files
curl -O https://raw.githubusercontent.com/onllm-dev/4DPocket/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/onllm-dev/4DPocket/main/.env.example
cp .env.example .env     # Edit with your settings

# Start
docker compose up -d

Open http://localhost:4040 — first registered user becomes admin.

Minimal setup (SQLite, single container):

curl -O https://raw.githubusercontent.com/onllm-dev/4DPocket/main/docker-compose.simple.yml
docker compose -f docker-compose.simple.yml up -d

With local AI (Ollama):

docker compose --profile ai up -d
docker compose exec ollama ollama pull llama3.2

With Meilisearch (full-text search):

SEARCH_BACKEND=meilisearch docker compose --profile search up -d

With semantic search (ChromaDB):

docker compose --profile vectors up -d

All services:

docker compose --profile ai --profile search --profile vectors up -d

Available on PyPI:

pip install 4dpocket

# First-time setup wizard (database, AI provider, auth mode)
4dpocket setup

# Start the server
4dpocket start

# Or start with a specific profile:
4dpocket start --sqlite              # Zero-config, no Docker needed
4dpocket start --postgres            # PostgreSQL + Meilisearch (auto-starts Docker)
4dpocket start --full                # Full stack (+ ChromaDB + Ollama)

# Background (daemon) mode
4dpocket start --sqlite -d

Open http://localhost:4040 — the setup wizard runs automatically on first start if no config exists.

Note: The PyPI package name is 4dpocket, but the Python import is fourdpocket (Python identifiers can't start with a digit). Optional extras: pip install 4dpocket[postgres], 4dpocket[semantic], 4dpocket[processors], 4dpocket[all].

git clone https://github.com/onllm-dev/4DPocket.git
cd 4DPocket

# Backend
uv sync --all-extras
make dev                    # → http://localhost:4040

# Or via CLI
4dpocket start --reload     # → http://localhost:4040

# Frontend (separate terminal)
cd frontend && pnpm install && pnpm dev   # → http://localhost:5173

No login needed in single-user mode.

Run the app from source while using Docker for PostgreSQL, Meilisearch, or Ollama:

# Start PostgreSQL with pgvector (enables vector search without ChromaDB)
docker run -d --name 4dp-postgres -p 5432:5432 \
  -e POSTGRES_USER=4dp -e POSTGRES_PASSWORD=4dp -e POSTGRES_DB=4dpocket \
  pgvector/pgvector:pg16

# Run backend against PostgreSQL with multi-user auth
FDP_DATABASE__URL=postgresql://4dp:4dp@localhost:5432/4dpocket \
FDP_AUTH__MODE=multi make dev

Add Meilisearch, Ollama, ChromaDB, or cloud AI — see the Development Guide for all combinations.

FDP_AUTH__MODE=multi make dev

First registered user automatically becomes admin.

The 4dpocket command provides full lifecycle management — setup, start/stop, database, Docker services, and maintenance.

4dpocket setup                       Interactive first-run wizard
4dpocket start [--sqlite|--postgres|--full]  Start server with profile
4dpocket start -d                    Start in background (daemon mode)
4dpocket stop                        Stop background server
4dpocket restart                     Restart server
4dpocket status                      Show server + Docker service status
4dpocket logs                        Tail server logs

4dpocket db init                     Create database tables
4dpocket db reset [-y]               Drop + recreate database (destructive)
4dpocket db migrate                  Run Alembic migrations
4dpocket db shell                    Open psql or sqlite3 CLI

4dpocket services up [postgres meili chroma ollama all]
4dpocket services down [names...]
4dpocket services status

4dpocket clean                       Remove logs, PID files, caches
4dpocket version                     Show version

The setup wizard configures database (SQLite/PostgreSQL), AI provider (Ollama/Groq/NVIDIA/Custom/None), auth mode, and server port. Configuration is saved to ~/.4dpocket/.env.

Start profiles auto-manage Docker containers — --postgres starts PostgreSQL + Meilisearch, --full adds ChromaDB + Ollama. No manual docker run needed.

4DPocket ships a built-in Model Context Protocol server at /mcp, letting Claude Desktop, Cursor, Claude Code, Codex, and any other MCP-capable agent use your knowledge base as persistent memory.

Ten tools are exposed, covering the full persist-recall-navigate-update-delete cycle:

In the app: Settings → API Tokens & MCP → New token. Choose:

• Role: viewer (read-only) or editor (read + write)
• Access: All collections, or specific collections (plus optional "uncollected items" toggle)
• Allow deletion: optional, editor-only
• Admin scope: optional, admins only — gates /api/v1/admin/*
• Expiry: Never / 30d / 90d / 1 year / 2 years

The plaintext token is shown once. Copy it immediately — it's stored only as a sha256 hash.

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "4dpocket": {
      "url": "http://localhost:4040/mcp",
      "headers": { "Authorization": "Bearer fdp_pat_..." }
    }
  }
}

Cursor — ~/.cursor/mcp.json (same shape as above).

Claude Code / Codex / other — use the Raw JSON template from the Settings page.

Stdio-only clients — if your client can't speak streamable HTTP directly, use the published npm launcher @onllm-dev/4dpocket-mcp:

{
  "mcpServers": {
    "4dpocket": {
      "command": "npx",
      "args": ["-y", "@onllm-dev/4dpocket-mcp",
               "--url", "https://your.pocket.tld",
               "--token", "fdp_pat_..."]
    }
  }
}

Ask your agent things like:

• "Save this article to my 'research' collection."
• "What did I save last month about FastAPI?"
• "Show me everything related to the 'async patterns' concept."
• "Regenerate the synthesis for the Postgres entity."

Collection-scoped tokens only return items the user authorized. Viewer tokens cannot call write tools. Admin endpoints reject PATs without admin_scope.

Each entity accumulates an LLM-authored structured synthesis as more items mention it. Regeneration is automatic (after 3+ mentions, throttled to once per 24h) or manual via POST /api/v1/entities/{id}/synthesize?force=true / the Regenerate button in the UI. Visualize the full concept graph at Knowledge Graph in the sidebar.

Paste a URL and 4DPocket detects the platform, deeply extracts content, and enriches it with AI — all automatically.

Multi-Provider AI — Ollama (local), Groq, NVIDIA, or any OpenAI/Anthropic-compatible API. No vendor lock-in.

Every saved item goes through a stage-based enrichment pipeline with dependency tracking, retry support, and per-stage status monitoring:

Item Created
  ├─ chunked     → Section-aware chunking with provenance (kind, author, heading_path)
  ├─ tagged      → AI auto-tagging with confidence scores
  └─ summarized  → AI summary generation
       │
       ├─ embedded           → Generate embeddings (depends on: chunked)
       └─ entities_extracted → Extract entities + relations (depends on: chunked)

Independent stages run in parallel. Dependent stages auto-enqueue when prerequisites complete. Failed stages can be retried (up to 3 attempts). Monitor progress via GET /items/{id}/enrichment.

4DPocket uses a multi-stage retrieval architecture inspired by LightRAG, combining keyword search, vector similarity, and optional cross-encoder reranking for production-grade search quality.

Architecture:

Query → Keyword Backend ─────────────────────┐
Query → Vector Backend ──────────────────────┤→ N-ranker RRF → Reranker (optional) → Results
Query → Graph Ranker (entities, 1-hop) ─────┘  (opt-in)

Backend abstraction — pluggable KeywordBackend and VectorBackend protocols:

Search modes: Full-text, fuzzy fallback, semantic, hybrid (RRF), unified (items + notes). Inline filter syntax: docker tag:devops is:favorite after:2024-01. All 7 filter types supported across all backends.

Full-featured note-taking with a rich text editor (Tiptap).

• Create, edit, and organize notes alongside saved items
• Rich text editing — headings, bold, italic, strikethrough, code, lists, task lists, blockquotes, highlights
• Tag notes independently, search them alongside items
• AI summarization and title generation per note
• Highlights can link to notes (not just items)
• Notes appear in collections, knowledge base, and unified search

• Reading List — Dedicated "To Read" and "Read" tabs for managing your reading queue
• Reading Progress — Track reading progress (percentage) on any item
• Reading Status — Items move through unread → reading → read
• Timeline View — Browse your knowledge base chronologically

• Create named collections to organize items and notes
• Add items and notes to multiple collections
• Drag-and-drop reorder within collections
• Smart Items — AI suggests items that belong in a collection based on its contents
• Collection RSS — Every collection exposes an RSS feed for external consumption

• Highlight text within items or notes with color options
• Add annotation notes to highlights
• Position tracking (paragraph, sentence, start, end)
• Search across all highlights
• Chrome extension captures highlights directly from web pages

• Subscribe to RSS/Atom/JSON feeds
• Auto mode — New entries automatically saved to your knowledge base
• Approval mode — Entries queued for manual approve/reject
• Keyword filters per feed
• Manual fetch trigger, error tracking, entry management

• Condition-Action rules — "If URL matches reddit.com, auto-tag reddit and add to collection"
• Conditions: URL regex, source platform, title/content keywords, has tag
• Actions: add tag, add to collection, set favorite, archive
• ReDoS-safe regex execution with cross-platform timeout

• Share items, collections, or tag groups with specific users
• Public links — Generate public URLs with optional expiry
• Roles — Viewer or editor per share recipient
• Comments — Discuss shared items with collaborators
• Knowledge Feed — Follow other users' shared content
• Shared With Me — View all content shared to you

URL validation on import, content size caps (1MB content, 50K description), XSS-safe HTML export.

• User Management — List, activate/deactivate, change roles, delete users (with full cascade cleanup)
• Registration Control — Toggle open/invite/disabled, set max users
• AI Configuration — Change provider, API keys, model, base URL at runtime. Admin settings override .env
• Instance Settings — Name, default role, feature toggles

• Save complex search/filter combinations for quick re-use
• Execute saved filters with one click
• Full CRUD management

• Full CRUD with slug generation
• Tag Merge — Merge duplicate tags, combining their usage counts
• Merge Suggestions — AI suggests similar tags that could be consolidated
• Usage count tracking (auto-maintained on item/note add/remove)
• Browse items by tag

4DPocket is hardened for self-hosted production deployment:

• Installable on Android, iOS, desktop
• Service worker caches static assets for offline access
• Share Target — share URLs from your phone's share sheet directly to 4DPocket
• Responsive — mobile (bottom nav), tablet (collapsible sidebar), desktop (full sidebar + shortcuts)
• Dark mode — system-aware with manual toggle (Doraemon Blue theme)

Save pages with one click, highlight text on any page, view highlights in a sidebar. Published on the Chrome Web Store — install with one click, no manual zip upload needed.

Install from Chrome Web Store

Build from source:

cd extension && pnpm install && pnpm build

Load extension/dist/chrome-mv3 as an unpacked extension in chrome://extensions (Developer mode → Load unpacked).

• One-click save current page
• Right-click context menu save
• Auto-detect already-saved pages (badge indicator)
• Text highlight capture with floating tooltip
• Side panel for browsing highlights

• Cmd+K / Ctrl+K — Command palette (search, navigate, quick actions)
• n — Add new item
• / — Focus search
• Bulk select + bulk tag/archive/delete

All config via environment variables with FDP_ prefix. See .env.example.

# Core
FDP_AI__CHAT_PROVIDER=ollama          # ollama, groq, nvidia, or custom
FDP_SEARCH__BACKEND=sqlite            # sqlite (zero-config) or meilisearch
FDP_AUTH__MODE=single                 # single (no login) or multi (JWT)

# Search & Retrieval
FDP_SEARCH__VECTOR_BACKEND=auto       # auto (pgvector for Postgres, chroma for SQLite), chroma, pgvector
FDP_SEARCH__CHUNK_SIZE_TOKENS=512     # Target chunk size for content splitting
FDP_SEARCH__CHUNK_OVERLAP_TOKENS=64   # Overlap between adjacent chunks
FDP_SEARCH__GRAPH_RANKER_ENABLED=true  # Third RRF input from the concept graph (default on; admin-disableable)
FDP_SEARCH__GRAPH_RANKER_HOP_DECAY=0.5 # Neighbor contribution multiplier (0.0-1.0)
FDP_SEARCH__GRAPH_RANKER_TOP_K=50      # Max items returned by the graph ranker

# Reranker (optional, improves search precision)
FDP_RERANK__ENABLED=false             # Enable cross-encoder reranking
FDP_RERANK__MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2

# Enrichment
FDP_ENRICHMENT__EXTRACT_ENTITIES=false  # Enable entity extraction for concept graph
FDP_ENRICHMENT__SYNTHESIS_ENABLED=true   # LLM-authored entity wiki pages
FDP_ENRICHMENT__SYNTHESIS_THRESHOLD=3    # Regen after N new item mentions
FDP_ENRICHMENT__SYNTHESIS_MIN_INTERVAL_HOURS=24

# Embeddings
FDP_AI__EMBEDDING_PROVIDER=local      # local (sentence-transformers) or nvidia
FDP_AI__EMBEDDING_MODEL=all-MiniLM-L6-v2  # pgvector dimension auto-detected from model

Or run 4dpocket setup for an interactive configuration wizard.

Interactive docs at http://localhost:4040/docs when running.

Items — POST /items, GET /items, GET /items/{id}, PATCH /items/{id}, DELETE /items/{id}, POST /items/bulk, POST /items/{id}/archive, POST /items/{id}/reprocess, GET /items/{id}/related, GET /items/{id}/enrichment, PATCH /items/{id}/reading-progress, POST /items/{id}/download-video, GET /items/{id}/media-proxy

Notes — POST /notes, GET /notes, GET /notes/{id}, PATCH /notes/{id}, DELETE /notes/{id}, POST /notes/{id}/summarize, POST /notes/{id}/generate-title

Search — GET /search (full-text), GET /search/unified (items + notes), GET /search/hybrid (RRF fusion), GET /search/semantic (vectors), GET /search/filters

Tags — Full CRUD, GET /tags/{id}/items, GET /tags/suggestions/merge, POST /tags/merge

Collections — Full CRUD, item/note management, GET /collections/{id}/smart-items, GET /collections/{id}/rss, PUT /collections/{id}/items/reorder

Reading List — GET /items/reading-list, GET /items/read, GET /items/reading-queue, GET /items/timeline

AI — GET /ai/status, POST /ai/items/{id}/enrich, GET /ai/suggest-collection, GET /ai/knowledge-gaps, GET /ai/stale-items, GET /ai/cross-platform, POST /ai/transcribe

RSS — GET /rss, POST /rss, PATCH /rss/{id}, DELETE /rss/{id}, POST /rss/{id}/fetch, GET /rss/{id}/entries, POST /rss/{id}/entries/{id}/approve

Sharing — POST /shares, GET /shares, DELETE /shares/{id}, GET /public/{token}

Highlights — Full CRUD, GET /highlights/search

Comments — POST /items/{id}/comments, GET /items/{id}/comments, DELETE /items/{id}/comments/{id}

Entities — GET /entities, GET /entities/{id}, GET /entities/{id}/items, GET /entities/{id}/related, GET /entities/graph, POST /entities/{id}/synthesize

API Tokens (PATs) — POST /auth/tokens, GET /auth/tokens, DELETE /auth/tokens/{id}, POST /auth/tokens/revoke-all

MCP — Streamable-HTTP server at /mcp; see Using 4DPocket as an MCP Server

Admin — User management, AI config (GET/PATCH /admin/ai-settings), search config (GET/PATCH /admin/search-settings — graph ranker toggle), instance settings, saved filters

Auth — Register, login, logout, profile update, password change

Import/Export — POST /import/{source}, GET /export/{format}

4dpocket/
├── src/fourdpocket/           # Python backend
│   ├── cli.py                 # CLI entry point (4dpocket command)
│   ├── __main__.py            # python -m fourdpocket support
│   ├── api/                   # 26 FastAPI routers (items, search, entities, AI, ...)
│   ├── models/                # 26 SQLModel tables (items, chunks, entities, relations, ...)
│   ├── processors/            # 17 platform extractors
│   ├── ai/                    # Providers, tagger, summarizer, extractor, canonicalizer, LLM cache
│   ├── search/                # Search service + pluggable backends
│   │   ├── service.py         # SearchService orchestrator (keyword + vector + graph + RRF + rerank)
│   │   ├── base.py            # Protocol definitions (KeywordBackend, VectorBackend, Reranker, GraphHit)
│   │   ├── graph_ranker.py    # Graph-anchored ranker (opt-in third RRF input; entities + 1-hop)
│   │   ├── backends/          # Backend implementations
│   │   │   ├── sqlite_fts_backend.py   # SQLite FTS5 (item + chunk search)
│   │   │   ├── chroma_backend.py       # ChromaDB vector store
│   │   │   ├── pgvector_backend.py     # pgvector with HNSW (auto-dimension)
│   │   │   └── meilisearch_backend.py  # Meilisearch keyword + chunk indexing
│   │   ├── chunking.py        # Content chunking (paragraph/sentence/word split)
│   │   ├── reranker.py        # NullReranker + LocalReranker (cross-encoder)
│   │   └── filters.py         # Inline filter syntax parser
│   ├── sharing/               # Share manager, permissions, feed manager
│   ├── workers/               # Background tasks
│   │   ├── enrichment_pipeline.py  # Stage-based enrichment (chunk→embed→tag→summarize→entities)
│   │   ├── fetcher.py         # URL content extraction
│   │   └── ...                # Media, archiver, RSS, rules, scheduler
│   └── storage/               # User-scoped file storage
├── frontend/                  # React 19 PWA
│   └── src/
│       ├── pages/             # 22 page components
│       ├── components/        # UI components (editor, cards, dialogs, layout)
│       ├── hooks/             # TanStack Query hooks + keyboard shortcuts
│       └── stores/            # Zustand UI state
├── extension/                 # Chrome browser extension
├── tests/                     # 304 pytest tests (incl. PAT + MCP + synthesis)
├── Dockerfile                 # Multi-stage build
├── docker-compose.yml         # Full stack (pgvector/pgvector:pg16 for vector support)
└── .env.example               # Configuration reference

See the full Development Guide for detailed setup instructions, hybrid configurations, and troubleshooting.

make dev        # Start dev server (hot reload)
make test       # Run test suite (304 tests)
make lint       # ruff check
make format     # ruff format
make test-cov   # Tests with coverage report

See CONTRIBUTING.md for contribution guidelines, code conventions, and how to add platform processors.

• Android — Native app with share intent and offline support
• iOS — Native app with share extension and widget support

GNU General Public License v3.0 — see LICENSE for details.

Built with ❤ by onllm.dev

onllm.dev · GitHub · Support 4DPocket