Quickstart

Install the SDK, run a Z3rno server locally, and store + recall your first memory in under five minutes.

Quickstart

This page walks you from zero to a working store → recall round-trip — first against a local Docker stack, then optionally with a conversation scope and an MCP host wired in.

Already running a Z3rno server? Skip to step 3.

1. Install the SDK

Python

pip install z3rno

Both SDKs ship every server verb (store / recall / forget / audit / ingest / distill / refine) plus Phase G conversation memory and tenant self-management. See Python SDK / TypeScript SDK for the full method reference.

2. Run a Z3rno server locally

The fastest path is the bundled docker-compose.dev.yml — it spins up Postgres (with pgvector + Apache AGE + pg_cron pre-compiled), Valkey, and the server in one command.

git clone https://github.com/the-ai-project-co/z3rno-server
cd z3rno-server
docker compose -f docker-compose.dev.yml up
# Server at http://localhost:8000 — dev API key: z3rno_sk_test_localdev

For Kubernetes deploys, see Self-hosting → Kubernetes and Components → z3rno-helm.

3. Store and recall your first memory

Python

from z3rno import Z3rnoClient

client = Z3rnoClient(
    base_url="http://localhost:8000",
    api_key="z3rno_sk_test_localdev",
)

# Store a memory
memory = client.store(
    agent_id="agent-1",
    content="User prefers dark mode and uses Python.",
    memory_type="semantic",
    importance=0.85,
)
print("stored:", memory.id)

# Recall — defaults to the AUTO strategy router
results = client.recall(
    agent_id="agent-1",
    query="What does the user prefer?",
    top_k=5,
)
for r in results:
    print(r.content, "(relevance:", round(r.relevance_score, 2), ")")

4. Add a conversation (optional)

For multi-turn agents, scope memories to a conversation so recall returns turn-aware context and the summarization cadence triggers automatically.

Python

conv = client.create_conversation(agent_id="agent-1", title="Allergy intake")

client.add_turn(conv.id, role="user",      content="I'm allergic to penicillin")
client.add_turn(conv.id, role="assistant", content="Noted — I'll flag amoxicillin too.")

# Recall scoped to this conversation
scoped = client.recall(agent_id="agent-1", query="allergies", conversation_id=conv.id)

5. Or skip the SDK entirely — use MCP

If you’re using Claude Desktop, Cursor, or Claude Code, point them at the z3rno-mcp server and the agent inherits all twelve tools (z3rno.store, z3rno.recall, z3rno.start_conversation, z3rno.time_travel, …) without any code:

// ~/Library/Application Support/Claude/claude_desktop_config.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-desktop"
      }
    }
  }
}

Restart your host. See Integrations → Anthropic MCP for the full walkthrough.

Next steps

The Z3rno Verbs

Canonical store / recall / forget / audit / ingest / distill / refine reference.

Core Concepts

Four memory types, the lifecycle, and how SCD-2 temporal versioning works.

Framework integrations

LangChain, LlamaIndex, CrewAI, OpenAI Agents, Vercel AI, Mastra, Anthropic MCP.

Self-hosting

Every env var, every gating flag, every opt-in surface.