Export & Observability

Getting data out of a session, in the format the destination expects — and seeing how the server itself is performing.

`export_knowledge`

Converts a session’s current structure to an external interchange format for use with other tools (Protégé, Neo4j, triple stores).

Parameters: session_id (required), format (optional — one of "json-ld" (default), "turtle", "rdf-xml").

Response: {"format": "json-ld", "data": "<converted document>"}.

`export_session`

Packages a full session bundle for migration or archival — the current structure, the complete version history, and session metadata. This is a different job from export_knowledge: that one converts format, this one preserves everything needed to reconstruct the session elsewhere.

Parameters

Name	Type	Required	Description
`session_id`	string	yes	Session to export.
`format`	string	no	`"bundle"` (default) — full migration envelope with version history. `"cks"` — bare canonical CKS JSON of the current structure only (equivalent to `serialize_knowledge`).
`include_structures`	boolean	no	When `true` and `format="bundle"`, embed the full serialized structure for every historical version (can be large for long-lived sessions). Default `false` — only version metadata (id, timestamp, state hash) is included.

Response (format="bundle")

{
  "format": "bundle",
  "session_id": "sess-abc123",
  "bundle": {
    "cks_mcp_export": true,
    "schema_version": "1.0",
    "session": {"session_id": "...", "parent_session_id": null, "parent_version_id": null, "closed": false, "metadata": {}},
    "current_structure": {"root_hash": "...", "objects_count": 4, "relations_count": 2, "cks_json": "<canonical JSON>"},
    "version_history": {"count": 2, "include_structures": false, "versions": [{"version_id": "v-1", "transaction_id": "tx-1", "created_at": "...", "state_hash": "..."}]}
  },
  "bundle_json": "<the same bundle as a raw JSON string, ready to write to disk>"
}

A bundle can be reimported elsewhere by feeding its cks_json (or a version’s cks_json, if include_structures was set) into validate_knowledge.

`get_metrics`

Returns two independent dashboards: runtime-level operation metrics from cks-runtime, and per-tool call telemetry collected by cks-mcp itself.

Parameters: none.

Response

{
  "runtime_metrics": {
    "operation_counts": {"validate": 12, "evolve": 5},
    "average_execution_times": {"validate": 0.004, "evolve": 0.011}
  },
  "tool_telemetry": {
    "validate_knowledge": {"calls": 12, "success_rate": 1.0, "p50_ms": 3.1, "p95_ms": 9.8, "p99_ms": 14.2, "top_errors": []},
    "evolve_knowledge": {"calls": 5, "success_rate": 0.8, "p50_ms": 8.0, "p95_ms": 20.1, "p99_ms": 22.0, "top_errors": ["invalid_operations"]}
  }
}

tool_telemetry is scoped to the current server process — it resets on restart. Use it to spot which tool is slow or erroring most often across a session, not as a durable audit log (for that, see list_versions and export_session).

`register_graph`

Saves a named reference to an existing session’s Knowledge Graph, allowing it to be found and reused later via get_graph.

Parameters: name (required), session_id (required), description (optional), tags (optional, comma-separated), public (optional boolean, default false — opts the graph into the gallery, discoverable by other callers via list_graphs(public_only=true) / search_graphs, not just by name).

Response: {"registered": true, "name": "my-graph", "public": false}.

`get_graph`

Looks up a previously registered graph by name and returns its session_id and metadata, or {"found": false} if no graph is registered under that name.

Parameters: name (required).

Response: {"found": true, "name": "my-graph", "session_id": "...", "description": "...", "tags": "...", "public": false, "lifecycle_state": "draft", "created_at": "...", "updated_at": "..."}.

`update_graph_lifecycle`

Transitions a registered graph’s lifecycle_state – one of draft, published, active, stale, under_review, archived. Only registered graphs have a lifecycle state; a first-time registration defaults to published if public/visibility='public' is set, otherwise draft. Not every transition is allowed:

From	Allowed to
`draft`	`published`, `archived`
`published`	`active`, `under_review`, `archived`
`active`	`stale`, `under_review`, `archived`
`stale`	`under_review`, `active`, `archived`
`under_review`	`active`, `published`, `archived`
`archived`	(none – terminal)

Requesting the state the graph is already in is a no-op (returns {"updated": false, "reason": "already in requested state", ...} rather than an error). Requesting a disallowed transition returns {"error": "invalid_state_transition", "allowed": [...], ...} without changing anything.

Parameters: name (required), state (required, one of the six lifecycle states above).

Response: {"updated": true, "name": "my-graph", "previous_state": "draft", "new_state": "published"}.

`list_graphs`

Lists every registered graph, most recently updated first. Optionally filter to graphs whose tags contain a given substring, and/or restrict to public graphs only (the gallery).

Parameters: tag (optional), public_only (optional boolean, default false).

Response: {"graphs": [{"name": "my-graph", "session_id": "...", "public": false, ...}, ...]}.

`search_graphs`

Free-text search over registered graphs, matched case-insensitively against each graph’s name, description, and tags. Use this to discover a graph to resume with get_graph when you don’t already know its exact name.

Parameters: query (required), tag (optional, further narrows by exact/substring tag), public_only (optional boolean, default false).

Response: {"graphs": [{"name": "my-graph", "session_id": "...", ...}, ...]}.

