MCP tools

The chat-recall MCP server has 68 tools. A new session lists a short default set and recall_help, which names every tool; every tool answers by name. Set CHAT_RECALL_MCP_PROFILE=full to list all of them. The recall_code_* tools register only when the codeindex companion is installed.

Sessions that work together

recall_inbox

Receive the messages other sessions sent to a session. Each message is returned once. With wait_secs, wait for a message to arrive, for example the answer from a child session. Claude Code sessions with the message hook receive messages without this tool; use it to wait, or in a tool without the hook.

Parameter	Type	Required	Description
session	string	yes	The receiving session id, usually this one.
wait_secs	number	no	Poll for up to this many seconds (max 600) when nothing waits. Default: 0.
limit	number	no	Default: 50.

recall_message_send

Send a message to another running AI session of this account. Use it when one session coordinates others: a parent gives work to its children, a child reports back.

The recipient gets the message at its next prompt, tool call or turn end (Claude Code, through the chat-recall message hook). A session that waits for its user reads it when the user types next. "children" sends to every running child of from; "parent" sends to its parent; "group" sends to the parent and every running child — use it to announce a decision to the whole group.

to also takes an absolute folder: the session running there is the recipient, and zero or more than one is refused instead of guessed. When the folder is known, pass it in both to and expect_cwd; a recipient that is in another folder is refused and nothing is sent. An opencode TUI that has no session yet appears as its folder, and the message becomes its first prompt.

Parameter	Type	Required	Description
from	string	no	The sending session id, so the recipient can answer.
to	string	yes	A session id, the start of one, a session name, an absolute folder, "parent", "children" or "group".
body	string	yes	The message. Secrets are redacted before it is sent.
reply_to	string	no	The id of the message this answers.
expect_cwd	string	no	The folder the recipient must be in; the send is refused when it is elsewhere.

recall_session_register

Give a session a name other sessions can send to, link it to its parent session, and say what it works on. A child calls this once with its own id and the parent's id or name, so the parent can list it with recall_session_status and reach it with to: "children". Set doing when you start a task and when it changes, so every other session can see who works on what.

Parameter	Type	Required	Description
session	string	yes	The session to change, usually this one.
name	string	no	A name, e.g. "backend-worker". Empty string removes it.
parent	string	no	The parent: id, start of id, or name. Empty string removes the link.
doing	string	no	One line: the project, issue or task this session works on. Empty string clears it.

recall_session_spawn

Start a child session that works on a task in the background, linked to this session as its parent. It runs as a Claude Code background session (claude --bg) on this machine, in the parent's folder and profile unless you pass cwd. It does its task, reports to the parent with recall_message_send, and wakes again on the next message from the parent. The user can watch or take over any child with claude attach <id>.

Without permission_mode, a tool call that needs approval stops the child until a person attaches; recall_session_status shows that. Pass a permission mode only when the user chose it.

Parameter	Type	Required	Description
from	string	yes	This session id (the parent).
prompt	string	yes	The task, as the first prompt. Say what done means and what to report.
name	string	no	A name to send to, e.g. "worker-a".
doing	string	no	One line on what the child works on.
cwd	string	no	Working directory. Defaults to the parent's.
model	string	no	Model alias or id. Defaults to the user's setting.
permission_mode	acceptEdits | auto | dontAsk | plan | manual	no	Only when the user chose it.
resume	string	no	Continue this ended child (session id) with the prompt.

recall_session_status

read-only

See which sessions of this account are running, what each works on, and what state each is in: working, idle and waiting for input, or ended. Each line starts with the name, the folder and the tool and process kind (an opencode TUI, a headless serve or run, a Claude Code session), so a recipient is checked before anything is sent to it; serve and run say "no window". The rest of the line is the state, the "doing" line the session set, the board cards in progress linked to it, and unread messages. An opencode TUI that has no session yet is listed by its folder, and so is any local opencode or claude process with no session (Linux). With parent, list the children of one session — the check a coordinating session runs on the sessions it started. With session, show one session and its message thread. To read what a session did, follow up with recall_show and from_end.

Parameter	Type	Required	Description
parent	string	no	List only the children of this session (id, start of id, or name).
session	string	no	Show one session and its messages.
include_ended	boolean	no	Default: false.
messages	number	no	Messages to show with session. Default: 10.

Memory, knowledge graph and wake-up

recall_decision_record

Record an explicit decision so it shows up in wake-up context. Writes a KG triple (subject → decided → decision) plus a diary entry. Use this when you and the user agree on something non-obvious that future sessions should remember.

PASS area. It is the key a reversal supersedes on: recording a new auth decision closes the previous auth one and leaves every other area alone. Without it the decision is stored but nothing it contradicts is closed, and both answers stay live forever.

Parameter	Type	Required	Description
subject	string	yes	What the decision is about
decision	string	yes	The decision itself
reason	string	no	Why this was decided
area	string	no	The area this decides, so a later decision on the same area supersedes it. Standard areas: auth, database, payments, api, frontend, deploy, testing, observability, security, pricing, licensing, positioning. Any short slug works for an area not listed.
project	string	no	Project this applies to. Omit for an account-wide decision that applies everywhere.
importance	number	no	1-5. Only 4 and 5 surface in the wake-up bundle, so reserve those for decisions a future session must not miss. Default: 4.
session_id	string	no	Session this decision came out of. Pass your own current session id so the decision can be traced back to the conversation that made it.
agent_name	string	no	Which agent is recording this, so diary entries stay separable per agent. Default: "agent".

recall_diary_read

read-only

Read your recent diary entries. See what past versions of yourself recorded across sessions.

Parameter	Type	Required	Description
agent_name	string	yes	Agent name to read diary for
last_n	number	no	Number of recent entries Default: 10.

recall_diary_write

