Tool reference

The 46 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

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.
tool	string?	Surface that produced the write: claude-code, cursor, cli/observe, etc. Stamps every turn for cross-tool attribution.
requires_claim	string?	Coordination gate. Engine looks up claim:${key} and verifies an active claim exists. See Team coordination.
holder	string?	If set with requires_claim, must match the active claim holder.
claim_policy	"soft" | "hard"	Default soft: record + stamp claim_violation. hard rejects the write.

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>?
tool	string?	Surface that produced the pin (cross-tool attribution).
derived_from_turn_ids	string[]?	Up to 50 source turn ids. Engine validates each against this project; unresolved ids are dropped (reported on derived_from_dropped) rather than rejecting the pin.

forget_memory

Soft-delete a memory by id. Removes from search index; audit trail preserved.

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.

extract_semantic

Promote a durable fact (preference, convention, API contract) out of a session into a semantic-tier memory. Writes a memory of kind=semantic anchored to the supplied source turns.

input	type	notes
content	string	Up to 4 KB.
tags	string[]?	Up to 20 tags, 64 chars each.
metadata	Record<string, unknown>?
tool	string?	Surface attribution.
derived_from_turn_ids	string[]?	Up to 50 source turn ids.

Reads

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" | "skills"	Default auto. See Quickstart §2.
filters	Record<string, unknown>?	Free-form metadata filter.
actor	string?	Provenance scope: only hits from this actor email.
tool	string?	Provenance scope: only hits from this tool surface.
since / until	number?	Time-window bounds (ms epoch).

actor / tool / since / until are silently ignored by mode=skills and mode=entities. Both have semantics that don’t compose with provenance scoping.

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

Chronological recall of the most recent turns for this project (optionally scoped to a session). DO hot-cache; cheap.

input	type	notes
limit	number?	1–200, default 50.
session_id	string?	Restrict to a session.
actor	string?	Provenance scope.
tool	string?	Provenance scope (e.g. cursor, claude-code).
since / until	number?	Time-window bounds (ms epoch).

get_project_state

Snapshot of pinned memories + active broadcasts + last 50 turns. One round-trip rehydrate for an agent.

Broadcasts

set_broadcast

Upsert a project-scoped key/value pointer (e.g. active_sprint, current_pr). Fans out to every subscriber sub-second.

get_broadcast

Read a broadcast by key. Returns null if not set. Omit the key to list every broadcast for this project.

Presence

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).

input	type	notes
session_id	string?
display_name	string?
tool	string?	Surface (cursor, claude-code, …).
current_file	string?	What the agent is currently editing.
current_function	string?	Function/symbol focus.
current_action	string?	Free-form verb: editing, reading, claiming, idle.

Intent fields fan out on presence_updated so the dashboard can paint the live “what is each agent doing right now” view.

list_active_subscribers

List users who have heartbeat-ed or recorded activity within the last since_ms (default 30 minutes, max 24 h).

Coordination

Distributed leases for cross-agent rendezvous. See Team coordination for end-to-end recipes.

claim

Acquire a TTL-bounded lease on an arbitrary project-scoped key (story id, file path, branch name, etc.). Atomic: exactly one holder at a time. Same holder calling again refreshes the lease and returns deduped=true. Different holder gets ok=false with held_by + expires_at. Let the caller back off or wait. Fans out claim_acquired to every subscriber sub-second.

input	type	notes
key	string	Free-form 1–256 chars (file:apps/api/src/auth.ts, story:JIRA-123, branch:feat/auth).
holder	string	Identity asserting the claim, typically tool@user#session.
ttl_ms	number	5 s to 24 h.
metadata	Record<string, unknown>?

release

Release a lease the caller currently holds. Only the active holder can release; mismatched holders get ok=false with reason=wrong_holder. Fans out claim_released. Idempotent: releasing a lease that has already expired or been released returns ok=false with reason=not_held without error.

extend_claim

Extend the TTL on a lease the caller currently holds. New expires_at = now + ttl_ms (replaces the previous deadline; not additive). Only the active holder can extend.

Reviews

Typed multi-agent handoff. See Team coordination.

request_review

Open a review request. Use to gate one agent’s work behind another agent’s (or human’s) approval. Optionally tie to a claim_key so dashboards show the lease alongside the pending review. Fans out a review_requested broadcast.

