bookmarks-lifecycle

bookmarks-lifecycle

Give your saved bookmarks a lifecycle.

Saving is easy. Almost nothing you save ever gets decided about — it justaccumulates. This is a local MCP server that puts every bookmark on a clock:24 hours to decide, or 30 days to keep watching, or keep it for good. Nothingis ever deleted — a bookmark that times out without a decision just leavesyour attention, not your disk, and every change (including ones an AI made)can be undone.

Aggregates via bookmarks-mcp. Writes only its own local state file, atomically. No accounts, no cloud, no network calls.

The model

Five states:

aggregate → inbox
              │ drip (up to N/day, oldest first)
              ▼
           pending ──you decide──→ watching / kept / lapsed
              │
              └──24h, no decision────────────→ lapsed
                                                  ▲
           watching ──30d, no decision───────────┘
              └──you decide──→ kept

lapsed ──restore──→ pending (clock resets)
any state ──undo (by history event)──→ whatever it was right before that event

From pending you can go to any of the three outcomes. From watching, adecision can only be keep — that matches the model above; to back out of awatch or a drop, use undo rather than re-deciding an item that'salready moved on.

Bookmarks don't all land in pending the moment you aggregate them — aone-time import of 3,000 old bookmarks would otherwise all time out on thesame day and the mechanism would mean nothing. They drip in at a dailyrate instead (default 15/day, oldest first — by real save date when thesource provides one). This is computed lazily whenever you call a tool, notby a background timer, and it does not accumulate across a long absence:however many days you've been away, one call promotes at most one day'squota. A 3,000-bookmark backlog at 15/day realistically takes months ofdaily visits to clear — that's an honest tradeoff of "no reminders, nothingruns unless you ask", not a claim that this replaces a habit-forming app.

Install

No account, no API key, no configuration — it works the moment it'sinstalled.

Claude Code:

claude mcp add -s user bookmarks-lifecycle -- npx -y bookmarks-lifecycle

Claude Desktop / Cursor / any MCP client (mcpServers JSON):

{
  "mcpServers": {
    "bookmarks-lifecycle": {
      "command": "npx",
      "args": ["-y", "bookmarks-lifecycle"]
    }
  }
}

To run from source instead (for development), clone parse-bookmarks,bookmarks-mcp, and this repo as sibling directories, run npm install inbookmarks-mcp and then in bookmarks-lifecycle, and point your client atnode /absolute/path/to/bookmarks-lifecycle/src/index.js.

Use -s user. Without it the scope defaults to local, which registers theserver only for the directory you ran the command in — you'd have to be insidethat folder for your assistant to see it. Your bookmarks have nothing to do withwhich code project you happen to be sitting in, so register it once for yourwhole account.

Config file locations (for the JSON form above):

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cursor: ~/.cursor/mcp.json (or per-project .cursor/mcp.json)

Verifying it's connected: ask your assistant to call the stats tool, orcheck your client's MCP/server log — a successful initialize handshake anda tools/list containing intake, today, decide, list_layer, restore, undo, stats means it's up.

After changing any environment variable below, fully restart your MCPclient's connection to this server (quit/reopen Claude Desktop, or restartthe Cursor MCP process) — it reads them once at startup.

First run

If you're on macOS and want Safari bookmarks included, the app hosting thisserver (Claude Desktop, your terminal, Cursor) needs Full Disk Access(System Settings → Privacy & Security → Full Disk Access) — ~/Library/Safariis protected. Without it, intake's response will show "sourceStatus": "permission_denied" and a warnings entry explaining exactly that; it willNOT silently look like an empty result. Chromium browsers and Firefox neednothing extra.

Call intake first — nothing shows up in today until you do. Then todaygives you the day's actual queue. If both intake and today come backcompletely empty and sourceStatus says "ok", that's an honest "you haveno bookmarks in the sources this scanned" — check sourceStatus beforeassuming something's broken:

no_sources even though you can see bookmarks in your browser? This detectsChromium browsers (Chrome, Edge, Brave, Arc, Vivaldi, Chromium) only in theirstandard per-OS install locations. If your browser uses a custom profile ordata directory (a separate work profile, a portable install, a renamed userdata folder, …), it won't be found automatically:

1. Open chrome://version in that browser (edge://version, brave://version,etc. — the same page exists in every Chromium browser) and copy the valuenext to Profile Path.
2. In your MCP client's config for this server, add an environment variableCHROMIUM_BOOKMARKS_PATH set to that path with /Bookmarks appended, e.g."/Users/you/Library/Application Support/BraveSoftware/Brave-Browser/Custom/Bookmarks".Comma-separate multiple paths if you have more than one profile to include.
3. Fully restart the MCP client's connection to this server (seeConfiguration below).

This doesn't apply to Safari — see the Full Disk Access note above instead.

Talking to it

You never call these tools yourself — your assistant does. You just talk. Ifyou'd rather be walked through it, run the clean_up_my_bookmarks promptonce (in Claude Code: /mcp; in Claude Desktop: the prompts menu) and it willset you up and do one round with you.

Otherwise, plain sentences are enough:

Two things worth knowing on day one:

