z3rno-mcp

Overview

z3rno-mcp is a Model Context Protocol server that wraps the Python SDK and surfaces it over stdio. Drop it into Claude Desktop, Cursor, Claude Code, or any MCP-compatible runtime and the agent inherits persistent memory, an immutable audit log, knowledge-graph extraction, and turn-aware conversation memory — without any code on your side.

For a step-by-step install + walkthrough optimized for Claude Desktop, see Integrations → Anthropic MCP. This page is the reference: every tool, every parameter, every env var.

Current version: z3rno-mcp 0.6.1 (pins z3rno SDK >=0.7.0).

Tools

Twelve tools, grouped by what they touch.

Memory primitives

`z3rno.store`

Persist a memory. Returns the stored memory and its id.

{
  "content": "User prefers dark mode and Python",
  "agent_id": "claude-desktop",
  "memory_type": "episodic",
  "user_id": "user_abc",
  "metadata": { "source": "preferences-survey" },
  "importance": 0.8,
  "ttl_seconds": 86400
}

Field	Type	Default	Notes
`content`	string	required	The fact / preference / decision to persist.
`agent_id`	string	from `Z3RNO_AGENT_ID`	Falls back to the env var when unset; errors if neither is set.
`memory_type`	string	`"episodic"`	One of `episodic`, `semantic`, `procedural`, `working`.
`user_id`	string	—	Optional end-user identifier for multi-user agents.
`metadata`	object	—	Arbitrary JSON; useful for `{ "conversation_id": "...", "role": "user" }`.
`importance`	float	—	0.0–1.0; influences the importance-decay lifecycle.
`ttl_seconds`	int	—	Optional time-to-live; omitted = no expiry.

`z3rno.recall`

Semantic search. Defaults to the AUTO strategy router which picks VECTOR, GRAPH, LEXICAL, TEMPORAL, TRACE, TRIPLET, CYPHER, or CODE per query.

{
  "query": "What are the user's UI preferences?",
  "agent_id": "claude-desktop",
  "memory_type": "semantic",
  "top_k": 5,
  "similarity_threshold": 0.7,
  "filters": { "metadata": { "source": "preferences-survey" } }
}

Field	Type	Default	Notes
`query`	string	required	Free-text query.
`agent_id`	string	from env	Falls back to `Z3RNO_AGENT_ID`.
`memory_type`	string	—	Optional filter.
`top_k`	int	`10`	Result count.
`similarity_threshold`	float	`0.0`	Drops results below this cosine score.
`filters`	object	—	Server-side WHERE-clause kwargs (e.g. `metadata`, `dataset_id`).

`z3rno.forget`

Soft-delete (default) or hard-delete one or more memories. Hard delete emits a Merkle-rooted, ed25519-signed certificate to forget_certificates for GDPR right-to-erasure compliance.

{
  "memory_id": "550e8400-e29b-41d4-a716-446655440000",
  "hard_delete": true,
  "cascade": false,
  "reason": "User requested data erasure"
}

Field	Type	Default	Notes
`memory_id`	string	—	Single-id form.
`memory_ids`	array	—	Batch form. Exactly one of `memory_id` / `memory_ids` is required.
`agent_id`	string	from env	Scopes the delete.
`hard_delete`	bool	`false`	`true` = irrecoverable; emits a forget certificate.
`cascade`	bool	`false`	Also forget Memos extracted from this memory by the Forge.
`reason`	string	—	Logged on the audit row.

`z3rno.audit`

Paginated read over the hash-chained audit log.

{
  "agent_id": "claude-desktop",
  "operation": "store",
  "page": 1,
  "page_size": 50
}

Field	Type	Default
`agent_id`	string	from env
`operation`	string	— (returns all ops if unset)
`memory_id`	string	—
`page`	int	`1`
`page_size`	int	`50`

Forge (knowledge graph)

`z3rno.ingest`

Push raw text or a URL into the Forge. Returns a job_id; when INGEST_AUTO_DISTILL=true (the default), the server chains directly into z3rno.distill.