Write to your agent diary. Record observations, decisions, what you worked on, what matters.

Each agent gets their own persistent diary across sessions. Use this at the end of sessions or when you learn something important that should persist.

Parameter	Type	Required	Description
agent_name	string	yes	Your name — each agent gets their own diary
entry	string	yes	What happened, what you learned, what matters
topic	string	no	Topic tag Default: "general".
session_id	string	no	Current session ID (for linking)
project_path	string	no	Project path (for context)

recall_get

read-only

Read a key/value pair previously written with recall_set — or, when key is omitted, LIST the recorded keys (in one scope, or across all scopes when scope is also omitted). Use the list mode to discover what state has been recorded without remembering specific keys.

Parameter	Type	Required	Description
key	string	no	Key name. Omit to list keys instead.
scope	string	no	Namespace (default "default" when reading; omit to list across all scopes)
limit	number	no	Max entries in list mode Default: 50.

recall_kg_add

Add a fact to the knowledge graph. Subject → predicate → object with optional time window.

E.g. ("example-app", "uses", "Postgres", valid_from="2026-01-15")

Parameter	Type	Required	Description
subject	string	yes	The entity doing/being something
predicate	string	yes	Relationship type (e.g., "uses", "works_on", "prefers")
object	string	yes	The entity being connected to
valid_from	string	no	When this became true (YYYY-MM-DD, optional)
source_session	string	no	Session ID where this was learned (optional)

recall_kg_invalidate

destructive

Mark a fact as no longer true. Use when things change — tools replaced, decisions reversed, people leave.

Parameter	Type	Required	Description
subject	string	yes	Entity
predicate	string	yes	Relationship
object	string	yes	Connected entity
ended	string	no	When it stopped being true (YYYY-MM-DD, default: today)

recall_kg_query

read-only

Query the knowledge graph for an entity's relationships.

Returns typed facts with temporal validity. E.g. "example-app" → uses TypeScript, deploys to Kubernetes. Filter by date with as_of to see what was true at a specific point in time. Use this to VERIFY facts before asserting them.

Parameter	Type	Required	Description
entity	string	yes	Entity to query (e.g., "Alice", "chat-recall")
as_of	string	no	Date filter (YYYY-MM-DD, optional)
direction	outgoing | incoming | both	no	Which edges to follow: facts where the entity is the subject (outgoing), the object (incoming), or both. Default: "both".

recall_kg_stats

read-only

Knowledge graph overview: entities, triples, current vs expired facts, relationship types.

recall_kg_timeline

read-only

Get chronological timeline of facts. Shows the story of an entity (or everything) in order.

Parameter	Type	Required	Description
entity	string	no	Entity to get timeline for (optional)
limit	number	no	Default: 50.

recall_memory_item

read-only

Fetch ONE memory item, its full text, or its links — or browse a whole source type.

Complements recall_memory_search: search finds candidates, this reads the specific item. mode=browse lists a type (e.g. every skill, every plan) without a query.

Parameter	Type	Required	Description
source_type	session | plan | task | claude_md | paste | history | diary	yes
id	string	no	Item id. Omit with mode=browse.
mode	item | content | links | browse	no	item = metadata, content = full text, links = related items, browse = list the type Default: "item".
limit	number	no	browse mode only Default: 50.

recall_reclassify

destructive

Re-run the memory classifier over already-indexed chunks so classifier improvements reach old data. Idempotent — only rewrites tags that actually changed.

recall_set

Persist a small key/value pair across sessions. Use this for state that doesn't fit the diary (narrative) or knowledge graph (entity-relationship facts) — things like "current PR url", "branch I'm working on", "user's preferred test runner". Scope namespaces keys so per-project state doesn't collide.

Parameter	Type	Required	Description
key	string	yes	Key name
value	string	yes	Value to store. JSON-encode if structured.
scope	string	no	Namespace Default: "default".

recall_wake_up

read-only

Build startup context for an AI session: identity blurb + the top classifier-flagged facts (decisions/preferences/milestones at importance >=4) + current knowledge-graph facts. Replaces a manual context dump. Call this once at the start of a session to "remember who you are and what's true right now".

Parameter	Type	Required	Description
max_facts	number	no	How many high-importance classifier facts to include. Default: 10.
max_kg_facts	number	no	How many current knowledge-graph facts to include. Default: 15.
identity	string	no	Override the identity line at the top of the bundle. Defaults to ~/.chat-recall/identity.txt when present.
project_filter	string	no	Scope facts, KG entities and the task count to a project (substring match). Without it, facts are global.
project	string	no	Alias for project_filter — the name every sibling tool uses.

Decisions

recall_decision_scan

What THIS repository's manifests say its stack is, beside what the register currently answers. Use it when a decision card asks you to record an area, or before recording one yourself.

The register is push-only: it holds what somebody asserted, and it never reads a repository. So a project that never had the conversation inherits an answer from a broader scope — which is how a Tauri app whose store is rusqlite came to be told its database decision was Postgres.

This reads package.json, Cargo.toml, pyproject.toml, requirements.txt, go.mod, Gemfile and composer.json at rest, and reports the product that answers each area with the file and line it read. That is EVIDENCE, not a decision: it says what is there, never what was ruled out or why.

record: true writes the areas the manifests answer, at project scope, with the file and line as the reason. Areas the manifests do not answer are never written — ask the user instead.

Parameter	Type	Required	Description
path	string	no	Repository root to read. Defaults to the current directory.
project	string	no	Project the decisions belong to. Defaults to the repository folder name.
area	string	no	Only this area. Standard areas: auth, database, payments, api, frontend, deploy, testing, observability, security, pricing, licensing, positioning.
record	boolean	no	Record what the manifests answer, at project scope, citing the file and line. Leave false to look first. Default: false.
session_id	string	no	Your current session id, so each write traces back to this conversation.

