{
  "markdown": "# bookmarks-lifecycle\n\n**Give your saved bookmarks a lifecycle.**\n\nSaving is easy. Almost nothing you save ever gets decided about — it just\naccumulates. This is a local MCP server that puts every bookmark on a clock:\n24 hours to decide, or 30 days to keep watching, or keep it for good. Nothing\nis ever deleted — a bookmark that times out without a decision just leaves\nyour attention, not your disk, and every change (including ones an AI made)\ncan be undone.\n\n```\nAggregates via bookmarks-mcp. Writes only its own local state file, atomically. No accounts, no cloud, no network calls.\n```\n\n## The model\n\nFive states:\n\n| State | Meaning | Counts down? |\n|---|---|---|\n| `inbox` | Aggregated, not yet up for a decision | no |\n| `pending` | The 24-hour layer — today's actual to-do list | yes |\n| `watching` | The 30-day layer — \"give it more time\" | yes |\n| `kept` | Decided: keep this for good | no |\n| `lapsed` | Timed out or let go — **fully recoverable, never deleted** | no |\n\n```\naggregate → inbox\n              │ drip (up to N/day, oldest first)\n              ▼\n           pending ──you decide──→ watching / kept / lapsed\n              │\n              └──24h, no decision────────────→ lapsed\n                                                  ▲\n           watching ──30d, no decision───────────┘\n              └──you decide──→ kept\n\nlapsed ──restore──→ pending (clock resets)\nany state ──undo (by history event)──→ whatever it was right before that event\n```\n\nFrom `pending` you can go to any of the three outcomes. From `watching`, a\ndecision can only be `keep` — that matches the model above; to back out of a\n`watch` or a `drop`, use `undo` rather than re-deciding an item that's\nalready moved on.\n\nBookmarks don't all land in `pending` the moment you aggregate them — a\none-time import of 3,000 old bookmarks would otherwise all time out on the\nsame day and the mechanism would mean nothing. They **drip in** at a daily\nrate instead (default 15/day, oldest first — by real save date when the\nsource provides one). This is computed lazily whenever you call a tool, not\nby a background timer, and it does **not** accumulate across a long absence:\nhowever many days you've been away, one call promotes at most one day's\nquota. A 3,000-bookmark backlog at 15/day realistically takes months of\ndaily visits to clear — that's an honest tradeoff of \"no reminders, nothing\nruns unless you ask\", not a claim that this replaces a habit-forming app.\n\n## Install\n\nNo account, no API key, no configuration — it works the moment it's\ninstalled.\n\nClaude Code:\n\n```bash\nclaude mcp add -s user bookmarks-lifecycle -- npx -y bookmarks-lifecycle\n```\n\nClaude Desktop / Cursor / any MCP client (`mcpServers` JSON):\n\n```json\n{\n  \"mcpServers\": {\n    \"bookmarks-lifecycle\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"bookmarks-lifecycle\"]\n    }\n  }\n}\n```\n\nTo run from source instead (for development), clone `parse-bookmarks`,\n`bookmarks-mcp`, and this repo as sibling directories, run `npm install` in\n`bookmarks-mcp` and then in `bookmarks-lifecycle`, and point your client at\n`node /absolute/path/to/bookmarks-lifecycle/src/index.js`.\n\n**Use `-s user`.** Without it the scope defaults to `local`, which registers the\nserver only for the directory you ran the command in — you'd have to be inside\nthat folder for your assistant to see it. Your bookmarks have nothing to do with\nwhich code project you happen to be sitting in, so register it once for your\nwhole account.\n\n**Config file locations** (for the JSON form above):\n- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\n- Cursor: `~/.cursor/mcp.json` (or per-project `.cursor/mcp.json`)\n\n**Verifying it's connected**: ask your assistant to call the `stats` tool, or\ncheck your client's MCP/server log — a successful `initialize` handshake and\na `tools/list` containing `intake, today, decide, list_layer, restore, undo,\nstats` means it's up.\n\n**After changing any environment variable below**, fully restart your MCP\nclient's connection to this server (quit/reopen Claude Desktop, or restart\nthe Cursor MCP process) — it reads them once at startup.\n\n## First run\n\nIf you're on macOS and want Safari bookmarks included, the app hosting this\nserver (Claude Desktop, your terminal, Cursor) needs **Full Disk Access**\n(System Settings → Privacy & Security → Full Disk Access) — `~/Library/Safari`\nis protected. Without it, `intake`'s response will show `\"sourceStatus\":\n\"permission_denied\"` and a `warnings` entry explaining exactly that; it will\nNOT silently look like an empty result. Chromium browsers and Firefox need\nnothing extra.\n\nCall `intake` first — nothing shows up in `today` until you do. Then `today`\ngives you the day's actual queue. If both `intake` and `today` come back\ncompletely empty and `sourceStatus` says `\"ok\"`, that's an honest \"you have\nno bookmarks in the sources this scanned\" — check `sourceStatus` before\nassuming something's broken:\n\n| `sourceStatus` | Meaning |\n|---|---|\n| `no_sources` | No supported browser was even detected on this machine |\n| `permission_denied` | At least one source failed to read (commonly Safari without Full Disk Access) |\n| `empty` | Every source scanned successfully and genuinely has 0 bookmarks |\n| `ok` | Scanned successfully and found something |\n\n**`no_sources` even though you can see bookmarks in your browser?** This detects\nChromium browsers (Chrome, Edge, Brave, Arc, Vivaldi, Chromium) only in their\nstandard per-OS install locations. If your browser uses a custom profile or\ndata directory (a separate work profile, a portable install, a renamed user\ndata folder, …), it won't be found automatically:\n\n1. Open `chrome://version` in that browser (`edge://version`, `brave://version`,\n   etc. — the same page exists in every Chromium browser) and copy the value\n   next to **Profile Path**.\n2. In your MCP client's config for this server, add an environment variable\n   `CHROMIUM_BOOKMARKS_PATH` set to that path with `/Bookmarks` appended, e.g.\n   `\"/Users/you/Library/Application Support/BraveSoftware/Brave-Browser/Custom/Bookmarks\"`.\n   Comma-separate multiple paths if you have more than one profile to include.\n3. Fully restart the MCP client's connection to this server (see\n   [Configuration](#configuration) below).\n\nThis doesn't apply to Safari — see the Full Disk Access note above instead.\n\n## Talking to it\n\nYou never call these tools yourself — your assistant does. You just talk. If\nyou'd rather be walked through it, run the **`clean_up_my_bookmarks`** prompt\nonce (in Claude Code: `/mcp`; in Claude Desktop: the prompts menu) and it will\nset you up and do one round with you.\n\nOtherwise, plain sentences are enough:\n\n| Say something like | What happens |\n|---|---|\n| \"Pull in my browser bookmarks\" | `intake` — scans your browsers, adds new URLs to the inbox |\n| \"What should I look at today?\" | `today` — the day's queue, oldest first, up to the daily quota |\n| \"Keep the first one, drop the last two\" | `decide` — after you've confirmed, not before |\n| \"Actually, undo that\" | `undo` — reverses any decision, including \"keep\" |\n| \"What did I let go of?\" | `list_layer` on `lapsed` — everything is still there |\n| \"Bring that one back\" | `restore` — returns it to the queue with a fresh clock |\n| \"How much is left?\" | `stats` — counts per layer and what's still waiting in inbox |\n\nTwo things worth knowing on day one:\n\n- **Nothing reminds you.** There is no background process and no notification.\n  The queue only moves when you ask — which also means it can never surprise you.\n- **An empty result explains itself.** Every response carries a `nextStep`\n  telling your assistant what to suggest, so \"0 items\" never has to be guessed\n  at: it will say whether you simply haven't scanned yet, whether today's batch\n  is done, or whether a source failed to read.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `intake` | Scan bookmark sources, merge new ones into `inbox`, reconcile ones that moved or disappeared |\n| `today` | The `pending` layer right now, oldest first — your daily entry point |\n| `decide` | Judge one or more items: `keep` / `watch` / `drop` |\n| `list_layer` | See any single layer, paginated (default 50/page), including `lapsed` (\"what did I let go of\") |\n| `restore` | Bring a `lapsed` item back to `pending`, clock reset |\n| `undo` | Revert an item to what it was right before one of its own history events — works for `kept`/`watching` too, not just `lapsed` |\n| `stats` | Counts per layer, today's decision count, how much is waiting in `inbox` |\n\nEvery read tool (`today`/`list_layer`/`stats`) may still write to disk on\nthe call you make: expiry and drip are computed lazily, so even \"just\nlooking\" can move items between layers as a side effect. It only writes\nwhen something actually changed — a call that finds nothing due and nothing\nto drip touches nothing.\n\nPlus two prompts:\n\n| Prompt | When |\n|---|---|\n| `clean_up_my_bookmarks` | First time. Explains the decision-clock mechanism, runs `intake`, and does one small triage round with you. |\n| `daily_triage` | Every day after that. `today` → a suggestion per item → waits for your confirmation → applies it. |\n\nBoth `intake` and `today` also return a `nextStep` object (`code` + `why`) so\nyour assistant knows what to suggest next instead of inferring it from an\nempty list. It is operational guidance only — never promotion.\n\n## Honesty about authorization\n\n**This server cannot verify that a tool call attributed to `\"user\"` actually\ncame from you confirming something.** Every parameter it receives — including\n`actorClaim: \"user\"` — comes from the AI, over the same channel as everything\nelse. There is no separate, trusted channel this code can check. An earlier\nversion of this README claimed \"AI can't act without your say-so\" as a\nserver-enforced guarantee; that was tested and shown to be false — an AI\nthat simply omits the field, or claims `\"user\"`, goes through unchallenged.\nWe're not going to repeat that claim.\n\nWhat's actually true:\n\n- **Whether an AI needs your click-through before it can call a mutating\n  tool depends on your MCP client's own tool-approval settings** — Claude\n  Desktop and Cursor both have per-tool or per-session approval prompts.\n  That's the real gate, and it lives in your client, not in this server.\n- `actorClaim: \"ai\"` is rejected unless you've explicitly set\n  `BOOKMARKS_LIFECYCLE_AUTO_DECIDE=true` — but a caller can just omit the\n  field (recorded as `\"mcp-client\"`) or claim `\"user\"` instead, so don't\n  treat this as a security boundary either.\n- **What this server actually guarantees is reversibility.** Every mutation\n  — including ones made under `autoDecide`, including expiry, including\n  drip — is undoable. `restore` reverses `lapsed → pending`. `undo` reverses\n  *any* state change, including `kept` and `watching`, by history event, with\n  a `preview` mode to check first. If an AI does something you didn't want,\n  the fix is `undo`, not a promise that it couldn't have happened.\n- `history` records `by: \"user\" | \"ai\" | \"mcp-client\" | \"drip\" | \"expiry\" |\n  \"system\"` on every change. The first two are **claims**, not verified\n  identity — treat them as a hint for your own review, not evidence.\n\n## Configuration\n\nAll via environment variables in your MCP client config — none require\ntouching this package's code. **Restart your MCP client's connection after\nchanging any of these.**\n\n| Variable | Default | What |\n|---|---|---|\n| `BOOKMARKS_LIFECYCLE_PENDING_HOURS` | `24` | Hours in the `pending` layer before an undecided item lapses |\n| `BOOKMARKS_LIFECYCLE_WATCHING_DAYS` | `30` | Days in the `watching` layer before an undecided item lapses |\n| `BOOKMARKS_LIFECYCLE_DRIP_PER_DAY` | `15` | Max `inbox` items promoted to `pending` per day (never accumulates across a gap) |\n| `BOOKMARKS_LIFECYCLE_AUTO_DECIDE` | `false` | Whether `decide`/`restore`/`undo` calls claiming `actorClaim: \"ai\"` are allowed through (see [Honesty about authorization](#honesty-about-authorization) — this is not a security guarantee) |\n| `BOOKMARKS_LIFECYCLE_STATE_DIR` | `~/.bookmarks-lifecycle` | Where `state.json` (and its lock/backup files) live |\n\n## What gets stored\n\nOne file: `~/.bookmarks-lifecycle/state.json`. Plain JSON, human-readable.\nWrites are atomic (temp file → fsync → rename, never a partial write left\nbehind mid-crash) and the previous generation is kept as `state.json.bak`\nbefore each overwrite.\n\nPer bookmark: id, url, title, the browser source(s) it's known from (a URL\nsaved in two browsers keeps both), when it was actually added according to\nthe browser (`addedAt`, used for oldest-first ordering — `null` if the\nsource didn't provide one, never fabricated), current lifecycle state, when\nit entered that state, a full history of every transition (each with a\nstable `eventId`, when, who/what did it, and an optional note), and a\n`sourceGone` flag for bookmarks no longer found in any source that was\nsuccessfully re-scanned (their record stays — nothing here is ever\nauto-deleted; a source that merely *failed* to read never counts as\nevidence something's gone).\n\nOnly identifiers and your own judgments are stored — never the page content\nitself. The file has an internal `version`; if a future version of this tool\nwrites a shape this version doesn't understand, this version refuses to\ntouch the file rather than guess.\n\n**Concurrent access**: if two MCP clients (say, Claude Desktop and Cursor)\nrun this server against the same state file at once, a lock file\n(`state.json.lock`) serializes them — the second one waits briefly rather\nthan silently overwriting the first one's changes.\n\n## Time zone\n\n`stats`'s \"today\" (for `decidedToday`) uses the local calendar day on the\nmachine running this server. Because this server only ever runs on your own\nmachine (it reads local browser files directly — there's no remote/hosted\ndeployment of it), that's the same clock you're living by, so this is\nintentional, not a bug to fix. The 24h/30d layer durations are strict\nelapsed-time windows, not calendar-day counts — a daylight-saving transition\nshifts wall-clock time without changing how long 24 hours actually is.\n\n## Guarantees\n\n- **Never touches a browser bookmark file.** Reading is entirely delegated\n  to `bookmarks-mcp`, which is itself read-only. The only files this\n  package ever writes are its own `state.json`, `state.json.bak`, and a\n  transient lock file.\n- **No lifecycle record is ever deleted**, and every state change is\n  reversible — see [Honesty about authorization](#honesty-about-authorization)\n  for exactly what that does and doesn't protect against.\n- **No network calls, no telemetry, no accounts.**\n\n## Design boundaries\n\n- **No background process, no cron, no push notifications.** Everything here\n  is computed lazily, the instant you call a tool — that's what makes \"no\n  daemon\" possible. The honest tradeoff: if you don't come ask, the queue\n  just quietly lapses. Nobody reminds you.\n- **No UI.** This stays an MCP tool, not an app.\n- **Bring your own AI.** This server does no inference and charges nothing —\n  the AI judging your bookmarks is whatever you've already connected it to.\n  What this project provides is the state machine and the prompt, not a\n  model.\n\n## Who makes this\n\nBuilt by the team behind [Burn 451](https://www.burn451.cloud) — the 24h /\n30-day mechanic here is modeled on Burn's. The difference: this tool only\nruns when you ask it to, right where you're already working. If you want the\nsame idea running automatically, reminding you daily, and reachable from\nyour phone, that's what Burn is — this project stays useful on its own\neither way.\n\n## License\n\nMIT\n",
  "bytes": 15661,
  "sha": "b63c1d6271e6aebc0cb4006527ae68aa03d34d1c4ed64bc54cd1542a825b4ff5",
  "repo_slug": "fisher521/bookmarks-lifecycle",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fisher521_bookmarks_lifecycle_039e0640/readme"
}