# Quipu MCP server

> Provides a governed, bitemporal knowledge store that allows AI agents to read, reuse, and share facts with provenance and history.

- Repository: https://github.com/intigraph/quipu
- Page: https://hostedmcp.org/servers/intigraph/quipu
- Transport: stdio
- Stars: 16
- License: Apache-2.0
- Latest version: 0.18.1

## Install

### Claude Code

```sh
claude mcp add quipu -- docker run -i --rm ghcr.io/intigraph/quipu:0.18.1
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "quipu": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/intigraph/quipu:0.18.1"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "quipu": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/intigraph/quipu:0.18.1"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"quipu","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/intigraph/quipu:0.18.1"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "quipu": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/intigraph/quipu:0.18.1"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add quipu -- docker run -i --rm ghcr.io/intigraph/quipu:0.18.1
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.quipu]
command = "docker"
args = ["run", "-i", "--rm", "ghcr.io/intigraph/quipu:0.18.1"]
```

### Gemini CLI

```sh
gemini mcp add -s user quipu docker -- run -i --rm ghcr.io/intigraph/quipu:0.18.1
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "quipu": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/intigraph/quipu:0.18.1"
      ]
    }
  }
}
```

## Tools (87)

- `quipu_query`: Execute a SPARQL SELECT query against the knowledge graph (supports time-travel via valid_at/tx). Declare every prefixed name with an explicit PREFIX; namespaces are not assumed. For exploratory text discovery use quipu_search instead of unbound FILTER(CONTAINS(...)) scans. Search does not replace exact-ID, owner-plate, named-graph or absence checks. (read-only)
- `quipu_export`: Export deterministic RDF scoped to one named graph, provenance group, SPARQL CONSTRUCT, or ROOT when no scope is supplied. Scope fields are mutually exclusive. (read-only)
- `quipu_align_propose`: READ. Propose candidate cross-graph alignments between two named graphs, scored, as an SSSOM mapping set. Returns expected_version, which align_apply requires. Refuses an unknown graph IRI rather than returning 0 candidates. (read-only)
- `quipu_align_decide`: READ. Apply operator accept/negate decisions to a proposed mapping set. Touches no store. Returns the decided set and the expected_version to carry into align_apply. (read-only)
- `quipu_align_apply`: WRITE. Materialise decided alignments as owl:sameAs / quipu:distinctFrom in a derived alignment graph. expected_version is REQUIRED and must be carried from the decision: computing it here would hash the set being written, always match, and silently discard a concurrent operator's decision.
- `quipu_merge_decisions`: READ. Review rows for merging an incoming share (incoming + base) or promoting a fork (fork) into ROOT, with base/ours/theirs values and provenance. Convergent rows default to continue, which preserves the current claim without writing. propose:true adds advisory proposals; conflicts still require the reviewer's choice. present:true returns {decisions, presentation, view}. Writes nothing. (read-only)
- `quipu_merge_apply`: WRITE. Finish a share merge (incoming + base) or fork promotion (fork) under one writer reservation, with ordered receive/decide transactions recording reviewer and decisions hash. Convergent continue writes no slot operations. Refuses undecided or stale inputs, invalid RDF values, invalid explicit cardinality decisions or failed validation. Applying the same decisions again reports already-applied and writes nothing.
- `quipu_merge_resolve`: Record one choice on one row of a merge decisions file (share or fork) and return {decisions, presentation, view}. Convergent rows accept continue/base/value. Conflicts accept ours/theirs/base/both (within sh:maxCount), value or defer. Continue is refused on a conflicting row. Touches no store. Apply with quipu_merge_apply. (read-only)
- `quipu_knot`: Assert facts into the knowledge graph (with optional SHACL validation). When a loaded class vocabulary exists, unknown rdf:type IRIs refuse before writing. Inspect quipu_shapes with action=vocabulary; similar class names are not semantic equivalence. Propose and load a shape if no sanctioned type fits.
- `quipu_cord`: List entities in the knowledge graph, optionally filtered by type or predicate (read-only)
- `quipu_unravel`: Time-travel query: see facts as they were at a given point (read-only)
- `quipu_validate`: Validate RDF data against SHACL shapes without writing (read-only)
- `quipu_shapes`: Manage persistent SHACL shapes (load, list, get, remove) and inspect the loaded class vocabulary. Loaded shapes auto-validate on writes.
- `quipu_queries`: Manage STORED named queries — competency questions a consumer ships with its domain, callable through quipu_ask alongside the compiled-in catalog. Definitions are validated at LOAD (template must parse; every {placeholder} needs a spec; an optional param needs a default) and versioned: re-loading a name closes the prior version rather than overwriting it.
- `quipu_graph_create`: Register a committed named graph before graph-scoped knot writes or labeling. Idempotent: an existing graph retains its original creation timestamp and declared actor. Interned terms are not registration.
- `quipu_graph_label`: Declare lattice labels on an already registered committed graph. Create first with quipu_graph_create. Declarations are versioned; policy tokens describe data, not authorization.
- `quipu_graph_list`: List registered named graphs; optional graph selects one exact registered IRI without materialization enrichment (cannot combine with kind/lifecycle). Includes class, source, lifecycle and labels (freshness/durability/trust/policy/kind). Filter with `kind` (a dataKind token, e.g. operational | archive) and/or `lifecycle` (frozen). Also the capability probe for the graph-kinds surface: a store without this tool predates it. (read-only)
- `quipu_graph_freeze`: Deep-freeze a named graph: export its FULL history (retracted rows and transactions included) into a read-only archive pack, verify the copy by content hash, delete the local rows, and re-attach the pack so the graph stays addressable at the same IRI. Compose frozen graphs back in with FROM <iri>, the urn:quipu:dataset:frozen dataset, or include_kinds:["archive"]. Refuses ROOT, the meta-graph, overlays, attached graphs, and double-freezes.
- `quipu_graph_thaw`: Thaw a frozen graph: verify its archive pack, detach it, restore the full history into the local store under the same IRI, and reopen the graph for writes. The pack file is kept on disk; the freeze registry row is closed, never deleted.
- `quipu_datasets`: Manage named datasets — a reusable NAME for an arbitrary set of graphs, so it can be labelled, governed and handed to another agent. `FROM <dataset-iri>` then means FROM over its members. Datasets overlap freely and are never implicitly active.
- `quipu_mapping_propose`: READ. Qualify explicit one-hop schema correspondences, existing named scope and exact current shape/ontology pins. Returns a digest-bound proposal. Creates no graphs or transactions and performs no automatic matching. (read-only)
- `quipu_mapping_decide`: READ. Pure explicit per-row accept/decline decisions bound to the whole proposal digest. Every full correspondence key needs exactly one decision. Returns the selected mapping and expected_digest; declared reviewer is provenance, not a credential. (read-only)
- `quipu_mapping_apply`: WRITE. Apply or retire a decided mapping with exact expected_digest. Both graphs must already exist; existing graph authority/validation gates remain. Records the actual lifecycle decision and MappingRecord in the same tx. Exact replay does not reopen retirement. No consumer or replica activation.
- `quipu_retract`: Retract ROOT/default-graph facts for an entity: all of them, or narrowed by predicate and/or value. Supplying a graph field is refused; named-graph facts are untouched. Entity + predicate + value retracts exactly ONE (e,a,v) statement — use this to remove a stray edge instead of retracting a whole episode and rebuilding it.
- `quipu_set`: Atomically SET (entity, predicate) to exactly one value in the ROOT/default graph. Supplying a graph field is refused; named-graph facts are untouched. Retracts every current object on that predicate and asserts the new one in a single transaction. The supersede primitive — re-parenting (reports_to A -> B) is one call, with no empty-predicate window and no way to end up with two supervisors by forgetting the retract half. SINGLE-VALUE semantics: replaces ALL current objects; to add without removing, assert via quipu_knot.
- `quipu_retract_episode`: Episode-scoped logical retraction: retract all currently-active facts an episode's ingest contributed (activity node, entities, edges, reified statements), via the bitemporal valid_to close path. Logical, not physical — time-travel history is preserved. Entities and other episodes' facts are untouched. Idempotent. Node IDENTITY is protected: by default (on_orphan=preserve) rdfs:label/rdf:type survive for any node that other episodes still reference, so retraction never leaves an unlabelled, untyped ghost. The response always reports identity_orphans.
- `quipu_retract_source`: RETRACT-ONLY repair: retract every currently-live fact whose transaction source equals an exact string. Reaches facts that no snapshot replacement can touch — quipu_knot composes its own tag as snapshot:<key>, so facts written under any other source (a free-form producer string, a hand-run CLI promote) were previously unretractable forever. There is NO turtle input: the transaction cannot carry an assertion, so this cannot write facts attributed to the named producer. The retraction is stamped with its OWN source, repair:<ticket>, never the source being cleared. PLANS BY DEFAULT: without apply=true it writes nothing and reports what would be retracted, so planned:0 means 'that source owns nothing live'. Applying requires expect=<planned> as a confirmation handshake, and the response reports 'remaining' — a fresh read of the post-state, not an echo of the request. RE-KEYING ORDER: retract FIRST, then re-promote canonically; asserting first is skipped as a duplicate and the retraction then removes everything.
- `quipu_episode`: Ingest structured knowledge from an agent episode (nodes + edges)
- `quipu_namespaces`: List the effective owner namespace registry; no writes or allocation. (read-only)
- `quipu_entity_ref`: Mint a typed stable entity, resolve a registered reference or verify a local key IRI against its key triples without fetching. Uncertain mint responses must be reconciled, never blindly retried.
- `quipu_share`: Produce a bounded portable share payload, including canonical manifest and member bytes. Read-only; no server-local output path. Pass the exact scope. Internal-only export exemptions are not accepted over this transport. (read-only)
- `quipu_import`: Stage a portable share with hash, vocabulary and attestation gates. Copy member contents from quipu_share; this is not a server file path. Exact-name merges default off; review before promotion.
- `quipu_import_promote`: Promote a staged share only when existing promotion gates permit it. Does not bypass quarantine or resolution review. With target_graph, promote into that named graph instead of ROOT, replacing only the share's subjects there; with retire_from too, move those subjects out of that source graph in the same transaction. With dry_run, report what the move would assert, replace and retire, and write nothing.
- `quipu_acquire`: Acquire complete bounded registered named graphs from an expected MAIN store lineage. Unknown graphs, unsupported attachments/pins and overflow refuse. (read-only)
- `quipu_acquire_composed`: Acquire qualified MAIN graphs with a fenced attachment census. expected_generation is required with an explicit main tx; provider clocks are never a global transaction. (read-only)
- `quipu_knot_stage`: Stage one immutable numbered snapshot part. Supply exact sha256 hashes and upload identity; replay is idempotent, changed bytes refuse. No file paths.
- `quipu_knot_promote`: Start or read back atomic promotion of a staged snapshot upload. pending=true is not completion; poll the same upload_id. Existing validation gates remain authoritative.
- `quipu_reason`: Run stored or inline Datalog rules to fixpoint and persist derivations. Omitted graph means ROOT; pass graph to scope premises. Derivations persist in that graph's reserved companion inferred graph, not alongside asserted facts.
- `quipu_update`: Execute SPARQL 1.1 Update through the guarded update endpoint. Use explicit GRAPH clauses for named graphs; absent scope has standard SPARQL default-graph semantics. Actor/source are declared provenance, not authorization.
- `quipu_events`: Read a bounded batch of ROOT's events without committing a consumer cursor. since overrides consumer. types is a comma-separated event-type filter; group is an episode group, not a graph selector. A named graph's events are quipu_graph_events. (read-only)
- `quipu_graph_events`: Read a bounded batch of ONE registered committed named graph's events (its own log and offsets) without committing a cursor. Same filters as quipu_events. (read-only)
- `quipu_events_commit`: Durably set a consumer cursor. Lower offsets explicitly rewind; delivery alone never commits.
- `quipu_graph_events_commit`: Durably set a consumer cursor in one registered committed named graph's event log. Lower offsets explicitly rewind.
- `quipu_changes`: Read whole transaction change pages. graph scopes an exact graph; use next_tx for the next page. No cursor write. (read-only)
- `quipu_subscriptions`: Manage persistent push subscriptions (create/list/delete). Creates may deliver externally; list is still conservatively write-classified like REST.
- `quipu_workflow_capabilities`: Read whether the server enforces direct-workflow guards before using quipu_update. Reports capability only, never configuration or credentials. (read-only)
- `quipu_entity`: Dereference an exact IRI as JSON-LD. IRIs are encoded as query values, including slashes and fragments; expanded includes label expansion. (read-only)
- `quipu_entity_history`: Read exact entity history. Without graph, legacy ROOT-only history. With graph and source_store_id, the quipu-entity-history/main-v1 contract returns bounded retained MAIN history with source/generation-qualified transactions; attachments, continuous history and historical-policy proof remain outside coverage. (read-only)
- `quipu_transactions`: Read bounded transaction metadata after since; does not change a cursor. (read-only)
- `quipu_embed_backfill`: Backfill missing ROOT entity embeddings using the configured provider. May consume external embedding resources and persist vectors.
- `quipu_embed_backfill_graph`: Backfill a bounded number of named-graph entity embeddings; does not rewrite ROOT entity text.
- `quipu_search_query`: Fuse ranked search seeds with a SPARQL query. Existing mode-specific validation and query budgets apply. (read-only)
- `quipu_fragments`: Read a bounded triple-pattern fragment. page and pageSize select a page; absent terms are wildcards. (read-only)
- `quipu_reconcile`: Get the reconciliation service manifest or resolve keyed query objects without merging entities. (read-only)
- `quipu_spotlight`: Annotate text with known entities, read-only. A busy cold cache may return no annotations; that is not an absence proof. (read-only)
- `quipu_stats`: Read server graph and transaction statistics. This describes the serving store, not a client-local database. (read-only)
- `quipu_health`: Read server health as a positive liveness control; healthy does not prove complete graph coverage. (read-only)
- `quipu_version`: Read served version, source commit and dirty-build identity through MCP without a REST fallback. (read-only)
- `quipu_search`: Search defaults to semantic when an embedding provider or query embedding is available, otherwise SQLite FTS5 keyword search. Explicit modes override automatic selection. Configurable lexical/vector hybrid fusion is opt-in. Keyword mode requires query text and an enabled, backfilled index; it needs no embedding provider. Ranked REST results are diagnostic candidates; native MCP renders admitted context only. Agent context uses context_results when insufficient_context is false under quipu-context/v1. (read-only)
- `quipu_hybrid_search`: Combined SPARQL + vector similarity search with predicate pushdown. Accepts a pre-computed embedding or natural-language query. Simple type constraints (e.g. ?s a <Type>) are pushed into the vector index for O(log n) filtered ANN. (read-only)
- `quipu_search_nodes`: Search for entities in the knowledge graph by natural language query. Uses text matching on entity names, labels, and values. Replaces Graphiti's search_nodes. (read-only)
- `quipu_search_facts`: Search for relationships/edges in the knowledge graph by natural language query. Finds facts where the predicate or value matches the query. Replaces Graphiti's search_memory_facts. (read-only)
- `quipu_episodes_complete`: Graphiti-compatible flat episode ingestion. Accepts name, body text, group, and source — converts to Quipu episode and ingests.
- `quipu_impact`: Impact analysis: walk downstream from an entity. With remove=true, speculatively retracts the entity first (counterfactual: 'what would break if I removed this?'). The store is never mutated.
- `quipu_path_cone`: Golden paths: compute the provenance cone of a trajectory — which steps did its falsifier-gated verified result depend on? Per-step verdicts are in-cone (load-bearing; pruning needs a human Decision), out-of-cone (mechanically prunable), or cannot-evaluate (no derivation edges recorded — never silently prunable). Refuses trajectories with no steps or no falsifier-gated verification. (read-only)
- `quipu_path_backtest`: Golden paths: backtest a pruned candidate (exemplar trajectory minus omitted steps) over recorded history — which past trajectories with a shared work-item topic would have conformed under gp-grammar/1, and how did their work items close? Distinguishes 0 matches from cannot-evaluate, and refuses a pattern it cannot compile. (read-only)
- `quipu_unified_search`: Unified knowledge search for Bobbin integration. Combines text and optional vector search, returning results tagged with source='knowledge' and normalized 0-1 scores. When an EmbeddingProvider is attached, the query is auto-embedded for semantic search. (read-only)
- `quipu_ask`: Run a curated, parameterized named query by name instead of hand-writing SPARQL. Call with no 'name' (or name='list') to discover the self-describing catalog of available queries and their parameters (e.g. service_deps, references_to, entity_facts, entities_of_type, labeled_like). (read-only)
- `quipu_propose_schema_change`: Submit a schema evolution proposal (new shape, class, property, or ontology change). Proposals require explicit acceptance before taking effect.
- `quipu_list_proposals`: List schema evolution proposals, optionally filtered by status (pending, accepted, rejected) (read-only)
- `quipu_accept_proposal`: Accept a pending schema proposal. For shape proposals, validates the Turtle before writing to the shapes table. A proposal carrying a migration runs it in the same transaction; a refused migration leaves the proposal pending and nothing written. With dry_run=true nothing is accepted: the report lists existing facts the new shapes would refuse, what the migration would change, and whether acceptance would go through. Before accepting, a blast-radius plan is computed and returned as 'plan'; a plan whose risk score exceeds risk_threshold, or that cannot be determined, is refused unless accept_risk=true with a risk_reason (recorded in the decision note).
- `quipu_reject_proposal`: Reject a pending schema proposal with a reason
- `quipu_resolve_entity`: Check for existing near-duplicate entities before writing. Uses vector similarity (embedding) and canonical name matching (Jaro-Winkler) to find entities that may be duplicates. Returns candidates with similarity scores and match explanations. (read-only)
- `quipu_graph`: Project the knowledge graph into a render-ready node-link payload in ONE response: nodes (iri, label, rdf:type, degree), edges as [source_index, target_index, predicate] into that node array, and a type census ordered by prevalence. Excludes prov:Activity episodes and rdf/rdfs/prov scaffolding predicates by default so the domain graph is not buried in provenance. Nodes are ranked by degree and capped; the response states what was dropped. (read-only)
- `quipu_project`: Project the knowledge graph and run a graph algorithm over it: stats (node/edge counts), in_degree (most-referenced entities), pagerank/ppr (global or personalized PageRank from seed entities), components (weakly-connected components), louvain (modularity community detection), or shortest_path. Optionally restrict the projection to a node type or predicate. Read-only by default; louvain with persist:true writes quipu:memberOfCommunity facts (superseding any prior derivation).
- `quipu_context`: Query the knowledge graph for context around a natural-language query: returns relevant entities and their facts, ready to prime an agent. Optionally expand to linked entities. (read-only)
- `quipu_report`: Generate a live graph report (graphify's GRAPH_REPORT.md equivalent, but queryable): top hubs / 'god-nodes' (by PageRank with in-degree as a secondary signal), surprising connections (low-prior edges that bridge two otherwise-separate Louvain communities — rarer bridges rank first), and auto-suggested questions seeded by those hubs and bridges. Read-only; derived from current graph structure. Communities here are emergent clustering for surfacing, NOT an access boundary. (read-only)
- `quipu_rule_query`: Read explicit positive/negative support as supported/refuted/both/neither, plus a separate admitted judgment disposition. Current ROOT only; failed/incomplete reads are UNKNOWN, never absence. No action authority or implicit boolean conversion. (read-only)
- `quipu_policy_check`: Committed-tier evaluation of a governance Policy over the graph of record: evaluates the policy's aegis:claim (a SPARQL ASK, optionally with a $target placeholder) against the committed graph and returns a Verdict — outcome ∈ {satisfied | unsatisfied | unknown} bound to a reproducible evidence_hash. Deterministic and reproducible: any verifier re-running the same ASK over the same committed evidence gets the same verdict (checked, not trusted). Returns the verdict UNSIGNED (signing + persistence is the Phase-0 verifier registry's job). (read-only)
- `quipu_verdict_verify`: Verify a signed Verdict against the root of trust AS OF the signature (signing-plane S1): the signature must be valid under a key registered to the verifier at that instant, AND that same registration must authorize the predicate. 'trusted' is that conjunction — the property a consumer should gate on. Pass 'verdict' (the stored verdict's IRI) for a trust decision: quipu then reads when the store recorded the signature, which the signer cannot choose. 'as_of.basis' says which instant was used (recorded | caller-supplied | now). A caller-supplied signed_at/tx is a what-if: 'trusted' is then always false and the answer is in 'would_verify_as_of_supplied_instant'. (read-only)
- `quipu_verifier_authorized`: Check the Phase-0 verifier registry: may this verifier attest this predicate? The discovery half of the governance gate — lets an agent learn who is authorized before trusting (or requesting) an attestation. (read-only)
- `quipu_cooccurrence`: Deterministic, auditable work-item co-occurrence: given a work-item (Bead) IRI, returns the other work-items that share at least one touched code entity via the provenance chain Bead <-implements- GitCommit -modifies-> entity. A graph query over typed provenance edges, not a statistical mine; ordered by overlap strength. Bitemporal: pass valid_at for 'which work co-occurred as of <date>'. (read-only)
- `quipu_overlay_create`: Register an overlay-class named graph bound (bind-once) to a committed parent branch. Overlays are scratch layers over the committed graph: write hypotheses into an overlay, read the composed view, and the committed layer stays untouched.
- `quipu_overlay_write`: Write one overlay primitive: assert, retract, or tombstone a triple in an overlay graph. Tombstone masks the parent branch's fact in the composed view without touching the committed layer.
- `quipu_overlay_compose`: Resolve an overlay's composed view over [overlay > parent-branch-root]: asserted-and-not-tombstoned, nearest wins. Read-only. (read-only)
- `quipu_load_ontology`: Manage OWL ontologies: load (parse + materialize entailments), list, or remove. Loaded ontologies enforce class hierarchy, disjoint-class constraints, and property characteristics (inverse, symmetric, functional).
- `quipu_explain`: Walk a fact's derivation chain: a base fact answers with its transaction and source; a reasoner:<rule-id> fact answers with the rule and the premises it currently re-matches; an owl:materialize fact answers with every axiom family that currently re-derives it, premises recursed to base facts. Read-only. (read-only)

## FAQ

### What makes Quipu 'governed'?

Quipu is governed because it allows you to check incoming knowledge against your specific vocabulary and SHACL shapes.

### Does Quipu support historical queries?

Yes, it is bitemporal, meaning it keeps a queryable history of facts and decisions, allowing you to see what was true at a specific time.

### Can I perform searches on the knowledge store?

Yes, fresh stores support keyword search by default, and you can also use semantic search if an embedding provider and model are configured.
