X bookmarks | History import + live saves | Supported |
| 
Reddit saves | History import + live saves | Supported |
| 
GitHub stars | Full import + live star/unstar events | Supported |
| 
Web pages & bookmarks | Save pages, selections, and Chrome bookmarks | Supported |
| Chrome bookmarks (web submode) | Optional mirroring into Web pages & bookmarks | Supported |
| 
TikTok favorites | Signed-in browser import | Browser capture restored; authenticated acceptance pending |
> GitHub capture is extension-only. It reads the signed-in GitHub stars pages in your browser, includes repositories visible to that account β including visible private repositories β and needs no GitHub OAuth or personal access token.
Live saves are delivered immediately for sources with extension capture. Anansi also performs one daily incremental catch-up for sources that support history import, covering changes made while Chrome or the extension was inactive. GitHub and Reddit import via background session requests without opening tabs. Anansi closes only tabs it created. If a provider session is missing, the popup asks you to sign in β use the explicit **Sign in** button, then retry. Network and rate-limit failures keep the resume cursor. TikTok's browser importer observes its signed-in Favorites responses; its authenticated behavior still needs an end-to-end browser check.
## π Quickstart
Two paths, same library: run it locally or host it in your own Cloudflare account.
### A. Local
Requirements: [Bun](https://bun.sh/) 1.4.2+, Chrome. The local Worker uses emulated D1/R2; `bun run dev` builds the app, applies local SQL migrations and starts the compiled Worker.
```bash
bun install
cp .dev.vars.example .dev.vars
# Edit .dev.vars and set your master secret:
# ANANSI_SECRET=your-random-secret
bun run dev
```
Open `http://127.0.0.1:8787`. This is the one public local origin: the library is at `/`, JSON endpoints are under `/api`, and MCP is at `/mcp`.
Build the extension:
```bash
bun run --cwd apps/extension build
```
Open `chrome://extensions` β enable **Developer mode** β **Load unpacked** β choose `apps/extension/.output/public/chrome-mv3`. Click the Anansi icon, enter your local Worker URL (`http://127.0.0.1:8787` or hosted URL) and `INGEST_TOKEN` if configured (otherwise `ANANSI_SECRET`), and click **Connect**. Public builds contain no deployment credentials. Configured owner-only builds require the explicit `build:private` command; never distribute them.
GitHub first import: sign in to GitHub in the same browser profile β popup β **Import** beside GitHub. It walks your stars pages in the worker (no tabs open), persists the pagination cursor, and resumes after interruptions. Unstarring hides from current-star view without deleting history; re-starring restores it.
TikTok favorites: sign in to TikTok in the same browser and press **Import** in the extension's TikTok row. Anansi opens your profile, selects Favorites, and observes TikTok's own list responses. The live path is enabled in this build but still needs an authenticated browser acceptance check. It keeps Favorites separate from Likes and does not store video files.
Library data backup: use **Saved views β Download library data (no media files)**. On a new, empty Anansi installation, choose **Restore into an empty library** in the same menu and select that JSON file. Restore validates the file before starting and uploads records in resumable batches; choose the same file after an interruption. It restores item and collection data, tags and manual tag decisions, highlights, media metadata, and Chrome bookmark links. It does not contain R2 or local media bytes; those must be fetched again where their origin is still available. A permanently rejected chunk after partial progress requires a fresh empty installation for recovery. Browser restore accepts files up to 100 MB.
### AI Tagging & Semantic Search
Anansi leverages Cloudflare Workers AI and Vectorize:
- **Automatic Tagging**: Powered by `@cf/clef-flash-9b` to assign concise, consistent topic tags to saves as they are captured.
- **Semantic Search**: Powered by `@cf/baai/bge-small-en-v1.5` and Cloudflare Vectorize to find items by concept and meaning alongside BM25 keyword search.
- Both features are optional and can be toggled on/off in **Settings** (`/settings`).
### B. Cloudflare β one-click self-hosting
Use the **Deploy to Cloudflare** button at the top of this README. Cloudflare
copies this public GitHub repository into your account, provisions the Worker
resources declared in [`wrangler.jsonc`](./wrangler.jsonc), and builds and
deploys the app with Workers Builds. Future pushes to the connected repository
can trigger builds and deployments. Cloudflare requires the source repository
to be public for this button flow.
The root build targets the web Worker; the browser extension remains a separate
local build. Keep the project root at the repository root because the Worker
build uses shared Bun workspace packages. See Cloudflare's [Deploy to Cloudflare
button documentation](https://developers.cloudflare.com/workers/platform/deploy-buttons/)
for the button flow and its repository requirements. D1 migration files in
`packages/db/drizzle` are the canonical schema history. Never use `db:push`:
the FTS5 virtual table and triggers require the SQL migration path.
The hosted library uses new D1 and R2 resources in your Cloudflare account.
Deploying does not copy an existing local `data/anansi.db` or `data/media`
directory; the first hosted library starts empty. Keep the local copy as a
backup if you need those captures, because this deployment path does not
include a local-to-cloud import.
In Cloudflare's deploy form, set the Vectorize index to **384 dimensions** and
the **cosine** metric. Anansi's default hosted embedding model,
`@cf/baai/bge-small-en-v1.5`, returns 384-dimensional vectors. The Deploy form
does not infer these fixed index settings from Wrangler, so this is a required
resource-setup value; using a different dimension or metric will break semantic
search. The model and Vectorize index are only used after semantic search is
enabled in Settings.
During setup, enter your master secret when Cloudflare prompts for it:
- `ANANSI_SECRET` β master secret protecting library sign-in, Chrome extension ingestion, and MCP clients. Optional `LIBRARY_TOKEN`, `INGEST_TOKEN`, and `MCP_TOKEN` override it for their respective roles. A distinct `INGEST_TOKEN` limits the extension key to extension endpoints.
Generate with `openssl rand -hex 32`. Both Cloudflare AI features start off; enable
Semantic search or Automatic tags from `/settings` only when you want to use
your account's AI quota.
#### Hosted semantic search
Hosted semantic search is off until you enable it in Settings. Before the first
backfill, Anansi shows the number of saved items and chunks and asks you to
confirm. Captures continue while indexing runs in the background. You can pause
indexing without removing the vectors already in use, or turn semantic search
off to remove hosted chunk text from D1 and queue its Vectorize vectors for
retryable deletion.
Long captures are split at paragraph and sentence boundaries into chunks of up
to 1,800 characters, with 180 characters of overlap. D1 stores the normalized
title/capture-text chunks, offsets, hashes, and model/chunker generation;
Vectorize stores the corresponding vectors under stable IDs. Search combines
keyword and vector candidates, applies the same library filters, collapses
chunk matches to one saved item, and shows the best-matching chunk excerpt.
MCP search remains keyword/BM25.
Hosted indexing and query embeddings share a per-library monthly cap of 10,000
app credits by default. One credit counts each started 1,000 characters sent in
an embedding input. Credits track workload; they are not a provider-bill estimate.
At the cap, Anansi sends no more embedding requests; captures still save, and
search requests that cannot be embedded fall back to keyword results. You can
change the cap in Settings.
After the first successful deploy, open the Worker projectβs **Settings β Build
β Build Variables and Secrets** and add `BUN_VERSION=1.4.2` for subsequent
builds. The first button build uses Cloudflare's default Bun version and must
pass the clean-account acceptance check before this button is announced as
ready.
After deployment returns `https://
