neo4j-agent-memory TCK

May 7, 2026 · View on GitHub

neo4j-labs License Python 3.10+ TypeScript Go 1.21+ .NET 8 R 4.1+

Technology Compatibility Kit for neo4j-agent-memory implementations.

The TCK provides a formal behavioral specification, 189 executable test scenarios, and a compliance framework that enables any implementation — in any language — to verify conformance with the neo4j-agent-memory data model. It also ships TypeScript, Go, C#, R, and Python client libraries with framework integrations and a multi-agent reference demo.

Neo4j Labs Project — This project is maintained by Neo4j Labs as an experimental, community-supported project. It is not officially supported by Neo4j. For community support, use GitHub Issues.

multi agent neo4j agent memory demo app screenshot

Two Endpoint Families

Every client speaks two transports behind one MemoryClient API:

TransportEndpoint shapeUsed for
RestTransporthttps://memory.neo4jlabs.com/v1The hosted Neo4j Agent Memory Service — production deployments
BridgeTransporthttp://localhost:3001 (or any /{snake_case_method} server)TCK conformance servers and the local reference adapter

Selection is automatic based on the endpoint shape (any /v1 segment routes through REST). Override with transport: "rest" | "bridge" (TS), WithTransportMode(...) (Go), Transport = TransportMode.Rest (C#), or transport_mode = "rest" (R / Python).

Repository Contents

agent-memory-tck/
  tck/                  Python TCK specification + 189 test scenarios
  clients/typescript/   @neo4j-labs/agent-memory npm package
  clients/go/           agent-memory-go module
  clients/csharp/       Neo4j.AgentMemory .NET package
  clients/rlang/        neo4j.memory R package (httr2 + R6)
  clients/python/       neo4j-agent-memory-client Python package (httpx + asyncio)
  demo/                 6-agent polyglot demo (Python, TypeScript, Go, C#, R)
  docs/                 AsciiDoc documentation (Diataxis framework)
  SPEC.md               Normative specification (v1.0.0 + Volume 5)
ComponentDescription
TCK Specification189 test scenarios across 4 compliance tiers, backed by SPEC.md
Scenario Registry189 stable scenario IDs (SCN-B-001…SCN-G-018, SCN-P-001…SCN-P-011) with SPEC clause traceability
HTTP BridgeCross-language conformance protocol — Python test suite validates TS, Go, C#, R, Python (or any) client
TypeScript Client@neo4j-labs/agent-memory — MemoryClient, dual transport, Vercel AI middleware, LangChain JS, Mastra, 12-tool MCP
Go Clientmemory package — context-aware API, functional options, generic Entity[T], dual transport, MCP handler
C# ClientNeo4j.AgentMemory .NET 8 — async/await, dual transport, Semantic Kernel connector, MCP dispatcher
R Clientneo4j.memory — R6 classes, httr2 transport, ellmer integration, plumber conformance server
Python Clientneo4j-agent-memory-client — async, dual transport, LangGraph + PydanticAI integrations
Multi-Agent DemoLenny (Python/PydanticAI), Scout (TS/Vercel AI), Forge (Go), Atlas (Python/LangGraph), Sage (C#/Semantic Kernel), Rune (R/ellmer)
DocumentationAsciiDoc following the Diataxis framework — tutorials, how-to, reference, explanation

Compliance Tiers

TierScenariosScope
Bronze93Schema compliance + short-term (conversational) memory
Silver67Bronze + long-term (entity/preference/fact) + reasoning (trace/step/tool call)
Gold18Silver + cross-memory + multi-agent sharing semantics
Platinum11Gold + Volume 5 / hosted-service operations (3-tier context, observations, reflections, feedback, history, graph view, provenance, Cypher)

Quick Start (Hosted Service)

The fastest path is against the hosted service at https://memory.neo4jlabs.com/v1. Get an API key from the NAMS dashboard, then:

# Sanity-check the token
curl -H "Authorization: Bearer $MEMORY_API_KEY" \
  https://memory.neo4jlabs.com/v1/conversations

// TypeScript
import { MemoryClient } from "@neo4j-labs/agent-memory";

const client = new MemoryClient({
  endpoint: "https://memory.neo4jlabs.com/v1",
  apiKey: process.env.MEMORY_API_KEY,
});

const conv = await client.shortTerm.createConversation({ userId: "alice" });
await client.shortTerm.addMessage(conv.id, "user", "Alice works at Acme Corp.");
const ctx = await client.shortTerm.getContext(conv.id);   // 3-tier context

See the full hosted-service quickstart for Python, Go, C#, and R variants.

Quick Start (TCK / Self-Hosted)

Install the TCK

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

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

Write an Adapter

Implement the BaseAdapter interface for your memory system:

from tck.adapters.base_adapter import BaseAdapter, TCKMessage

class MyAdapter(BaseAdapter):
    async def setup(self) -> None: ...
    async def teardown(self) -> None: ...
    async def clear_all_data(self) -> None: ...

    async def add_message(self, session_id, role, content, *, metadata=None) -> TCKMessage:
        ...

    # ... implement remaining methods for your target tier (Platinum is opt-in)

Register and Run

# conftest.py
import pytest

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

# Run Bronze tier (93 scenarios)
uv run pytest -m bronze -v

# Run all 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

# Generate compliance report
uv run pytest --json-report --json-report-file=results.json
uv run tck results.json --name "My Implementation" -o report.json --html report.html

Cross-Language Testing

Test any language client via the HTTP bridge protocol:

# Start a conformance server (TypeScript example)
cd clients/typescript
MEMORY_ENDPOINT=https://memory.neo4jlabs.com/v1 \
  MEMORY_API_KEY=nams_... \
  npm run conformance:server

# Run the Python TCK against it
uv run pytest -m bronze --bridge-url http://localhost:3001 -v

TypeScript Client

import { MemoryClient } from "@neo4j-labs/agent-memory";

const client = new MemoryClient({
  endpoint: "https://memory.neo4jlabs.com/v1",
  apiKey: process.env.MEMORY_API_KEY,
});
await client.connect();

// Short-term memory
await client.shortTerm.addMessage(conv.id, "user", "Hello!");

// Long-term — full hosted operations
const graph = await client.longTerm.getEntityGraph();
const history = await client.longTerm.getEntityHistory(entityId);

// Reasoning provenance (Volume 5)
const provenance = await client.reasoning.getEntityProvenance(entityId);

Includes Vercel AI middleware, LangChain JS, Mastra, and the 12-tool MCP surface. See the TypeScript README.

Go Client

client, _ := memory.New(
    memory.WithEndpoint("https://memory.neo4jlabs.com/v1"),
    memory.WithAPIKey(os.Getenv("MEMORY_API_KEY")),
)
defer client.Close(ctx)

conv, _ := client.ShortTerm.CreateConversation(ctx, memory.CreateConversationParams{
    UserID: "alice",
})
ctxView, _ := client.ShortTerm.GetContext(ctx, conv.ID)
graph, _ := client.LongTerm.GetEntityGraph(ctx)

Includes the 12-tool MCP handler. See the Go README.

C# Client

await using var client = new MemoryClient(new MemoryClientOptions {
    Endpoint = "https://memory.neo4jlabs.com/v1",
    ApiKey = Environment.GetEnvironmentVariable("MEMORY_API_KEY"),
});
await client.ConnectAsync();

var conv = await client.ShortTerm.CreateConversationAsync("alice");
await client.LongTerm.SetEntityFeedbackAsync(entityId, userScore: 0.95, confirmed: true);
var graph = await client.LongTerm.GetEntityGraphAsync();

Includes Semantic Kernel and MCP dispatcher. See the C# README.

R Client

library(neo4j.memory)

client <- MemoryClient$new(
  endpoint = "https://memory.neo4jlabs.com/v1",
  api_key = Sys.getenv("MEMORY_API_KEY")
)

conv <- client$short_term$create_conversation(user_id = "alice")
ctx <- client$short_term$get_context(conv$id)
graph <- client$long_term$get_entity_graph()

Includes ellmer integration and an MCP dispatcher. See the R README.

Python Client

import asyncio
from neo4j_agent_memory_client import MemoryClient

async def main():
    async with MemoryClient(
        endpoint="https://memory.neo4jlabs.com/v1",
        api_key="nams_...",
    ) as client:
        conv = await client.short_term.create_conversation(user_id="alice")
        ctx = await client.short_term.get_context(conv.id)
        prov = await client.reasoning.get_entity_provenance(entity_id)

asyncio.run(main())

Distinct from the neo4j-agent-memory PyPI package (which is the reference adapter used by the TCK). Includes LangGraph and PydanticAI integrations. See the Python README.

Framework Integrations

FrameworkLanguageModule
Vercel AI SDKTypeScript@neo4j-labs/agent-memory/middleware/vercel-ai
LangChain JSTypeScript@neo4j-labs/agent-memory/integrations/langchain
MastraTypeScript@neo4j-labs/agent-memory/integrations/mastra
LangGraphPythonneo4j_agent_memory_client.integrations.langgraph
PydanticAIPythonneo4j_agent_memory_client.integrations.pydantic_ai
Semantic KernelC#Neo4j.AgentMemory.Integrations.SemanticKernel
ellmerRregister_memory_tools()
MCPAllhttps://memory.neo4jlabs.com/mcp (12 tools) — also exposable via each client's mcp module

See the framework-integrations how-to for end-to-end examples.

Multi-Agent Demo

Six agents in five languages sharing one memory graph — locally or against the hosted service:

AgentLanguageFrameworkRole
LennyPythonPydanticAIPodcast research, primary entity builder
ScoutTypeScriptVercel AI SDKWeb search, graph enrichment
ForgeGoCustom HTTPData pipeline, property enrichment
AtlasPythonLangGraphOrchestrator, cross-agent synthesis
SageC#Semantic KernelKnowledge validation, conflict detection
RuneRellmerStatistical analysis, analytical reasoning
# Local mode (dockerized Neo4j)
cd demo/infra
docker compose up

# Hosted mode (no local Neo4j)
MEMORY_API_KEY=nams_... docker compose \
    -f docker-compose.yml -f compose.hosted.yml up

Dashboard: http://localhost:3000.

Documentation

Documentation is written in AsciiDoc following the Diataxis framework:

cd docs
make html         # Build HTML docs (requires asciidoctor)
make install-deps # Install asciidoctor if needed
SectionContents
TutorialsGetting Started, Hosted-Service Quickstart, First TypeScript Agent
How-ToAuthenticate, Framework Integrations, Writing an Adapter, Cross-Language Testing, CI Integration, Certification
ReferenceREST API, MCP Tools, BaseAdapter, Bridge Protocol, Compliance Tiers, Scenario Registry
ExplanationArchitecture, Memory Model, Multi-Agent Sharing

Certification Badges

Implementations that pass the TCK can display the appropriate badge:

![Bronze Certified](https://img.shields.io/badge/agent--memory--tck-Bronze-F97316?logo=neo4j)
![Silver Certified](https://img.shields.io/badge/agent--memory--tck-Silver-22C55E?logo=neo4j)
![Gold Certified](https://img.shields.io/badge/agent--memory--tck-Gold-6366F1?logo=neo4j)
![Platinum Certified](https://img.shields.io/badge/agent--memory--tck-Platinum-9333EA?logo=neo4j)

Contributing

See CONTRIBUTING.md for development setup, coding standards, and contribution guidelines.

Roadmap

See ROADMAP.md for implementation status, gap analysis, and future plans.

License

Apache 2.0 — See LICENSE.