io.github.contextq/contextq-mcp

Boot an autonomous agent: ONE token-budgeted call returning everything needed to start or resume work. Call this FIRST in any agent run. Returns {agent, session:{...,role}, resume:{checkpoint_summary, open_tasks}, handoff:{tldr, source}, lessons:[], facts:[], brief, skills:[], skills_full, repo_map, siblings:[], budget:{limit, used, dropped}, client}. If a non-terminal session exists for this agent (or session_id is given), `resume` tells you exactly where you left off; `handoff` is the best-ranked latest handoff (a hand-written wrap SEED first). `goal` drives the facts, lessons AND skills retrieval. `skills` are parametrized procedures distilled from verified past runs matching the goal ({context_id, name, description, success_count, similarity}) -- check them BEFORE re-deriving a solution. On a session's later boots `skills` holds only new or changed entries and `skills_full` is false (empty then means nothing new, not no skills); pass `full:true` for the complete set. With `project_id` you also get a goal-graph `brief` {north_star, role, lane, next, blocked_on, blocking, done} and the session role is inferred from the matched goal node. With `include_repo_map:true` on a code-indexed workspace, `repo_map` carries top-ranked file signatures to answer "where is X handled" without grepping. `siblings` lists other active sessions in this workspace (last ~60 min, max 5) so you can coordinate via relay_* before touching shared resources. Slots fill resume > handoff > lessons > facts > brief; overflow is reported in budget.dropped. Trigger: resume or catch up on tracked work ("hôm trước tới đâu", "tiếp gì", "tóm lại đang làm gì", "what's next", "resume", "where did we leave off", "catch me up"). Skip for unrelated casual questions.

Snapshot the agent's working state so a restart/crash can resume from exactly here. `state` is an arbitrary JSON scratchpad (cursor, partial results, plan, open files). `summary` is a 1-line 'where I am'. Returns the checkpoint with its monotonic seq. Call periodically after each chunk of progress.

Generate a handoff document for the session's workspace at run end (wraps the dream handoff generator — LLM-synthesized TL;DR + in-progress + next-steps + open-questions). Links the handoff context back to the session. Pass complete=true to also mark the session completed. Requires an LLM provider configured on the server.

Record a lesson learned during a run so the agent doesn't repeat the failure. Embedded for goal-relevant recall at the next agent_boot. Mirrors the vibe-loop '## Lessons' log. scope controls breadth: 'session' (this run), 'agent' (this agent always), or 'workspace'.

Read the resume bundle for a session WITHOUT booting fresh: latest checkpoint, open tasks (pending/in_progress/blocked), and goal-relevant lessons. Use when you already know the session_id and just need to reload where you left off.

End or update an agent session's status. Use status='completed' when the goal is met, 'paused' to suspend (resume later from the checkpoint), 'stalled' when the vibe-loop stall detector trips, or 'abandoned' to drop the run. Setting completed/abandoned stamps ended_at.

Start a new agent session (a run with a goal). Returns the created session including its id. Use when beginning a fresh task that you want to track and resume. Pass parent_session_id to chain a resumed run to its predecessor.

Flip a task's status. Setting status='verified' REQUIRES non-empty `evidence` (real observed output: test result, HTTP status, exit code) — the no-self-certification rule. Returns 400 if you try to verify without evidence. Use this as each checklist item is proven. Trigger: user reports finishing a piece of tracked work ("xong rồi", "xong X", "done X", "done", "mark done", "finished X") — tick the matching session-scoped checklist item here (use goal_advance instead for a board-level task). Only call when it maps to a tracked item; ignore unrelated casual chatter.

Create or update one checklist item in a session's task tree. Omit task_id to create; pass task_id to update. `verify_cmd` names HOW the item is proven done (the agent must run it before ticking). Use parent_task_id for subtasks. This productizes the vibe goal-file checklist. Trigger: call at the START of a tracked piece of work to record a checklist item (session-scoped — for a task meant to persist across sessions use goal_add on the board instead). Only call when the work is actually being tracked; ignore unrelated casual chat.

Permanently delete a context entry by ID. This action cannot be undone. Use this only when you are sure the entry should be removed.

Get a single context entry by its ID. Use this when you already know the exact context ID you want to read. Response includes lifecycle, atomic, quality_score, valid_from, and valid_to alongside the standard fields.

Run the deep health probe and return the full report. Probes DB, Elasticsearch, embedding provider, LLM provider, and scheduler states. 30-second in-memory cache on the server. Returns `{status, components, schedulers, queue}` - status is `ok|degraded|fail`. Useful for ad-hoc prod health checks from MCP clients.

List context entries with optional filters. Use this to browse existing contexts by workspace, project, type, or tag without a search query.

