This tutorial walks you through installing the TCK, writing a minimal adapter, and running the test suite for the first time.

Tip
 If you only want to use the hosted service from your application (not run the conformance suite against your own backend), start with the Hosted-Service Quickstart instead.

Prerequisites

  • Python 3.10 or later

  • uv package manager (recommended) or pip

  • A running Neo4j instance (local or Aura) or a nams_* API key for the hosted service at https://memory.neo4jlabs.com/v1

Step 1: Install the TCK

# Using uv (recommended)
uv add neo4j-agent-memory-tck

# Or with pip
pip install neo4j-agent-memory-tck

For development, install with extras:

uv sync --extra dev        # Includes ruff, mypy
uv sync --extra reference  # Includes neo4j-agent-memory Python package
uv sync --extra bridge     # Includes httpx, aiohttp for HTTP bridge

Step 2: Understand the Adapter Pattern

The TCK tests your implementation through an adapter — a class that bridges the TCK’s abstract interface to your concrete implementation.

from tck.adapters.base_adapter import BaseAdapter, TCKMessage

class MyAdapter(BaseAdapter):
    """Maps TCK operations to your memory implementation."""

    async def setup(self) -> None:
        # Connect to your backend
        pass

    async def teardown(self) -> None:
        # Close connections
        pass

    async def clear_all_data(self) -> None:
        # Delete all data (called before each test)
        pass

    async def add_message(self, session_id, role, content, *, metadata=None) -> TCKMessage:
        # Store a message and return a TCKMessage
        pass

    # ... implement remaining methods for your target tier

Step 3: Register Your Adapter

Create a conftest.py file that provides the adapter to the test suite:

# my_project/tests/conftest.py
import pytest
from my_project.adapter import MyAdapter

@pytest.fixture(scope="session")
async def adapter():
    adapter = MyAdapter(uri="bolt://localhost:7687")
    await adapter.setup()
    yield adapter
    await adapter.teardown()

Step 4: Run the Tests

# Run Bronze tier tests (schema + short-term memory) — 93 scenarios
uv run pytest -m bronze -v

# Run the required tiers (Bronze + Silver + Gold) — 178 scenarios
uv run pytest -m "bronze or silver or gold" -v

# Run Platinum (hosted-service operations) — 11 scenarios, opt-in
uv run pytest -m platinum -v

# See what tests would run without executing
uv run pytest --collect-only -m bronze -q

If no adapter is configured, all tests skip with:

SKIPPED: No adapter configured. Provide an 'adapter' fixture...

Step 5: Generate a Compliance Report

# Run tests with JSON output
uv run pytest --json-report --json-report-file=results.json -v

# Generate the compliance report
uv run tck results.json \
  --name "My Implementation" \
  --version "1.0.0" \
  --output report.json \
  --html report.html

Open report.html in your browser to see a tier-by-tier pass/fail breakdown.

Next Steps