FalkorDB
A RocketRide tool node that exposes a FalkorDB graph database to an AI agent.
Experimental. This node is marked experimental and its surface may change.
What it does
Lets an agent query a FalkorDB graph database with Cypher. The agent can run queries, list the graphs on the server, and inspect a graph's schema (labels, relationship types, and property keys) to discover the data model before querying.
Queries are read-only by default: they run through GRAPH.RO_QUERY, so the FalkorDB server
itself rejects any write clause (CREATE/MERGE/SET/DELETE), the restriction is enforced
server-side, not by client-side parsing. Turn on Allow Writes to let the agent mutate the
graph.
Values always travel as Cypher parameters ($name), which FalkorDB treats strictly as data and
never as query text. Node, edge, and path results are serialized to plain JSON-safe objects, and
result sets are capped at Max Rows with a truncated flag so a broad query cannot flood the
agent's context.
Configuration
| Field | Type | Description |
|---|---|---|
host | string | Default localhost. FalkorDB host, e.g. localhost or your-instance.falkordb.cloud. |
port | integer | Default 6379 (1–65535). FalkorDB port (Redis protocol). |
username | string | Default empty. Username, e.g. default for FalkorDB Cloud. Leave empty for no auth. |
password | string | Default empty. Password for the FalkorDB instance. Leave empty for no auth. |
tls | boolean | Default false. Connect with TLS (for FalkorDB Cloud TLS endpoints). |
graph | string | Default agent. Graph queried when the agent does not pass one explicitly. |
allow_writes | boolean | Default false. Permit CREATE/MERGE/SET/DELETE. When off, queries run via GRAPH.RO_QUERY and the server rejects write clauses. |
max_rows | integer | Default 250 (1–25000). Upper cap on rows returned to the agent per query. |
query_timeout_ms | integer | Default 30000 (100–600000). Server-side timeout for a single query. |
Available tools
| Tool | Description |
|---|---|
query | Run a Cypher query against a graph and return rows. |
list_graphs | List the graph names that exist on this FalkorDB instance. |
get_schema | Return a graph's node labels, relationship types, and property keys. |
query
| Parameter | Required | Description |
|---|---|---|
cypher | yes | Cypher query. Reference values as $name placeholders, never inline data into the query string. |
params | no | Object of values for the $name placeholders (injection-safe). |
graph | no | Graph to query. Defaults to the graph configured on the node. |
Returns columns, rows (nodes/edges serialized to objects, capped at max_rows),
row_count, and truncated. When writes are enabled and a query mutates the graph, non-zero
write counters are returned under stats. On failure it returns error with empty
rows/columns, row_count: 0, and truncated: false.
list_graphs
No parameters. Returns graphs (or error on failure).
get_schema
| Parameter | Required | Description |
|---|---|---|
graph | no | Graph to inspect. Defaults to the graph configured on the node. |
Returns labels, relationship_types, and property_keys (or error on failure). Useful when
a query returns unexpected results or the agent needs to discover the data model.
Read-only by default
With allow_writes off (the default), query runs every statement through GRAPH.RO_QUERY.
FalkorDB rejects write clauses at the server, so the agent cannot create, merge, set, or delete
no matter what Cypher it sends. Set allow_writes: true to switch query to the read/write
GRAPH.QUERY path; write counters then surface under stats. get_schema always uses the
read-only path.
Local quickstart
docker run -p 6379:6379 -it --rm falkordb/falkordb:latest
Point the node at localhost:6379 and ask the agent to MATCH away, or to CREATE with
Allow Writes turned on.
Running the tests
# Unit tests (mocked FalkorDB client — no server or network needed)
pytest nodes/test/test_tool_falkordb.py -v
Schema
| Field | Type | Description | Default |
|---|---|---|---|
tool_falkordb.allow_writes | boolean | Allow Writes Permit CREATE/MERGE/SET/DELETE. When off, queries run via GRAPH.RO_QUERY and the server rejects write clauses. | false |
tool_falkordb.graph | string | Default Graph Graph queried when the agent does not pass one explicitly. | "agent" |
tool_falkordb.host | string | Host FalkorDB host, e.g. localhost or your-instance.falkordb.cloud. | "localhost" |
tool_falkordb.max_rows | integer | Max Rows Upper cap on rows returned to the agent per query. | 250 |
tool_falkordb.password | string | Password Password for the FalkorDB instance. Leave empty for no auth. | "" |
tool_falkordb.port | integer | Port FalkorDB port (Redis protocol). | 6379 |
tool_falkordb.query_timeout_ms | integer | Query Timeout (ms) Server-side timeout for a single query. | 30000 |
tool_falkordb.tls | boolean | TLS Connect with TLS (FalkorDB Cloud TLS endpoints). | false |
tool_falkordb.username | string | Username Username, e.g. "default" for FalkorDB Cloud. Leave empty for no auth. | "" |
Dependencies
falkordb>=1.6,<2redis>=7.1,<8