{ "kind": "text", "text": "..." }
{ "kind": "url",  "url":  "https://example.com/article" }

Field	Type	Notes
`kind`	`"text"` \| `"url"`	Required. File uploads aren’t supported via MCP — use the HTTP `/v1/ingest/file` endpoint for those.
`text`	string	Required when `kind="text"`.
`url`	string	Required when `kind="url"`.
`agent_id`	string	from env.
`dataset_id`	string	Optional dataset to scope the ingest into.

`z3rno.distill`

Build or extend the knowledge graph from stored memories. Runs the Forge pipeline (chunk → LLM entity + relationship extraction → write Memo nodes + edges) and returns a job_id. Poll status with poll_job_id. Idempotent.

// kick off
{ "memory_ids": ["m1", "m2"], "agent_id": "claude-desktop" }

// poll
{ "poll_job_id": "job_xyz" }

`z3rno.refine`

Improve the graph in place: dedupe Memos sharing an ontology URI or normalized name (SCD-2 supersede), EMA-blend edge weights from accumulated feedback, prune sub-threshold edges. Optional LLM stages (infer / summarize) are server-side flags. Admin-scoped.

{ "dataset_id": "ds_abc" }
{ "poll_job_id": "job_xyz" }

`z3rno.visualize_url`

Return a URL to the Z3rno graph viewer for a dataset or agent. Use when the user asks “show me the graph”.

{ "dataset_id": "ds_abc", "agent_id": "claude-desktop" }

Returns a string URL of the form ${Z3RNO_WEB_URL}/graph?dataset_id=....

Conversation memory (Phase G)

`z3rno.start_conversation`

Open a new conversation. Returns the conversation_id so subsequent stores can be tagged. Call at the start of a chat to enable turn-aware recall and automatic summarization triggers.

{
  "agent_id": "claude-desktop",
  "user_id": "user_abc",
  "title": "Allergy intake",
  "summary_cadence": 10
}

Field	Type	Default	Notes
`agent_id`	string	from env
`user_id`	string	—
`title`	string	—	Display label for dashboards.
`summary_cadence`	int	`10`	Trigger `needs_summary` flag every N turns.

`z3rno.end_conversation`

Mark a conversation finished. The metadata row is soft-deleted and no further turns can be added; existing turn Memos stay queryable via standard recall.

{ "conversation_id": "conv_abc123" }

`z3rno.summarize_conversation`

Fetch turn history in order so the agent can produce a summary. The agent runs its own summarization; once done, it persists the result via z3rno.store with memory_type='semantic' and metadata={"kind": "summary", "covers_turns": [start, end]}.

{
  "conversation_id": "conv_abc123",
  "after_turn": 0,
  "limit": 50
}

`z3rno.time_travel`

Recall memories as they existed at a past timestamp. Uses Z3rno’s SCD-2 temporal index. Supply an ISO-8601 timestamp.

{
  "as_of": "2026-01-15T12:00:00Z",
  "query": "user allergies",
  "agent_id": "claude-desktop",
  "conversation_id": "conv_abc123",
  "top_k": 10
}

Environment variables

Variable	Required	Default	Notes
`Z3RNO_API_KEY`	yes	—	API key. The dev default on a fresh local server is `z3rno_sk_test_localdev`.
`Z3RNO_BASE_URL`	no	`https://api.z3rno.dev`	Server URL. Override to `http://localhost:8000` for local dev.
`Z3RNO_AGENT_ID`	no	—	Default agent id used when a tool call omits one. Without it, every tool call must pass `agent_id` explicitly.
`Z3RNO_WEB_URL`	no	`https://app.z3rno.dev`	Base URL the `z3rno.visualize_url` tool returns links against.

Install

# Run directly (recommended — no install step, always latest)
uvx z3rno-mcp

# Or install into your environment
pip install 'z3rno-mcp>=0.6.1'

# Or from source
git clone https://github.com/the-ai-project-co/z3rno-mcp
cd z3rno-mcp
uv sync
uv run z3rno-mcp

