This directory contains comprehensive examples demonstrating Neo4j Agent Memory's Google Cloud integration features (Vertex AI, ADK, MCP, MemoryIntegration with session strategies).
Diagram source: img/architecture.excalidraw -- open in Excalidraw to edit
| Feature | Script | Description |
|---|---|---|
| Vertex AI Embeddings | vertex_ai_embeddings.py |
Generate embeddings using Google's text-embedding-004 model |
| Google ADK Integration | adk_memory_service.py |
Use Neo4jMemoryService with Google ADK agents |
| MCP Server | mcp_server_demo.py |
Start and interact with the MCP server |
| Complete Pipeline | full_pipeline.py |
End-to-end demo combining all features |
Start a local Neo4j instance or use Neo4j Aura:
# Docker (local)
docker run -d \
--name neo4j \
-p 7474:7474 -p 7687:7687 \
-e NEO4J_AUTH=neo4j/password \
-e NEO4J_PLUGINS='["apoc"]' \
neo4j:5-enterprise# Authenticate with Google Cloud
gcloud auth application-default login
# Set your project
export GOOGLE_CLOUD_PROJECT=your-project-id# Install with all Google Cloud features
pip install neo4j-agent-memory[google,mcp]
# Or for development
cd neo4j-agent-memory
pip install -e ".[google,mcp]"# Copy example and configure
cp .env.example .env
# Required variables:
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=password
# For Vertex AI embeddings:
export GOOGLE_CLOUD_PROJECT=your-project-id
export VERTEX_AI_LOCATION=us-central1python vertex_ai_embeddings.pyThis demonstrates:
- Initializing
VertexAIEmbedderwith text-embedding-004 - Generating embeddings for single texts
- Batch embedding for multiple texts
- Using Vertex AI embeddings with MemoryClient
python adk_memory_service.pyThis demonstrates:
- Creating
Neo4jMemoryServicefor ADK integration - Storing conversation sessions
- Semantic memory search
- Entity and preference extraction
# Start the server
python mcp_server_demo.py
# Or use the CLI
neo4j-agent-memory mcp serve --transport stdioThis demonstrates:
- Starting the MCP server programmatically
- Core (6 tools) and extended (16 tools) profiles
- Tool usage: memory_store_message, memory_search, memory_get_conversation, etc.
- Both stdio and SSE transports
python full_pipeline.pyThis runs all features together in a cohesive demo.
┌─────────────────────────────────────────────────────────────────┐
│ Google Cloud Platform │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌────────────────┐ │
│ │ Google ADK │ │ MCP Client │ │ Your App │ │
│ │ Agent │ │ (Claude) │ │ │ │
│ └───────┬───────┘ └───────┬───────┘ └───────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Neo4j Agent Memory Library │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │Neo4jMemoryService│ │ MCP Server │ │ │
│ │ │ (ADK Interface) │ │ (5 tools) │ │ │
│ │ └────────┬────────┘ └────────┬────────┘ │ │
│ │ │ │ │ │
│ │ ▼ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ MemoryClient │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌───────────────┐ │ │ │
│ │ │ │ Short-Term │ │ Long-Term │ │ Reasoning │ │ │ │
│ │ │ │ Memory │ │ Memory │ │ Memory │ │ │ │
│ │ │ └─────────────┘ └─────────────┘ └───────────────┘ │ │ │
│ │ └────────────────────────┬────────────────────────────┘ │ │
│ └───────────────────────────┼───────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────┼───────────────────────────────┐ │
│ │ ▼ │ │
│ │ ┌─────────────────┐ ┌─────────────────────────────────┐ │ │
│ │ │ Vertex AI │ │ Neo4j Database │ │ │
│ │ │ Embeddings │ │ (Graph + Vector Storage) │ │ │
│ │ │ text-embedding-004│ │ │ │ │
│ │ └─────────────────┘ └─────────────────────────────────┘ │ │
│ │ Storage & AI Layer │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
See deploy/cloudrun/README.md for production deployment instructions.
Quick deploy:
# From the neo4j-agent-memory directory
cd deploy/cloudrun
# Deploy
gcloud run deploy neo4j-memory-mcp \
--source . \
--region us-central1 \
--set-secrets NEO4J_URI=neo4j-uri:latest,NEO4J_PASSWORD=neo4j-password:latestThe MCP server supports two tool profiles:
| Tool | Description | Key Parameters |
|---|---|---|
memory_search |
Semantic search across memory | query, limit, memory_types |
memory_get_context |
Assembled context for a session | session_id, query, max_items |
memory_store_message |
Store a conversation message | content, role, session_id |
memory_add_entity |
Create/update entity with POLE+O type | name, entity_type, description |
memory_add_preference |
Record a user preference | category, preference |
memory_add_fact |
Store a fact triple | subject, predicate, object_value |
| Tool | Description |
|---|---|
memory_get_conversation |
Full conversation history for a session |
memory_list_sessions |
List sessions with previews |
memory_get_entity |
Entity details with graph relationships |
memory_export_graph |
Export subgraph as JSON |
memory_create_relationship |
Create typed entity relationship |
memory_start_trace |
Begin reasoning trace |
memory_record_step |
Record reasoning step |
memory_complete_trace |
Complete reasoning trace |
memory_get_observations |
Session observations and insights |
graph_query |
Execute read-only Cypher queries |
Vertex AI supports these embedding models:
| Model | Dimensions | Best For |
|---|---|---|
text-embedding-004 |
768 | General purpose (recommended) |
textembedding-gecko@003 |
768 | Legacy applications |
textembedding-gecko-multilingual@001 |
768 | Multilingual content |
# Check authentication
gcloud auth application-default print-access-token
# Re-authenticate if needed
gcloud auth application-default login# Test connection
cypher-shell -a bolt://localhost:7687 -u neo4j -p password "RETURN 1"# Check server logs
neo4j-agent-memory mcp serve --transport stdio 2>&1 | tee mcp.log