recall_decisions

read-only

What this codebase has already settled — read it BEFORE choosing a library, a datastore, an auth method or anything else in a decided area, and you will not rebuild what was already ruled out.

Returns one effective value per area with the cascade already resolved (project beats account; personal preferences fill gaps and never override a team decision), what each value replaced and when, and the session it came from. Also returns gaps — areas nobody has decided, where you are free to choose, and where recording the choice afterwards is worth doing.

Parameter	Type	Required	Description
area	string	no	Only this area. Standard areas: auth, database, payments, api, frontend, deploy, testing, observability, security, pricing, licensing, positioning.
project	string	no	Resolve for this project, so its overrides win over account-wide decisions. Omit for the account-wide view.
include_candidates	boolean	no	Also return unconfirmed guesses the indexer extracted. These are NOT decisions — never treat one as settled. Default: false.

Tasks

recall_task_comment

Leave a progress note on a team task — a comment visible to everyone on the board. Use it to record what you did, what is blocked, or why a status changed, without editing the task itself. Pass the task id (t_…) from recall_tasks.

Parameter	Type	Required	Description
task_id	string	yes	Task id (t_…) from recall_tasks
body	string	yes	The comment text

recall_task_create

Create a collaborative team task. Optionally assign it to a teammate and attach it to a project. Returns the new task id.

When you then START working on a task, use recall_task_update to set status 'in_progress' and link your current session (linked_session_id) — that is what lets the board verify the work actually shipped.

Parameter	Type	Required	Description
title	string	yes	Task title
description	string	no	What the work actually is. The title is the label; this is where the detail a future reader needs belongs.
project	string	no	project_id this task belongs to
assignee	string	no	Teammate user id (sub) to assign
due	number	no	Due date, epoch milliseconds. Set one when the work is time-bound; omit otherwise.
linked_finding_id	string	no	The code finding this task comes from (ca_…). Setting it lets the card close itself when a re-index stops reporting the finding, and dedupes against an existing card for the same finding.

recall_task_policy

Read or change what the board FILES — call with no arguments to read it.

max_pri severity floor, inclusive: 0 critical, 1 high, 2 medium, 3 low ceiling how many auto-filed cards may be open at once max_per_run cap on new cards per run categories only file these categories (e.g. ["security"]); [] means all project apply max_pri/categories to THAT REPOSITORY ONLY — one floor across every repo forces the strictest one on all of them exclude_project / include_project a repository that never files a card — a client's codebase, an archive, a mirror. Indexed and searchable as before; simply never put on the board.

Use this when the user says what they want worked on — "only security", "high and critical for now", "stop filing hotspots", "let more in". Reading it first also explains a quiet board: at the ceiling, filing pauses until cards close.

Parameter	Type	Required	Description
enabled	boolean	no	Turn auto-filing on or off.
max_pri	number	no	Severity floor: 0 critical, 1 high, 2 medium, 3 low.
ceiling	number	no	How many auto-filed cards may be OPEN at once.
max_per_run	number	no	Cap on NEW cards per run.
categories	array	no	Only file these categories; [] means all.
project	string	no	Apply max_pri/categories to THIS project only, leaving other repos on the global setting.
excluded_projects	array	no	Replace the never-file list.
exclude_project	string	no	Add ONE project to the never-file list.
include_project	string	no	Remove ONE project from the never-file list.

recall_task_update

Update a team task: change status, reassign, rename, link a session, and/or add a comment. Pass the task id (t_…) from recall_tasks.

WORKFLOW — do this whenever the user asks you to work on a task from the board:

1. When you start, set status 'in_progress' AND pass your own current session id as linked_session_id (the session id you know from your own context; this MCP server cannot see it). This is REQUIRED — claiming without it is refused, because "in progress" with nothing behind it cannot be asked about. The card then shows that session's changes as they land, not only after the commit.
2. When you finish, set status 'done' AND RECORD WHAT YOU CHANGED: pass the diff (unified — what git diff printed for this fix) and the commits if you committed it. The close is refused without one of them. Do not expect the board to work it out — it cannot see edits made through a shell, and its commit scan only searches repositories this session already tool-touched. The diff you paste is what the next person reads on the card.

STAY INSIDE THE CARD'S PROJECT. A card names one project; fix it there and nowhere else. If the real fix needs a change in another repository, say so and leave the card open rather than reaching across — the person who filed this board did not ask you to touch a second codebase, and a diff spanning repositories cannot be reviewed as one change.

TELL THE USER WHAT YOU ARE DOING. Say that you are taking tasks off the chat-recall board, name the ones you picked, and say when each is done and what changed. A card closing on its own, with no word to the person whose board it is, is how this board stopped being trusted the first time.

THE THREE ENDINGS ARE NOT THE SAME:

• 'done' — you fixed it. Needs linked_session_id; refused without one.
• 'closed' — the card no longer applies: its finding stopped being reported, or it duplicates another card. Needs closed_reason.
• rejected — NOT yours to set. If the card is not a real problem, say so to the user and let them reject it, because that also stops the finding being re-filed. (When they do, the API requires their reason.) Closing a card you did not fix, as 'done', is the one thing that makes this board worthless: two thirds of one real board's Done column turned out to be work nobody had done.