Host configuration

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "z3rno": {
      "command": "uvx",
      "args": ["z3rno-mcp"],
      "env": {
        "Z3RNO_BASE_URL": "http://localhost:8000",
        "Z3RNO_API_KEY": "z3rno_sk_test_localdev",
        "Z3RNO_AGENT_ID": "claude-desktop"
      }
    }
  }
}

// .cursor/mcp.json (per-workspace) or ~/.cursor/mcp.json (global)
{
  "mcpServers": {
    "z3rno": {
      "command": "uvx",
      "args": ["z3rno-mcp"],
      "env": {
        "Z3RNO_BASE_URL": "http://localhost:8000",
        "Z3RNO_API_KEY": "z3rno_sk_test_localdev",
        "Z3RNO_AGENT_ID": "cursor"
      }
    }
  }
}

// ~/.claude/settings.json
{
  "mcpServers": {
    "z3rno": {
      "command": "uvx",
      "args": ["z3rno-mcp"],
      "env": {
        "Z3RNO_BASE_URL": "http://localhost:8000",
        "Z3RNO_API_KEY": "z3rno_sk_test_localdev",
        "Z3RNO_AGENT_ID": "claude-code"
      }
    }
  }
}

Self-hosted

Point the MCP server at your own Z3rno instance — works identically whether the server runs from docker compose locally or from the Helm chart on a cluster:

export Z3RNO_BASE_URL=http://localhost:8000
export Z3RNO_API_KEY=z3rno_sk_test_localdev
export Z3RNO_AGENT_ID=my-agent
uvx z3rno-mcp

Troubleshooting

Tools don’t appear — uvx not on PATH. Run which uvx; if empty, install uv from astral.sh/uv.
agent_id is required — Set Z3RNO_AGENT_ID in the env block, or pass agent_id on every tool call. No implicit fallback by design.
Connection refused — Verify Z3RNO_BASE_URL is reachable and the server is running (curl $Z3RNO_BASE_URL/v1/health).
401 Unauthorized — Verify Z3RNO_API_KEY matches the server. Default dev key is z3rno_sk_test_localdev; rotate for production via POST /v1/api-keys.
z3rno.visualize_url returns a 404 — The graph viewer at the returned URL isn’t deployed. Run z3rno-web locally and set Z3RNO_WEB_URL=http://localhost:3000, or wait for the hosted viewer to land at app.z3rno.dev/graph.

Getting Started

Architecture

Components

Core Concepts

SDKs

Integrations

Guides

Self-Hosting

Performance

Support

Overview

Tools

Memory primitives

`z3rno.store`

`z3rno.recall`

`z3rno.forget`

`z3rno.audit`

Forge (knowledge graph)

`z3rno.ingest`

`z3rno.distill`

`z3rno.refine`

`z3rno.visualize_url`

Conversation memory (Phase G)

`z3rno.start_conversation`

`z3rno.end_conversation`

`z3rno.summarize_conversation`

`z3rno.time_travel`

Environment variables

Install

Host configuration

Self-hosted

Troubleshooting

​Overview

​Tools

​Memory primitives

​z3rno.store

​z3rno.recall

​z3rno.forget

​z3rno.audit

​Forge (knowledge graph)

​z3rno.ingest

​z3rno.distill

​z3rno.refine

​z3rno.visualize_url

​Conversation memory (Phase G)

​z3rno.start_conversation

​z3rno.end_conversation

​z3rno.summarize_conversation

​z3rno.time_travel

​Environment variables

​Install

​Host configuration

​Self-hosted

​Troubleshooting

Overview

Tools

Memory primitives

`z3rno.store`

`z3rno.recall`

`z3rno.forget`

`z3rno.audit`

Forge (knowledge graph)

`z3rno.ingest`

`z3rno.distill`

`z3rno.refine`

`z3rno.visualize_url`

Conversation memory (Phase G)

`z3rno.start_conversation`

`z3rno.end_conversation`

`z3rno.summarize_conversation`

`z3rno.time_travel`

Environment variables

Install

Host configuration

Self-hosted

Troubleshooting