Skip to content

afaraha8403/mental

v0.14.0MIT

Never reconstruct where you left off. Local-first continuity for you and your coding agents — resume, decisions, and what's still in the air. CLI, MCP, and Agent Skills for Cursor, Claude Code, Copilot, and Codex.

GitHubOpen Website

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Changes

  • The production site deploy waits until the three-OS test matrix is green, then publishes only if that commit changes the site.
  • The production site deploy runs the homepage and docs browser checks before it publishes.
  • The homepage is redesigned as numbered chapters. It opens with a large headline over a teal glow, a three-line install card, and a sample dashboard that settles flat as you scroll. It then shows a list of supported agents, the research figures on lost context, the install-to-pulse loop, a breakdown of what the pulse shows, a privacy section on what leaves the machine, and a closing install call.
  • Docs pages group the sidebar into Start, Surfaces, Reference, and Background. Each page adds an "On this page" outline that tracks scroll position, previous and next links, and an "Edit on GitHub" link. Code blocks, tables, and callouts are restyled.
  • Docs on the site cover the dashboard, the Claude Code mod, the Cursor sidebar, and decision models. Create commands in the CLI docs require --tag. Personal notes stay off the model unless option decide personal on.
  • Docs pages keep a full-width column on a phone, mark each section with an icon, and show bullets and numbers in the article.
  • The homepage marks each section with an icon, and numbers the install commands and the three-step cycle.
  • The site version and the sample pulse show 0.14.0.
  • The homepage states the value first, puts install above an interactive sample dashboard, and describes the Claude Code mod.
  • The homepage stays in a fixed column: a contained sample dashboard, then the out-of-the-box session (no pre-configuration, no command list, agents already know it).
  • The pulse is a terminal of that sample session, and attention and decisions are live views.
  • The sample dashboard follows the page's light or dark mode, not the operating system.

[0.14.0] - 2026-10-30

Fixes

  • Titles keep #, :, and quotes, and a newline in a title is rejected instead of breaking the file.
  • The README and install docs name Node >=22.13, matching engines.
  • Recording an attention item that was resolved opens it again.
  • A ## heading inside a journal body no longer splits the next hop.
  • Journal days and bindings.json are written atomically and locked so two agents cannot drop an update.
  • The search index rebuilds in one transaction, once per write, and a search refreshes it when files changed outside Mental.
  • Every search backend matches word prefixes and ranks a title hit above the same words in a body.
  • Writes redact obvious credentials locally, including .env values, without a model key. Long slugs, paths, SHAs, and UUIDs stay. mental doctor --fix rewrites files that still match.
  • Heartbeat docs say what it writes (last_seen when tracking is on, the update cache) and that MENTAL_SKIP_UPDATE_CHECK=1 skips the npm check. Config files on Windows get an owner-only ACL when icacls is available.
  • Heartbeat skips journal days that cannot contain today's hops and reads each bundle file once.

Features

  • mental why <path|sha|path:line> shows decisions and hops anchored to that code, plus Mental-Decision trailers.
  • --ref stores a session link on journal, park, handoff, decide, attention, and note. Mental never fetches it.
  • mental handoff --share <dir> packs one project, and mental import <dir> merges it into the binding with the same git origin.
  • mental option trailer on installs a prepare-commit-msg hook that appends Mental-Decision: <id>/<path> and never fails the commit.
  • The README privacy section lists what can leave the machine. mental doctor --json repeats it as network and reports which agent hosts can see the skill.

[0.13.3] - 2026-10-29

Changes

  • The release tests give the decision model 30 seconds per request (through a test-only MENTAL_JEV_TIMEOUT_MS) so a busy Windows CI runner no longer drops mental brief to its unranked fallback and blocks a publish. mental brief keeps its short 4-second limit for everyone else.

[0.13.2] - 2026-10-29

Changes

  • The Mental panel in Claude Desktop has real surfaces now. The hero card sits on a teal wash, each pulse tile is tinted by what it shows (needs you, decisions, context, this session), and every row, link and the entry body sits on a filled card that lights teal under the pointer. Row fills use Claude's own theme backgrounds, so they follow light and dark mode.

Fixes

  • A row in the Claude Desktop panel no longer stays lit after the pointer leaves it.

[0.13.1] - 2026-10-29

Fixes

  • mental install, mental doctor --fix, mental uninstall and the hooks option now also cover the Claude Code profile named by CLAUDE_CONFIG_DIR, next to ~/.claude. Before, a profile launched with its own config dir never received the Mental skill, rule, CLAUDE.md block or session-start hook and went stale after every upgrade. mental doctor reports that profile as rule-claude-profile, and an install with hooks already on adds the hook to a profile that lacks it. The doctor's skill-version check reads that profile's copy too, so a profile left behind after an upgrade shows up.

[0.13.0] - 2026-10-28