Parameter	Type	Required	Description
id	string	yes	Task id (t_…)
status	todo | in_progress | done | closed	no	Set the card's state. 'done' needs linked_session_id; 'closed' needs closed_reason. There is no 'rejected' here on purpose: rejecting is the user's verdict, not yours.
closed_reason	string	no	Why the card no longer applies. REQUIRED with status 'closed'.
diff	string	no	THE CHANGE YOU MADE for this card, as a unified diff. REQUIRED with status 'done' unless you pass commits — the board cannot reconstruct shell-driven edits, so this is the only reliable record.
commits	array	no	Commit sha(s) carrying that change, if you committed it.
files	array	no	Files those commits changed. PASS THESE: the card scopes the session's diff by them, and without them it can show no changes rather than risk showing another repository's.
summary	string	no	One line on what changed (optional).
assignee	string	no	Reassign to this user id (sub)
title	string	no	Rename the card. Omit to leave the title alone.
comment	string	no	Add a comment
linked_session_id	string	no	Session id to attach — pass YOUR OWN current session id when you start working on this task, so the board can check whether the work shipped. Null detaches.

recall_tasks

read-only

List the task board — and, with detail, the work itself.

Without detail: one line per card (title, id, assignee). Use for "what's on the team's plate", "my tasks", or to find a task id to update.

With detail: true: the full brief per open card — the fix, the file locations and the agent prompt that the auto-filer already wrote — plus how to claim a card and how it gets closed. Use that whenever you intend to DO the work rather than report on it.

Closing is earned: 'done' is refused without a linked session. Rejecting is the user's call, never yours.

Parameter	Type	Required	Description
mine	boolean	no	Only tasks assigned to me
project	string	no	Filter to one project_id
status	todo | in_progress | done | rejected | closed	no	Filter by status
detail	boolean	no	Return the full brief per task — the fix, the file locations and the agent prompt — plus how to claim and close one. Use this when you intend to DO the tasks, not just list them.

Security

recall_security_dismiss

destructive

Mark a secret finding as rotated, false_positive, or dismissed.

Use when the user confirms a key was rotated or that the match is not a real secret. The dismissal syncs across devices.

Parameter	Type	Required	Description
preview	string	yes	Masked secret preview from the security dashboard
status	rotated | false_positive | dismissed | undismissed	yes	Resolution status, or undismissed to put the finding back on the action-required list
reason	string	no	Optional note

recall_security_rules

read-only

List tenant custom secret-detection rules, or test a regex in the sandbox.

Tenant rules are configured in the chat-recall dashboard; this tool exposes them to the agent and lets you test new regexes without persisting them.

Parameter	Type	Required	Description
action	list | test	no	list = existing rules; test = regex sandbox Default: "list".
name	string	no	For test: rule name
regex	string	no	For test: regex to evaluate
sample	string	no	For test: text to match against

recall_security_session

read-only

Get secret findings for a specific session.

Use after recall_search or recall_security_summary to show exactly which lines in a session matched which detector.

Parameter	Type	Required	Description
session_id	string	yes	Session ID from search results

recall_security_summary

read-only

Get a security overview from the synced chat-recall server.

Returns the action-required list of distinct leaked secrets (grouped by redacted preview), plus per-detector totals and top rules. Use this when the user asks "do we have any leaked secrets?" or "security findings" or "what should I rotate".

Call this first; then call recall_security_session for specific sessions.

Parameter	Type	Required	Description
include_dismissed	boolean	no	Show previously dismissed findings Default: false.
top_k	number	no	Max distinct secrets to list Default: 20.
group_by	detector | rule | project | trend | sessions	no	detector = action-required view; rule/project = grouped counts; trend = daily counts; sessions = one row per session with findings Default: "detector".
days	number	no	group_by=trend only: window in days (1-365) Default: 30.
min_detectors	number	no	group_by=sessions only: require N detectors agreeing

Code intelligence

recall_code_actions

read-only

The ranked, actionable plan for a codebase — prioritised tasks synthesised from the findings, each with a ready agent prompt. This is the "what should I fix next" list. Filter by project/status.

Parameter	Type	Required	Description
project	string	no	Project id (omit for all)
status	suggested | queued | done | dismissed	no
limit	number	no	Default: 30.

recall_code_findings

read-only

List code findings (security / hardcoded literals / copy-paste clones / reinvention / dead code / coupling / cycles). Each finding carries a concrete, ready-to-run agent prompt that references codeindex tools. Filter by project/severity/category.

Parameter	Type	Required	Description
project	string	no	Project id (omit for all)
severity	critical | high | medium | low | info	no
category	string	no	security|literal|clone|duplication|dead_code|coupling|cycle
limit	number	no	Default: 50.
view	findings | summary | hotspots | file-sessions	no	findings = the list; summary = counts by severity/category; hotspots = churn-ranked files; file-sessions = which sessions touched file Default: "findings".
file	string	no	view=file-sessions only: repo-relative path

recall_code_index

Index a code repository with codeindex and sync its findings/hotspots/actions to your chat-recall server. Runs the codeindex analyzer LOCALLY (needs the repo files + git history), then ships the result. Use before recall_code_findings/actions if a repo hasn't been indexed yet.

Parameter	Type	Required	Description
path	string	no	Repo path (default: cwd)

recall_code_projects

read-only

List code-indexed projects on your server with health score, finding count, and label (poc/production/engineering).

Toolkit sync

recall_toolkit_status

read-only

Which MCP servers, skills, commands and agents exist, on which AI tool, on which device.

Use it before recall_toolkit_sync to see what is missing where, and after, to confirm what landed. Counts are per (type, tool) and rows name the device that uploaded them, so you can tell "my laptop has it" from "my desktop has it".

NOTE: the server holds an INVENTORY. MCP registrations carry enough to rebuild elsewhere; skills and agents do not (their file content is not uploaded), and this tool says which is which.

Parameter	Type	Required	Description
type	mcp | skill | command | agent | instructions	no	Restrict to one artifact type. Omit for every type.

recall_toolkit_sync

read-only

Install the account's MCP servers / skills / agents onto a device, or fan a device's own artifacts out across its tools.

TWO DIFFERENT OPERATIONS — pick with scope:

scope: 'pull' Install what the ACCOUNT has onto the target device, sourced from the server. This is the cross-device one: it is what sets up a new laptop. Omit device to target every device.

scope: 'fan_out' Copy what ONE device already has between that device's own tools (claude → codex → cursor …). Single machine only; it reads that machine's disk.

Examples: everything, everywhere { } every MCP, everywhere { types: ['mcp'] } every MCP on one machine { types: ['mcp'], device: 'my-laptop' } one artifact { types: ['mcp'], name: 'acme-mcp' } fan a machine's own set out { scope: 'fan_out', device: 'my-laptop' }

The work is QUEUED, not done inline: the target device performs it on its next drain (the watch daemon polls, or run chat-recall toolkit drain). Only that device can write its own config files, so nothing else could do it. Read the outcome back with recall_toolkit_status.

Parameter	Type	Required	Description
types	array	no	Artifact types to install. Omit for all.
name	string	no	Install ONE named artifact. Requires exactly one entry in types.
device	string	no	Hostname of the target machine. Omit to target every device on the account.
scope	pull | fan_out	no	pull = install from the server (cross-device). fan_out = copy between one machine's own tools. Default: "pull".

Projects, cost and team

recall_analytics_summary

read-only

Cross-tool spend & activity overview. Returns total sessions, total cost, weekly delta, top tools/projects/models, and how many sessions had unknown pricing (Gemini/Ollama/custom). Same data as the web Dashboard, available to the agent so it can answer "how much have I spent this week" without you opening the UI.

view: "patterns" returns behavioural patterns across sessions instead of the spend rollup.

Parameter	Type	Required	Description
view	summary | patterns	no	summary = spend/activity rollup; patterns = behavioural patterns across sessions Default: "summary".

recall_claude_suggestions

read-only

Every finding that turns into an agent-instruction change, in one list — the "what should I tell Claude about this?" view.

Merges the CLAUDE.md rules and skill installs from BOTH recommendation engines: account scope (leaked secrets the scanner found + how your sessions actually went) and every code-indexed project (code findings × session behaviour). Each item carries the rationale, the evidence behind it, and the exact rule text to paste.

This is the read side. To apply one, use the apply rail the recommendation already names (recall_recommendations documents it) — this tool never edits a CLAUDE.md itself.

Parameter	Type	Required	Description
project	string	no	Limit to one code-indexed project id (from recall_code_projects)
include_projects	boolean	no	Also fan out over code-indexed projects. false = account scope only. Default: true.
kind	rule | skill	no	rule = a CLAUDE.md line; skill = a skill to install. Omit for both.

recall_project_context

read-only

Get the full project dossier as markdown — rich project context.

Aggregates everything the index knows about one project into a single report: overview (from CLAUDE.md), tech stack (KG uses), architecture / deployment / security sections (from CLAUDE.md), decisions log (KG chose/rejected), recent session activity with summaries, open tasks, plans, agent diary conclusions, and cost rollup.

Accepts EITHER a project path / name substring (e.g. "api", "example-app", "/home/user/code/example") OR a stable project_id:

• "git:<host>/<owner>/<repo>" (e.g. "git:github.com/owner/repo")
• "ws:<name>" (workspace rollup)
• "git-local:<sha1>" (local-only git repo)
• "user:<custom>" (declared in ~/.chat-recall/projects.json)

Use at the START of a new session to understand what's been happening in a project.

Parameter	Type	Required	Description
project_path	string	yes	Project path, name substring, or project_id (git:/ws:/git-local:/user:)
limit	number	no	Number of recent sessions to include Default: 5.
tasks	number	no	Max open tasks to list Default: 20.
plans	number	no	Max plans to list Default: 20.

recall_project_label

Label a project POC, production or engineering — the guardrails every future session reads.

This is the highest-leverage single call in the surface: the label tells any assistant working here whether it may reset a database and move fast (poc), must protect data and avoid destructive steps (production), or should hold a higher bar on tests and review (engineering).

ASK THE USER before setting 'production' or clearing a label. Both change what other agents will consider permitted, and that is not yours to decide alone.

Parameter	Type	Required	Description
project	string	yes	Project id from recall_code_projects
label	poc | production | engineering | none	yes	none clears it

recall_recommendation_apply

Apply a recommendation: add its rule to the repo's CLAUDE.md, or set the label it asks for.

Use it when a recommendation from recall_recommendations is right. You do not need to ask permission for a CLAUDE.md rule — it is additive, visible in the diff, and the user can delete a line. DO ask first for anything that changes what the AI is allowed to do destructively.

A CLAUDE.md edit is queued for the machine that has the repo and lands within about 45 seconds; only that machine has the file. A label applies immediately. Applying twice is harmless.

Parameter	Type	Required	Description
id	string	yes	Recommendation id from recall_recommendations
project	string	yes	Project id the recommendation belongs to

recall_recommendation_dismiss

destructive

Say no to a recommendation for this project, with a reason.

Use it when advice does not apply to THIS repo — a reuse rule on a repo that is deliberately duplicated per environment, a label on a scratch project. Dismissed recommendations stop being offered for that project and no other.

TELL THE USER what you dismissed and why. This changes how future sessions treat their codebase, and a reason nobody sees is a decision nobody can review. Pass undo: true to put one back.

Parameter	Type	Required	Description
id	string	yes	Recommendation id from recall_recommendations
project	string	yes	Project id the recommendation belongs to
reason	string	yes	Why it does not apply here. Required.
undo	boolean	no	Restore a previously dismissed recommendation.

recall_recommendations

read-only

Actionable recommendations, two scopes on one tool:

