Quipu agent primer
What Quipu is
Quipu is a knowledge graph for agents: RDF facts in one SQLite file, queried with SPARQL.
Writes are checked against SHACL shapes, so the graph refuses data its vocabulary does not allow.
Every fact keeps its transaction and valid time, so you can ask what was true at any point.
ROOT is the default graph; named graphs hold scoped knowledge and are selected explicitly.
quipu (alias qp) works on a local store; quipu mcp and quipu-server serve the same tools to agents.
Query first
- Before you act on an entity, ask the graph what it already knows:
quipu search, thenquipu read. - Prefer stored queries (
quipu_ask) over hand-written SPARQL when one fits. - Declare every PREFIX; the endpoint declares none for you.
- Name the dataset: ROOT unless you pass a graph (
FROM,FROM NAMED, or thegraphfield). - Treat an empty or failed answer as unknown, not as proof of absence.
- Write only facts you can source, through a validated path (
knot,episode), never by editing the file.
Core commands
| Command | Use |
|---|---|
quipu prime | Print this primer and a summary of the local store |
quipu read "<sparql>" | Run a SPARQL query (--valid-at, --tx for time travel; alias query) |
quipu search "<text>" | Search automatically with vectors when a provider is ready, keyword otherwise (--mode overrides) |
quipu model install / quipu model backfill | Install the pinned default model explicitly; prepare existing ROOT subjects in bounded batches |
quipu cord --type <IRI> | List entities, optionally of one type |
quipu impact <IRI> | Walk what depends on an entity (--remove for a what-if) |
quipu unravel --valid-at <date> | See the graph as it was at a point in time |
quipu explain <s> <p> <o> | Trace a derived fact back to its premises |
quipu knot <file.ttl> | Assert Turtle facts, validated against loaded shapes (alias load) |
quipu episode <file.json> | Ingest a structured episode of nodes and edges |
quipu retract <IRI> | Retract an entity’s facts (history is kept) |
quipu validate --shapes <s> --data <d> | Check data against shapes without writing |
quipu shapes list | Show the SHACL shapes that guard writes |
quipu graph list | List registered named graphs |
quipu stats / quipu doctor labels / quipu doctor search | Store statistics, graph-label drift, and search readiness |
quipu store status | Inspect native ownership; explicit store adopt / store restore mint a new epoch, while ordinary legacy opens remain INACTIVE |
quipu export | Export RDF from ROOT or one graph |
quipu databook export / import | One graph as a DataBook (Markdown + YAML + Turtle), and back; import never runs its queries |
quipu memory read <owner.json> | Read versioned file memory (export, commit for the rest; off unless configured) |
quipu competency lint <pendant> | Check contract schema and query/command syntax offline; execute nothing |
quipu share / quipu import | Hand a graph to another store and verify one in |
quipu mcp | Serve the MCP tools over stdio |
Run quipu help <command> for the exact syntax of any command.
MCP tools
| Tool | Use |
|---|---|
quipu_search | Semantic, keyword or hybrid search for entities |
quipu_context | Entities and facts around a natural-language question |
quipu_query | SPARQL SELECT, with valid_at / tx time travel |
quipu_ask | Run a stored, parameterized query by name (no name lists them) |
quipu_cord | List entities by type or predicate |
quipu_impact | Downstream walk from an entity, optionally counterfactual |
quipu_unravel | Facts as they were at a point in time |
quipu_entity | One exact IRI as JSON-LD |
quipu_explain | Trace a derived fact back to its premises |
quipu_export | RDF from ROOT, one graph, a provenance group or a CONSTRUCT |
quipu_resolve_entity | Check for near-duplicate entities before writing |
quipu_shapes | Inspect the loaded shapes and class vocabulary |
quipu_validate | Validate RDF against shapes without writing |
quipu_knot | Assert Turtle facts with SHACL validation |
quipu_episode | Ingest an episode of nodes and edges |
quipu_set | Set an entity’s predicate to exactly one value |
quipu_retract | Retract facts for an entity |
quipu_retract_episode | Retract everything one episode contributed |
quipu_graph_create | Register a named graph before writing to it |
quipu_graph_list | List named graphs |
quipu_list_proposals | List schema change proposals and their status |
quipu_stats / quipu_health | Serving store statistics and liveness |
Writing safely
- Check
quipu_resolve_entity(or search) first, so you extend an entity instead of duplicating it. - Use types and predicates the loaded shapes define; a refusal names the violated shape.
- Give writes a timestamp and a source you can point back to.
- Schema changes go through proposals (
quipu propose submit,quipu_propose_schema_change), not direct shape edits.
Reconciling a failed merge
A share merge, fork promotion or Git pendant merge that hits a conflict writes nothing and holds the slot. Finish all three the same way:
- Emit decisions with proposals:
quipu merge <share-dir> --emit-decisions f.json --propose,quipu fork promote <name> --emit-decisions f.json --propose, orquipu git-merge <ref>(writes<pendant>/decisions.json). MCP:quipu_merge_decisionswithproposeandpresent. - Show the user
quipu merge show f.json --format md(MCP: thepresentationfield) as printed; do not paraphrase it. - Record each choice:
quipu merge resolve f.json <row> --choose ours|theirs|base|both|value|defer --by <who>(MCP:quipu_merge_resolve). - Apply with
--decisions f.json --reviewer <who>,--dry-runfirst, on the samequipu mergeorquipu fork promotecommand (MCP:quipu_merge_apply); for Git,git addthe pendant and commit. Re-applying reportsalready-appliedand writes nothing.
Decide a row yourself only when every side was written by agents and you take the suggested choice; record your agent id with --by and say so.
Otherwise ask the user once, for all rows, with the numbered choices: always when a person wrote either side or you cannot tell, for value and both, and for sh:maxCount conflicts on human-owned data.
If apply says the decisions are stale, emit again; never edit the file’s hashes.
Next steps
- Wire Quipu into your agent: https://intigraph.github.io/quipu/getting-started/agent-setup.html
- Full CLI reference: https://intigraph.github.io/quipu/reference/cli.html
- MCP tool reference: https://intigraph.github.io/quipu/reference/mcp-tools.html
- Reconciling a failed merge: https://intigraph.github.io/quipu/sharing/reconcile.html
The command above prints the same text, followed by a bounded, read-only
summary of the local store (named graphs, shapes, ontologies and the last
transaction). quipu prime --brief prints five to ten lines: version and job,
key live counts or a store diagnosis, then the command for the full primer.
--brief --static condenses the What section without opening a store.
quipu prime --section <name> prints one section.
--json follows the shared stack-prime/1 contract: tool, version,
primer.sections and primer.text, live.{status,elapsed_ms,summary}, and
an overall status. --brief --json omits primer.text; store fields such as
last_tx, graphs, shapes, ontologies and path are under live.summary.
This replaces the earlier {primer: string, store: object} output.
--static reports live.status: skipped with an empty summary. An absent,
unreadable or partial store degrades overall status while prime still exits 0;
ok and skipped yield overall ok. Bad flags or sections exit 2.
To register Quipu with a client, see Agent Setup.