Features

  • Heartbeat reports needYouCount, agingCount and directionCount next to attentionCount: open attention under 7 days old, open 7+ days, and standing directions. The dashboard nav badge, Today "In the air" lane, project cards, the Claude Desktop panel and the tool card now count what needs you instead of every open item, so they agree with the Attention page.
  • The Mental skill has an aging-triage recipe: an agent sorts old attention items into likely done (with the commit or file as evidence), still true and unclear, shows the list, and resolves only the likely-done group after the user says yes.
  • Mental for Cursor: a VS Code extension (cursor-ext/, installed from a .vsix) adds a Mental view to the activity bar that shows the live dashboard for the open project in embed mode, starting a dashboard (it exits after 30 idle minutes) when none is running and finding it through ~/.mental/dashboard.json. A status bar item says how many items need you, with the pick-up line and the list in its tooltip. Commands: Park, Hand off (the prompt goes on the clipboard and a new agent chat opens, since Cursor has no supported way for an extension to type into its chat), Refresh, Open the dashboard in the browser, and Stop the dashboard.
  • mental restore --from <dir> --dry-run previews a restore without writing anything: per project and for personal files it says whether the backup would be adopted, merged or replaced, how many files would land, how many journals would merge, how many of your newer files stay, and (with --replace) how many would be removed. --dry-run --replace needs no confirm token because nothing is touched.
  • The dashboard's Attention page is a worklist instead of a wall of cards. The header reads "N need you · M aging · K directions", fresh items stay on the board, items open 7+ days fold into an Aging section, and directions (standing guidance, not a to-do) fold into their own section outside the count. Aging has Select all and per-item checkboxes, and "Copy resolve commands" puts one mental attention --status resolved line per selected item on the clipboard. The dashboard stays read-only; you run the commands.
  • The Mental pane in Claude Desktop is a console that follows the light or dark theme and draws no background of its own. A hero card shows the project, its live status and branch, where to pick up, and the thread: the last eight hops as a timeline coloured by the agent that left each one (Claude, Cursor, Copilot, Codex, OpenCode). Pulse tiles show what needs you by kind, the decisions in force, the context window and this session. Park and Hand off, each open item, and the Journal, Decisions, Notes and Threads links stay native controls under the drawings. The terminal pane keeps its native layout.
  • Mental's accent colour is teal instead of violet in the Claude Desktop panel and the dashboard. The dashboard's Today card now follows the light or dark theme like the rest of the page, and journals use pink so nothing reads as purple.
  • The Mental panel's pages are redesigned on Claude Desktop. Journal, Decisions, Notes and Threads open with a drawn header and a bar that splits the list by status, then group their entries (open, later and resolved threads; open, decided and superseded decisions; the journal by month) as outlined rows tagged by kind and status. An entry opens with its kind, status, date and tags, its body framed, an "Ask Claude about this" action, and the entries that link to it.
  • Rows in the Mental panel on Claude Desktop are whole targets: a need, a list entry, a linked entry, a Read in Mental tile or Last hand-off lights its border and title when the pointer is anywhere on it, and a click anywhere on the row (or Enter once it has focus) opens it. If the host cannot run the row module, rows fall back to native outlined rows that still light on hover.
  • When the agent runs a mental … command in Claude Desktop, the chat shows a compact console row instead of a tall violet card. It spans the chat's width, follows the light or dark theme with the teal accent, and is one line tall (two only when the summary needs it). It says what the call did: the resume line a park, hand-off or journal saved; an attention item's title, kind and whether it was raised or resolved; where things stand after a heartbeat ("3 need you · main · 49 open decisions"); which host a hook served and how much context it sent; search and list counts; doctor's errors and warnings; the clock stopped and for how long. A running call shows a live dot, and a failed one shows Mental's actual error and hint in red.
  • The band above the prompt in Claude Desktop is one strip with the project, live status and resume line, plus a plain "N need you ›" link, instead of two crowded lines and a red reminder.
  • A running dashboard can be stopped from the Mental pane. The panel stops only the server named in ~/.mental/dashboard.json, and only after its address still answers as a Mental dashboard.
  • mental dashboard writes ~/.mental/dashboard.json (port, pid, url, startedAt) once it is listening and removes it on a clean exit, so launchers such as the Claude Desktop panel can find a dashboard that fell back to another port instead of assuming 3847. A second dashboard owns the file until it exits; the first one never deletes it.
  • mental dashboard --idle-exit <minutes> stops the server after that long with no requests, for detached launches that should not linger.
  • The dashboard has an embed mode for editor panels and iframes: open it with ?embed=1 (for example http://127.0.0.1:3847/?embed=1#/today) to hide the sidebar and tab bar, compact the top bar, stack lanes in one column, and skip the refresh on returning to the tab.

Fixes

  • Session-start hooks hand Cursor and Claude Code a short brief instead of a raw mental status JSON dump: where to pick up, the last hop, what needs you (open items only, with their true count), open decisions, the branch and last commit, and the next command with the host's own --via token. It runs to about 800 characters instead of 4,000, and long lists are cut with a pointer to mental heartbeat --json.
  • The dashboard no longer shows old open items in red as "stale". Age is only a reason to ask "is this still true?", so it is now a quiet grey "7d" chip and an "Aging 7d+" filter.
  • The Mental pane is titled with the project's folder name instead of its id.
  • Pressing "N need you" no longer shows a toast that repeats the whole list the pane is about to show. Only when the pane cannot open does a short line say how many items need you.
  • The Mental panel no longer counts a subagent's turns as turns of the session, so "This session" shows how many times you and Claude went back and forth.
  • MCP tools now act on every argument their schema offers. slug on attention, decide and note, description on attention, passive on heartbeat, this and provider on option, and started and accept_stale on track were accepted but silently ignored.
  • A dashboard started from the Mental panel now stops after 30 minutes with no requests instead of running until you sign out.
  • On Windows, Mental no longer prints a Node DEP0190 deprecation warning when it checks npm for updates or asks Claude Code and npm for versions. It runs their .cmd shims through cmd.exe with quoted arguments instead of shell: true.
  • mental serve now speaks the MCP stdio transport that real clients use: one JSON-RPC message per line (newline-delimited JSON). It previously framed messages with LSP-style Content-Length headers, so Claude Code, Cursor and Codex could not talk to it. Input with Content-Length headers is still accepted, and a client that sends it gets replies framed the same way.
  • The MCP initialize reply negotiates the protocol version: it echoes the client's requested version when supported (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05) and otherwise offers the newest one, instead of always answering 2024-11-05.
  • MCP error handling follows JSON-RPC: a malformed line gets a -32700 parse error, an unknown tool a -32602 error, an unknown method -32601, and notifications (including unknown ones) are never answered. Batched requests are answered as a batch.
  • On Windows, mental install --mcp and mental option mcp on register the server as cmd /c mental serve. Hosts start MCP servers without a shell, so the npm-installed mental.cmd shim could not be launched from a bare mental command. Other platforms keep mental serve, and mental uninstall / option mcp off recognise both forms.
  • The dashboard can be shown inside the Claude Code panel, VS Code webviews and loopback iframes. Its Content-Security-Policy no longer forbids all framing; it allows loopback pages and editor webviews, and the Host check still blocks DNS-rebinding.
  • The dashboard no longer hangs on "Loading…" in sandboxed webviews. Theme, sidebar and pin preferences fall back to defaults when storage is blocked, and a startup failure shows an error with a Try again button.
  • Today shows the real branch and recent commits when a project is opened by id. The dashboard used the first path in bindings.json, which can be a checkout from another machine (/home/... on Windows), so git read nothing and showed "detached". It now uses the checkout that contains the working directory, else the first path that exists here, and shows "no git" when there is none.
  • When the dashboard server stops or fails, a banner says so with a Retry button, instead of views quietly showing "All quiet".
  • Returning to the dashboard tab no longer refetches and redraws every panel each time; it refreshes only when the data is more than 30 seconds old.
  • The dashboard starts faster. Projects and the opened project's heartbeat arrive in one request (/api/boot), and the server reuses the parsed catalog, graph and project list until a file in them changes.
  • "Copy resume line" in the command palette shows a confirmation, or a clear message when the clipboard is blocked.
  • Markdown links that hide a javascript: scheme behind a tab or newline are dropped, and Map tooltips escape titles, descriptions and tags.
  • The Map is drawn once per visit instead of twice, follows the OS theme in "Match system", and an unknown view address is rewritten to Today so Back does not bounce through it.
  • openBrowser only launches plain loopback dashboard URLs, so &, % or quotes can never reach cmd start on Windows.
  • The Claude panel kept working after /clear, /resume or /branch only until then: those commands end the conversation, not the session, and the panel stopped its refresh timer. It now starts a fresh session view and keeps refreshing.
  • A commit message, echo or heredoc that mentioned mental park or mental decide no longer shows a false "Parked" or "Decision" receipt or resets the edit count. Only a real mental … call at the start of a command (or after &&, ;, |) counts, and the inline chat card appears only on shell tool rows.
  • The panel's Dashboard button no longer starts a second dashboard when one is already running for another project. It finds the running server from ~/.mental/dashboard.json (falling back to port 3847), opens this project's Today view with a native link, and only starts a server when none answers.
  • Panel buttons no longer leave unhandled errors when Claude cannot open the pane, and every gating hook now has an error handler, so claude plugin validate --strict is clean.
  • Receipts and inline cards read the tool result when the host gives no text, so their titles show again.
  • "Needs you" counts every open item, not just the first few the heartbeat lists, and no longer lists each verify item twice. Hiding an item is remembered by its file, so a retitle does not bring it back.
  • Panel text is readable on light terminals and light Desktop themes: primary text keeps the host's colour, secondary text is dimmed, and accents use theme colour names instead of a fixed dark palette.
  • The panel shows the real error when Mental cannot be read, instead of "heartbeat failed", and no longer waits up to a minute trying mental and mental.cmd on PATH when the plugin's own CLI fails.
  • Writes from Claude Code, Codex and OpenCode are no longer labelled as Cursor. The rule and skill told every host to pass --via cursor; mental install now writes each host's own token into its copy (claude-code in ~/.claude, codex in ~/.codex/AGENTS.md, opencode in OpenCode's dirs, cursor in Cursor's), and copies several hosts share (~/.agents, .github/skills) say --via <host> next to the token list. Re-running install rewrites older copies even when the skill version has not changed.
  • Session-start hooks now survive a Node reinstall or nvm switch and work in Cursor on Windows. mental hooks on writes mental hooks session-start <host> (resolved through PATH; mental.cmd on Windows) instead of an absolute path to hooks/session-start.sh.
  • Session-start hooks now emit what each host reads: additional_context for Cursor and hookSpecificOutput.additionalContext for Claude Code, instead of raw status JSON that Cursor ignored. Output stays valid JSON under 4,000 characters by shortening long lists and strings rather than cutting bytes mid-token.
  • Cursor no longer loads the Mental rule twice when the Mental Cursor plugin is installed: mental install skips and removes ~/.cursor/rules/mental.mdc, and mental doctor warns while both are present.

Changes

  • MCP tool definitions now close their input schemas (additionalProperties: false) and carry annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) derived from each command's effects. Tool results include structuredContent with the same JSON as the text content, which is kept for older clients. Tool names are unchanged.
  • mental install --mcp and mental option mcp on also register the server in Codex (~/.codex/config.toml, [mcp_servers.mental]) when ~/.codex exists. Other tables in that file are left untouched, and turning MCP off removes only Mental's table.
  • Dashboard styles define each colour once with light-dark() instead of a duplicated dark-theme block, and the remaining hard-coded colours are tokens, so the light theme has no dark-only colours. The project picker fits narrow panels, full-height areas use dynamic viewport units, and there is a phone breakpoint at 480px.
  • The Mental panel in Claude Desktop and Claude Code is redesigned around what you need next. The top of the pane is where to pick up, Park and Hand off (Hand off leads when the context is nearly full), and what needs you as one button per item that opens it. Below are this session in one line, the clock, recent receipts, and Journal, Decisions, Notes and Threads to read in the panel. The terminal and Desktop now draw the same native panel instead of separate tab and card designs, the terminal pane scrolls instead of cutting to "+N more", and the terminal can browse and open entries too. Desktop uses the host's own text sizes, a primary button and Markdown on Claude Code 2.1.299 or later, keeps the logo as the only image, and drops the stat cards and looping animations.
  • When Mental cannot be read, the band says why instead of "Not linked here".
  • mental install rewrites session-start hook entries left by 0.12.1 and older when hooks are on; the old session-start.sh still works and forwards to the new command. Claude Code no longer gets a PreCompact entry, since SessionStart already fires after compaction and PreCompact output never reaches the model.
  • mental doctor explains OpenCode's rule source: without ~/.config/opencode/AGENTS.md it reads the Mental block in ~/.claude/CLAUDE.md, and a new rule-opencode-fallback warning fires when OPENCODE_DISABLE_CLAUDE_CODE turns that fallback off. install still never creates that file, because doing so would stop OpenCode from reading CLAUDE.md.

