Tool reference
The 12 tools below are what your MCP client sees on tools/list. Descriptions mirror packages/mcp/src/tools.ts verbatim — that file is the source of truth.
Writes
Section titled “Writes”record_turn
Section titled “record_turn”Capture a single turn (user message, assistant reply, tool call, agent event). Idempotent by client_turn_id when supplied. Primary write path.
| input | type | notes |
|---|---|---|
role | "user" | "assistant" | "tool" | "system" | "agent" | "event" | Default event. |
content | string | Up to 64 KB. |
session_id | string? | Group turns into a session for summarization + scoped search. |
metadata | Record<string, unknown>? | Arbitrary tags; included in the dedup hash. |
client_turn_id | string? | Caller-supplied idempotency token; replays return the same turn_id. |
pin_memory
Section titled “pin_memory”Explicit long-term memory write. Survives consolidation; bypasses turn-extraction heuristics.
| input | type | notes |
|---|---|---|
content | string | Up to 8 KB. |
tags | string[]? | Up to 20 tags, 64 chars each. |
ttl_ms | number? | Soft-deletes the memory after this many ms. |
metadata | Record<string, unknown>? |
forget_memory
Section titled “forget_memory”Soft-delete a memory by id. Removes from search index; audit trail preserved.
summarize_session
Section titled “summarize_session”Produce or refresh the rolling summary for a session. Auto-runs every ~20 turns or 10 minutes; pass force=true to summarize now. Writes a memory of kind=consolidated and broadcasts consolidation_completed.
search_memory
Section titled “search_memory”Hybrid (dense + lexical + DO-hot) retrieval over recorded turns and pinned memories for this project.
| input | type | notes |
|---|---|---|
query | string | Up to 4 000 chars. |
k | number? | 1–100, default 10. |
session_id | string? | Restrict to a session. |
mode | "auto" | "chunks" | "summaries" | "entities" | "code" | Default auto. See Quickstart §2. |
search_entities
Section titled “search_entities”Look up structured entities extracted from turns: symbols (camelCase/snake_case identifiers), files (paths with extensions), error codes (TS2345, ERR_*, EACCES), and CLI commands. Deterministic exact/prefix match — pair with search_memory for full-text recall.
| input | type | notes |
|---|---|---|
query | string | |
kinds | ("symbol" | "file" | "error_code" | "command")[]? | Restrict to a subset. |
k | number? | 1–100, default 10. |
list_recent_turns
Section titled “list_recent_turns”Chronological recall of the most recent turns for this project (optionally scoped to a session). DO hot-cache; cheap.
get_project_state
Section titled “get_project_state”Snapshot of pinned memories + active broadcasts + last 50 turns. One round-trip rehydrate for an agent.
Broadcasts
Section titled “Broadcasts”set_broadcast
Section titled “set_broadcast”Upsert a project-scoped key/value pointer (e.g. active_sprint, current_pr). Fans out to every subscriber sub-second.
get_broadcast
Section titled “get_broadcast”Read a broadcast by key. Returns null if not set. Omit the key to list every broadcast for this project.
Presence
Section titled “Presence”heartbeat
Section titled “heartbeat”Mark the caller as active in this project. Fans out a presence_updated broadcast. Idempotent — safe to call on a short interval (e.g. every 30 s from a long-running agent).
list_active_subscribers
Section titled “list_active_subscribers”List users who have heartbeat-ed or recorded activity within the last since_ms (default 30 minutes).