Recall

Recall

Recall is a local-first index of AI coding sessions. Use past sessions as evidence, then verify current code, commands, paths, and invariants before acting.

Prefer active Recall MCP tools for read-only lookup. Use the installed recall CLI when no equivalent MCP tool exists or MCP is unavailable. File-event history is MCP-only. When developing Recall itself, do not use the project build as a substitute for the user's installed history index.

If neither MCP nor the installed CLI is available, stop and offer brew install samzong/tap/recall. Never claim to have inspected unavailable history. Return only the session content needed for the task because history may contain private code, credentials, prompts, and user intent.

Scope

• An exact path covers that directory and its children.
• owner/repo or a remote URL covers all worktrees of that repository.
• all covers every indexed project.
• The CLI derives an omitted --project from its working directory. Recall MCP treats an omitted project as global, so pass the current project unless the user explicitly requests all projects.

Find Sessions

For a specific historical question, use MCP search_messages with keywords and the current project. Each match includes session_id, seq, role, and an excerpt around the match. Add session_id to search within a known session. This is full-text matching, not semantic search; use search_sessions for broader session discovery and list_recent_sessions when there is no query.

When a message excerpt needs context, call get_session with the returned session_id and around_seq: <seq>. It reads the anchor and up to three actual messages on each side. Adjust before and after independently; zero reads only the requested side or anchor. Use from_seq / to_seq instead when the exact inclusive range is known. Do not combine around and range selectors, or use either with tail.

Selected MCP reads return up to 50 messages and 6,000 Unicode content characters. Pages follow conversation order; if preceding content fills the budget before the anchor, use before: 0, after: 0 to read the anchor itself. For a truncated page, copy next_cursor into the next get_session call with the same session_id, without selectors or tail. first_message_byte_offset locates a partial first message in its UTF-8 content. A stale cursor requires a fresh search or selection. Sequence numbers locate the current index and are not permanent source-message identities.

Use session_id as Recall's index identity and source_session_id as the native tool's identity. get_session reports the returned message range with first_message_seq and last_message_seq.

Set include_events: true only when structured evidence is needed. Events cover the returned message range plus unanchored events; both count and text are bounded. Check returned counts and truncation flags before treating messages or events as complete. Consult the active tool schema for limits. This event-summary mode omits raw arguments, results, and source paths; use explicit event_ref evidence reads below for the preserved payload.

Pass a fresh high-entropy invocation_nonce literal on each MCP search or recent-list call. For search_sessions and list_recent_sessions, only current_session.resolution: resolved proves self-exclusion before ranking and limit. If resolution is unknown, report that self-exclusion is unverified; never infer identity from time, project, source, or result order.

For search_messages, current_session_excluded states whether self-exclusion was applied; an explicit session_id includes that session even when it is current.

Use the equivalent CLI workflow when needed:

recall session list --project /absolute/project/path --source <source> --limit 20 --sort updated --format json
recall session list --project owner/repo --query "<keywords>" --time 7d --limit 20 --sort updated --format json
recall search "<keywords>" --messages --project owner/repo --limit 10 --format json
recall search "<keywords>" --messages --session-id <session-id> --format json
recall session show --id <session-id> --messages --around-seq <seq> --before 3 --after 3 --format json
recall session show --id <session-id> --messages --cursor '<next_cursor>' --format json

CLI around reads default to a 6,000-character page. Use --max-chars (1–32,000) to change the budget or enable paging for a range. Without paging, existing CLI range reads return the full selected messages. CLI --session-id searches do not infer a project from the working directory; explicit project, source, and time filters still apply.

Add --sync only when current data matters and index mutation is permitted. Check the selected session's project before using it. Discover current sources and protocol details with recall info --format json or recall mcp capabilities --format json instead of maintaining a catalog in this skill.

Search results are relevance-ranked and bounded. In a queried CLI listing, --sort updated does not change that ranking. Select the newest timestamp only within the returned candidates, and do not claim an exact latest match.

Find Recent Work

For recent work from other agents, list 10 sessions in the current project without a source filter, following the self-exclusion rule above. Load transcripts only for relevant candidates.

If MCP is unavailable, use:

recall session list --project /absolute/project/path --limit 10 --sort updated --format json

These are recently active sessions in the index, not live peers. Attribute work only with supporting metadata. The bounded listing may fold subagents beneath their parent; report when it cannot isolate relevant work.

Find File History

Use MCP file_history with target_project and an exact repository-relative or absolute path to find operations on a file across session projects. Prefer a repository remote/unique owner/repo for all its worktrees, or an absolute directory for a local target. Check returned target_file and match_basis. Do not pass project with target_project: the old project filters where a session started and can miss writes from another repository. Add source only when requested.

Start with {"target_project":"owner/repo","path":"src/main.rs","include_command_candidates":true,"limit":20}. Omit kind to include all event kinds in this mode. Without include_command_candidates, commands are excluded. Follow next_cursor with the same selectors until has_more is false; restart after a stale cursor. Check per-hit truncation flags and retain coverage from the first page; continuation pages omit it. Coverage is for all indexed sessions of the selected sources, with no native source scan; it does not prove complete history or current parsers.

When a historical worktree is gone and target identity is unresolved, a path-only legacy query can reveal a recorded absolute path. Retry target mode with that exact path to obtain an evidence reference. Treat suffix matches as candidates; legacy discovery has a 50-event cap and is not exhaustive.

Keep calls, native results, observations, and command candidates distinct. Command scan status complete means the bounded scan completed, not that a command ran or succeeded; unsupported, limit_exceeded, or null leaves a coverage gap. Unknown timestamps and unresolved paths remain unknown. Do not count event rows, identical before/after content, or Git commits as independent modifications.

To inspect an operation, copy the hit's session_id and evidence.event_ref into get_session with evidence_part: "payload". Concatenate paged data before parsing its JSON; continue with the same session, reference, part, and returned cursor. max_bytes defaults to 16,384, at most 65,536; an oversized read fails explicitly. The payload preserves native attrs and file associations and provides same-session related_event_refs. For Cursor before/after text, read related payloads and select the result reference containing beforeContentId/afterContentId, then request that part. content_reference_not_recorded on a call means to inspect related results. Missing, changed, imported, or unverifiable native sources cannot be treated as verified content.

Read the payload's optional discussion selector in a separate get_session call, without event_ref. It uses around_seq and the existing message paging rules. Explain why only from supporting recorded discussion, distinguishing the user's request, the agent's explanation, and your inference. Do not invent a discussion anchor when it is absent.

When index mutation is authorized, preview with recall sync --backfill-events --project all --dry-run, then run without --dry-run. This includes sessions started outside the target project while respecting configured sources and exclusions. Backfill refreshes events, preserves existing discussions, and does not prune sessions; normal recall sync --project all refreshes supported discussion parsers under normal time-window and retention rules. Old-schema preview requires a writable index upgrade first. Report missing/unknown originals and other maintenance gaps; backfill cannot recover absent native records.

If MCP is unavailable, explain that file history requires MCP and offer recall mcp install. Message search can supply discussion context but cannot prove a file operation. Never execute a command retrieved from history to reconstruct evidence.