What Graph Storage Backends Are Supported by Semantica? 4 Database Options Explained

Semantica supports four graph storage backends: Neo4j, FalkorDB, Amazon Neptune, and Apache AGE, with Neo4j set as the default. Each backend is implemented as a separate class in semantica/graph_store/ and registered in a unified factory pattern that exposes the same API regardless of the underlying database.

The Semantica AGI framework provides a pluggable graph-store layer that abstracts property-graph databases behind a common interface. When you instantiate GraphStore, the framework consults an internal registry to resolve the backend name to the appropriate implementation class, enabling seamless switching between databases without changing your application logic.

Supported Graph Storage Backends

Semantica's graph storage architecture decouples the high-level API from backend-specific drivers. The following four backends are built-in and production-ready:

Neo4j

Neo4j is the default backend when no explicit configuration is provided. The implementation lives in semantica/graph_store/neo4j_store.py as the Neo4jStore class.

• Connection protocol: Bolt (bolt:// or neo4j://)
• Authentication: Username/password with optional database selection
• Best for: Local development, enterprise deployments, Cypher query compatibility

from semantica.graph_store import GraphStore

neo4j_store = GraphStore(
    backend="neo4j",
    uri="bolt://localhost:7687",
    user="neo4j",
    password="my-secret",
    database="neo4j"
)
neo4j_store.connect()

FalkorDB

FalkorDB (formerly RedisGraph) provides a high-performance, Redis-backed option implemented in semantica/graph_store/falkordb_store.py as FalkorDBStore.

• Connection protocol: Redis protocol over TCP
• Authentication: Optional password authentication
• Best for: In-memory graph analytics, high-throughput scenarios

falkordb_store = GraphStore(
    backend="falkordb",
    host="localhost",
    port=6379,
    password=None,
    graph_name="my_graph"
)
falkordb_store.connect()

Amazon Neptune

Amazon Neptune enables managed cloud deployments via the AmazonNeptuneStore class in semantica/graph_store/amazon_neptune.py.

• Connection protocol: HTTPS with optional IAM authentication
• Authentication: IAM roles or static credentials with regional endpoint resolution
• Best for: AWS-native architectures, serverless scaling, compliance requirements

neptune_store = GraphStore(
    backend="neptune",
    endpoint="my-neptune.cluster.amazonaws.com",
    port=8182,
    region="us-east-1",
    iam_auth=True,
    use_ssl=True
)
neptune_store.connect()

Apache AGE

Apache AGE extends PostgreSQL with graph capabilities, implemented in semantica/graph_store/age_store.py as ApacheAgeStore.

• Connection protocol: PostgreSQL wire protocol
• Authentication: Standard PostgreSQL connection string
• Best for: Existing PostgreSQL infrastructure, hybrid relational/graph workloads

age_store = GraphStore(
    backend="age",
    connection_string="host=localhost dbname=agedb user=postgres password=postgres",
    graph_name="semantica"
)
age_store.connect()

How Backend Selection Works

The framework determines which graph storage backend to use through a cascading configuration hierarchy defined in semantica/graph_store/config.py:

1. Explicit backend parameter passed to GraphStore() (highest priority)
2. GRAPH_STORE_DEFAULT_BACKEND environment variable
3. Configuration file settings
4. Hardcoded default: "neo4j" (lowest priority)

# Default configuration excerpt from semantica/graph_store/config.py

{
    "default_backend": "neo4j",  # Fallback when no other source specifies a backend

    # ... connection-specific parameters for each backend ...

}

The semantica/graph_store/registry.py module maintains a mapping from backend name strings to concrete implementation classes. This registry enables the factory pattern used by GraphStore.__init__() to instantiate the correct driver without explicit imports of backend-specific modules.

Unified API Across All Backends

Despite different connection semantics, every backend exposes identical high-level methods:

• create_node(labels, properties) – Create a node with given labels and properties
• create_relationship(from_id, to_id, rel_type, properties) – Create an edge between nodes
• execute_query(query, parameters) – Run backend-appropriate query language (Cypher or openCypher variants)
• connect() / close() – Lifecycle management

This abstraction lets you prototype locally with Neo4j and deploy production workloads to Neptune without rewriting application code.

Summary

• Four graph storage backends are supported: Neo4j, FalkorDB, Amazon Neptune, and Apache AGE
• Neo4j is the default backend, configurable via GraphStoreConfig or environment variables
• Implementation classes (Neo4jStore, FalkorDBStore, AmazonNeptuneStore, ApacheAgeStore) reside in dedicated modules under semantica/graph_store/
• Backend resolution happens through registry.py, which maps string names to concrete classes
• Unified API means identical method calls work across all backends, with connection details handled internally

Frequently Asked Questions

How do I change the default graph storage backend in Semantica?

Set the GRAPH_STORE_DEFAULT_BACKEND environment variable to your preferred backend name ("neo4j", "falkordb", "neptune", or "age"), or modify the default_backend field in your configuration file. The framework checks these sources in priority order before falling back to "neo4j".

Can I use multiple graph storage backends in the same Semantica application?

Yes. Instantiate separate GraphStore objects with different backend parameters. Each instance maintains its own connection pool and driver state, allowing you to read from one backend and write to another—for example, migrating data from FalkorDB to Neptune.

Does Semantica support custom graph storage backends?

The registry pattern in semantica/graph_store/registry.py is designed for extensibility. You can register new backend classes by importing the registry and calling register_backend(name, implementation_class), provided your class implements the expected interface methods.

Which graph storage backend performs best for large-scale graphs?

Amazon Neptune provides the most scalable managed option with automatic read replicas and serverless configurations. For self-hosted deployments, FalkorDB offers excellent single-node performance through Redis's in-memory architecture, while Neo4j provides the most mature clustering and enterprise tooling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}