`check_graph_freshness`

Read-only check of whether a registered graph is still fresh, using the same TTL GraphFreshnessSweeper (cks-runtime) applies in the background (graph_freshness_ttl_seconds in RuntimeConfig, default 7 days). Does not refresh the graph itself — a stale graph is left for a future update agent to act on (cks-runtime enqueues a graph_outdated outbox task for it independently, on the same TTL).

Parameters: name (required).

Response: {"fresh": true} when within the TTL, or {"fresh": false, "last_updated": "...", "ttl_days": 7.0} when outdated. {"found": false} if no graph is registered under that name.

`check_graph_health`

Computes an aggregate health score (0.0–1.0) for a registered graph by combining five read-only checks into one weighted metric: version freshness (weight 0.3), TTL freshness (weight 0.1), contradictions (weight 0.3), verification coverage (weight 0.2), and dead‑lettered conflict tasks (weight 0.1). Read-only — does not modify the graph.

Parameters: name (required — registered graph name).

Response: {"name": "cks-ecosystem", "session_id": "...", "health_score": 0.85, "metrics": {...}, "timestamp": "..."}.

`explain_graph`

Generates a human-readable Markdown report for any registered graph, grouping entities by type (Component, Module, Sweeper, Agent, Tool, ADR, Plugin) and showing their relations. Makes knowledge graphs accessible to any LLM or person without parsing raw JSON.

Parameters: name (required — registered graph name).

Response: {"found": true, "name": "cks-ecosystem", "session_id": "...", "report": "<markdown text>"}.

`compare_graphs`

Read-only diff of two graphs (registered or bare sessions): which objects/relations they share by identity id, which are unique to each side, and structural differences between shared objects.

Parameters: graph_a_name / graph_a_session_id (one required for side A — session id takes precedence), graph_b_name / graph_b_session_id (one required for side B), include_relations (optional boolean, default true).

Response: {"graph_a": "...", "graph_b": "...", "shared_object_count": 5, "only_in_a_count": 3, "only_in_b_count": 2, "shared_object_ids": [...], "only_in_a": [...], "only_in_b": [...], "differences": [{"id": "obj-1", "action": "modified", "type": "...", "name": "...", "changes": {"field": {"from": ..., "to": ...}}}, ...]} — differences only lists shared objects whose structure actually diverges.

`merge_graphs`

Three-way merges two graphs into a new session using KnowledgeStructure.merge(), the same primitive merge_knowledge uses. Neither source session is modified. Without a base_graph_name/base_session_id, the merge base is an empty structure — every object present in both sides will surface as a conflict candidate unless a resolutions mapping resolves it.

Parameters: graph_a_name / graph_a_session_id (side A), graph_b_name / graph_b_session_id (side B), base_graph_name / base_session_id (optional common ancestor), resolutions (optional per-object resolution mapping, same shape as merge_knowledge), register_as (optional name to register the merged result under).

Response on success: {"merged": true, "session_id": "...", "version_id": "...", "registered_as": "..."}. Response on conflict: {"merged": false, "conflicts": [...]} — no new session is created.

`link_graphs`

Creates a relation between an object in graph A and an object in graph B, writing it to both source sessions so the link is discoverable from either graph. Because a relation’s participants must exist in the same structure, a copy of each remote participant is added alongside the relation on the side it’s missing from (skipped if already present, e.g. from a prior link between the same graphs).

Parameters: graph_a_name / graph_a_session_id, graph_b_name / graph_b_session_id, object_a_id (required), object_b_id (required), relation_type (required), relation_name (optional).

Response: {"linked": true, "relation_id": "cross-link:<a>:<objA>:<b>:<objB>:<type>", "graph_a_version": "...", "graph_b_version": "..."}. Errors: object_not_found, relation_already_exists (the derived id is deterministic, so re-linking the same pair/type is a no-op error), duplicate_object_conflict (an id collision with different content), or partial_failure: true if graph A’s write committed but graph B’s did not (the id scheme makes a retry idempotent on the already-written side).

`export_storage`

Exports a complete dump of all sessions, versions, graph registry entries, embeddings, and pending/failed outbox tasks to a JSON file. Returns the file path and a summary of what was exported. This is the foundation for backup and migration workflows (ADR-012).

Parameters: output_path (optional — path for the dump file; defaults to a temp file).

Response: {"output_path": "...", "summary": {"sessions": N, "versions": N, "graphs": N, "embeddings": N, "outbox": N}}.

`import_storage`

Restores data from a previously exported dump file into the current storage backend. Supports two modes:

clear — deletes all existing data before importing.
merge — adds/updates data alongside existing records (default).

Parameters: file_path (required), mode (optional, "merge" by default).

Response: {"imported": true, "mode": "merge", "summary": {...}}.

`migrate_storage`

Transfers all data from the current storage backend to a new backend of a different type (e.g. SQLite → Postgres). Exports from the current backend, creates a new target backend, and imports the data. Returns the path or DSN of the new storage. Does not replace the active runtime.storage — the caller must restart the server pointing at the new backend.

Parameters: target_backend (required, "sqlite" or "postgres"), target_path (required — file path for SQLite, connection string for Postgres).

Response: {"migrated": true, "target_backend": "sqlite", "target_path": "...", "summary": {...}}.