[0.12.1] - 2026-10-08

Fixed

  • The Claude Desktop panel no longer fights your scrolling. A render without an isWorking prop was treated as a change, which repainted the panel and re-rendered it in a loop, snapping the scroll back. The "starting" dashboard check also repaints only when its state changes.
  • Starting the dashboard from the panel no longer opens and closes terminal windows in a loop on Windows. The dashboard runs detached with no console, so each git call it made per request (git --version, rev-parse, remote get-url, check-ignore, ls-files) flashed a console window. All child processes are now spawned with windowsHide, and a test enforces it.

[0.12.0] - 2026-10-08

Features

  • Mental in Claude Desktop and Claude Code (2.1.287+): the Claude plugin ships a mod with a two-row band above the prompt (resume point, live pulse while the agent works, open attention and decision counts, a receipt when Mental writes) and a /mental pane with Now, Residue, Decisions, Session, and Time tabs. Park and Handoff put the request in the prompt rather than writing directly. In the Claude Desktop Code tab a Mental button with the brain logo sits in the prompt footer and opens a side panel of dashboard-style cards (resume point, this session, needs you, files touched, recorded in Mental, guardrails) that refreshes itself, animates in, and reorders to fit the session; in a terminal it docks in fullscreen at 110+ columns. Browse opens journals, decisions, notes, threads and the last hand-off inside the panel (click an item, then Back), a concern can be hidden from the footer without removing it from Mental, and the panel no longer repaints while you scroll. mental doctor adds a claude-panel row that warns when Claude Code is too old to show it. See docs/install.md. (#66)
  • mental heartbeat --passive reads the thread without pinging the focused Track timer, so a panel that polls does not stretch a sit-down.
  • The dashboard inspector keeps a history as you follow links between items. A back arrow, a breadcrumb trail (long trails collapse to …, click to expand), and stacked cards behind the drawer show where you came from, and clicking a crumb or a card jumps back to it. Each step is a browser history entry, so Back, Forward, Alt+←, and Backspace all move through the trail, and scroll position is restored when you return.
  • mental dashboard is redesigned around one question: where does this project stand? Today leads with the resume point, open attention, recent guardrail decisions, and a 30-day journal activity stream. Attention and Decisions are boards, and Library is one filterable list of every note, decision, attention item, and journal. Map keeps the tag graph, Sit-downs appears only when Track is on, and All projects shows each catalog's last outcome and when it was last touched. Any item opens in a side inspector you can pin, with backlinks and related-by-tag. A command palette (Ctrl/? K) searches items, projects, and views, and keyboard shortcuts cover navigation. Light and dark themes follow the system, with a manual toggle. The layout works down to phone width. The server is still read-only with no dependencies; it adds /api/activity, plus lastTouched and outcome on /api/projects.
  • mental decide, mental attention, and mental note require --tag (1–3 topic slugs) when creating a file. Omitting it on update leaves existing tags in place, so older files stay as they are. mental doctor warns untagged (exit 0) and lists files whose tags are missing or empty. The dashboard map defaults to a force graph of file dots and still has the Brain and Tree layouts.
  • Stale and superseded notes and decisions. mental supersede <path> --by <newer> and mental obsolete <path> mark a note or decision as replaced or no longer true (status: superseded with a superseded_by pointer, or status: obsolete); --restore undoes it. Only the frontmatter changes, the file is never deleted, and journals stay untouched history. The replacement gets a supersedes: link. Marked files drop out of the heartbeat, brief, open-decision and conflict lists, are no longer offered as link candidates, and mental search shows them last with superseded by <path> / obsolete. mental doctor (with a model key) now also proposes superseded marks when two notes or decisions clearly replace one another; the newer file wins by date, and --apply is required to write. Both commands work without any model.
  • The shipped agent rule and skill now cover supersede / obsolete and the obsolete status.
  • mental doctor repairs historical data with a decision model (optional, needs a key): plain mental doctor now previews model-proposed topic tags for untagged files and typed links for older files (a jev-repair warn check; next: mental doctor --apply). --apply writes them (tags line and a ## Related list only), --limit N sets files checked for links per run (default 10, max 200) and progress carries over between runs. --offline skips it; --apply without a model or on a personal slice with personal off warns and writes nothing. Findings never change doctor's exit code.
  • mental brief (read-only, also an MCP tool): one paste-ready "continue this work" packet for a new agent or chat. It holds the resume line, last hop, branch and changed files, capped residue (needs eyes, in the air, later), open decisions, and the last few hops (--hops N, --find WORD, --since park|handoff; each hop shows its kind and the plan it ran against). No transcript is included. With a decision-model key, residue is ordered by relevance to the current branch and changes and clearly irrelevant items are hidden (counted under hidden); --no-rank skips the model and any failure falls back to the plain packet. The model sees only titles and descriptions, redacted.
  • mental search --rank (optional, needs a key): re-orders hits by relevance to the query. It also asks which kind of file the question wants (decision, attention, note) and moves matching hits up half a level. It never drops a hit and falls back to the normal order on any failure.
  • A zero-hit mental search with a key now falls back to the model reading the 24 freshest files (same filters, higher bar, output broad: true) when typo and stem variants find nothing, so paraphrases like "credentials" for "login" can still surface.
  • mental extract <file|-> (optional, needs a key): proposes actions, decisions and concerns from pasted meeting notes or a transcript. Dry run by default; --apply --tag <slug> writes each proposal as an attention item or open decision (re-running does not duplicate). The raw text is never stored, and lines are redacted before sending and before writing.
  • Write-time guards (optional decision model, advisory only). journal, handoff, decide, note, attention and park writes may return data.guard: secret (the text looks like a credential; rotate it and rewrite the file), resume (vague or missing: the resume line is not an exact next step) and suggestDecide (a journal entry reads like a decision; record it with decide). handoff is now wrapped too. mental show adds data.flags (instructions) when stored text reads like instructions aimed at an agent. A write is never altered or blocked, text is redacted before sending, local pre-filters mean ordinary writes make no request, and the personal slice is skipped when option decide personal off. mental doctor keeps the global scans.
  • Multi-provider decision models. mental option decide (alias option jev) now supports TypeSafe Jev, OpenAI Decisions (gpt-6-luna), Cloudflare Clef (clef, clef-flash; needs your account id) and a custom TypeSafe-shaped endpoint. Store several keys with key <KEY> --provider P, choose the active one with provider P, and set a fallback used when the active provider fails. Spend and the daily budget are shared across providers.
  • Personal-slice notes may be sent to the model when a key is set (secrets are still redacted before sending); opt out with mental option decide personal off, which restores the old behaviour for retag and doctor.
  • mental retag [path] [--apply] [--limit N] (optional, needs a Jev key): proposes one topic tag for each untagged file. It picks from existing tags (on 2+ files) and, for repos with few tags, frequent title words (marked * as a new topic). Dry run by default; --apply edits only the tags: line of matches at 70%+ confidence. Personal notes are included unless option decide personal off; content is redacted before sending.
  • Duplicate triage is now one Choice question over all candidates ("which one already records this, or none") instead of one yes/no per candidate, so the write-time "similar" hint is cheaper and cannot flag several near-twins at once.
  • Typed links: relink and show label each suggested link as supports, supersedes, contradicts or depends_on (plain related stays unlabelled), and relink --apply writes - supersedes: [Title](path). The label is advisory and falls back to related on low confidence or failure.
  • Optional Jev assist (TypeSafe AI System One, a fast typed-judgment API). Mental works fully without it; with a key it adds: search recovery when a query has zero hits (typo/variant expansion, then Jev keeps only relevant files, data.recovered), a "similar to existing" hint on journal/decide/note/attention/park writes (data.similar, never blocks the write), suggested links on mental show (data.suggestedLinks), and mental relink [path] [--apply] (dry run by default; --apply writes only high-confidence links under ## Related). Everything fails open: no key, network error, timeout, or HTTP error leaves behavior unchanged. Set the key with mental option decide key <KEY> (config file only); mental option decide off mutes it. Without a key, heartbeat and a zero-hit search print a rate-limited (3 days per surface) reminder that Jev exists (data.jev); MENTAL_NO_HINTS=1 silences it. Agents relay the hint but never set a key or enable Jev (the MCP option tool rejects decide/jev).
  • mental doctor runs optional Jev content checks when a key is set (all warn-only, exit code unchanged): stale residue that looks resolved/obsolete, contradictory decisions, a missing or vague handoff Resume:, topic suggestions for untagged files (suggest only, never written), and files that may contain credentials (paths only; values are redacted before sending). Personal-slice notes are never sent; calls fail open and count toward the daily budget. mental doctor --offline skips them.
  • Jev client generalised beyond yes/no: Choice and Score questions with model confidence (normalised, malformed answers dropped), token-aware request splitting under the API limits (too-large fails open), retry-after honoured on 429/529, a local usage ledger plus optional daily budget (mental option jev budget <tokens>|off, status shows today's spend), and answer caching keyed by model version. Groundwork for upcoming auto-topic, triage and guard features; no behaviour change for existing Jev surfaces.
  • Dashboard map Graph redesign: files are grouped into visible topic bubbles (a file joins its largest topic tag; untagged files group by type), so the overview is readable instead of a ring of tiny dots. Labels appear by zoom level with collision culling, hovering a file fades everything but its links, clicking a bubble zooms into it, the tag chip row collapses to one line with "Show all N tags", and a small legend explains colour, size and fading. Brain and Tree are unchanged.
  • Dashboard UX pass: collapsible overview (remembered) with a 2-line resume and "Show more", side-by-side pulse on wide screens, richer catalog rows (icon, 2-line title, status dot, tags), a draggable and keyboard-adjustable catalog splitter, ↑/↓ list navigation, an empty preview with quick-jump buttons, filled filter-chip states, and previously undefined --shadow-xl / --ink-muted tokens defined.
  • mental move <path> --to <project> (and attention --move-to <project>) re-files an attention/decision/note into another bound project, preserving timestamp, frontmatter and body; warns on dangling links; -2 suffix on name clash. attention, decide and note take --project to file into another bundle from any cwd (never mints a binding for the cwd). MCP: move, project, move_to.
  • mental list and mental search page their results (default 50) with --limit, --offset, and --all, and report total, returned, truncated, and nextOffset. --since / --on YYYY-MM-DD filter by timestamp. Rows carry timestamp, updated, and project. MCP tools accept the same arguments.
  • mental list and mental search take --project <id|name|id-prefix> to read one other bound project and --all-projects to read every binding; results are tagged with project, report scope / projects, and page over the union. MCP: project, all_projects.
  • The heartbeat surfaces stale decisions and attention (open/deferred decisions, open/later attention untouched for 14+ days) as stale in JSON and a Stale (> 14d) text block, and the skill tells agents to propose resolving, deciding, or superseding them (#62).

Changed

  • Breaking for early Jev users: decision-model keys and URLs are now read only from ~/.mental/config.json; the MENTAL_JEV_KEY, TYPESAFE_API_KEY and MENTAL_JEV_URL env vars are ignored, and a 401 no longer retries with a raw Authorization header. An existing jev config key migrates to the TypeSafe provider automatically.
  • The shipped agent rule and CLI reference now cover optional Jev: the data.jev hint, data.similar, relink, retag and jev-* doctor advice. Agents never set or run option decide / option jev.

Fixes

  • OpenAI Decisions batches now cap at 10 questions per request (the documented limit) instead of 16. Verified the Cloudflare Clef response shape (model, answers, usage), which the adapter already handles bare or inside the REST result envelope.
  • Jev, found in live testing: mental doctor no longer suggests a junk topic when the bundle has almost no tags (a topic needs at least 3 files and 0.7 confidence), and relink and show now find candidates from body text, not only titles, with a calibrated 0.75 link threshold. The secret guard keeps its own 0.9 bar.
  • mental search 2026-09-24 matches that date instead of AND-ing 2026, 09, and 24. Results exclude nested projects/ paths, and the index schema is rebuilt automatically.
  • Heartbeat counts agree with mental list totals: nested attention/decision files are counted, and files without a status count as open (#67).
  • mental attention warns (warning in JSON) when a new open item's title starts with DONE, CLOSED, COMPLETE(D), or CORRECTION: settled facts belong in note/journal, not open residue. The skill documents the rule (#67).

[0.11.0] - 2026-10-08

Features

  • The dashboard map groups by topic tag. Graph draws one hub per tag with its files around it, and Brain and Tree use those same tag hubs. Zoom and pan can move between the clusters.
  • mental dashboard opens an optional read-only localhost explorer (127.0.0.1:3847, ephemeral fallback if busy) so a human can browse the catalog, explore an interactive 2D SVG mind map with D3.js (structured non-overlapping columnar layout per category, sticky drag-and-drop positioning, smooth organic cubic Bezier branch links, and collapsible branches), or peek at one file as rendered markdown. When Track is on, the page shows running clocks, today's stops, and a timeline of what was written during each sit-down. The CLI stays heartbeat-and-exit; agents keep --json.
  • Interactive Mind Map clusters concepts by Open Knowledge Format (OKF) subject matter and frontmatter tags rather than file type, while preserving type-colored node indicators (🎯 Decision, 🚦 Attention, 📝 Note, 📓 Journal). Features high-signal cross-cluster links (markdown links, frontmatter against and from references, concept mentions, and shared tags across domains), responsive type filter chips, keyword/tag search filtering with real-time glowing matches, persistent selection highlights where connectors and related nodes remain illuminated after click, and a 1-click layout switcher between Organic Brain (dynamic force clustering with zero-overlap collision bounds where connected items gravitate together) and Structured Tree (neat columnar layout).
  • mental backup --out <dir> packs this machine's OKF and identities into a portable directory (no sqlite, no hours, no machine paths). mental restore --from merges per UUID so dest-ahead work stays; --replace --confirm REPLACE is disaster-only for packed slices.

Fixes

  • Fixed "no file selected" message persisting after document selection by enforcing [hidden] { display: none !important; } across all components so specificity rules do not override hidden view states.
  • Fixed mind map node crowding, overlap, and cluster collisions by replacing force simulations with a deterministic, structured radial/columnar layout with 600px cluster separation, 100px column gutters, 38px row gutters, and edge-to-edge hierarchical connecting lines.
  • Fixed node dragging snapping back on mouse release by persisting drag coordinates in a pinned node store, disabling snap-back forces, and visually indicating pinned nodes with a dashed accent border.
  • Fixed dashboard mind map failing to load in environments without hardware WebGL by bundling client-side D3.js v7.9.0 for universal SVG rendering without external CDNs.
  • Fixed low-contrast "light on light" elements across Light and Dark themes, including form inputs, select dropdowns, status pills, and kind badges with WCAG AAA compliant contrast.
  • Fixed layout collapse and word-wrapping in narrow viewports by making the reader pane responsive with proper min-widths and non-overlapping header rows.
  • mental dashboard listens on IPv6 loopback (::1) as well as 127.0.0.1, so Chrome's IPv6-first localhost does not get connection refused.
  • CLI update check no longer treats a failed npm view (timeout, Windows ENOENT, junk stdout) as a successful check. Failures record lastFailedAt and retry after 15 minutes instead of locking out discovery for 24h/7d. Windows now spawns npm.cmd the same way install does. Envelope refresh uses the same 5s timeout as doctor.
  • Personal-mode list / search no longer walk ~/.mental/projects (project slices stay exclusive; mental pulse / dashboard project switcher remain the other-repos view).
  • Park, handoff, and journal stop the sole remaining Track interval when none is focused (a nested --new hop can steal focus and stop, leaving the sit-down clock running). Two or more unfocused runners still skip.
  • mental restore refuses a backup whose slice ids are not UUIDs, so a packed id cannot escape ~/.mental/projects.
  • mental track --json glance is compact (running + today's stops + counts). It no longer dumps nested tasks[] history, so agent hosts with a 64 KiB stdout cap can parse it. Full history is mental track --history --json or mental track report.
  • Thrown errors under --json (install, handoff, journal) return a JSON envelope with error.code / path / hint instead of a raw Node stack. IO failures exit 4.
  • mental install skips recopies when the dest skill version already matches the CLI (pass --force to recopy). mental doctor --fix still force-recopies.
  • mental install --project writes only repo dests (.github/skills/mental and .cursor/rules/mental.mdc) so a sandboxed agent can vendor without home-dir access. uninstall --project is the matching inverse.
  • Install continues past individual dest failures and reports written / skipped / failed.
  • mental doctor warns time-unclocked when Track is on and today has a hop with no clock row. Hooks still do not start a clock.

Changes

  • Revamped dashboard UI/UX with professional developer-tool design system: systematic dark/light token hierarchy, responsive context hub with live status beacon, segmented view switcher with vector icons, keyboard shortcuts (/ search, Esc), copy path/markdown actions with feedback, and accessible contrast.
  • The localhost dashboard opens on where you left off: resume, last outcome, git, and the in-the-air, later, and unsettled titles. Catalog, sit-downs, and the open file sit in a two-pane workspace. Clocks stay collapsed until opened.
  • Dashboard type labels are chips with the same emoji the CLI uses (📓 journal, 🚦 attention, 🎯 decision, 📝 note). Each kind has its own background and text color. The page title is Mental CLI Dashboard.
  • The project mark is the brain emoji. The README and the Cursor plugin use assets/logo.png. The dashboard tab uses the same image. The previous pixel character is gone.
  • Optional feature listings say what hooks and Track actually do: hooks load mental status --json; Track is a ledger until mental track start.

[0.10.2] - 2026-09-09

Fixes

  • Unbound search, list, and show no longer walk every home project under ~/.mental/projects. Until a write creates a UUID, glance returns an empty catalog (show is not-found). Leftover ./.mental still imports only on write. mental pulse remains the cross-project view.

[0.10.1] - 2026-09-08

Features

  • mental track stop --billable suggested records glance suggested_billable (elapsed to last heartbeat) instead of requiring the caller to copy that value by hand.

Fixes

  • mental track report includes running intervals with live wall and always emits wall_minutes plus running / running_minutes, so an unstopped clock is not a silent zero.
  • mental doctor warns on a stale running interval (idle since last heartbeat) instead of listing it as a healthy info line.
  • --accept-stale is a no-op, including under --json, so a hook or timer can pass it. stop already worked without the flag.

[0.10.0] - 2026-09-07

Features

  • mental doctor --fix applies safe repairs only: recopies home skills/rules, purges leftover Balakit Mental wiring, and adds global git excludes. It does not write project .cursor/rules, does not enable hooks/MCP/track, and does not update npm or host plugins. After doctor, agents re-run mental doctor --json, then mental doctor --fix --json once if needed, and ask before --project or optionals.
  • Doctor TTY and JSON print a portable next: command (mental doctor --fix, mental install --project, mental-repair / mental-repair.cmd, or npm i -g). ASCII only, no &&, same on Windows, macOS, and Linux.

Fixes

  • mental doctor treats ~/.cursor/rules/mental.mdc as coverage (Cursor 2.1+ loads home rules). A missing file is an error, same as Claude's ~/.claude/rules/mental.md. Project .cursor/rules/mental.mdc stays a warning for Cloud/CLI. TTY prints ⚠ for failed warn checks and ✖ only for errors, so warn-only still ends with doctor clean.

[0.9.1] - 2026-09-06

Fixes

  • mental install writes the always-on rule to each host's documented path: ~/.claude/rules/mental.md plus the CLAUDE.md managed block, ~/.codex/AGENTS.md, and ~/.config/opencode/AGENTS.md when that file already exists. Cursor still gets ~/.cursor/rules/mental.mdc (not natively loaded) and a project .cursor/rules/mental.mdc on mental install --project. mental doctor fails when a load-true host file is missing and warns that Cursor global rules are not natively loaded. mental uninstall removes each destination and deletes a leftover empty AGENTS.md/CLAUDE.md so OpenCode can fall back to CLAUDE.md.

[0.9.0] - 2026-09-01

Features

  • mental-repair provides a one-time, unshadowed migration path for existing Windows installs. It fingerprints Mental 0.7/0.8 launchers under ~/.local/bin, quarantines only owned files, preserves unknown paths, verifies npm's current launcher, and restores the quarantine if verification fails.

Changes

  • npm is the sole owner of the mental executable. Fresh installs use the same npm i -g, mental install, and mental doctor commands in PowerShell, cmd.exe, Windows Terminal, Git Bash, macOS, and Linux. mental install now installs skills/rules/config only; it no longer self-updates, performs a second global npm install, or writes duplicate PATH launchers. Existing Windows installs from 0.8.1 or older run mental-repair.cmd once. Strict PowerShell policies can use npm's .cmd launchers.

  • Node.js 22.13 or newer is now required, matching the unflagged node:sqlite runtime used by Mental Track.

Fixes

  • CI and the Release workflow run the full tests plus install recipes on Ubuntu, macOS, and Windows before publish. Windows verifies npm's .cmd launcher and bare mental from PowerShell, cmd.exe, and Git Bash. Dirty-profile tests cover rollback-safe 0.7/0.8 launcher repair. Paths canonicalize via native realpath; export --out walks NTFS identity so an 8.3 short-name destination inside the worktree is still refused. Lockstep file keys remain POSIX.

[0.8.1] - 2026-08-31

Fixes

  • Windows install/upgrade no longer leaves a mental symlink (or raw copy) that ShellExecutes cli.mjs — the "how do you want to open this file?" dialog. mental install now writes mental.cmd, mental.ps1, and a Git Bash shim in both ~/.local/bin and the npm prefix, and deletes the leftover link 0.7.x created. Agent paste and the setup skill no longer name cli.mjs as a command (that path is what agents ran). Developers on a git checkout use npm run mental -- install.

[0.8.0] - 2026-08-30

Features

  • Track automatically records AI-generated private and customer-ready title/body fields alongside wall and billable time. Start is ensure-running; --new starts another clock. Park, journal, and handoff refresh the customer copy and default billable to wall in the same command. Missing copy returns a renderer-safe single-select question (id, plain prompt, short { id, label } options, allow_multiple: false) with numbered-text fallback. Dated external exports contain customer descriptions, wall, and billable while omitting private detail. Existing user-time values migrate to first-class billable columns; --user remains a compatibility alias.

Changes

  • README, install, CLI, agents, why, and the agent procedure describe automated time capture, low-friction defaults, native structured questions only for genuine ambiguity, and steerable customer copy.

Fixes

  • Never-started is short wall (start → now under 2 minutes), not last_seen ≈ started. Overnight leftover still flags stale_stop without wiping user. Overlap detection treats a running interval as open through now.

  • Update notice learns a new npm version within 24h when this CLI thinks it is current. The 7-day cache applies only while already behind. TTY prints the hint once per day; --json still includes update on every call. Failed npm lookups back off instead of retrying every command. Prerelease sorts below the matching release.

  • Windows install no longer ShellExecutes .mjs files (the "how do you want to open this file?" dialog). mental install writes a mental.cmd shim that runs node, and self-upgrade re-invokes via process.execPath. The agent paste leads with npm i -g and forbids running .mjs as a command.

[0.7.1] - 2026-08-29

Features

  • mental decide create requires --body (the why). Same --title without --body still updates. Decision files are title plus body — no Context/Options/Outcome placeholders.
  • Search JSON includes tokens and op (and or or). Space-separated words are AND prefixes unless --any. MCP q may be a string array (union of queries). Quotes are not a phrase operator.
  • Journal hops (## HH:MM — title) index as their own search rows (journal/YYYY-MM-DD.md#HH:MM). mental show that path returns the section. list stays one file per day.
  • Search ranks Decision, then Note, then Attention, then Journal.
  • Heartbeat TTY splits Later (attention --status later) from In the air. JSON adds later / laterCount. "Come back to this" / "note that for later" is this status — not a note.

Fixes

  • Attention create no longer writes <why this would cost a reload if forgotten> into the file. Title-only residue is allowed.

Changes

  • Skill and always-on rule: before proposing a flag, crate, or approach, search that name; rejected approaches are Decisions with a searchable title. Journal is not the graveyard of failed ideas.
  • Skill and rule: "come back to this" / "for later" → attention --status later --kind thread. Never note for leftovers.
  • Existing users upgrade with npm i -g @balacode/mental then mental install then mental doctor. Agent paste no longer skips those steps when Mental is already on PATH. Search index rebuilds on the next search; journals stay. Host plugin is a second channel.
  • Agent install paste names skills/mental-setup vs skill/mental, fail-open, and no plugin MCP. README and install-doc pastes stay identical.
  • Official product name is Mental CLI (short forms Mental / mental). Docs and agent skill/rule copy; binary, npm package, and repo stay mental.
  • Official slogan is I type mental. Landing docs; npm/plugin descriptions still lead with the continuity promise.

[0.7.0] - 2026-08-28

Features

  • Plugin skill is a CLI bootstrap (skills/mental-setup/). The full procedure lives in skill/mental/ and is copied by mental install.

Changes

  • Native plugin no longer auto-starts clone MCP from mcp.json / .mcp.json. Use mental install --mcp for PATH mental serve. Breaking for plugin-only MCP users.

0.6.0 - 2026-08-28

Features

  • Single command catalog drives grouped help, mental schema --json, shell completions, and MCP inputSchema. Groups: Daily, Lookup, Write, Identity, Setup.
  • Progressive help: mental -h is Daily (one screen); mental --help is all commands grouped; mental <cmd> --help and mental help <cmd> show that command with examples first, required vs optional, and enums.
  • mental schema --json dumps the catalog (no auth, no network). mental schema <cmd> --json is one command.
  • mental completion bash|zsh|fish prints a completion script from the catalog (does not write shell rc files).
  • mental --json with no command is a heartbeat (exit 0). Non-TTY no-args without --json still prints help and exits 2.
  • Unknown flags fail (exit 2, unknown-flag) instead of becoming silent booleans. Hint lists legal flags for that command.
  • POSIX -- ends option parsing (mental search -- -label is a query, not a flag).
  • JSON errors include error.hint (copy-paste next argv). Usage failures exit 2. Human errors go to stderr; --json stays on stdout.
  • doctor --json sets ok: false when process exit is 3 (error-level problems). Warn-only stays ok: true.
  • list / search JSON include truncated and total (default cap 50).
  • Heartbeat JSON includes id and mode so agents can skip a where round-trip.
  • mental heartbeat --json --fields resume,attention masks keys. --fields with no value lists legal names.
  • --plain / --no-color, plus NO_COLOR (any non-empty) and TERM=dumb: no emoji, no ANSI. MENTAL_ASCII still strips emoji only.
  • TTY heartbeat footer: more · mental doctor · mental search · mental --help.
  • TTY-only “did you mean” for unknown commands. Never auto-run. --json hard-fails with unknown-command and a Daily hint.

Fixes

  • journal requires --resume (no silent “Continue” default). Aligns with park/handoff and the skill.

Changed

  • Agent install paste tells the host to use only this client's plugin flow (do not run other hosts' /plugin / copilot plugin / Command Palette steps).
  • Human install docs match Cursor Customize / local symlink, Claude slash vs CLI, and Copilot shell. No GitHub URL /add-plugin.
  • Skill points agents at --help / schema instead of inlining a flag table (skills/mental/references/cli.md). Procedure stays in SKILL.md.
  • MCP inputSchema is generated from the catalog for the existing session subset (identity and setup stay CLI). Journal MCP accepts against. Closed enums for kind / status where the CLI already has them.

0.5.1 - 2026-08-28

Changed

  • Release workflow publishes with secrets.NPM_TOKEN (NODE_AUTH_TOKEN) and setup-node registry-url. workflow_dispatch can republish HEAD when git tag v$(package.json version) already exists. Agent rule: a release is not done until that npm version equals the tag.
  • Agent install paste no longer includes in-repo release lockstep. After doctor, agents ask about optional hooks and time tracking, and whether MCP is needed, with a one-liner for each. Still wait for yes this turn.

0.5.0 - 2026-08-28

Added

  • Optional time tracking as an isolated, default-off add-on. Hours live in bundle time.sqlite (never git, never the FTS cache). Durations are wall (sum of in-session elapsed) and user (human time inside that wall), rendered as h:mm. mental option flags track (per UUID), MCP, and hooks in ~/.mental/config.json. mental track start/stop/focus/discard/report/export. Heartbeat --json may include a compact data.track sibling (ids only, no titles or hours); TTY heartbeat and pulse stay freeze without a timesheet. Park/handoff stop the focused interval only. The track skill lives in optional/mental-track/ (not plugin skills/). Install and doctor return optionals[] with needsConsent: true. Agents must not enable a feature unless the user named it this turn.
  • Product version lockstep: package.json is source of truth. Portable plugin.json, Cursor/Claude shims, the lockfile, and skill metadata.version must match. node scripts/bump-version.mjs <semver> writes them; --check (and release.yml) refuse drift. Marketplace plugin entries still omit version (Claude uses plugin.json).
  • mental doctor warns when a Claude Code or Copilot plugin, or a copied skill, is behind this CLI. Probes claude plugin list --json / copilot plugin list --json (fail open if missing). Does not write host plugin caches. MENTAL_SKIP_HOST_PLUGIN_CHECK=1 skips.

Changed

  • Skill metadata.version now tracks the product version (was 1.0.0). Native plugin install is documented as a second channel: mental install refreshes CLI + skill copies, not the host plugin UI.

0.4.1 - 2026-08-27

Added

  • Every --json envelope may include an update sibling (current, latest, hint) when npm is ahead of this CLI. Agents tell the user once and suggest mental install. TTY prints the same hint. Backed by a 7-day cache under ${XDG_CACHE_HOME:-~/.cache}/mental/npm-latest.json so ordinary commands never npm view; MENTAL_SKIP_UPDATE_CHECK=1 still skips. doctor / install still check live.

Fixed

  • GitHub Release workflow no longer sets setup-node registry-url. That wrote a dummy NODE_AUTH_TOKEN and made npm skip OIDC trusted publishing (E404), so 0.3.1 and 0.4.0 never landed on the registry.

0.4.0 - 2026-08-27

Added

  • Attention kind verify — “agent produced this, human has not looked.” Heartbeat lists it first under Needs eyes. Cap still 7. Not a review queue.
  • Hops on the TTY pulse = parks today (hopsToday). delta.parks stays since-last-pulse. Makes stealth switching visible without analytics.
  • Settled on heartbeat: newest decided titles (cap 7, no bodies) so the next agent does not re-litigate.
  • --via <token> on journal / park / handoff / attention / decide — short client token (cursor, claude-code, copilot, codex, mcp, cli). Rejects emails, URLs, paths, and session ids.

Changed

  • Ship a 256×256 PNG mark (assets/logo.png, ~29KB) instead of the 262KB traced SVG. README and Cursor plugin point at the PNG; the SVG is not in the package.
  • README “Why this exists” and docs/research.md now cite 2024–2026 agent-era studies (verification load, supervisory engineering, stealth context switching, the productivity–experience paradox) instead of 1998–2011 interruption papers as the primary proof. The ready-to-resume mechanism still maps to park / handoff.

0.3.1 - 2026-08-27

Changed

  • New Mental mark (assets/logo.svg) on the README and Cursor plugin. Editor chrome stripped; portable plugin.json still has no logo field (schema is closed).

0.3.0 - 2026-08-27

Added

  • mental park --resume — encode continuity at an interruption (default journal title "Parked"), optional attention in the same call, then heartbeat. For mid-hop context switches, not only planned closes.
  • mental handoff --title --resume — planned task-boundary sugar: journal then heartbeat in one shot.
  • mental pulse — compact cross-project rows from bindings.json (resume + residue/decision counts, no journal bodies) for multi-repo orchestration.
  • Since-last-pulse delta counts on heartbeat / pulse / park / handoff (${XDG_CACHE_HOME:-~/.cache}/mental/<uuid>.pulse.json). Heartbeat stays read-only for the watermark; writers refresh it after computing the delta.
  • Open-decision budget mirrors attention (cap 7 on heartbeat TTY and JSON; attentionCount / openDecisionCount; doctor warns when over).
  • Doctor warns (exit still 0 if only warns) for attention and decisions left open/later/deferred longer than 14 days (--days override).
  • First-class README: landing-page promise, measured numbers, and a docs hub (docs/why.md, install.md, cli.md, agents.md, identity.md, benchmarks.md, research.md).
  • README research section + docs/research.md: Parnin/Rugaber resumption lag, Leroy attention residue, Mark interrupted-work stress — mapped to heartbeat, Resume:, and attention.
  • Reproducible micro-benchmarks via npm run bench (scripts/bench.mjs) — CLI vs in-process heartbeat and search at 100 / 500 / 2,000 notes.

Changed

  • Agent Mental receipt is a markdown bullet list: 🧠 **Mental** then - emoji **Kind** › *action* › title. No ──────── wrapper. Actions (italic, lowercase): Journal/Note recorded; Attention recorded/resolved; Decision opened/decided; Read heartbeat/pulse/searched/showed/listed.
  • README is a landing page. Depth (install edge cases, full command table, Agent Plugins, remap) lives in docs/.
  • SQLite index still writes concepts + links when Node’s node:sqlite has no FTS5 module. Search uses LIKE with title-first ranking; FTS5 + bm25 remains the path when the module exists. INDEX_VERSION is 3 so older caches rebuild.
  • Discovery metadata for AI-tooling developers: npm keywords + author, plugin/marketplace keywords, skill tags (coding-agents, mcp, cursor, claude-code, …), and a README subtitle / works-with row (Cursor, Claude Code, Copilot, MCP, Agent Skills).
  • README Who writes — agents journal / decide / record residue after mental install; humans are not expected to keep the log by hand. Same CLI if you want the pulse yourself. Not a hidden hook; not every chat turn.
  • README rebuilt on the award-style 3-tier layout used by uv / Aider / Goose / Mem0: pitch + demo + quick start above the fold; highlights; who-writes table; research as proof not a lecture; FAQ for agents and humans; depth stays in docs/.

Fixed

  • mental park --attention upserts by title like mental attention (same-day retry no longer crashes after the journal write).
  • mental pulse reads opted-in ./.mental for store=local bindings instead of a stale home slice.
  • Heartbeat decision cap keeps the newest open/deferred decisions (same newest-first order as attention).
  • Pulse watermark writes fail open so an unwritable cache cannot fail park/handoff after a successful journal.

0.2.3 - 2026-08-26

Added

  • mental doctor checks npm for a newer @balacode/mental (warn only; fail open). mental install from a published install upgrades the global CLI when npm is ahead, then re-runs so skills match. MENTAL_SKIP_UPDATE_CHECK=1 skips the network. Heartbeat never checks.

Changed

  • Agent Mental receipt wraps with a separator line (────────) instead of </br>, which printed as literal tags in Claude Code and other agents.

Fixed

  • mental install / npm i -g overwrites an existing global mental bin (npm 11 EEXIST). Leftover @mental/cli links no longer block @balacode/mental.

0.2.2 - 2026-08-26

Added

  • mental install finds leftover Balakit Mental skill/rule copies (fingerprint: npx balakit doctor, mentalDataPolicy, …) and deletes them before writing the standalone skill. Mental-only <!-- BEGIN balakit --> blocks are stripped. Journals and ./.mental data are not deleted. mental doctor warns if any remain.

0.2.1 - 2026-08-26

Changed

  • Agent Mental receipt wraps with </br>, uses a markdown hard break after 🧠 Mental, and prints indented Kind: Verb lines so Cursor chat does not collapse the block onto one line.

0.2.0 - 2026-08-26

Added

  • Ranked FTS search (bm25) with snippets, and SQL-side --type / --status / --tag / --kind filters so a typed query cannot be crowded out by untyped matches.
  • mental list includes each concept's description; --kind filters attention on list and search.
  • mental show returns backlinks from the derived link index (file-scan fallback).
  • MCP list tool; search accepts the same typed filters as the CLI; tool results are compact JSON.
  • Agent Mental receipt at the end of a turn that used the CLI: <br>, title 🧠 Mental, then type lines (📓 journal, 🚦 attention, 🎯 decision, 📝 note, 🔍 read). Example in the skill; the always-on rule points at it. TTY writes use the same type emojis. --json stays ASCII (MENTAL_ASCII=1 strips emoji).
  • mental install copies the skill to ~/.config/opencode/skills/mental (OpenCode).

Changed

  • README now shows the logo, npm (@balacode/mental), Agent Plugins 1.0.0 packaging, and copy-paste install prompts for Cursor, Claude Code, VS Code, and GitHub Copilot.
  • npm package is @balacode/mental (unscoped mental is taken). The CLI bin stays mental.

0.1.0 - 2026-08-26

First public release of the Mental CLI.

Added

  • Standalone Mental CLI: on a TTY, no args prints a one-shot heartbeat and exits; named commands are one-shot; agents use --json.
  • UUID identity in ~/.mental/bindings.json, with remap / split / link and local --import / --move.
  • Attention residue (mental attention) and journal --against so heartbeat carries what is still in the air.
  • Agent Plugins 1.0.0 package: root plugin.json, skill at skills/mental/, MCP at mcp.json (stdio ./bin/cli.mjs serve).
  • Cursor / Claude Code shims: .cursor-plugin/plugin.json (SVG logo) and .claude-plugin/plugin.json (displayName: Mental).
  • install --mcp registers serve; decide updates by title so an open decision can close.
  • Install, doctor, uninstall; hooks stay off by default.