RALPH Spec: Memgraph Tool Adaptation¶
Status: Draft Created: 2026-04-22 Goal: Make all KG tools, ingestion, and querying work natively on Memgraph — no Neo4j fallbacks, no silent failures.
Context¶
The database abstraction layer (RALPH-database-abstraction) is complete. The API connects to Memgraph, sessions create, and basic Cypher queries work. However, the agent toolset still fails at runtime because:
- Vector search tools call
db.index.vector.queryNodes(Neo4j-only) - Fulltext search tools call
db.index.fulltext.queryNodes(Neo4j-only) - KG tools are hardcoded for biology domain (Protein/Disease labels)
- Ingestion pipeline writes embeddings using Neo4j vector index procedures
- Demo instances use plain
memgraph/memgraph(no MAGE modules)
Memgraph MAGE provides vector_search.search() and text_search.search() but requires the memgraph-mage image. The MemgraphSearchIndex implementation exists but isn't wired into the tools.
Chapter 1 — Fix Runtime Tool Failures¶
US-001: Wire SearchIndex into Graph Tools¶
As a user querying a Memgraph database,
I want vector and fulltext search tools to use the SearchIndex abstraction,
So that they work on both Neo4j and Memgraph without errors.
Acceptance Criteria:
- src/tools/graph_tools.py vector_search_entities() uses self.search_index.vector_search() instead of inline CALL db.index.vector.queryNodes
- src/tools/graph_tools.py vector_search_literature() uses self.search_index.vector_search() instead of inline Cypher
- Remove hardcoded db.index.vector.queryNodes and db.index.fulltext.queryNodes from the allowed procedures list
- When SearchIndex raises (e.g. no vector index exists), tools return "No vector index available for this database" instead of crashing
- src/services/query/structural_embedding_engine.py uses SearchIndex for its vector queries
US-002: Graceful Degradation When Indexes Don't Exist¶
As a user querying a demo database without embeddings, I want search tools to return helpful messages instead of stack traces, So that the query still completes using other tools.
Acceptance Criteria:
- MemgraphSearchIndex.vector_search() catches "no such procedure" errors and returns []
- MemgraphSearchIndex.fulltext_search() catches "no such procedure" errors and returns []
- Agent synthesis still runs using results from non-vector tools (count_nodes, lookup_entity, etc.)
- Error messages in tool results say "Vector search not available — using graph traversal" not raw exceptions
US-003: Upgrade Demo Instances to MAGE¶
As a platform operator, I want demo Memgraph instances to include MAGE modules, So that vector search and text search are available for demos with embeddings.
Acceptance Criteria:
- docker-compose.hetzner-dev.yml uses memgraph/memgraph-mage:latest for all demo instances
- Memory limit increased to 384MB per instance (MAGE adds ~100MB overhead)
- vector_search.search() and text_search.search() procedures available on all instances
- Health checks still pass
Chapter 2 — Domain-Agnostic Tools¶
US-004: Make KG Tools Schema-Aware Instead of Hardcoded¶
As a user querying a non-biology database,
I want tools to discover available labels and relationships from the schema,
So that get_disease_proteins doesn't run on a financial database.
Acceptance Criteria:
- src/tools/graph_tools.py constructor queries the database schema on init (get_labels(), get_relationship_types())
- Tools like get_disease_proteins, get_protein_interactions, get_protein_diseases are only registered when Protein/Disease labels exist
- A generic get_related_entities(entity_name, relationship_type) tool is always available
- A generic get_entity_by_label(label, name) tool is always available
- The agent prompt includes the actual schema labels, not hardcoded biology terms
US-005: Dynamic Tool Registration from Domain Config¶
As a platform operator, I want each domain's YAML config to define which tools are available, So that the legal domain gets legal-specific tools and biology gets biology tools.
Acceptance Criteria:
- DomainConfig.sample_queries already exists — add DomainConfig.tools: list[str] field
- When tools is empty, auto-discover from schema (US-004)
- When tools is specified, only register those tools
- config/domains/free.yaml gets generic tools only
- config/domains/biology.yaml gets biology-specific tools + generic tools
US-006: Schema-Aware Agent Prompts¶
As a user, I want the LLM agent to know what's in the current database, So that it generates relevant Cypher and uses appropriate tools.
Acceptance Criteria:
- Agent system prompt includes: available labels, relationship types, sample properties
- Prompt is generated per-session from the connected database's schema
- Agent doesn't hallucinate labels that don't exist in the database
- TwoPhaseAgent and DynamicQueryAgent both use the schema-aware prompt
Chapter 3 — Memgraph-Native Ingestion¶
US-007: Embedding Pipeline for Memgraph¶
As a platform operator, I want to generate and store vector embeddings in Memgraph, So that semantic search works on Memgraph databases.
Acceptance Criteria:
- ingest_main.py --add-graph-embeddings works with DATABASE_TYPE=memgraph
- Embeddings stored as node properties (Memgraph stores lists natively)
- Vector index created via CREATE VECTOR INDEX (Memgraph syntax)
- Uses MemgraphSearchIndex.create_vector_index() which already exists
- Embedding dimensions configurable (default 384 for sentence-transformers)
US-008: Text Index Pipeline for Memgraph¶
As a platform operator, I want fulltext indexes created on Memgraph databases, So that text search tools work.
Acceptance Criteria:
- Text indexes created on name, description, text properties for all entity labels
- Uses MemgraphSearchIndex.create_fulltext_index() which already exists
- Index creation runs as part of the ingestion pipeline post-processing
- text_search.search() returns results after indexing
US-009: Domain-Routed Ingestion¶
As a platform operator, I want ingestion jobs to write to the correct Memgraph instance based on domain, So that biology data goes to demo4 and legal data goes to demo2.
Acceptance Criteria:
- Ingestion API accepts domain_id parameter
- DomainRegistry resolves the connection URI for the target instance
- Ingestion job manager creates the database connection via domain config
- Embeddings and indexes are created on the target instance
Chapter 4 — Query Pipeline Hardening¶
US-010: Fix Cypher Generation for Memgraph Dialect¶
As a user running LLM-generated Cypher on Memgraph, I want generated queries to use Memgraph-compatible syntax, So that queries don't fail on dialect differences.
Acceptance Criteria:
- dynamic_cypher_query tool's Cypher validation strips/rewrites Neo4j-only syntax:
- elementId() → id() (already handled by RALPH US-020)
- datetime() → localdatetime() or parameterized
- SHOW DATABASES → blocked
- Agent prompt tells the LLM to use openCypher (no Neo4j extensions)
- Cypher compatibility test suite (existing tests/compatibility/) validates generated queries
US-011: Connection Pool Per Domain¶
As a platform operator, I want database connections pooled and reused per domain, So that each query doesn't create a new Bolt connection.
Acceptance Criteria:
- TenantRouter connection pool is used by all query paths (agents, tools, ingestion)
- Pool size configurable per domain (default: 5 connections)
- Connections are health-checked and recycled on failure
- Pool is shared across sessions for the same domain
US-012: Tool Timeout and Error Boundaries¶
As a user, I want individual tool calls to timeout gracefully, So that one slow tool doesn't block the entire query.
Acceptance Criteria:
- Each tool call has a 10-second timeout (configurable)
- Timeout returns "Tool timed out after 10s" as the tool result
- Agent continues synthesis with available results
- Memgraph-specific errors (no procedure, no index) caught and returned as tool messages
Dependency Graph¶
US-001 ─→ US-002 ─→ US-003
US-004 ─→ US-005 ─→ US-006
US-007 ─→ US-008 ─→ US-009
US-010 ──────────────────────→ US-012
US-011 ──────────────────────┘
Execution Order¶
| Phase | Stories | Outcome |
|---|---|---|
| 1 — Unblock Queries | US-001, US-002, US-003 | Tools stop crashing on Memgraph |
| 2 — Multi-Domain | US-004, US-005, US-006 | Tools adapt to any database schema |
| 3 — Ingestion | US-007, US-008, US-009 | Full pipeline works on Memgraph |
| 4 — Hardening | US-010, US-011, US-012 | Production-ready query pipeline |