• scope "account" (default) — from YOUR chat-recall data: leaked secrets found by the scanner + session behaviour (unresolved/abandoned). Returns concrete CLAUDE.md rules to apply globally.
• scope "project" (requires project) — behavior × code recommendations for a code-indexed project. Concrete changes to apply: add a CLAUDE.md rule, install a skill, set a project label, or reset a POC db. Reasons over BOTH the code findings and how sessions in this project went (failed/abandoned, recurring corrections). Each has rationale + evidence + an apply-action.

Parameter	Type	Required	Description
scope	account | project	no	account = your chat-recall data; project = one code-indexed project Default: "account".
project	string	no	Project id (from recall_code_projects). Required when scope is "project".

recall_shares

read-only

Which projects are shared into your team. scope=mine for your own shares, scope=all for every share visible to you. Private by default — nothing is visible to teammates until shared.

Parameter	Type	Required	Description
scope	mine | all	no	Default: "mine".

recall_team_activity

read-only

See what each teammate did, grouped by project — the team activity view.

Returns a per-member × per-project rollup (session counts + last activity) for your team. Scoped to what you're allowed to see: your own work plus teammates' work on projects they've shared into the team (private projects never appear).

Use for "what has the team been working on", "what did <teammate> do on <project>", or standup/status. Filter by project, by member, or by recency (since_days).

Parameter	Type	Required	Description
project	string	no	Filter to one project_id
member	string	no	Filter to one teammate (user id / sub)
since_days	number	no	Only activity in the last N days

recall_weekly_digest

read-only

Get a weekly activity digest across all projects.

Returns:

• Session count, total cost, coding time
• Top projects by activity
• Cost trend vs previous week
• Open tasks across projects
• Git activity summary

Use to understand overall productivity and spending.

Parameter	Type	Required	Description
weeks_back	number	no	0 = current week, 1 = last week Default: 0.

Your data

recall_exclude_path

destructive

Stop syncing a project path. Nothing under it leaves the machine from the next sync on.

Use it when the user says "stop syncing this repo", "don't upload anything from ~/work/client", "keep this project out of chat-recall".

WHAT IT DOES: adds the path to the exclusion rules — on this machine, and on the account so every device the user syncs from honours it. Sessions ALREADY uploaded from that path stay until they are deleted; say so, and offer recall_forget for the ones that matter.

There is deliberately no tool to REMOVE an exclusion: an agent may narrow what is synced, never widen it. Undo it with chat-recall exclude remove <path> or in the dashboard.

Parameter	Type	Required	Description
path	string	yes	Absolute path (or a distinctive part of one) to stop syncing.
confirm	boolean	yes	Must be true. Only when the user actually asked to stop syncing it.

recall_forget

destructive

Delete one conversation from chat-recall, everywhere, permanently.

Use it when the user says "forget this conversation", "delete that session", "remove what we discussed about X" — anything that asks for a conversation to stop existing on the server.

WHAT IT DOES: purges the session on every server this machine is logged in to, and tombstones the id so no later sync can bring it back. The AI tool's own transcript file on the user's disk is NOT touched — tell them that, because it is usually what they mean to keep.

IRREVERSIBLE. There is no undo and no tool that restores it. Only pass confirm: true when the user has actually asked for this; do not infer it from a complaint about a conversation.

Parameter	Type	Required	Description
session_id	string	yes	Session ID to delete (from recall_recent / recall_search).
confirm	boolean	yes	Must be true. Only when the user actually asked to delete it.

recall_heal_audit

read-only

Report how many of your sessions are DAMAGED — the rendered conversation is thinner than the shrink-protected raw archive, which happens when an upstream tool truncates a transcript in place (a resume/compaction rewrite, or a script mirroring a shorter file over a longer one).

This is the authoritative "0 remaining" check. Read-only by default; apply=true heals, and healing only ever makes a conversation FULLER.

Parameter	Type	Required	Description
since_hours	number	no	Bound the scan to the last N hours. Default 168 (7 days). The scan is capped at 500 sessions so it returns within the request timeout; the reply reports what it did not cover.
apply	boolean	no	false = audit only; true = heal now Default: false.

recall_index

Index all Claude Code sessions for semantic search.

Scans ~/.claude/projects/ and creates embeddings for all sessions. By default, only indexes new or changed sessions.

Parameter	Type	Required	Description
force	boolean	no	Force re-index all sessions Default: false.
provider	ollama | gemini	no	Embedding provider Default: "ollama".

recall_rename_session

destructive

Give a conversation a memorable name — or rename it — so you (and the user) can find and resume it later.

Mirrors Claude Code's session naming (/rename). The name replaces the auto-generated summary in recall_recent and the web UI. Use it when the user says "name this conversation X", "call this session Y", or "rename this to Z". Pass an empty string to clear the name and revert to the auto title.