input	type	notes
subject	string	Up to 512 chars.
claim_key	string?	Optional tie-back to a claim.
reviewers	string[]?	Suggested reviewer identities (free-form, up to 20).
metadata	Record<string, unknown>?
deadline_ms	number?	1 min to 7 days; computed server-side to a deadline_at instant.

mark_reviewed

Decide an open review with approved / rejected / needs_changes. Idempotent on first decision; subsequent calls return ok=false with reason=already_decided + the current decision so a racing reviewer can detect that someone got there first. Fans out a review_completed broadcast.

input	type	notes
review_id	string (uuid)
decision	"approved" | "rejected" | "needs_changes"
comment	string?	Up to 8 KB.

list_pending_reviews

List reviews that haven’t been decided yet, optionally filtered by reviewer (matches against the suggested-reviewers list at request time) or requester. Use to populate a reviewer’s queue without subscribing to the broadcast stream.

Rules

Declarative rules that fire on broadcasts. See Memory rules for the predicate grammar and recipes.

install_rule

Install or replace a declarative rule. When a broadcast of on_kind fires, the rule’s actions run with template substitution (string args may reference payload.X / event.X via the ${...} syntax). Actions are limited to set_broadcast / pin_memory / record_turn: derivative writes only, no nested rule installs.

input	type	notes
name	string	Lowercase alphanumerics + dashes; unique within project.
description	string?	Up to 2 000 chars.
on_kind	RuleEventKind	One of: turn_recorded, memory_pinned, memory_forgotten, broadcast_set, consolidation_completed, claim_acquired, claim_released, claim_expired.
where	Record<string, unknown>?	Optional event-shape predicate (Mongo-flavored: { "payload.metadata.kind": "error" }).
actions	RuleAction[]	1–10 actions per rule.
enabled	boolean	Default true. Re-install with enabled: false to disable.

list_rules

List installed rules for this project. Soft-deleted rules are excluded.

forget_rule

Soft-delete a rule by name. Stops future firings; the row is retained for audit.

list_default_rules

Return the bundled default-rule catalog (error-pin / claim-watchdog / review-router). Each entry is a ready-to-install rule body; pass it back to install_rule to enable. Pure data, no project state read.

Skills

Agent Skills (agentskills.io v1): discovery, activation, execution. See the Skills page for the spec.

list_skills

List available skills for this project. Returns each skill’s name + description (the discovery layer per the agentskills.io progressive-disclosure model). Call before performing a multi-step task to see if a packaged playbook already exists.

get_skill

Fetch a skill’s full SKILL.md body and parsed manifest by name. The activation layer; call after list_skills picks a relevant entry.

get_skill_file

Read a supporting file from inside a skill bundle (anything under scripts/, references/, assets/, or arbitrary subdirectories). Path is relative to the skill root; absolute paths and .. segments are rejected.

install_skill

Install or update a skill. Accepts the SKILL.md text plus an optional file map for bundled scripts/references/assets. Frontmatter is validated against the agentskills.io v1 spec.

input	type	notes
skill_md	string	8 B to 64 KB. Full SKILL.md text including YAML frontmatter.
files	Record<string, string>?	Path → contents. Each file capped at 1 MB.

forget_skill

Soft-delete a skill by name. Removes from list_skills + search results; the manifest history is retained.

list_default_skills

Return the bundled default-skill catalog (memoturn-mcp-toolkit + stack-tailored bundles). Each entry includes the tags it’s recommended for and a full SKILL.md body suitable for install_skill. Pure data — no project state read; used by the onboarding flow.

Code engine

search_code

Hybrid (dense + lexical + activity-boost) retrieval over indexed repo content. Returns code chunks (path, line range, snippet) ordered by RRF-fused rank. Filter by repo_id, path_glob, lang, kind, or insertion time. Pair with search_memory to fuse code with the conversational/operational layer.

context_for

Single-call gather: returns code chunks for a target (path / symbol / file_id) plus the recent turns mentioning it, active claims keyed on it, and undecided reviews touching it. The code+activity fusion that single-vendor code engines can’t deliver — pair this with search_code when you need everything an agent needs to safely work on a file.

expand_symbol

BFS over the code import/call graph from a starting symbol (or path → that file’s module sentinel). Returns visited symbols + a representative chunk for each, scoped by hops, edge kinds (imports / calls / references), and direction (out / in / both). Use after search_code to expand context around a hit without another semantic query.

