MCP tools

The surface an agent sees. rememd speaks MCP, so anything that speaks MCP can use it — these are the tools it finds when it connects.

You do not call these yourself

rememd never launches your agent. You start it however you already do, run rememd connect in that terminal, and context arrives through tool calls rather than through a file injected at startup. That is why there is nothing to configure per project — the connection is the configuration.

An agent that is already running picks up a change on its next rememd tool call, so connecting in another pane is enough.

rememd connect                       # pick in the menu bar
rememd connect famnly                # pick the feature in the menu bar
rememd connect famnly -f "Track usage"
rememd connect --product-only famnly

Knowing where you are

A session is bound to a product or feature, and that binding decides where every other call lands. It is per-terminal, and it survives the agent restarting.

`connect`

Connect this session to a rememd product (and optionally a feature), from any folder on the machine. Call when the user says 'connect to X', 'switch to X', 'work on X', 'point this terminal at X', or otherwise asks to work on a product/feature this session is not already connected to. Product alone is a valid connection — it unlocks knowledge, backlog and search; adding a feature also unlocks its PRD, tasks and timeline. If the target is ambiguous or omitted, rememd opens a picker in the menu bar and waits for the user to choose. Switching away from a current connection closes and logs its session.

Parameter	Type	What it is
`feature_name`	`string`	Optional feature to connect to within the product.
`workspace_hint`	`string`	Optional workspace name, when the product name is ambiguous across workspaces.
`product_hint`	`string`	Product name, e.g. 'Famnly'. Omit to let the user pick in the menu bar.

`disconnect`

Disconnect this session from rememd and log its session. Use only when the user explicitly wants to stop recording while continuing to work — quitting the agent does NOT need this, since an unlogged session stays open and resumes next time you connect. Call when the user says 'disconnect', 'stop recording', 'stop tracking this', 'unhook this terminal'.

`get_connection`

Report what this session is currently connected to — workspace, product, feature and session. Call when the user says 'what am I connected to', 'which feature/product are we on', 'where am I', or before assuming a target. Never answer those questions from CLAUDE.md or from memory: the connection is the only source of truth and it can change mid-session.

`attach_to_feature`

Start or resume a feature-scoped session from the current terminal without opening a new tab. Call when the user says 'also work on X', 'while I am in here', 'quick detour to X', 'this bug belongs to another feature', 'log that against X instead' — work done here that belongs somewhere else. Writes (notes, diagrams, plans, log_session) target THIS feature's session until you attach to a different one. Multiple features can be attached at once — most recent is the current target; others stay parked. Omit `mode` unless the user clearly signalled one; where it matters and they did not, the server asks rather than guessing.

Parameter	Type	What it is
`mode`	`string`	'resume' continues the most recent prior session; 'new' always creates a fresh one. Omit if the user hasn't signalled.
`product_hint`required	`string`	The product name.
`feature_name`required	`string`	The feature name to attach to.
`workspace_hint`	`string`	The workspace name. Required only when the same product/feature name exists in multiple workspaces — pass to disambiguate.

`detach_from_feature`

Park a feature's attached session — writes no longer target it, but the session itself is preserved (not logged). Call when the user says 'park that', 'stop working on X', 'back to the main thing', 'I am done with X for now' — switching away without finalizing. Call attach_to_feature again any time to resume. If feature_name is omitted, detaches the current target. To finalize (close) a session, use log_session instead.

Parameter	Type	What it is
`workspace_hint`	`string`	The workspace name. Required only when the same product name exists in multiple workspaces — pass to disambiguate.
`product_hint`required	`string`	The product name.
`feature_name`	`string`	The feature to detach. If omitted, the current target is detached.

`where_was_i`

What was worked on recently, across every product and workspace at once. Call when the user says 'where was I', 'what did we do yesterday', 'what did I work on this week', 'catch me up', 'what have I been up to'. Names no product and no feature: that is the point, since the thing you have forgotten is which feature it was, and every other tool needs that as its input. Returns a short spoken-length summary grouped by product, saying what kind of work each saw, not a list of events. Follow up with get_feature_context for detail on any one of them. Derived from what was actually written, so work never captured by log_session still appears.

Parameter	Type	What it is
`days`	`integer`	How far back, in days. 1 (the default) means yesterday and today. Use 7 for the week.

Reading context

What an agent loads before it does anything — the PRD, the level above it, and what the last session ended on.

`get_feature_context`