Load one additional group of ContextQ tools into this session (group names come from ctx_tool_groups) so they become callable without reconnecting. Pass "all" to load every remaining ContextQ tool at once. Some MCP clients need to refresh their tool list to actually see newly loaded tools in the model's context -- if a loaded tool still doesn't show up, call it directly by name anyway (ContextQ accepts a tool call for any known tool name regardless of what tools/list currently returns), or restart this server with the environment variable CONTEXT_MCP_TOOL_PROFILE=full to get every tool from the start.

Extract durable memories from a raw multi-turn conversation and save them as deduped atomic contexts. Turn-aware sibling of ctx_ingest: the server builds a speaker-attributed transcript, extracts only durable facts/preferences via LLM (skipping chit-chat), and runs the claims through the SAME kNN-dedup + diff + create/update/archive pipeline ctx_ingest uses. Pass subjectId to scope memories to a single end-user of your application (Mem0-parity user_id) — dedup then only considers that subject's own prior memories, and every created context is tagged with that subjectId so ctx_search (subjectId param) and GET /api/memory can retrieve it later. Set dryRun=true to preview without persisting. Long conversations run async — the response is { jobId, statusUrl } and you must poll ctx_ingest_status (or GET /api/ingest-jobs/:id) until status='succeeded' or 'failed'. Short conversations return the full result inline. Pass async=true/false to force a path explicitly.

Save a new context entry (reference doc, feedback, project note, incident report, lesson learned, or user profile). Use this when you want to persist knowledge for future retrieval. Optional lifecycle/valid_from/valid_to flag the note's maturity and bi-temporal validity. Response includes atomic, quality_score, and lifecycle once the backend judge has run. Trigger: user asks you to remember/save something ("nhớ cái này", "lưu lại", "ghi nhớ giúp", "remember this", "save this", "note this down") — call whenever work-relevant info should persist across sessions. Only call when the request is actually about tracked work/memory; ignore unrelated casual chat.

Search / recall saved knowledge and memories using hybrid full-text + semantic search ranked by relevance — the default tool for 'what do I know about X' or 'did I already save this'. Use this when you need to find, remember, or look up existing knowledge by keyword or phrase. Set chunk_search=false to disable per-chunk passage matching, lifecycle_boost=false for legacy ranking, or include_archived=true to surface retired notes. Results may include lifecycle, quality_score, and matched_chunk per hit.

Get aggregate statistics: total context count, breakdown by workspace, type, tag, recently updated entries, and orphan_rate (notes with no tags and no inbound references). Use this for an overview of what is stored and to spot disconnected knowledge.

List additional groups of ContextQ tools not loaded in this session by default -- code-graph lookup, admin/audit, relay handoff, world-model snapshots, saved searches, knowledge-graph traversal, bulk import/ingest, and more. Search here first if a ContextQ tool you expect (a saved search, a relay, a snapshot, a code reference) is missing from your current tool list. Returns each group's name, one-line purpose, member tool names, and how many of them are already loaded, plus how to load a group with ctx_load_tool_group.

Update an existing context entry. Only the provided fields are changed; omitted fields remain unchanged. Use this to correct, append to, reclassify, or retire (archive) an existing entry. Optional lifecycle/valid_from/valid_to update note maturity and bi-temporal validity.

Add a node to the goal graph. Progressive elaboration: only title is required -- omit parent_id to create a root node (a vague node is created status='draft'); fill the rest as reality reveals it. kind: objective|milestone|goal|work_item|relay. owner_role/status/origin are free strings. Trigger: when a user (including a non-technical one) asks you to remember or hand off a piece of work for later ("thêm việc", "thêm task", "todo", "add a task", "add to the board"), create a node here with a valid status (draft is fine if details are vague) — this is how a casual request becomes a durable tracked task. Only call when the request is genuinely about work to track; ignore unrelated casual questions.

Advance a node's status. A leaf moving to 'done' REQUIRES non-empty evidence (real observed output) — the no-self-certification rule. Parent status rolls up automatically from children. Trigger: when the user reports finishing a tracked piece of work ("xong rồi", "xong X", "done X", "done", "mark done", "finished X"), advance the matching board node's status here. Only call when the report maps to a tracked board item; ignore unrelated casual chatter.

The ready-frontier: nodes (optionally for a role, or scoped to one objective_run_id) whose ALL blocking dependencies are done and that aren't done yet — i.e. 'what can I start NOW'. Returns GoalNode[] with depsIn/depsOut ([{nodeId, kind}]). A node whose externalRef.blocker is set is waiting on a person or an external event, not on a dependency: treat it as not runnable.

List goal nodes, filtered. Use to read the graph (your lane, a status column, all milestones, or one objective's whole run via objective_run_id). Returns a COMPACT view by default (id, title, status, kind, externalRef.local_id/priority, blocked, depsIn/depsOut) and omits done nodes unless include_done is true or a status filter is given; call goal_get for one node's full payload, or pass view="full".