list_repo_files

Paginated listing of indexed repo files for this project. Filter by repo_id, lang, path_prefix, or modified_since (ms epoch). Cursor pagination via the file id; pass the previous response’s next_cursor to advance.

list_redaction_reviews

List turns where the deterministic redactor flagged a span and the async LLM review escalated it (or any other review status). Mirrors the dashboard’s redactions tab. Use to surface secret leaks an agent should not have written, without subscribing to broadcasts.

Focus

list_focus

Top files by team activity in the configured window (default last 1 h). Each entry returns the file path, the count of turns referencing it, and the (tool, actor) pairs that touched it. That is, who from which surface is currently focused on what. Powers the dashboard’s Focus map; agents discovering it via MCP can use it to detect cross-tool collisions before reaching for the claim primitives.

input	type	notes
since_ms	number?	1 min to 24 h, default 1 h.
limit	number?	1–100, default 20.

Temporal facts

Structured subject-predicate-object triples with temporal validity windows. Recording a fact for an existing subject+predicate auto-supersedes the previous one.

record_fact

Record a structured fact. If an active fact with the same subject+predicate already exists, its valid_to is set to now before the new fact is inserted.

input	type	notes
subject	string	Up to 512 chars.
predicate	string	Up to 256 chars.
object	string	Up to 4 KB.
confidence	number?	0–1, default 1.0.
valid_from	number?	Ms epoch; defaults to now.
source_turn_id	string?	Link to the turn that produced this fact.
metadata	Record<string, unknown>?

query_facts

Query the temporal knowledge graph. Supports point-in-time queries (“what was true on date X?“).

input	type	notes
subject	string?	Filter by subject.
predicate	string?	Filter by predicate.
point_in_time	number?	Ms epoch — returns facts valid at that instant.
active_only	boolean?	Default true — only facts where valid_to IS NULL.
limit	number?	1–200, default 50.

invalidate_fact

Close a fact’s validity window (valid_to = now). The fact remains queryable for historical point-in-time queries but won’t appear in active_only searches.

input	type	notes
fact_id	string (uuid)

Synthesis

synthesize

Search memory and synthesize results into cited prose with gap analysis. Returns a narrative answer referencing specific memories by id, plus an explicit list of what the project’s memory doesn’t cover.

input	type	notes
query	string	Up to 4 KB.
k	number?	1–50, default 10. Number of search results to feed to the LLM.
mode	"auto" | "chunks" | "summaries" | "code"	Default auto.

Returns { answer, cited_memory_ids, gaps }.

Contradiction detection

find_contradictions

Scan the temporal knowledge graph for conflicting active facts. Groups facts by subject, identifies pairs with the same predicate but different objects, and sends candidates to an LLM judge. Returns detected conflicts with severity and an explanation.

input	type	notes
subject	string?	Scope to a single subject.
limit	number?	1–50, default 10.

Returns { contradictions: [{ fact_a, fact_b, severity, explanation }] }.

Candidate staging

LLM-extracted memory proposals that need review before promotion to durable memory. The ingest pipeline extracts candidates from every turn; agents or humans accept/reject them.

list_candidates

Browse staged memory candidates by status.

input	type	notes
status	"pending" | "accepted" | "rejected"	Default pending.
limit	number?	1–200, default 50.

review_candidate

Accept or reject a staged candidate. Accepting promotes it to a durable pinned memory with full embedding and search indexing. Rejecting discards it.

input	type	notes
candidate_id	string (uuid)
decision	"accept" | "reject"

Edge transactions

Typed edges between memories or facts with cascading side effects.

execute_edge

Create a relationship edge with transaction semantics. Side effects depend on the edge kind.

input	type	notes
src_id	string (uuid)	Source memory or fact.
dst_id	string (uuid)	Destination memory or fact.
kind	"supersedes" | "contradicts" | "derives_from" | "same_as"
confidence	number?	0–1, default 1.0.
metadata	Record<string, unknown>?

Side effects by kind:

• supersedes — closes dst validity (valid_to = now), transfers 50% of dst’s salience to src
• contradicts — records a contradiction between src and dst
• derives_from — provenance tracking: src was inferred from dst
• same_as — equivalence link without deletion

Returns { ok, edge_id, side_effects }.