Get complete context for a specific feature — its PRD, tasks, notes and recent session history. Use this at the start of a session on a known feature, and before planning or editing anything the PRD covers. Call when the user says 'the PRD', 'the spec', 'the requirements', 'what are we building', 'where are we', 'status', 'what have we done', 'what is left'.

Parameter	Type	What it is
`product_hint`	`string`	The product name to narrow the search
`feature_name`required	`string`	The feature name, e.g. 'Push notifications' — or a feature id, which is what the user has pasted when they hand you eight characters of hex. The app's feature header copies one.

`get_focus_area_context`

Read the focus area description/PRD — the scope, goals, non-goals and conventions for one area of work. Call when the user says 'what is this area for', 'what is in scope here', 'the conventions for this part', 'the ground rules'.

Parameter	Type	What it is
`product_hint`	`string`	The product name, used to disambiguate if multiple products share a focus area name.
`focus_area_hint`required	`string`	The focus area name (e.g. 'Development').

`get_product_context`

Read the PRODUCT VISION document (what the product is, who it's for, tech stack, conventions). Call when the user says 'the vision', 'what is this product', 'who is it for', 'the tech stack', 'the pitch', 'the high-level description'. Returns the full vision markdown.

Parameter	Type	What it is
`product_hint`	`string`	The product name. If omitted, uses the active product.

`get_product_knowledge`

Read the accumulated product knowledge document (learnings, gotchas, conventions, dead ends promoted from past features). Call when the user says 'what have we learned', 'the gotchas', 'the lessons', 'the conventions', 'have we been burned by this before', 'is there a known trick to this'. Distinct from the product vision — use get_product_context for the vision.

Parameter	Type	What it is
`product_hint`	`string`	The product name. If omitted, uses the active product.

`get_workspace_context`

Read the WORKSPACE context document — what is true of everything built here regardless of product: hosting and DNS habits, and the rules for working with agents. Call when the user says 'the workspace rules', 'our conventions', 'how do we do things here', 'what applies everywhere', 'the top level'. This is the rung above product knowledge — use get_product_knowledge for one product's learnings, get_focus_area_context for one slice of it. Read this before promote_knowledge(level: "workspace"), which replaces the whole document.

Parameter	Type	What it is
`workspace_hint`	`string`	Which workspace. Defaults to the connected one, or the only one there is.

`get_context`

Get recent session context for a product — the last few sessions rather than one. Use this at the start of a session to understand what was previously worked on. Call when the user says 'what has been happening on X', 'recap the last few sessions', 'bring me up to speed on this product'. For the single most recent session, use get_last_session.

Parameter	Type	What it is
`product_hint`required	`string`	The product or repo name
`limit`	`number`	Number of recent sessions to include (default 3)

`get_last_session`

Get the most recent session log for a product, including reusable context and next steps. Call when the user says 'continue', 'where were we', 'pick up where I left off', 'resume', 'what did we do last time', 'carry on'. That is when they have named the product; when they have not named anything, use where_was_i instead.

Parameter	Type	What it is
`product_hint`required	`string`	The product or repo name

`get_session`

Get the full content of a specific session, including every earlier log on it — a session can run for months and be logged many times, and the older logs are not superseded. Call list_sessions or get_feature_context first — both print an id for each session — then pass one here. Pass event_id instead to read one event's whole body, which is how you open a plan or any long entry a listing had to shorten. Call when the user says 'open that session', 'read session X', 'what happened in that one', 'show me that plan', 'read the whole note'.

Parameter	Type	What it is
`event_id`	`string`	Read one event's whole body instead of a session. Pass the 8-character id printed beside a body a listing had to shorten — a plan, a long note, a PRD update. Takes precedence over session_id.
`product_hint`	`string`	The product name (helps narrow the workspace search).
`session_id`required	`string`	Which session: the 8-character id the listings print, a full UUID, or a substring of the session's title.

`list_sessions`

List recent sessions for a product — title, date and the id to read it with. Pass an id to get_session for the full body. Call when the user says 'list the sessions', 'the history', 'when did I work on this', 'how many times have we been here'.

Parameter	Type	What it is
`limit`	`number`	Number of sessions to list (default 10)
`product_hint`required	`string`	The product or repo name

Capturing as you go

The writes that make a session worth resuming. A session receives logs; a feature receives intent.

`add_note`

Save a quick note to the current product in rememd, capturing a decision, an insight or a gotcha mid-session. Call when the user says 'remember', 'note that', 'make a note', 'write that down', 'do not forget', 'capture this', 'for the record'. Pass workspace_hint when the same product name exists in multiple workspaces — otherwise the call errors with the colliding workspaces listed.

Parameter	Type	What it is
`workspace_hint`	`string`	The workspace name. Required only when the same product name exists in multiple workspaces — pass to disambiguate.
`product_hint`	`string`	The product name if known
`content`required	`string`	The note content to save
`feature_hint`	`string`	The feature name if the note belongs to a specific feature.

`add_diagram`

Store a Mermaid diagram in the rememd session timeline, where it renders as a native image. Call when the user says 'diagram this', 'make a diagram of X', or says 'save that', 'keep that', 'make it a diagram' about a sketch already on screen — this is the keep step. If they said draw, sketch, visualise or map out and nothing is on screen yet, render it with show(what: 'sketch') first. Pick the most fitting type — flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram, journey, gantt, pie.

Parameter	Type	What it is
`title`required	`string`	Short title describing what the diagram shows (e.g. 'Auth token refresh flow').
`product_hint`	`string`	The product name if known.
`workspace_hint`	`string`	The workspace name. Required only when the same product name exists in multiple workspaces — pass to disambiguate.
`mermaid`required	`string`	The raw Mermaid source, WITHOUT the ```mermaid fences. Just the diagram code starting with e.g. 'flowchart TD' or 'sequenceDiagram'.
`feature_hint`	`string`	The feature name if the diagram belongs to a specific feature.

`save_plan`

Save the PLAN (what we decided to do) BEFORE executing it. This is the strategy/approach/decisions — NOT what was built. Call when the user says 'go ahead', 'do it', 'sounds good', 'approved', 'let us do that', 'start with that' about a plan you just proposed — right after they approve it, and BEFORE you start building.

Parameter	Type	What it is
`plan_title`	`string`	Short title for the plan, e.g. 'Sidebar Navigation Menu'
`product_hint`	`string`	The product name if known
`feature_hint`	`string`	The feature name to link this plan to (optional). Links the plan event to a specific feature for context retrieval.
`workspace_hint`	`string`	The workspace name. Required only when the same product name exists in multiple workspaces — pass to disambiguate.
`plan_content`required	`string`	The plan as structured markdown with line breaks. Use ## headings, numbered lists, and bullet points. Example:\n## Plan\n1. Step one\n2. Step two\n\n## Approach\n- Detail A\n- Detail B

`log_session`

Save a structured log of the current session to rememd. Call this at the end of every session. Call when the user says 'log this', 'recall session', 'checkpoint', 'wrap up', 'that is it for today', 'I am done', 'save where we got to'. A session is logged many times over its life and every log is kept, so write what happened SINCE THE LAST LOG rather than a fresh summary of the whole session — a session can run for months, and restating earlier work buries it while making the newest and thinnest entry the one a reader sees first. If you do not know what the earlier logs already cover, read them with get_session before writing. If work also happened on other features (rememd will have said 'Also attached: …'), each of those gets its own log too — pass feature_summaries to write them yourself, otherwise they are reconstructed from what was recorded against them.

Parameter	Type	What it is
`files_changed`	`array`
`git_diff`	`string`	Full git diff output for this session (optional but recommended)
`summary`required	`string`	A structured markdown summary of what happened SINCE THIS SESSION WAS LAST LOGGED — not a summary of the whole session. On a first log those are the same thing; after that they are not. Earlier logs are preserved and shown beneath this one, so restating them costs a reader twice and gains nothing.
`feature_hint`	`string`	The feature name if known (optional)
`workspace_hint`	`string`	The workspace name if known (optional)
`branch`	`string`	Current git branch
`feature_summaries`	`object`	Per-feature summaries for other features worked on this session, keyed by feature name — e.g. {"Menu bar connections": "Fixed the mid-session handoff…"}. Each is written to that feature's own session. Any attached feature you omit gets a digest reconstructed from its recorded activity, and one with nothing recorded is discarded rather than logged.
`product_hint`	`string`	The name of the product or repo being worked on
`feature_summary`	`string`	One sentence saying what this feature IS, not what you did this session. Replaces the existing summary — revise it only when it has become wrong or incomplete.

`show`

Put something on the user's screen in rememd — a sketch you author, or a stored diagram, note, session, PRD, product vision, product knowledge, focus area context or task. Call when the user says draw, sketch, render, visualise, illustrate, map out, show me, open that, or 'I don't understand how X fits together'. A sketch stores nothing, so reach for it freely whenever they are trying to understand rather than retrieve; add_diagram is the separate keep step. `what: sketch` renders HTML you write yourself (in `source`) and stores nothing. Everything else opens what rememd already holds; documents open in a real editor, so the user can correct and save what you wrote. With no `name`, `what: diagram` opens the most recent — the one you just drew. The rest resolve from the connected target. This opens a window: call it because you were asked, not because the thing exists.

Parameter	Type	What it is
`what`required	`sketch \| diagram \| note \| session \| prd \| vision \| knowledge \| focus_area \| task`	What to put on screen.
`feature_hint`	`string`	Feature to resolve against. Defaults to the connection.
`source`	`string`	For `what: sketch` only — the HTML to render, which you write. Static HTML and CSS: scripts do not run and no network request is made, so no <script>, no external images, no web fonts. The app's typography and palette are applied for you, and CSS variables --bg/--surface/--ink/--ink-dim/--ink-faint/--rule/--accent plus the classes .card/.row/.col/.muted are available; plain headings, tables and lists already look native. Nothing is stored — the window says how to keep it.
`product_hint`	`string`	Product to resolve against. Defaults to the connection.
`name`	`string`	Which one — a diagram, task or session title, matched as a case-insensitive substring, or a note's id prefix or first line. Omit for the most recent diagram or note — which is the one you just wrote — or when the connected feature/product already identifies it.

Tasks and the backlog

What is being done now, and what is queued behind it.

`create_tasks`

Break a feature's PRD into actionable tasks with dependencies. Call when the user says 'break this down', 'turn the PRD into tasks', 'make a task list', 'plan the work', 'what are the steps'. Read the PRD first via get_feature_context, then generate a structured task breakdown. Each task can reference other tasks it depends on via blocked_by_indices (0-based positions in the tasks array).

Parameter	Type	What it is
`tasks`required	`array`	Array of tasks to create
`product_hint`required	`string`	The product name
`feature_name`required	`string`	The feature name

`get_tasks`

Get all tasks for a feature grouped by status, with each task's description, dependency info and progress. Shows which task to work on next (first unblocked todo). Pass task_id to read one task in full instead. Call when the user says 'the tasks', 'the todos', 'what is next', 'what is left', 'the checklist', 'how far along are we', 'finish the last tasks'.

Parameter	Type	What it is
`feature_name`required	`string`	The feature name
`product_hint`required	`string`	The product name
`task_id`	`string`	Return this one task in full — description included — instead of the feature's list. Full UUID or the short id the list prints. feature_name is ignored when this is given.

`update_task`

Update a task's status, assignee, dependencies, feature assignment, or other fields. Call when the user says 'mark that done', 'tick it off', 'that is finished', 'I am on it', 'block this on X', 'that belongs to another feature'. Use to mark tasks done, assign work, reassign to a different feature, adjust dependencies, or delete.

Parameter	Type	What it is
`title`	`string`	New title
`product_hint`required	`string`	The product name
`add_blocked_by`	`string`	Task to add as a dependency. Full UUID or the short id get_tasks prints.
`task_id`required	`string`	The UUID of the task to update
`description`	`string`	New description
`remove_blocked_by`	`string`	Task to remove from dependencies. Full UUID or the short id get_tasks prints.
`feature_name`	`string`	Move this task to a different feature. The task's featureId is reassigned.
`status`	`todo \| inProgress \| done`	New status
`assignee`	`string`	Assign to this person/agent. Use empty string to unassign.
`delete`	`boolean`	Set to true to remove this task entirely.
`priority`	`low \| medium \| high`	New priority

`delete_task`

Permanently delete a task. Call when the user says 'delete that task', 'remove it from the list', 'that task should not exist'. For work that was finished rather than mistaken, use update_task with status done instead — a deleted task leaves no record that it was ever done.

Parameter	Type	What it is
`product_hint`required	`string`	The product name
`task_id`required	`string`	The UUID of the task to delete

`add_backlog_item`

Add an item to the product backlog. Call when the user says 'we should build', 'we should probably', 'someday', 'not now but', 'park that', 'add it to the backlog', 'note it as an idea'. These become features when the user decides to work on them.

Parameter	Type	What it is
`description`	`string`	Detailed description of what needs to be done
`product_hint`required	`string`	The product name
`priority`	`low \| medium \| high`	Priority level
`title`required	`string`	Short title for the backlog item (will be used to generate branch name feat/slug)
`focus_area_hint`	`string`	Focus area name. If omitted, inferred from the active feature's focus area. Use 'none' to explicitly create a product-level item.

`get_backlog`

Get pending backlog items for a product. Call when the user says 'the backlog', 'what should I work on', 'what needs doing', 'what ideas do we have', 'what is queued up', 'anything pending'.

Parameter	Type	What it is
`focus_area_hint`	`string`	Filter backlog to a specific focus area. If omitted, returns all product backlog items grouped by focus area.
`product_hint`required	`string`	The product name

`update_backlog_item`

Update an existing backlog item. Call when the user says 'bump that up', 'reprioritise', 'that is more urgent now', 'move it to X', 'rename that idea', 'that is not important any more'. Use to move items between focus areas, change priority, update title or description, or delete items.

Parameter	Type	What it is
`title`	`string`	New title
`product_hint`required	`string`	The product name
`backlog_item_id`required	`string`	The UUID of the backlog item to update
`description`	`string`	New description
`focus_area_hint`	`string`	Move to this focus area. Use 'none' to make it product-level (unfocused).
`delete`	`boolean`	Set to true to remove this backlog item
`priority`	`low \| medium \| high`	New priority level

`delete_backlog_item`

Permanently delete a backlog item by its ID. Call when the user says 'drop that idea', 'we are never doing that', 'remove it from the backlog'. Use item IDs from get_backlog output. Only call after the user confirms.

Parameter	Type	What it is
`item_id`required	`string`	The UUID of the backlog item to delete.
`product_hint`required	`string`	The product name.

`create_feature_from_backlog`

Promote a backlog item to a feature with a PRD. Call when the user says 'let us build X' about something already in the backlog, 'promote that', 'turn that idea into a feature', 'time to do X'. Creates the feature and writes the PRD but does NOT start a session. After calling this, tell the user the feature is ready and ask if they want to start working on it now. If yes, call attach_to_feature.

Parameter	Type	What it is
`focus_area_hint`	`string`	Override focus area for the new feature. If omitted, uses the backlog item's focus area, or falls back to the first focus area of the product.
`product_hint`required	`string`	The product name
`backlog_item_id`required	`string`	The UUID of the backlog item to promote
`prd_content`required	`string`	The PRD content as markdown, written based on the discussion with the user

Shaping the ladder

Creating and editing the levels themselves — products, focus areas, features and the documents attached to each.

`create_feature`

Create a new feature under a focus area. Call when the user says 'new feature', 'start something new', 'let us build X' about something not already in the backlog, 'set up a repo for'. Optionally creates a new folder + git repo and connects it to the feature, for work in a dedicated folder (e.g. a sibling repo outside the focus area's existing repos). After this, ask the user if they want to start working on it, and call attach_to_feature if so.

Parameter	Type	What it is
`product_hint`required	`string`	The product name
`prd_content`	`string`	Optional PRD markdown. If omitted, feature is created without a PRD.
`repo_path`	`string`	Optional absolute path to a folder. If the folder doesn't exist, it will be created. If it's not a git repo, git init will run. The feature will be connected to this path.
`name`required	`string`	Feature name
`focus_area_hint`	`string`	Focus area name. If omitted, inferred from active feature's focus area.

`update_feature`

Update a feature's status, summary or name, or move it to a different focus area within the same product. Call when the user says 'that feature is done', 'mark it complete', 'we shipped it', 'put it on hold', 'move it to X', 'rename it', 'that name is wrong now', 'describe it in a sentence'. Completion means the work scope is closed, not necessarily merged — a feature can be completed with no code changes. Moving keeps sessions, notes, tasks and PRD attached via featureId.

Parameter	Type	What it is
`focus_area_hint`	`string`	Optional — name of the target focus area (must belong to the same product). Moves the feature under it.
`summary`	`string`	One sentence saying what this feature is. Replaces the existing summary rather than adding to it. Usually maintained through `log_session`'s `feature_summary`; set it here when correcting one outside a session.
`feature_name`required	`string`	The feature name
`product_hint`required	`string`	The product name
`status`	`planning \| inProgress \| completed \| done \| archived`	New status. 'done' is an alias for 'completed'. 'archived' takes the feature out of the working set: listings leave it out and say how many they left out, while it stays addressable by name and still appears in search, marked. Archive when you have stopped thinking about it, not merely when it is finished. Starting a session on it brings it back on its own.
`new_name`	`string`	A new name for the feature. Keeps its sessions, notes, tasks, issues and PRD — only the name changes. Use when the name has stopped describing the work, not when the work itself changed. Rejected if another feature in the same product already has that name, since names are how features are looked up. The old name is recorded on the product timeline, so searching it still finds the feature.

`delete_feature`

Permanently delete a feature and all its linked data (sessions, notes, tasks, issues, PRD). Call when the user says 'delete that feature', 'that one was created by mistake', 'get rid of it entirely'. This is irreversible — only call after the user explicitly confirms they want to delete the feature. For work that is finished rather than mistaken, use update_feature to complete it instead.

Parameter	Type	What it is
`feature_name`required	`string`	The feature name to delete
`product_hint`required	`string`	The product name

`list_features`

List features for a product, optionally filtered by focus area. Useful when you need to discover what features exist without knowing names in advance. Call when the user says 'list the features', 'what else is in this product', 'what is in this focus area', 'what have we got on the go'. Archived features are left out by default and the count of what was left out is stated; pass include_archived to see them.

Parameter	Type	What it is
`include_archived`	`boolean`	Include archived features (default false). They are listed with an ARCHIVED marker rather than mixed in silently.
`product_hint`required	`string`	The product name
`focus_area_hint`	`string`	Optional focus area to filter by

`create_focus_area`

Create a new focus area under a product. Call when the user says 'new area', 'new category', 'organise this into', 'group that work under' — e.g. 'investigate', 'marketing', 'infrastructure'. The focus area will be scoped to the current product.

Parameter	Type	What it is
`description`	`string`	Brief description of what this focus area covers
`name`required	`string`	Name for the focus area
`product_hint`required	`string`	The product name

`delete_focus_area`

Permanently delete a focus area and all its linked features, sessions, notes, tasks, issues, and PRD. Call when the user says 'delete the area', 'get rid of that whole category'. This is irreversible — only call after the user explicitly confirms deletion.

Parameter	Type	What it is
`focus_area_hint`required	`string`	The focus area name to delete.
`product_hint`required	`string`	The product name.

`list_focus_areas`

List focus areas for a product with feature counts, backlog counts, and repo paths. Useful for discovering the structure of a product. Call when the user says 'list the focus areas', 'what areas are there', 'how is this product organised', 'where would this belong'.

Parameter	Type	What it is
`product_hint`required	`string`	The product name

`update_feature_context`

Update the feature PRD/context document. Call when the user says 'update the PRD', 'write the spec', 'add that to the requirements', 'the PRD is out of date', 'document what we decided'. Pass the COMPLETE updated content — this replaces the entire document by default.

Parameter	Type	What it is
`mode`	`replace \| append`	'replace' (default) overwrites the entire PRD. 'append' concatenates content to the existing PRD.
`content`required	`string`	The PRD content as markdown. In 'replace' mode (default) this REPLACES the entire document; in 'append' mode this is concatenated to the existing content.
`product_hint`	`string`	The product name
`feature_name`	`string`	The feature name

`update_focus_area_context`

Write or replace the FOCUS AREA description — scope, non-goals and conventions for this area of work. Call when the user says 'write the scope for this area', 'the conventions here', 'what is out of scope', 'describe this part of the product'. A focus-area PRD lives on the focus area itself, so do not create a feature to hold one. Pass the COMPLETE content; this replaces the whole description.

Parameter	Type	What it is
`focus_area_hint`required	`string`	The focus area name (e.g. 'Development').
`mode`	`replace \| append`	'replace' (default) overwrites the entire description. 'append' concatenates content to the existing description.
`product_hint`	`string`	The product name, used to disambiguate if multiple products share a focus area name.
`content`required	`string`	The full updated focus area PRD / description as markdown.

`update_product_context`

Update the PRODUCT VISION document only (what the product is, who it's for, tech stack, conventions). Call when the user says 'update the vision', 'change what this product is', 'rewrite the pitch', 'who it is for has changed'. NOT for learnings or knowledge — use promote_knowledge for that. Pass the COMPLETE updated content — this replaces the entire vision document by default.

Parameter	Type	What it is
`product_hint`	`string`	The product name
`content`required	`string`	The product vision content as markdown. In 'replace' mode (default) this REPLACES the entire document; in 'append' mode this is concatenated to the existing content.
`mode`	`replace \| append`	'replace' (default) overwrites the entire vision document. 'append' concatenates content to the existing document.

Finding things again

Search is word-wise: every word must appear somewhere, so adding words narrows rather than loses.

`search_rememd`

Search past notes, session logs and PRDs. Use this to check whether a problem has already been solved, find the reasoning behind a past decision, or recover context from an earlier session. Call when the user says 'search', 'find', 'have we', 'did we ever', 'where did I write that', 'what did we decide about X', 'has this come up before'.

Parameter	Type	What it is
`product_hint`	`string`	Limit search to a specific product name (optional)
`query`required	`string`	The words to look for. Every word must appear somewhere in a note, session or PRD — they do not have to be adjacent or on the same line — so adding words narrows the results rather than losing them. Words that appear together as typed rank higher. Prefer distinctive terms over common ones.
`limit`	`number`	Max results to return (default 5)

`list_notes`

List notes for a feature or product. Returns note titles, dates, and a first-line preview. Use when the user wants to see what notes exist without loading all content. Call when the user says 'the notes', 'what have I written down', 'what did I capture', 'are there any gotchas noted'.

Parameter	Type	What it is
`product_hint`required	`string`	The product name.
`feature_hint`	`string`	Filter to notes linked to this feature name (optional).

`list_diagrams`

List diagrams for a feature or product. Returns diagram titles and dates. Call when the user says 'the diagrams', 'what did we draw', 'is there a diagram of this', 'the architecture picture'. Diagrams are notes containing Mermaid code blocks or session events of type diagram.

Parameter	Type	What it is
`product_hint`required	`string`	The product name.
`feature_hint`	`string`	Filter to diagrams linked to this feature name (optional).

`list_issues`

List open issues for a feature or product. Returns title, severity, and status. Call when the user says 'the issues', 'the bugs', 'what is broken', 'tech debt', 'known problems', 'what still needs fixing'.

Parameter	Type	What it is
`feature_hint`	`string`	Filter to issues linked to this feature name (optional).
`product_hint`required	`string`	The product name.

Issues

Bugs and debt found mid-session, linked to the session that found them.

`report_issue`

Report a bug or tech-debt issue discovered during a session, automatically linked to that session. Call when the user says 'that is a bug', 'file an issue', 'this is broken', 'tech debt', 'we should fix that later', 'that is a papercut' — or when you hit a problem, edge case or piece of debt worth tracking.

Parameter	Type	What it is
`feature_name`	`string`	Feature this issue relates to (optional)
`title`required	`string`	Short issue title
`product_hint`required	`string`	The product name
`description`required	`string`	Detailed description of the issue
`severity`required	`low \| medium \| high \| critical`	Issue severity

`update_issue`

Update an existing issue — change status, title, description, or severity. Call when the user says 'reopen that', 'that is worse than we thought', 'bump the severity', 'it is back', 'edit that issue'. issue_id accepts either a full UUID or the short 8-char prefix shown by list_issues.

Parameter	Type	What it is
`issue_id`required	`string`	The issue's UUID or the 8-char prefix shown by list_issues (e.g. '2101aa96').
`severity`	`low \| medium \| high \| critical`	New severity (optional).
`status`	`open \| inProgress \| resolved`	New status. Setting to 'resolved' also stamps resolvedAt to now; setting back to open/inProgress clears it.
`title`	`string`	New title (optional).
`description`	`string`	New description (optional).
`product_hint`	`string`	Optional product name to narrow the search. If omitted, all workspaces are searched by id.

`close_issue`

Close (resolve) an issue — convenience for update_issue with status='resolved'. Call when the user says 'close issue X', 'resolve X', 'mark X done'.

Parameter	Type	What it is
`product_hint`	`string`	Optional product name to narrow the search.
`issue_id`required	`string`	The issue's UUID or the 8-char prefix shown by list_issues.

Distilling upward

The compounding step: what a finished feature taught, moved to the level that outlives it.

`promote_knowledge`

Distil what was learned into the levels of the tree where it is actually true. Call when the user says 'recall feature', 'wrap feature', 'ready to merge'. Propose the rewrite to the user and only call after approval. SPLIT THE SESSION ACROSS RUNGS, IN THIS ONE CALL. A session's learnings almost never belong at a single level. Pass `focus_area_content`, `product_content` and `workspace_content` — as many as apply. MOST OF A SESSION BELONGS TO THE FIRST: a Tailwind gotcha is true of the Tailwind migration, not of the product that happens to contain it, and once that migration ships it should stop appearing in every unrelated feature's context. Writing everything to one rung is what makes a product document unreadable. `focus_area_content` needs no hint when this terminal is connected — it uses the focus area you are working in. EACH REPLACES ITS WHOLE DOCUMENT. The value for a level is the complete new text for that level, not an entry to add. Before calling: read the current document (get_product_knowledge / get_focus_area_context / get_product_context), fold the new learning in, and REWRITE — merge duplicates, delete what is now wrong, keep it tight. If the new learning contradicts something already written, say so to the user before replacing it; a superseded decision is the most valuable thing here and the most dangerous to leave standing. CHOOSING THE LEVEL — pick the LOWEST one at which the claim is still true. Test: would this still hold if the thing below it were deleted? • focus_area = true of this COMPONENT, the slice of the product you are touching. This is where technology and platform knowledge belongs: a Swift or AppKit gotcha belongs to the component that is the Mac app, a notarization step to the component that ships it, a Postgres gotcha to the backend. A lesson about a technology belongs to the component built with it. • product = true across this product's components, not merely written inside one of them. • workspace = true whatever you are building — engineering judgement rather than platform fact. Rare, and never a home for 'the only X we have'. A lesson about one endpoint or one function belongs in the feature's PRD or a note; pushing it up buries the things that are genuinely broad. Also reached by 'what did we learn', 'distil this', 'graduate the learnings', 'promote it', 'write this up so we do not hit it again'.

Parameter	Type	What it is
`workspace_content`	`string`	COMPLETE new document for the workspace — true whatever you are building. Engineering judgement rather than platform fact, and rare. Never a home for 'the only X we have'.
`product_hint`required	`string`	The product name
`level`	`focus_area \| product \| workspace`	Where this is true. DEFAULTS TO focus_area — the component you are connected to — because most of a session is true of it and the product is not a dumping ground. Say `product` explicitly when the claim holds across the product's components, and mean it. Stack-specific knowledge is always focus_area: a focus area is a component, so the Swift gotchas belong to the component written in Swift.
`feature_name`	`string`	The feature these learnings came from. Marks it completed. Omit when distilling something that did not come from finishing a feature.
`product_content`	`string`	COMPLETE new document for the product — only what is true across its components, not merely written inside one of them. Decisions about what the product IS, and dead ends nobody should re-propose.
`focus_area_hint`	`string`	Required when level is focus_area.
`focus_area_content`	`string`	COMPLETE new document for the focus area — the component you were working in. Where most of a session's learnings belong: anything true of this part of the product and not beyond it. Stack-specific knowledge lives here, so the component written in Swift owns the Swift gotchas. Uses the connected focus area when focus_area_hint is omitted.
`content`	`string`	Single-level form, kept for compatibility — prefer the three per-level fields above, which write several rungs at once. The COMPLETE rewritten document for the level named in `level`. Not a diff and not an addition. Useful headings: ## Decisions, ## Gotchas, ## Conventions, ## Dead ends.

`compact_timeline`

Compact the current session's event timeline by removing low-signal noise (context loads, session resumes, searches). Call when the user says 'clean up the timeline', 'too much noise in there', 'trim the events', 'compact this'. Keeps high-signal events: notes, tasks, issues, plans, PRD updates, knowledge promotions. Worth doing when the timeline has grown large, or before log_session to reduce clutter.

Parameter	Type	What it is
`session_id`	`string`	Optional — UUID of the session to compact. Defaults to the current active session.
`product_hint`required	`string`	The product name
`dry_run`	`boolean`	If true, report what would be removed without actually modifying the timeline.

Everything else

Tools the server reports that this page has not sorted into a group yet.

`delete_note`

Delete a note by its ID. Call when the user says 'delete that note', 'remove what I wrote', 'that note was a mistake'. Use note IDs from get_feature_context or list_notes output. This permanently removes the note.

Parameter	Type	What it is
`product_hint`required	`string`	The product name.
`note_id`required	`string`	The note UUID (full or 8-char prefix).

`delete_session`

Permanently delete a session, its log body and every event on its timeline. Irreversible — only call after the user explicitly confirms. Takes an id only, never a title: pass the 8-character id list_sessions prints, or a full UUID. Use this to clean up a session written in the wrong place. Call when the user says 'delete that session', 'that one should not exist', 'it logged to the wrong feature'.

Parameter	Type	What it is
`product_hint`	`string`	The product name, to narrow the search.
`session_id`required	`string`	The 8-character id the listings print, or a full UUID. Titles are not accepted — they repeat, and this cannot be undone.

`update_note`

Edit or delete a captured note. Call when the user says 'fix that note', 'that note is wrong', 'add to what I wrote', 'that is out of date now'. Use note_id from get_feature_context output (each note event has a short id prefix).

Parameter	Type	What it is
`content`	`string`	New note content. Omit if only deleting.
`delete`	`boolean`	Set to true to remove the note entirely.
`product_hint`required	`string`	The product name
`note_id`required	`string`	The note event UUID (full or 8-char prefix)