• Nothing reminds you. There is no background process and no notification.The queue only moves when you ask — which also means it can never surprise you.
• An empty result explains itself. Every response carries a nextSteptelling your assistant what to suggest, so "0 items" never has to be guessedat: it will say whether you simply haven't scanned yet, whether today's batchis done, or whether a source failed to read.

Tools

Every read tool (today/list_layer/stats) may still write to disk onthe call you make: expiry and drip are computed lazily, so even "justlooking" can move items between layers as a side effect. It only writeswhen something actually changed — a call that finds nothing due and nothingto drip touches nothing.

Plus two prompts:

Both intake and today also return a nextStep object (code + why) soyour assistant knows what to suggest next instead of inferring it from anempty list. It is operational guidance only — never promotion.

Honesty about authorization

This server cannot verify that a tool call attributed to "user" actuallycame from you confirming something. Every parameter it receives — includingactorClaim: "user" — comes from the AI, over the same channel as everythingelse. There is no separate, trusted channel this code can check. An earlierversion of this README claimed "AI can't act without your say-so" as aserver-enforced guarantee; that was tested and shown to be false — an AIthat simply omits the field, or claims "user", goes through unchallenged.We're not going to repeat that claim.

What's actually true:

• Whether an AI needs your click-through before it can call a mutatingtool depends on your MCP client's own tool-approval settings — ClaudeDesktop and Cursor both have per-tool or per-session approval prompts.That's the real gate, and it lives in your client, not in this server.
• actorClaim: "ai" is rejected unless you've explicitly setBOOKMARKS_LIFECYCLE_AUTO_DECIDE=true — but a caller can just omit thefield (recorded as "mcp-client") or claim "user" instead, so don'ttreat this as a security boundary either.
• What this server actually guarantees is reversibility. Every mutation— including ones made under autoDecide, including expiry, includingdrip — is undoable. restore reverses lapsed → pending. undo reversesany state change, including kept and watching, by history event, witha preview mode to check first. If an AI does something you didn't want,the fix is undo, not a promise that it couldn't have happened.
• history records by: "user" | "ai" | "mcp-client" | "drip" | "expiry" | "system" on every change. The first two are claims, not verifiedidentity — treat them as a hint for your own review, not evidence.

Configuration

All via environment variables in your MCP client config — none requiretouching this package's code. Restart your MCP client's connection afterchanging any of these.

What gets stored

One file: ~/.bookmarks-lifecycle/state.json. Plain JSON, human-readable.Writes are atomic (temp file → fsync → rename, never a partial write leftbehind mid-crash) and the previous generation is kept as state.json.bakbefore each overwrite.

Per bookmark: id, url, title, the browser source(s) it's known from (a URLsaved in two browsers keeps both), when it was actually added according tothe browser (addedAt, used for oldest-first ordering — null if thesource didn't provide one, never fabricated), current lifecycle state, whenit entered that state, a full history of every transition (each with astable eventId, when, who/what did it, and an optional note), and asourceGone flag for bookmarks no longer found in any source that wassuccessfully re-scanned (their record stays — nothing here is everauto-deleted; a source that merely failed to read never counts asevidence something's gone).

Only identifiers and your own judgments are stored — never the page contentitself. The file has an internal version; if a future version of this toolwrites a shape this version doesn't understand, this version refuses totouch the file rather than guess.

Concurrent access: if two MCP clients (say, Claude Desktop and Cursor)run this server against the same state file at once, a lock file(state.json.lock) serializes them — the second one waits briefly ratherthan silently overwriting the first one's changes.

Time zone

stats's "today" (for decidedToday) uses the local calendar day on themachine running this server. Because this server only ever runs on your ownmachine (it reads local browser files directly — there's no remote/hosteddeployment of it), that's the same clock you're living by, so this isintentional, not a bug to fix. The 24h/30d layer durations are strictelapsed-time windows, not calendar-day counts — a daylight-saving transitionshifts wall-clock time without changing how long 24 hours actually is.

Guarantees

• Never touches a browser bookmark file. Reading is entirely delegatedto bookmarks-mcp, which is itself read-only. The only files thispackage ever writes are its own state.json, state.json.bak, and atransient lock file.
• No lifecycle record is ever deleted, and every state change isreversible — see Honesty about authorizationfor exactly what that does and doesn't protect against.
• No network calls, no telemetry, no accounts.

Design boundaries

• No background process, no cron, no push notifications. Everything hereis computed lazily, the instant you call a tool — that's what makes "nodaemon" possible. The honest tradeoff: if you don't come ask, the queuejust quietly lapses. Nobody reminds you.
• No UI. This stays an MCP tool, not an app.
• Bring your own AI. This server does no inference and charges nothing —the AI judging your bookmarks is whatever you've already connected it to.What this project provides is the state machine and the prompt, not amodel.

Who makes this

Built by the team behind Burn 451 — the 24h /30-day mechanic here is modeled on Burn's. The difference: this tool onlyruns when you ask it to, right where you're already working. If you want thesame idea running automatically, reminding you daily, and reachable fromyour phone, that's what Burn is — this project stays useful on its owneither way.

License

MIT