Add notebook: LangGraph OracleStore with OracleEmbeddings for Oracle-native semantic memory

[Abhinavaggarwal7]

Feature Area

Integration with external tools

Is your feature request related to a an existing bug? Please link it here.

No.

Service Information

Service Name: Oracle AI Database 26ai / Oracle Database

Service Website: https://www.oracle.com/database/

API Documentation / References:

python-oracledb driver: https://python-oracledb.readthedocs.io/
Oracle AI Vector Search User's Guide, 26ai: https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/
LangGraph persistence documentation: https://docs.langchain.com/oss/python/langgraph/persistence
LangGraph stores documentation: https://docs.langchain.com/oss/python/langgraph/stores
langchain-oracledb package: https://pypi.org/project/langchain-oracledb/
langgraph-oracledb package: https://pypi.org/project/langgraph-oracledb/

Use Case

I want to add a notebook-only example to the Oracle AI Developer Hub repo that demonstrates how to use Oracle AI Database 26ai as a LangGraph long-term memory and semantic vector search backend.

Target repo path: notebooks/oracle_langgraph_oraclestore_oracle_embeddings.ipynb

This issue is specifically for adding one new notebook at the target path above. The PR will not add package code, modify existing runtime behavior, or introduce a broader framework integration. The only intended repository change is the new notebook.

The notebook demonstrates how Oracle-native embeddings from langchain-oracledb can be used as the embedding provider for OracleStore from langgraph-oracledb.

The goal is to show LangGraph long-term memory and semantic vector search backed by Oracle AI Database 26ai, without calling an external embedding API.

Oracle Database generates embeddings through OracleEmbeddings, and OracleStore uses those embeddings through index["embed"].

This notebook would help developers learn how to:

1. Connect to Oracle AI Database 26ai.
2. Create OracleEmbeddings using the Oracle Database provider.
3. Pass OracleEmbeddings into OracleStore through index["embed"].
4. Store sample LangGraph memory records by namespace and key.
5. Run semantic search over those records.
6. Compile a minimal LangGraph workflow with store=store.
7. Retrieve the configured Oracle-backed store inside a LangGraph node using get_store().

The notebook also includes copy-friendly setup examples for running Oracle AI Database Free locally with Docker, creating a demo database user, granting the required privileges, configuring an Oracle directory object for ONNX model loading, and setting up local .env variables.

Proposed Install Shape

The notebook installs the required packages with:

python -m pip install "langchain-oracledb>=0.2.0" "langgraph-oracledb>=0.1.0" "langgraph>=0.3.0" "python-dotenv>=1.0.0" "oracledb>=2.0.0"

langchain-oracledb provides OracleEmbeddings, langgraph-oracledb provides OracleStore, langgraph provides graph APIs, python-dotenv reads local environment variables, and oracledb connects to Oracle Database.

For production usage, exact versions should be pinned in a lockfile or managed image.

Verification

• I have searched the existing issues to make sure this notebook has not already been requested.
• I have checked that this service has a public API/driver that can be integrated.

Describe the solution you'd like

Add a new notebook at:

notebooks/oracle_langgraph_oraclestore_oracle_embeddings.ipynb

The notebook title should be:

LangGraph OracleStore with OracleEmbeddings

The notebook should demonstrate an end-to-end LangGraph memory workflow using Oracle AI Database 26ai, OracleEmbeddings, and OracleStore.

The notebook should include the following sections:

1. Notebook overview
2. What you will learn
3. Prerequisites
4. Local Docker setup example for Oracle AI Database Free
5. SQL setup example for creating the demo user and Oracle directory object
6. Dependency installation
7. .env configuration example
8. Oracle connection setup using python-oracledb
9. Checking available ONNX models in USER_MINING_MODELS
10. Optional ONNX model loading using OracleEmbeddings.load_onnx_model
11. Creating OracleEmbeddings with provider="database"
12. Creating OracleStore using index["embed"]
13. Storing sample LangGraph memory records
14. Running semantic search over those records
15. Using OracleStore inside a minimal LangGraph workflow
16. Compiling the graph with store=store
17. Retrieving the configured Oracle-backed store inside a graph node using get_store()
18. Production considerations
19. Troubleshooting guidance
20. Cleanup by closing the database connection

The key behavior demonstrated should be creating a LangChain-compatible Oracle embedding object using the Oracle Database provider:

embedder_params = {
    "provider": "database",
    "model": ORACLE_MODEL_NAME,
}

embedder = OracleEmbeddings(conn=conn, params=embedder_params)

The notebook should then calculate the embedding dimensions from the actual embedding output:

sample_text = "OracleStore can use Oracle-native embeddings for LangGraph memory."
sample_vector = embedder.embed_query(sample_text)
EMBEDDING_DIMS = len(sample_vector)

Then the notebook should pass the embedder into OracleStore using index["embed"]:

index_config = {
    "dims": EMBEDDING_DIMS,
    "embed": embedder,
    "fields": ["text"],
    "index_type": {
        "type": "hnsw",
        "neighbors": 16,
        "efconstruction": 200,
        "distance_metric": "COSINE",
    },
}

store = OracleStore(
    conn,
    index=index_config,
    table_suffix="oraclestore_embeddings_demo",
)

store.setup()

The notebook should also demonstrate storing sample memories by namespace and key, where the configured fields=["text"] causes only the text field of each stored JSON-like value to be embedded for semantic search.

It should include a semantic search example where the query text is embedded using OracleEmbeddings, and OracleStore searches against vectors stored in Oracle AI Database.

Finally, the notebook should demonstrate LangGraph-specific usage by compiling a graph with:

graph = builder.compile(store=store)

and retrieving the configured Oracle-backed store inside a graph node with:

graph_store = get_store()

Describe alternatives you've considered

One alternative is to use an external embedding API and pass those embeddings into a LangGraph store, but the purpose of this notebook is to show a fully Oracle-native embedding path where Oracle AI Database generates the embeddings.

Another alternative is to manually wire together OracleEmbeddings, OracleStore, and LangGraph without a reference notebook, but that makes it harder for developers to understand the required setup steps, including ONNX model availability, vector dimensions, index["embed"], indexed fields, and vector index configuration.

A third alternative is to keep separate examples for Oracle embeddings and LangGraph memory, but that does not clearly demonstrate the end-to-end pattern of Oracle-backed LangGraph long-term memory with semantic search.

Additional context

This request is for a documentation/example notebook addition only.

Target repo path: notebooks/oracle_langgraph_oraclestore_oracle_embeddings.ipynb

This notebook demonstrates Oracle-native LangGraph memory using:

• Oracle AI Database 26ai
• python-oracledb
• OracleEmbeddings from langchain-oracledb
• OracleStore from langgraph-oracledb
• LangGraph StateGraph
• LangGraph get_store()
• Oracle VECTOR search through an HNSW index with cosine distance
• an ONNX embedding model stored in Oracle Database

The notebook is intended as a minimal, practical example rather than a full production application design.

Production considerations covered in the notebook include:

• using a dedicated schema or service account for memory tables
• granting only the privileges required to create and maintain the store objects
• pinning exact package versions in a lockfile or managed image
• using a stable table_suffix per application and environment
• defining retention, deletion, and audit policies before storing user memory
• monitoring table growth, vector index build time, query latency, and failed writes

The notebook also includes troubleshooting guidance for common setup issues, including empty USER_MINING_MODELS, CREATE MINING MODEL privilege errors, Oracle directory or ONNX file errors, vector dimension mismatches, wallet connection errors, and table or index conflicts.

Willingness to Contribute

Yes, I'd be happy to submit a pull request.