The name persists across re-syncs and summary regeneration (it's stored separately from the AI summary).

Parameter	Type	Required	Description
session_id	string	yes	Session ID to name (from recall_recent / recall_search).
name	string	yes	The name to give this conversation. Empty string clears it.

recall_status

read-only

Show index status and statistics: synced sessions, chunks, freshness, top projects, plus the full memory-system breakdown (items/chunks per source type, per AI tool, link count).

Search and reading

recall_commits

read-only

Find git commits that landed during a session's edit window, grouped by repo.

Multi-repo aware: a session that touched ~/code/example/infra and ~/code/example/api returns commits from each repo, with overlap shown between commit-files and session-touched-files.

Use this to verify "shipped" claims — if the session edited 18 files but no matching commit exists, work probably stayed local.

Parameter	Type	Required	Description
session_id	string	yes	Session ID to look up commits for
buffer_minutes	number	no	Window padding on each side Default: 30.

recall_context

read-only

Get structured context from a session for continuation.

Returns:

• Your requests/inputs
• Claude's work/decisions
• Key topics discussed
• Tools used and files changed
• Summary if available

Use this to understand what happened in a session before resuming.

Parameter	Type	Required	Description
session_id	string	yes	Session ID to get context from

recall_diff

read-only

Replay a session's Edit/Write/MultiEdit/NotebookEdit tool calls into a unified diff per file. Lets you see what the agent actually changed — not just that it edited, but how — without grepping the raw transcript.

Detects reverts: when a file was edited but the final state matches the initial state, the file is reported with reverted: true and a zero-line diff.

Pass file to focus on a single absolute path. Pass context_only: true for just the per-file stats (lines added/removed) when you don't need the diff body. Pass files_only: true for just the list of files the session touched (grouped by extension, with tools used) — "which files did session X actually touch?".

Parameter	Type	Required	Description
session_id	string	yes	Session ID to replay
file	string	no	Absolute file path to focus on (optional)
context_only	boolean	no	Skip diff bodies, return stats only Default: false.
files_only	boolean	no	Return just the file list (no diffs/stats) Default: false.
max_diff_chars	number	no	Truncate each per-file unified diff Default: 4000.

recall_edits_timeline

read-only

Chronological list of file edits across recent sessions, spanning every AI tool chat-recall indexes — Claude Code, Codex, Cursor, OpenCode and Antigravity.

Returns rows shaped like (timestamp, tool, session_id, project, file, op) sorted newest first. Pulls live from each tool's native session store — Claude JSONL, Codex JSONL, OpenCode SQLite — so the active session is included even though its metadata hasn't been re-indexed yet.

Great for "what were we just changing?" — call with since_hours: 2 to see the last two hours of edits across every session and every AI tool.

Pass group_by: "session" (with pattern + a wide since_hours, e.g. 720) to aggregate per session instead — "which sessions edited auth.rs in the last month?".

Parameter	Type	Required	Description
since_hours	number	no	Time window in hours Default: 24.
limit	number	no	Maximum edit rows to return Default: 100.
pattern	string	no	Optional substring filter on file path
project_filter	string	no	Filter by encoded project directory name
include_reads	boolean	no	Include Read tool_uses too Default: false.
tools	array	no	Restrict to specific AI tools. Default: every tool this machine has.
group_by_repo	boolean	no	Group results by detected git repo root. Default: false.
view	timeline | summary	no	timeline = chronological edit rows; summary = aggregated rollup over the same window Default: "timeline".
group_by	session	no	"session" = aggregate edits per session (which sessions touched files matching pattern).

recall_improvements

read-only

Every improvement worth doing, ranked highest-priority first — the "what should I fix next, across everything" view.

Merges the ranked code actions (recall_code_actions) with the non-instruction recommendations from account and project scope (focused reviews, project labels, POC resets). Code actions carry a numeric pri and recommendations carry a severity; both are mapped onto one scale so a single ordered list is honest.

Set create_tasks: true to open one task per improvement on the shared team board (recall_tasks). It is off by default — this reads unless you ask it to write.

Parameter	Type	Required	Description
project	string	no	Limit to one code-indexed project id
min_severity	high | medium | low	no	Drop anything below this severity Default: "low".
limit	number	no	Maximum improvements to return, after ranking Default: 30.
create_tasks	boolean	no	Create one team task per returned improvement Default: false.
assignee	string	no	create_tasks only: teammate user id (sub) to assign each task to

recall_markers

read-only

Tag every user prompt in a session with sentiment / corrective markers:

• interrupt — user hit ESC mid-response • frustrated — caps, profanity, "wtf", "ffs" • correction — "no", "stop", "don't" — negating the last action • approval — "yes", "do it", "i approve" • question — "why", "what", ends with ? • directive — "use X", "implement Y", "build Z" • clarification_request — "wdym", "explain", "what is"

Returns per-prompt markers + a session-level summary count. Use this to spot sessions where things went sideways before reading the whole transcript.

Parameter	Type	Required	Description
session_id	string	yes	Session ID to mark prompts in
limit	number	no	Maximum prompts to return Default: 200.

recall_memory_search

read-only

Search across all memory types: sessions, plans, tasks, CLAUDE.md files, history, paste cache, and agent diaries.

Returns results from any memory source, ranked by relevance. Use source_types to filter. Plans and tasks are found here (source_types: ['plan', 'task']); read a full plan with recall_show (pass the plan id).

Parameter	Type	Required	Description
query	string	yes	What you're looking for across all memory types
top_k	number	no	Number of results Default: 10.
source_types	array	no	Filter by source types (default: all)
project_filter	string	no	Filter by project path
provider	ollama | gemini	no	Embedding provider, when the server has vector search configured. Ignored on a keyword-only server. Default: "ollama".
scope	local | server	no	server = synced cross-device history (needs chat-recall login). Default: "local".
semantic	boolean	no	Reserved and currently ignored: the semantic tier is switched off server-side, so every search runs keyword FTS. Default: false.

recall_outcome_summary

read-only

Aggregate session outcomes (shipped / interrupted / abandoned / in_progress) over the last N days — "how much of my work actually landed?".

Parameter	Type	Required	Description
days	number	no	1-90 Default: 7.

recall_recent

read-only

List recent sessions across every AI tool chat-recall indexes.

Shows your most recent conversations across all projects or filtered by project. Use this when the user says "continue our last conversation" or wants to see recent work.

Pass since_hours: N to restrict to sessions modified in the last N hours.

It lists synced transcripts, which reach the server some time after they change. To find a session that runs NOW, or to send one a message, use recall_session_status: it lists the live sessions of every AI tool, with their ids and names.

Parameter	Type	Required	Description
project_filter	string	no	Filter by project name (e.g., "acme", "poly")
limit	number	no	Number of recent sessions to show Default: 10.
since_hours	number	no	Only include sessions modified in the last N hours.
scope	local | server	no	server = synced cross-device history (needs chat-recall login). Default: "local".

recall_redundant_files

read-only

Before creating a file, check whether you have written one like it before. Scores the filename against every file touched in your synced history.

Answers "have I built this already?" — the reinvention check.

Parameter	Type	Required	Description
filename	string	yes	Filename you are about to create
project	string	no	Restrict to one project
limit	number	no	Default: 20.

recall_regenerate_summary

destructive

Force a fresh AI summary for one session — use when its stored summary is missing, stale, or plainly wrong.

Parameter	Type	Required	Description
session_id	string	yes

recall_search

read-only

Search for relevant past sessions to resume.

Find past conversations matching your current task. Returns session IDs that can be used to resume that session in the tool that produced it.

Three modes on one tool:

• query — free-text search ("I'm working on X, what past work is relevant?").
• like_session — find sessions similar to an existing session id (uses its first prompt as the search text, excludes itself, groups hits by project).
• include_outcome: true — append a per-result outcome one-liner (shipped / interrupted / abandoned + edit stats) to judge whether each hit is worth resuming.

Parameter	Type	Required	Description
query	string	no	What you're looking for (e.g., "OAuth implementation"). Required unless like_session is set.
like_session	string	no	Find sessions similar to this session id instead of a free-text query.
include_outcome	boolean	no	Append per-result outcome one-liners (status + edit stats). Default: false.
top_k	number	no	Number of results to return Default: 5.
project_filter	string	no	Optional filter by project path substring
skip_ranking	boolean	no	Skip Claude ranking for faster results Default: false.
provider	ollama | gemini	no	Embedding provider Default: "ollama".
scope	local | server	no	Accepted for back-compat; search always runs against the synced server. Default: "local".

recall_show

read-only

Get conversation content from a specific session — or the full text of a plan.

Use this after recall_search to get full context from a session. Also accepts a plan id (the plan filename without .md, as returned by recall_memory_search(source_types:['plan'])) and renders the complete plan text.

Four ways to reach a message:

1. query finds the messages that contain a text and gives their lines.
2. around_line returns max_messages messages centred on a line.
3. from_end: N returns the last N messages.
4. expand_line returns one message whole. Message text and commands come back in full. Tool calls come with their inputs and results; a body over 2000 characters shows its first and last 100 and the line to pass as expand_line to get it whole.

Parameter	Type	Required	Description
session_id	string	yes	Session ID from search results, or a plan id (filename without .md)
around_line	number	no	Transcript line to centre on. Returns max_messages messages around the message nearest to it.
max_messages	number	no	Messages to return with around_line or query, or from the start of the session. from_end sets its own count. Default: 10.
from_end	number	no	Return the last N messages (alternative to around_line).
expand_line	number	no	Return only the message at this line, with every tool input and result whole.
query	string	no	Return the messages that contain this text (case-insensitive), with their lines. Searches message text, tool inputs and tool results.

recall_smart_resume

read-only

Get structured resume context for recent work — by default the last 3 sessions.

Call it with NO arguments to resume. That is the common case: "continue", "pick up where we left off". Pass session_id to resume one specific session, or project_filter to scope to one project.

Returns, for the newest session:

• What was done (completed work, decisions made)
• What's pending (unfinished tasks, TODOs mentioned)
• Files modified with change summary
• Token/cost budget used
• Resume command

Then a digest of each earlier session: its project, outcome, summary, the decisions it took and the task lists it left open. Set depth to change how many.

A bare call takes the globally newest sessions, which may belong to different projects — the output says so when they do. Pass project_filter to scope it.

Use this instead of recall_context for a more actionable summary when resuming work.

Parameter	Type	Required	Description
session_id	string	no	Session to resume. OMIT to resume the most recent session.
project_filter	string	no	With session_id omitted, resume the latest sessions from this project.
depth	number	no	How many recent sessions to cover: the newest in full, the rest as digests. Ignored when session_id is set. Default: 3.

recall_subagent_search

read-only

Search inside SUBAGENT transcripts — the explore/compact/aside sub-tasks that run within a session and whose work never appears in the main conversation.

Use when a session's own turns don't contain what you remember: the finding may have come from a subagent. Indexed server-side, so it works across devices.

Parameter	Type	Required	Description
query	string	yes	Text to find inside subagent transcripts
session_id	string	no	Restrict to one session
kind	string	no	Restrict to one subagent kind
limit	number	no	Default: 20.

recall_summary

read-only

Get the summary for a session — including its OUTCOME classification.

By default returns a rich summary that combines the AI summary (when available) with the structured outcome derived from the transcript itself: status (shipped / interrupted / abandoned / in_progress), the session window, decisions the agent announced, blockers hit (tool errors, interrupts), edit/commit stats, prompt markers, and the last assistant claim paired with the user's reaction to it (so you can see whether "done!" was actually accepted or met with "wtf"). This is the triage call when scanning a session list — it answers the question the AI summary doesn't: did this work actually land? Pass rich: false to fall back to the legacy single-line AI summary only.

Parameter	Type	Required	Description
session_id	string	yes	Session ID to get summary for
rich	boolean	no	Include structured outcome alongside AI summary Default: true.

recall_user_prompts

read-only

List the human-typed prompts from a session (or recent sessions), newest first. Tool results and system banners are stripped — you get only what the user actually wrote. Useful for "what was I asking yesterday?" or "what did I tell the agent in this session?". Pass query for "did I say X?": it keeps only the prompts that contain that text. Each prompt prints whole up to 2000 characters; a longer one prints its start and end and the recall_show expand_line call for the rest.

Parameter	Type	Required	Description
session_id	string	no	If set, only that session's prompts
since_days	number	no	How far back to look, in days. Default: 7.
limit	number	no	Maximum prompts to return, newest first. Default: 50.
query	string	no	Keep only the prompts that contain this text. Case and runs of whitespace are ignored.