Vercel AI SDK Integration — Phase 1: Python HTTP API

[johnymontana]

Overview

This is the first phase of a three-layer integration that will bridge neo4j-agent-memory (Python) with the Vercel AI SDK ecosystem (TypeScript). The full architecture:

1. Layer 1: Python HTTP API (this PR) — FastAPI server exposing MemoryClient over REST
2. Layer 2: TypeScript HTTP Client (@neo4j-labs/agent-memory-client) — auto-generated from OpenAPI spec
3. Layer 3: Vercel AI SDK Integration (@neo4j-labs/ai-sdk-memory) — implements Vercel AI SDK memory provider interface

This PR implements Layer 1: a new neo4j-agent-memory[server] optional module that wraps the entire MemoryClient API in a production-ready FastAPI server with auto-generated OpenAPI 3.1 spec, API key authentication, and CORS support.

What's Included

New server module (src/neo4j_agent_memory/server/) with 25 REST endpoints covering all three memory layers:

• Context — POST /api/v1/context returns both formatted context text and structured data (messages, entities, preferences, traces) in a single call; POST /api/v1/context/text for plain text; GET /api/v1/stats
• Short-term memory — Full CRUD for sessions and messages, conversation summaries, semantic message search
• Long-term memory — Entity management with deduplication results, preference CRUD by category, relationship creation, semantic search
• Reasoning — Trace lifecycle (start/step/complete), tool call recording, tool usage statistics, semantic trace search

New MemoryClient.get_context_structured() method — The existing get_context() only returns a formatted string. The new method returns a StructuredContext object with both the text and raw domain objects, enabling the critical POST /context endpoint that Layer 2 clients will depend on.

[server] optional dependency group — fastapi, uvicorn[standard], sse-starlette are only required when using the server module. The core library remains dependency-light.

CLI serve command — neo4j-memory serve --port 8000 --api-key <key> starts the server. Uses lazy imports so the server dependencies aren't required for other CLI commands.

API key authentication — Opt-in X-API-Key header middleware, configurable via --api-key flag or ServerConfig.

35 unit tests with mocked MemoryClient covering all endpoints, auth middleware, and request validation.

Key Design Decisions

• Thin API response models with from_domain() classmethods — exclude embedding vectors, serialize UUIDs as strings, separate from domain models
• App-scoped MemoryClient singleton via FastAPI lifespan context manager + Depends(get_memory_client)
• ServerConfig lives in config/settings.py (not server/config.py) to avoid requiring FastAPI as an import for the core config module
• add_entity returns entity + deduplication result since LongTermMemory.add_entity() returns a tuple

Stats

18 files changed, 2097 insertions(+), 1 deletion(-)

How to Test

# Install with server extras
pip install -e ".[server]"

# Start the server (requires Neo4j)
neo4j-memory serve --port 8321

# Health check
curl http://localhost:8321/health

# Browse OpenAPI docs
open http://localhost:8321/docs

# Query context
curl -X POST http://localhost:8321/api/v1/context \
  -H 'Content-Type: application/json' \
  -d '{"query": "test", "session_id": "sess-1"}'

# Run tests (no Neo4j required)
pytest tests/unit/server/

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agent-memory	Ready	Preview, Comment	Feb 9, 2026 5:13pm