Content
# SiftMarks
English | [简体中文](./README.md)
[](https://github.com/Lling0000/SiftMarks/actions/workflows/ci.yml)
[](./LICENSE)
**Turn your Chrome bookmarks into a local-first, searchable, reviewable, and AI-usable private context layer.**
SiftMarks is not just another cloud-based bookmark manager. It starts with your existing browser bookmarks and transforms them into a local SQLite bookmark library, where AI only generates suggestions, and you must review and confirm before making any changes to Chrome.
[Get Started](#get-started) · [Chrome Workflow](#chrome-workflow) · [20-second Demo](./docs/demo/siftmarks-demo.mp4) · [Privacy Model](./docs/PRIVACY.md) · [Roadmap](./docs/ROADMAP.md)
## 30-second Overview
```text
Import Chrome bookmarks
-> Discover duplicates, broken links, vague titles, and misplaced folders
-> Review and accept or ignore suggestions like reviewing a Pull Request
-> Confirm before writing back to Chrome
-> Turn bookmarks into AI-usable local context through search and MCP
```
## Core Value
SiftMarks' core value is not "automatically organizing everything for you" but creating a secure, closed-loop bookmark organization process:
- **Local Import**: Data is stored in `~/.siftmarks/siftmarks.sqlite` by default.
- **Suggestion Generation**: Titles, tags, categories, duplicates, and broken links are listed for review.
- **Review before Write-back**: Web panel prepares sync plans, but actual Chrome modifications are executed and confirmed by the extension.
- **AI Opt-in**: Mock mode does not call external models; AI actions are only triggered after you configure a Provider.
- **MCP Optional**: Expose your local bookmark library to MCP-enabled clients like Claude, Cursor, and Windsurf.
## Who is it for?
- Developers, researchers, and creators with years of bookmark accumulation, seeking to rediscover "I know I bookmarked this."
- Users who want to organize Chrome bookmarks into a searchable knowledge base without relying on cloud services.
- Individuals who want AI tools to retrieve their collected web pages, documents, projects, and materials while maintaining local control.
- Users requiring a review-based organization process: AI suggests, and you decide whether to accept, with Chrome not being silently modified.
## Current Capabilities
| Capability | Current Status | Limitations |
| --- | --- | --- |
| Chrome Bookmark Import | Available, supported by web and extension | Extension import preserves Chrome ID for write-back |
| Save Current Page | Available, extension calls local service | Original folder used if page is already bookmarked in Chrome |
| Local Bookmark Library | Available, stored in SQLite | Default path `~/.siftmarks/siftmarks.sqlite` |
| Keyword Search | Available, based on SQLite FTS | No AI Provider needed |
| Memory Search | Available, uses embedding by default | Falls back to keyword results if no embedding |
| Organization Suggestions | Available, supports title, move, tags, duplicates, broken links | Suggestions reviewed before Chrome changes |
| Write-back to Chrome | Available, executed through extension | Requires user confirmation in extension |
| AI Metadata | Available, supports OpenAI-compatible and Ollama-compatible | Mock mode does not call external models |
| MCP Server | Available | Only accessible to configured MCP clients |
| General User Package | Not released | Currently source code run + Chrome developer load |
## Trust Boundaries
| Scenario | Default Behavior | Potential Exceptions | Notes |
| --- | --- | --- | --- |
| Bookmark Library | Stored locally in SQLite | No automatic export | Backup `~/.siftmarks/siftmarks.sqlite` before critical operations |
| Chrome Extension | Only connects to `http://localhost:4399` | No external service access | Used for import, save current page, and write-back |
| AI | Mock mode, no model calls | Configured cloud OpenAI-compatible Provider and AI actions | Relevant titles, URLs, summaries, or content fragments may be sent to the Provider |
| Local Model | No cloud Key required | Depends on your deployment if not local | SiftMarks calls based on your endpoint configuration |
| Chrome Write-back | Not automatic | After user acceptance and extension confirmation | Chrome Sync may sync browser-side changes to Google |
| MCP | No clients connected by default | After configuring MCP server for a client | Client can read authorized local bookmark library |
## Get Started
Requirements:
- Node.js 18+
- npm
- Google Chrome (if using extension for import and write-back)
### 1. Start Local Panel
```bash
git clone https://github.com/Lling0000/SiftMarks.git
cd SiftMarks
npm install
npm run build:packages
npm run dev
```
Open:
```text
http://localhost:4399
```
### 2. Safe Trial, No Real Bookmarks Affected
This path is suitable for first-time experience, with all data written to `/tmp/siftmarks-demo`.
```bash
SIFTMARKS_HOME=/tmp/siftmarks-demo npm run cli -- init
SIFTMARKS_HOME=/tmp/siftmarks-demo npm run cli -- import examples/bookmarks.html
SIFTMARKS_HOME=/tmp/siftmarks-demo npm run cli -- search "mcp"
SIFTMARKS_HOME=/tmp/siftmarks-demo npm run cli -- rescue
```
### 3. Use Real Chrome Bookmarks
1. Keep the local panel running at `http://localhost:4399`.
2. Open `chrome://extensions`.
3. Enable **Developer mode**.
4. Click **Load unpacked**.
5. Select `apps/chrome-extension`.
6. Click SiftMarks extension icon, import bookmarks, or save the current page.
## Chrome Workflow
### Import
You can import from two entry points:
- Web panel: Import browser-exported `bookmarks.html`.
- Chrome extension: Reads the actual Chrome bookmark tree and preserves Chrome ID.
For writing back to original Chrome bookmarks, it's recommended to import via the extension.
### Review Organization Suggestions
Open:
```text
http://localhost:4399/rescue
```
Suggestions support:
- Title optimization: Change `Home`, `Untitled`, or too short titles to more searchable ones.
- Folder movement: Suggest moves based on existing folder strategies.
- Tag organization: Reuse existing tags; tags are not necessarily numerous.
- Duplicate cleanup: Duplicate URLs are not re-imported; can enter cleanup suggestions.
- Broken link handling: Broken links can be marked as locally deleted.
You can accept single or batch suggestions. Accepted suggestions are first written locally; Chrome changes are queued for write-back.
### Write-back to Chrome
Actual write-back to Chrome must be executed in the extension:
1. Accept suggestions on the web panel.
2. Preview or prepare write-back plans.
3. Open SiftMarks Chrome extension.
4. Click **Write-back to Chrome**.
5. Confirm in the popup.
Supports write-back:
- Title changes
- Folder moves
- Deleting duplicate bookmarks
- Deleting broken bookmarks
- Creating locally categorized but not yet in Chrome bookmarks
## Extension Permissions
Current permissions come from `apps/chrome-extension/manifest.json`.
| Permission | Purpose |
| --- | --- |
| `bookmarks` | Read Chrome bookmark tree; modify only after user confirmation for write-back |
| `activeTab` | Read current tab title and URL when clicking the extension, for saving the current page |
| `alarms` | Daily 8:00 AM trigger for local scan reminders/status refresh |
| `storage` | Save extension local state, e.g., last scan results |
| `http://localhost:4399/*` | Connect to local SiftMarks Web API only |
## AI Provider
SiftMarks defaults to **Mock** mode, which does not call external AI APIs.
| Mode | Requirements | Capabilities | Data Boundary |
| --- | --- | --- | --- |
| Mock | No Key needed | Local indexing, keyword search, basic rule organization | No external model calls |
| Ollama Compatible | e.g., `http://localhost:11434` and model name | Local summaries, tags, embeddings, categorization | Depends on your Ollama deployment location |
| LM Studio / Local OpenAI-compatible | e.g., `http://localhost:1234/v1` | Call local models via OpenAI-compatible protocol | No cloud Key needed |
| Cloud OpenAI-compatible | Base URL, API Key, chat model, optional embedding model | AI summaries, tags, memory search, organization suggestions | Sends necessary fields to the Provider when executing actions |
Configuration entry:
```text
http://localhost:4399/settings
```
Common addresses:
```text
OpenAI: https://api.openai.com/v1
Qwen: https://dashscope.aliyuncs.com/compatible-mode/v1
DeepSeek: https://api.deepseek.com/v1
Groq: https://api.groq.com/openai/v1
Ollama: http://localhost:11434
LM Studio: http://localhost:1234/v1
```
Note: Not all chat models support embeddings. SiftMarks only requests `/embeddings` if you explicitly configure a vector model; otherwise, search falls back to keyword/rewrite query results.
## MCP Server
SiftMarks can expose the local bookmark library to MCP-enabled clients.
Build:
```bash
npm run build:packages
```
Start:
```bash
npm run cli -- mcp
```
Claude Desktop example:
```json
{
"mcpServers": {
"siftmarks": {
"command": "node",
"args": ["/absolute/path/to/SiftMarks/apps/mcp-server/dist/index.js"]
}
}
}
```
Available tools:
| Tool | Purpose |
| --- | --- |
| `search_bookmarks` | Search local bookmarks |
| `read_bookmark` | Read a single bookmark's details |
| `list_tags` | List tags and counts |
| `list_folders` | List folders and counts |
| `find_related_bookmarks` | Find related pages |
| `summarize_collection` | Summarize collections by tag or folder |
| `save_bookmark` | Save a new bookmark |
| `run_bookmark_rescue` | Generate organization suggestions |
| `get_bookmark_stats` | Get bookmark library statistics |
## Screenshots
### Organization Suggestions
Review suggestions like reviewing a Pull Request, accept, ignore, or batch apply.
### Local Bookmark Library
Filter by status, folders, duplicates, missing metadata, and tags.
### Smart Search
Keyword search available immediately; stronger memory search after configuring a Provider and generating embeddings.
### AI Settings
Choose from Mock, OpenAI-compatible, Ollama-compatible, or local model services.
## CLI
Build first:
```bash
npm run build:packages
```
Common commands:
```bash
npm run cli -- init
npm run cli -- stats
npm run cli -- doctor
npm run cli -- search "mcp browser automation"
npm run cli -- rescue
npm run cli -- export ./siftmarks-export.json
```
Import browser-exported bookmark HTML:
```bash
npm run cli -- import ./bookmarks.html
```
Generate summaries, tags, and embeddings:
```bash
npm run cli -- index --limit 100
```
If still in Mock mode, indexing does not send bookmarks to external models.
## Project Structure
```text
siftmarks/
apps/
web/ Local Next.js panel and API
cli/ Command-line tool
mcp-server/ MCP stdio server
chrome-extension/ Chrome import and write-back extension
packages/
shared/ Shared types and utilities
db/ SQLite schema and data access
core/ Import, search, organization, cleanup logic
ai/ Mock, OpenAI-compatible, Ollama Provider
indexer/ FTS, summaries, tags, embeddings
```
## Development and Validation
```bash
npm install
npm run build:packages
npm run build
npm run typecheck
npm run lint
```
No unified `npm test` script in this repository. Before submission, it's recommended to run at least the above build, typecheck, and lint.
When testing import or organization logic, prioritize temporary data directories:
```bash
SIFTMARKS_HOME=/tmp/siftmarks-test npm run cli -- init
```
## SiftMarks is Not
- Not a replacement for Notion, Joplin, or Logseq: It does not handle note-taking.
- Not a replacement for ArchiveBox or Linkwarden: It does not focus on complete web page archiving.
- Not an automatic cleaner: Destructive changes require review and confirmation.
- Not a cloud AI bookmark service: No default account, no telemetry, no external AI calls.
- Not a general user installation package: Currently mainly for source code run and developer extension load.
## Roadmap
Current features include local panel, Chrome extension import, write-back to Chrome, SQLite storage, keyword search, memory search, organization suggestions, AI metadata, MCP Server, and CLI.
See [`docs/ROADMAP.md`](./docs/ROADMAP.md) for future plans. Key directions include better folder strategies, more stable semantic search experiences, browser extension release, desktop companion app, and more browser support.
## Contribution
Contributions are welcome. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) before starting.
Contributions should prioritize user data protection:
- Do not silently modify Chrome bookmarks without confirmation.
- Do not enable external AI calls by default.
- Do not record API Keys, complete bookmark exports, or user database contents.
- Changes involving import, write-back, AI, or MCP require data flow boundary explanations.
## Friends
- [Linux DO](https://linux.do) — Chinese developer community
## License
MIT. See [`LICENSE`](./LICENSE).
