MCP tools
The CTXone Hub exposes 68 MCP tools, served over HTTP at /mcp (the
standard setup) and over stdio, in ten groups:
- Memory (8):
remember,recall,prime,context,summarize_session,what_changed_since,why_did_we,project_status - Curation (5):
session_segments,draft_stage,drafts_list,draft_promote,draft_discard - Plans (16):
plan_new,plan_add,plan_start,plan_done,plan_abandon,plan_edit,plan_next,plan_list,plan_show,plan_tasks,plan_link,plan_stale,plan_move,plan_close,plan_complete,plan_archive - Sessions and workspaces (4):
session_info,session_link_plan,namespace_for_plan,namespace_for_task - Docs and help (2):
docs_find,help - Reminders (9):
reminder_create,remind_me,reminder_list,reminder_get,reminder_snooze,reminder_approve,reminder_cancel,reminder_start,reminder_record - Code intelligence (9):
code_repos,code_search,code_read,callers_of,callees_of,get_active_repo,set_active_repo,code_cross_repo_edges,code_impact(requires--asd-repoor--asd-urlat hub startup; the federatedcode_cross_repo_edges/code_impactshell out to theasdCLI over the shared repo registry)
Any MCP-compatible agent (Claude Code, Cursor, VS Code Copilot with MCP, Codex, etc.) can call these directly.
For setup instructions, see INTEGRATIONS.md. For the underlying concepts, see ARCHITECTURE.md.
Connecting
Section titled “Connecting”Standard (HTTP daemon). Point your tool at a running ctxone-hub --http
by URL — one daemon serves MCP + REST + Lens (see Architecture):
{ "mcpServers": { "ctxone": { "type": "http", "url": "http://localhost:3001/mcp?namespace=<detected>"} } }Fallback (stdio). The Hub also speaks MCP over stdio when spawned per-client
without --http — it stays alive for the agent session and handles one client
at a time:
{ "mcpServers": { "ctxone": { "command": "/path/to/ctxone-hub", "args": ["--path", "/Users/user/.ctxone/memory.db"]} } }ctx init writes the right shape for you automatically in every detected tool
(defaulting to the http daemon; --transport stdio for the fallback).
Namespace & branch mirroring
Section titled “Namespace & branch mirroring”Every stdio session is scoped to a namespace — the per-repo isolation unit for branches, plans, memory, taints, reminders, and history (see MEMORY_BRANCH_SCOPING.md). The namespace is resolved once, at server startup:
- An explicit
--namespace <ns>flag orCTX_NAMESPACEenv var wins. - Otherwise the project detection chain runs from the process cwd
(the spawning tool starts the MCP server in the project directory):
a
.ctxprojectfile in the cwd or any parent, then the repo’sgit remote get-url originlooked up in the Hub’s project registry. - No match → the reserved
defaultnamespace.
The repository is forked to the resolved namespace for the whole session — every tool call reads and writes inside it.
Branch mirroring happens at startup too: inside a project
namespace, the session’s default ref becomes the sanitized current git
branch (feature/x → feature-x), auto-created from main on first
use. Tools that omit their ref/branch parameter use this session
default; explicit refs are unchanged. Detached HEAD → no mirroring,
default stays main.
Call project_status at any time to see the resolved namespace,
agent id, and default ref.
All tools return structured text (usually JSON). Agents parse the response and decide what to do with it.
Every response from remember, recall, context, summarize_session,
what_changed_since, and why_did_we carries token usage metadata in an
_ctxone_stats trailer (or embedded fields for the JSON-native tools).
remember
Section titled “remember”Store a fact, preference, or decision.
Description (from the tool descriptor):
Store a fact, preference, or decision in agent memory. Facts are searchable and carry confidence scores based on importance.
Parameters:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
fact | string | yes | — | The fact to store |
importance | enum | no | medium | high / medium / low |
context | string | no | — | Category (becomes /memory/<context>/<id>) |
tags | string[] | no | — | Queryable tags |
ref | string | no | main | Branch to write to |
personal | bool | no | false | Write to the personal namespace’s main instead of this workspace |
Response: JSON object with status, path, commit_id, ref,
namespace (which namespace the write landed in), fact.
personal: true is for what belongs to the person rather than the
project, such as a preference. Every workspace’s recall reads the personal
namespace, and a personal write isn’t refused when the session fell back to
default (HTTP API).
When to call: any time the agent learns a fact about the user’s project that should persist to the next session. Agents are encouraged to call this liberally — the more facts, the better recall ranking gets.
recall
Section titled “recall”Retrieve memories for a topic.
Description:
Retrieve relevant memories for a topic. Always includes pinned context first, then topic-matched facts, respecting a token budget. Response is JSON including token savings metadata.
Parameters:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
topic | string | yes | — | Query string (tokenized) |
budget | integer | no | 1500 | Max token budget |
ref | string | no | main | Branch to read |
Response: JSON with results, pinned_count, topic_matches,
ctx_tokens_sent, ctx_tokens_estimated_flat, ctx_savings_ratio.
Results are structured: each item has path, pinned: bool and
namespace. Pinned items also have title and body; topic matches have
value, score, and full_match. Recall reads the personal namespace’s
main as well as this workspace, so namespace is either the workspace or
_personal; where both hold the same path, the workspace’s copy wins.
When to call: at the start of every agent session, and whenever the
agent needs project-specific context mid-session. Think of it as “search
my memory for anything relevant to
Load structured sections as pinned or primed memory.
Description:
Load markdown sections as pinned or primed memories. Pinned memories are always included in every recall response (critical context). Sections should be pre-parsed — each entry has a title and body.
Parameters:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
source | string | yes | — | Group name (idempotent) |
pinned | bool | no | false | If true, always include in recall |
sections | array | yes | — | Array of {title, body} objects |
ref | string | no | main | Branch to write to |
personal | bool | no | false | Prime into the personal namespace’s main, as ctx agents install does |
Response: JSON with sections_written count and paths array.
When to call: when loading a new document into memory. Agents
typically parse a markdown file on the client side (H1/H2 headings) and
pass the parsed sections. The CLI’s ctx prime does exactly this.
Use pinned: true for critical context (project conventions, current
status) and pinned: false for searchable reference material.
context
Section titled “context”Load the full context tree for a project.
Description:
Load the full context tree for a specific project or domain. Returns all stored state under that project path.
Parameters:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
project | string | yes | — | Project name (reads /memory/projects/<project>) |
ref | string | no | main | Branch to read |
Response: JSON with the full subtree serialized. Includes token stats.
When to call: at the start of a session when the user specifies a project, to dump everything under that project into context in one call.
summarize_session
Section titled “summarize_session”End-of-session commit.
Description:
End-of-session commit capturing what was learned and decided. Call this before closing a session to persist its knowledge.
Parameters:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
session_id | string | yes | — | Unique identifier for this session |
key_points | string[] | yes | — | Bullet points of what was learned |
decisions | string[] | no | [] | Decisions made this session |
Writes three paths:
/sessions/<id>/summary— joined key points (Checkpoint, 0.9 confidence)/sessions/<id>/decisions— decisions array (Checkpoint, 0.95 confidence)/sessions/<id>/details— full key points (Observe)
When to call: at session end, before the agent shuts down. The
corresponding recall on the next session will find these summaries,
enabling the “close session, open new one, context preserved” workflow.
what_changed_since
Section titled “what_changed_since”Recent commits filtered by timestamp.
Description:
See what has changed in the memory graph since a given date. Shows recent commits and their intents.
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
since | string | yes | ISO 8601 timestamp (e.g., 2026-04-12T00:00:00Z) |
Response: text listing of recent commits with timestamp, category, description, and confidence.
When to call: at session start when the agent wants to catch up on what’s happened since the last session.
why_did_we
Section titled “why_did_we”Trace the reasoning behind a past decision.
Description:
Trace the reasoning behind a past decision. Searches for the decision and returns its full provenance chain (blame).
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
decision | string | yes | Substring of the decision (e.g., “use BSL 1.1”) |
Response: text with matched paths and their blame chains (commit history showing who/when/why).
When to call: when the user asks “why did we decide X?” or the agent needs to justify a past choice to the user.
project_status
Section titled “project_status”Show which project namespace this session operates in.
Description:
Show which project namespace this session’s memory operations land in, plus the agent id stamped on commits. Call this to prove where a write went, or to debug why remembered facts seem missing (usually: they were written in a different namespace).
Parameters: none.
Response: JSON with namespace, agent_id, default_ref (the
session’s mirrored git branch, or main), and a hint string. In the
default namespace the hint suggests running ctx project add <id> in
the repo (or committing its .ctxproject) to get an isolated namespace.
When to call: whenever you need to prove where writes land — at
session start, or when a recall comes back empty and you suspect the
facts live in another namespace.
record_llm_usage
Section titled “record_llm_usage”Report the LLM turn’s token usage to CTXone.
Description:
Report LLM token usage to CTXone for metrics and cost accounting. Call this after any significant LLM turn — pass the numbers straight from the model’s response
usagefield.
Parameters:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
input_tokens | integer | yes | — | Tokens the model consumed as input |
output_tokens | integer | yes | — | Tokens the model generated |
cache_read_tokens | integer | no | 0 | Tokens served from prompt cache (Anthropic) |
cache_create_tokens | integer | no | 0 | Tokens written to prompt cache (Anthropic) |
model | string | no | — | Model identifier for display (e.g. claude-sonnet-4.5) |
provider | string | no | — | Provider identifier (anthropic, openai, gemini, …) |
Response: JSON object with the updated per-session totals
(llm_input_tokens, llm_output_tokens, llm_cache_read_tokens,
llm_cache_create_tokens, llm_call_count, last_model,
last_provider).
When to call: after every LLM turn where you actually invoked a
model. The agent just copies numbers out of the provider response’s
usage field into the call parameters. Don’t invent numbers, and
don’t call for trivial housekeeping turns.
Why it matters: CTXone’s internal savings ratio is computed from what the Hub itself sent in recall responses — an extrapolation. This tool gives Lens ground-truth measurements of actual model consumption, cache hit ratios, and real dollar cost. Sessions that report LLM usage render with real numbers in Lens; sessions that don’t fall back to the CTXone-side view only.
Token stats trailer
Section titled “Token stats trailer”Tools that return plain text (most of the older ones) append a stats line:
<response body>
_ctxone_stats: {"ctx_tokens_sent":42,"ctx_tokens_estimated_flat":451,"ctx_savings_ratio":10.7}Tools that return JSON natively (remember, recall, prime, context)
embed the same fields directly in the response object.
Well-behaved agents can extract and surface these numbers to the user — CTXone is the only memory layer where “how much did this query save?” is a first-class API response.
Authority chain
Section titled “Authority chain”Every tool call writes commits with agent_id = "ctxone" (or
"ctxone-prime" for prime operations). This means ctx blame shows
CTXone-mediated writes separately from writes via the raw engine CLI.
If you’re running multiple agents that share a Hub, consider giving each
agent its own namespaced branch (agents/alice, agents/bob) so blame is
unambiguous.
Curation
Section titled “Curation”Five tools turn a session into durable memory, with the user deciding what’s
kept. Split the session into arcs, stage candidate memories from the arcs
worth keeping, then keep or drop each candidate. Drafts live under
/drafts/<session>/ and aren’t recalled until they’re promoted. The
session’s turns stay in the archive either way.
session_segments
Section titled “session_segments”Split a session into topic arcs: contiguous stretches of turns on one git branch and working directory. An arc ends at a branch change, a working-directory change, or an idle gap. No LLM is involved.
When to call: before drafting memories from a session. A session is rarely one topic, so keep the arcs that matter and drop whole tangents.
Parameters: session_id, gap? (idle minutes that start a new arc;
default 30, and 0 turns the rule off), ref?.
Returns: { session_id, gap_minutes, segment_count, segments }. Each
segment has its turn range (start, end, turn_count), branch, cwd,
start and end times, tokens, a label, and the reason it started
(start, branch, cwd or gap).
draft_stage
Section titled “draft_stage”Stage a candidate memory distilled from an arc. It isn’t durable: it waits
in /drafts/<session>/ for the user to keep, edit or drop.
When to call: after session_segments, once for each decision, gotcha or
open thread worth keeping. The user decides what matters; you surface
candidates.
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
session_id | string | yes | Session the candidate came from |
content | string | yes | The candidate memory |
kind | string | no | decision, gotcha, open_thread or fact |
turns | [int, int] | no | Source turn range, carried onto the memory as provenance |
arc | string | no | Label of the arc it came from |
context | string | no | Suggested memory context for promotion |
pin | bool | no | Suggest pinning on promotion |
ref | string | no | Branch (default main) |
Returns: the staged draft, with its draft_id and path.
drafts_list
Section titled “drafts_list”List a session’s staged drafts for review, each with its content, kind, source turn range, and suggested context and pin.
Parameters: session_id, ref?.
Returns: { session_id, drafts }.
draft_promote
Section titled “draft_promote”Promote a draft to durable memory, the “keep” half of curation. Writes its
content under /memory/<context>/, or /memory/pinned/curated/ when it’s
pinned, records the source session and turn range in the commit, and removes
the draft.
When to call: only for drafts the user chose to keep.
Parameters: session_id, draft_id, context? (overrides the draft’s
suggestion; default facts), importance? (high 0.95, medium 0.7 by
default, low 0.4), ref?.
Returns: { status: "promoted", path, pinned, source: { session, turns } }.
draft_discard
Section titled “draft_discard”Drop a staged draft, the “drop” half of curation. It never reaches durable memory, and the session’s turns stay in the archive.
Parameters: session_id, draft_id, reason? (recorded in blame),
ref?.
Returns: { status: "discarded", draft_id }.
Plan tools
Section titled “Plan tools”Sixteen MCP tools wrap the plan primitives from the
agentstategraph-tasks crate and surface them with proactive
“CALL THIS WHEN” descriptions. Plans persist under /plans/<name>/
and survive session boundaries — the same plan can be picked up by
another agent or by you tomorrow.
plan_new
Section titled “plan_new”Create a plan.
When to call: the user describes a multi-step task. Don’t ask permission — if the work is multi-step, plan it.
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Kebab-case plan name |
description | string | no | One or two sentences |
ref | string | no | Branch, default main |
Returns the created plan as JSON.
plan_add
Section titled “plan_add”Add a task to a plan.
When to call: enumerating the steps of a multi-step task — add every step as a task before you start executing.
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
plan_id | string | yes | Plan name |
title | string | yes | Imperative sentence |
description | string | no | Longer-form (appended to title) |
priority | enum | no | low / medium / high / critical |
parent_id | string | no | Parent task id for a subtask |
assigned_to | string | no | Agent id (e.g. claude-code, codex) |
blocked_by | string[] | no | Task ids that must be done first |
ref | string | no | Branch, default main |
Passing assigned_to enables the state-driven orchestration pattern —
see plan_next below.
plan_start
Section titled “plan_start”Transition pending → in_progress.
When to call: you begin working on a task. Refuses with an error
listing the blockers if any entry in blocked_by is not yet done.
Parameters: plan_id, task_id, reason?, ref?.
plan_done
Section titled “plan_done”Transition in_progress → done. Requires a proof.
When to call: you finish a task. Proof kinds in order of preference:
commit— a git SHA (strongest)file— a path you created or editedtest— a test name that now exists or passestext— human-attested last-resort
Parameters: plan_id, task_id, proof ({kind, value, note?}),
reason?, ref?.
Completing the last open task in a plan auto-promotes the plan to
completed.
plan_abandon
Section titled “plan_abandon”Mark a task as abandoned. Requires a reason.
When to call: a task turns out to be unnecessary, superseded, or
no longer wanted. Legal from both pending and in_progress.
Parameters: plan_id, task_id, reason, ref?.
plan_edit
Section titled “plan_edit”Change a task’s title, description, priority or blockers after it was added. Status, proof, assignment and timestamps never change.
When to call: a task’s scope or wording changed, or its blockers need fixing. An abandoned blocker never counts as done, so after abandoning a task, edit its dependents’ blockers.
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
plan_id | string | yes | Plan name |
task_id | string | yes | Task to edit |
title | string | no | New title; the description is kept |
description | string | no | New description, or "" to remove it; the title is kept |
priority | string | no | low, medium, high or critical |
blocked_by | string[] | no | The whole new blocker list ([] clears it). Each must be a task in this plan, and the list can’t form a cycle |
force | bool | no | Edit a done or abandoned task (default false) |
ref | string | no | Branch (default main) |
Returns the task with changed, the fields that changed.
plan_next
Section titled “plan_next”Return the highest-priority pickable task.
When to call: you need to know what to work on next.
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
plan_id | string | yes | Plan name |
assigned_to | string | no | Agent id, or "me" |
include_unassigned | bool | no | Default true |
assigned_only | bool | no | Default false |
ref | string | no | Branch |
Pass assigned_to="me" to filter to tasks addressed to you. This is
the state-driven orchestration primitive: two agents with different
agent ids each call plan_next(assigned_to="me") and pick up their
own work without stepping on each other. Without assigned_to, any
agent sees any pickable task.
Returns the task object or null.
plan_list
Section titled “plan_list”List plans on the branch.
When to call: at the start of any session where you might be resuming prior work.
Parameters: status_filter? (active / completed / archived),
ref?.
plan_show
Section titled “plan_show”Fetch a plan with its full task list.
Parameters: plan_id, ref?.
plan_tasks
Section titled “plan_tasks”List the tasks of a plan, flat.
Parameters: plan_id, ref?.
plan_move
Section titled “plan_move”Move a plan and every task it contains from one branch (ref) to
another. Task ids, statuses, proofs, and the plan-meta envelope are
preserved bit-for-bit — only the ref changes.
When to call: promoting a sandboxed plan onto main, pulling
someone else’s plan onto a feature branch to collaborate, or refiling
work after a branch-strategy change. Refuses when source and target are
the same ref, or when a plan with the same name already exists on the
target ref.
Parameters: plan_id, target_ref, ref? (source branch, default main).
plan_close
Section titled “plan_close”Close a finished plan with a required summary of what it achieved, the
plan-level analog of a task’s proof. Refuses unless every task is done or
abandoned. Prefer it to plan_complete, which force-closes a plan that still
has open tasks.
When to call: the plan’s last task is finished. Afterwards, push the plan’s commits and open an MR for its branch.
Parameters: plan_id, summary, ref?.
plan_complete
Section titled “plan_complete”Force-close a whole plan in one shot: abandons every still-open task with
a reason, then closes the plan with a required summary. Use it when the
remaining work no longer matters (scope cut, plan superseded). When every task
is already finished, use plan_close; for progress, use plan_done per task.
Parameters: plan_id, summary, reason? (stamped on each abandoned
task; default “Plan force-completed by user”), ref?.
plan_archive
Section titled “plan_archive”Set plan status to archived. Soft — task data is preserved.
Parameters: plan_id, ref?.
plan_link
Section titled “plan_link”Record that a task, when done, satisfies a task in another plan — a
cross-plan dependency pointer (the substrate’s blocked_by is within-plan
only). Advisory: it does not auto-close the target; completing the linked task
surfaces a reminder to close the other one.
When to call: work in one plan closes out a task tracked in another.
Parameters: plan_id, task_id, target (as "plan/task"), ref?.
plan_stale
Section titled “plan_stale”List in-progress tasks idle for N days (default 7) across active plans,
most-stale first. The drift guard plan_start’s warning defends against.
When to call: resuming work or auditing state to catch tasks left silently
in-progress. Complements plan_next, which only returns the next pending
task and never shows what’s in progress.
Parameters: days? (default 7), ref?.
Sessions and workspaces
Section titled “Sessions and workspaces”session_info
Section titled “session_info”Describe a session: the workspace it lives in, the git branches it touched (with turn counts), and the plan tasks it worked on.
When to call: before acting on a session, to confirm it’s in the workspace
you expect or to see what plans it advanced. A session belongs to the
workspace of the repo it ran in; if this reports another one, you’re
connected to the wrong workspace (reconnect with ?namespace=<name>, or set
CTX_NAMESPACE for the CLI).
Parameters: session_id, ref?.
Returns: { session_id, namespace, present_in_this_workspace, provenance, links }. provenance and links are null for sessions recorded before
they were captured.
session_link_plan
Section titled “session_link_plan”Record that a session worked on a plan task. Links from commit messages that
name a task (a (plan t-NNN) trailer) are derived automatically; this records
the rest, such as a refactor with no trailer, or work discussed but not
committed.
Parameters: session_id, plan, task (t-4 or t-004), note? (kept
as the link’s evidence), ref?.
Returns: { status, plan, task, validated, already_linked }.
validated: false means the plan or task isn’t in this workspace. The link is
still recorded, but you’re probably connected to the wrong workspace.
namespace_for_plan
Section titled “namespace_for_plan”Find which workspace holds a plan, by scanning every workspace.
When to call: you have a plan id but not its workspace, for example after a write was refused because no workspace could be derived, or when resuming with a plan id from another session.
Parameters: plan_id.
Returns: { plan_id, namespaces, hint }. Pass the workspace as
CTX_NAMESPACE, --namespace or ?namespace=.
namespace_for_task
Section titled “namespace_for_task”Find which workspace holds a task, by scanning every workspace for the task under its plan.
Parameters: plan_id, task_id.
Returns: { plan_id, task_id, namespaces, hint }.
Docs and help
Section titled “Docs and help”docs_find
Section titled “docs_find”Find registered canonical docs whose path/scope/answers/owner match a query
(omit query to list all). Returns each doc’s path, status, scope, and what it
answers — a pointer to the canonical .md file, not its content.
When to call: before reading files or writing a new doc, to find where a
topic is already documented. Distinct from prime, which imports doc content
into recall.
Parameters: query?, ref?.
Exact syntax, examples and gotchas for a ctx or asd feature, on demand
(about 150-250 tokens), instead of carrying every tool’s full docs in context.
The docs are compiled into the Hub, so they match the running code.
When to call: before using a feature whose exact syntax you’re unsure of.
Omit topic for the grouped catalog of every feature, to discover ones you’d
otherwise miss.
Parameters: topic?: a feature name (remember) or a phrase (“save a
memory”); it fuzzy-matches. A topic that isn’t here may be an asd feature,
and the response says so.
Governance
Section titled “Governance”These tools mediate writes that shouldn’t be casual: deletion,
branch creation, and trust controls. They exist as MCP tools so
agents can introspect and act on the same surfaces a human reaches
for in Lens or via ctx.
forget
Section titled “forget”Forget a path by writing a rollback commit. The data isn’t physically
removed — its history is preserved in blame — but get and
recall will no longer surface it.
Parameters: path, reason?, ref?, personal? (forget from the
personal namespace; a recall result’s namespace says which holds it).
When to call: when a fact is wrong, expired, or the user
explicitly asks to forget it. Prefer forget over editing a fact in
place — the audit trail tells the next session “this used to be true,
here’s why we stopped believing it.”
branches
Section titled “branches”List every branch with its current head commit id.
Parameters: none.
branch
Section titled “branch”Create a new branch starting from from (default "main").
Parameters: name, from?.
When to call: before doing speculative or breaking work. Branches
sandbox both code and memory — remember calls on a feature branch
stay there until the branch merges. See
MEMORY_BRANCH_SCOPING.md for the full
model.
Merge source into target (default "main"). Returns {status: "ok", commit_id} on success, or {status: "conflict", conflicts: [...]} if the 3-way merge can’t proceed cleanly. Conflicting paths
are returned structurally so the caller can write the desired value
on target and re-attempt.
Parameters: source, target?, description?, reasoning?.
When to call: once a feature branch is ready to land back on the
trunk. Mirror of the ctx merge CLI command.
taint_list
Section titled “taint_list”List active taints / quarantines / watches across the graph.
Parameters: path_prefix?, effect?.
taint_check
Section titled “taint_check”Check whether agent_id may write to path at the given
confidence, given any active taints/quarantines. Returns
can_write, effect (the strongest blocking effect, if any), and
the matching taint id.
Parameters: path, agent_id, confidence?.
When to call: before any write you’re not certain is allowed — especially in multi-agent settings where another agent may have fenced off a path.
taint_apply
Section titled “taint_apply”Apply a taint, quarantine, or watch to a path. kind selects the
variant: taint (with an effect of warn/block/review/
isolate/advisory), quarantine (with optional authorized_agents
whitelist), or watch (advisory tracking).
Parameters: path, kind, reason, plus effect?,
authorized_agents?, min_confidence?, expires_at?.
taint_remove
Section titled “taint_remove”Resolve (lift) an active taint, quarantine, or watch by id. The record isn’t deleted — it’s marked resolved with a reason for audit.
Parameters: taint_id, reason.
Reminders
Section titled “Reminders”Pull-based scheduling primitives. Create a reminder now; call
remind_me at any future checkpoint to retrieve what’s due. Reminders
are ordered by priority then due_at. The autonomous flag controls
whether execution requires user approval first.
reminder_create
Section titled “reminder_create”Schedule a reminder for yourself or another agent.
Parameters: title, instructions, due_at (ISO 8601),
priority? (critical|high|medium|low|minimal, default medium),
autonomous? (default true), schedule? (once|interval|daily|weekly),
commands?, refs?, tags?.
remind_me
Section titled “remind_me”Return all currently actionable reminders (due or
awaiting_permission), ordered by priority. Lazily promotes any
pending reminders whose due_at has passed. Call this at session
start and after completing any task.
Parameters: none.
reminder_list
Section titled “reminder_list”List reminders with optional filters.
Parameters: status?, priority_at_most?, created_by?,
due_before?, ref_id?, tags?.
reminder_get
Section titled “reminder_get”Retrieve a single reminder by id, including its full execution history.
Parameters: id.
reminder_snooze
Section titled “reminder_snooze”Defer a reminder to a later time without cancelling it.
Parameters: id, until (ISO 8601).
reminder_approve
Section titled “reminder_approve”Approve a non-autonomous reminder for execution. Transitions
awaiting_permission → due.
Parameters: id, approved_by?.
reminder_cancel
Section titled “reminder_cancel”Cancel a reminder permanently. Use reminder_snooze to defer instead.
Parameters: id.
reminder_start
Section titled “reminder_start”Mark a reminder as in-progress. Opens a partial execution record.
Call just before acting; follow with reminder_record when done.
Parameters: id, agent_id?.
reminder_record
Section titled “reminder_record”Record the outcome of an execution attempt.
result is one of: success | failed | deferred | snoozed | cancelled.
On success with a repeating schedule, resets to pending with a new due_at.
Parameters: id, result, notes?, task_id?, agent_id?.
Read primitives
Section titled “Read primitives”Low-level read tools that mirror the engine’s HTTP surface. Agents
generally reach for recall first; these are for cases where the
agent already knows the path or wants to introspect provenance.
Read the JSON value stored at a path.
Parameters: path, ref?.
List every path under prefix on the given branch.
Parameters: prefix?, ref?.
search
Section titled “search”Full-text substring search across every stored value on the branch.
Parameters: query, ref?.
Return the last N commits on a branch — newest first — with agent id, intent category, description, confidence, and tags.
Parameters: limit?, ref?.
Return the full provenance chain for a path: every commit that touched it, who wrote it, with what intent and confidence.
Parameters: path, ref?.
Compute the structural diff between two refs (branches or commits).
Parameters: ref_a, ref_b.
Code intelligence tools
Section titled “Code intelligence tools”Code intelligence tools proxy read requests to an
AgentStateDeveloper (ASD)
server. They require the hub to be started with at least one ASD repo
configured — either via --asd-repo (hub manages asd-serve processes) or
--asd-url (you run asd-serve yourself).
Wiring ASD into the hub
Section titled “Wiring ASD into the hub”Option A — hub-managed process pool (recommended):
ctxone-hub --http \ --asd-repo myproject=/home/alice/myproject/.asd-state.db \ --asd-repo otherlib=/home/alice/otherlib/.asd-state.dbThe hub spawns one asd-serve process per repo on first use, kills it after
5 minutes of idle, and restarts it transparently on the next request.
Option B — pre-running asd-serve (manual):
asd-serve --db /home/alice/myproject/.asd-state.db &# Prints: listening on 127.0.0.1:4120
ctxone-hub --http --asd-url myproject=http://127.0.0.1:4120Multiple --asd-repo / --asd-url flags can be mixed. The repo name you
supply becomes the value for the repo parameter in every code tool call.
code_repos
Section titled “code_repos”List all ASD repos registered with this hub.
Parameters: (none)
Returns: JSON array [{ name, url }].
// response[ { "name": "myproject", "url": "http://127.0.0.1:54321" }, { "name": "otherlib", "url": "pool:otherlib" }]url is the resolved endpoint for pre-running repos; pool-managed repos show
pool:<name> until the process is first requested.
code_search
Section titled “code_search”Search code symbols by concept or keyword across name, signature, doc comment, file path, and ledger summaries. Returns ranked results.
Use this for feature archaeology when you don’t know the exact symbol name.
Parameters:
| Name | Type | Default | Description |
|---|---|---|---|
query | string | — | Search terms (concept, function name, effect label, …) |
repo | string | first registered | Repo name from code_repos. Omit when only one repo is registered. |
kind | string | — | Filter to function, method, class, module, variable |
language | string | — | Filter to python or typescript |
limit | number | 20 | Max results |
Returns: JSON array of matching symbol records with relevance scores.
// request{ "query": "charge card payment", "repo": "myproject", "limit": 5 }
// response[ { "qname": "payments.charge_card", "kind": "function", "file": "payments.py", "signature": "def charge_card(user_id: str, amount: float)", "score": 0.92 }]code_read
Section titled “code_read”Read a symbol by qualified name. Returns the symbol, its declared and transitive effects, and all ledger decisions — the full context needed to reason about a code unit.
Parameters:
| Name | Type | Default | Description |
|---|---|---|---|
qname | string | — | Fully-qualified symbol name (e.g. payments.charge_card) |
repo | string | first registered | Repo name |
Returns: { symbol, effects, ledger }.
// request{ "qname": "payments.charge_card", "repo": "myproject" }
// response{ "symbol": { "qname": "payments.charge_card", "kind": "function", "file": "payments.py", "signature": "def charge_card(user_id: str, amount: float)" }, "effects": { "declared": [ { "effect": "io.db.write", "note": "INSERT INTO charges" }, { "effect": "log" }, { "effect": "throw" } ], "transitive": [], "verification": { "status": "unverified" } }, "ledger": [ { "kind": "hazard", "summary": "boundary at 10000 is undocumented", "tags": ["approved", "approved-by:alice@example.com"] } ]}callers_of
Section titled “callers_of”List symbols that call the given symbol (inbound call edges).
Parameters:
| Name | Type | Default | Description |
|---|---|---|---|
qname | string | — | Target symbol |
repo | string | first registered | Repo name |
Returns: JSON array of calling symbol records.
// request{ "qname": "payments.charge_card", "repo": "myproject" }
// response[ { "qname": "driver.main", "kind": "function", "file": "_driver.py" }]callees_of
Section titled “callees_of”List symbols called by the given symbol (outbound call edges).
Parameters:
| Name | Type | Default | Description |
|---|---|---|---|
qname | string | — | Target symbol |
repo | string | first registered | Repo name |
Returns: JSON array of callee symbol records.
// request{ "qname": "driver.main", "repo": "myproject" }
// response[ { "qname": "payments.charge_card", "kind": "function", "file": "payments.py" }, { "qname": "payments.get_balance", "kind": "function", "file": "payments.py" }]code_cross_repo_edges
Section titled “code_cross_repo_edges”Map the service edges between every repo registered with ASD: a client call
in one repo matched to the route that serves it in another. It runs
asd repo edges over the shared repo registry, so index each repo first to
keep its contracts current.
When to call: before a cross-service change, or to find hidden
dependencies between repos. For one endpoint’s blast radius, use
code_impact; this returns every edge.
Parameters: none.
Returns: every cross-repo edge, as JSON from asd.
code_impact
Section titled “code_impact”Given an endpoint you’re about to change, return its consumers in other repos
and the invariants and hazards each consumer’s own ledger records: what
breaks if it changes, and what those callers were promised. It runs
asd repo impact <target>.
Parameters: target: a route-handler qname (get_orders or
app.routes.get_orders) or a contract (http:GET /api/orders/{}).
Returns: the consumers and their invariants and hazards, as JSON from
asd.
get_active_repo
Section titled “get_active_repo”Return the active ASD repo for this session (set via set_active_repo),
or null if none is set. Also returns the list of registered repo names
so the agent can pick one.
Parameters: none.
Returns: { "active_repo": <name|null>, "known_repos": [ … ] }.
set_active_repo
Section titled “set_active_repo”Set the active ASD repo for this session. Subsequent code tools
(code_search, code_read, callers_of, callees_of) default to this
repo when their repo parameter is omitted — so you don’t repeat repo
on every call in a single-repo session.
When to call: at the start of a session focused on one registered repo. Errors if the repo isn’t registered; pass an empty string to clear.
Parameters: repo (registered repo name; empty string clears).
Additional tools
Section titled “Additional tools”These tools round out the 65-tool surface. They follow the same
request/response conventions as the tools above; call the help tool
(ctx help <name>) for exact parameters and examples on demand.
Help & docs
help— on-demand instruction disclosure: returns per-feature syntax, examples, and gotchas for actx(orasd) tool, or the full catalog. Backed by a shared cross-tool registry soctxandasdresolve each other’s topics.docs_find— search docs that were imported into memory (viaprime/ctx prime) and return the best-matching sections.
Plans (extended)
plan_link— link a plan to a related plan, session, or task.plan_stale— surface plans that have gone stale (untouched / drifted).plan_close— close a plan out (distinct fromplan_complete/plan_archive).
Drafts — stage proposed memory writes for review before they land:
draft_stage— stage a proposed memory write without committing it.drafts_list— list currently staged drafts.draft_promote— promote a staged draft into committed memory.draft_discard— discard a staged draft.
Sessions
session_segments— list the segments (topic arcs) of a session.session_info— describe a session: its namespace, the branches it touched, and the plans/tasks it advanced.session_link_plan— associate a session with a plan.
See also
Section titled “See also”- HTTP_API.md — same logic exposed over REST
- INTEGRATIONS.md — how to wire these tools into specific AI clients
- ASD_INTEGRATION.md — full guide to the ASD code intelligence integration
- ARCHITECTURE.md — the underlying graph model
- Agent guidance — guidance on when to reach for plans vs. inline work