feat: Add Oracle AI Vector Database Integration

[Elif Sema Balcioglu (fileames)]

Adds Oracle AI Database persistence support for LangGraph.js through the new @langchain/langgraph-checkpoint-oracledb package.

• Adds OracleCheckpointSaver for durable graph checkpoints, pending writes, checkpoint listing, child namespaces, and
  thread deletion.
• Adds OracleStore for long-term memory, filtering, batched operations, and namespace management.
• Supports optional Oracle VECTOR-powered semantic search with explicitly managed vector indexes.
• Supports direct connections, existing pools, configurable table prefixes, automatic table setup, and cleanup APIs.

The code for this PR was primarily developed by Devansh Dhok (@Devx228) during his internship at Oracle.

[changeset-bot]

🦋 Changeset detected

Latest commit: a06d0a3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@langchain/langgraph-checkpoint-oracledb	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​types/​oracledb@​6.10.4
	npm/​@​msgpack/​msgpack@​3.1.3
	npm/​oracledb@​6.10.0

View full report

[pkg-pr-new]

Open in StackBlitz

@langchain/langgraph-checkpoint

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint@2660

@langchain/langgraph-checkpoint-mongodb

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-mongodb@2660

@langchain/langgraph-checkpoint-oracledb

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-oracledb@2660

@langchain/langgraph-checkpoint-postgres

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-postgres@2660

@langchain/langgraph-checkpoint-redis

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-redis@2660

@langchain/langgraph-checkpoint-sqlite

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-sqlite@2660

@langchain/langgraph-checkpoint-validation

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-validation@2660

create-langgraph

npm i https://pkg.pr.new/langchain-ai/langgraphjs/create-langgraph@2660

@langchain/langgraph-api

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-api@2660

@langchain/langgraph-cli

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-cli@2660

@langchain/langgraph

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph@2660

@langchain/langgraph-cua

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-cua@2660

@langchain/langgraph-supervisor

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-supervisor@2660

@langchain/langgraph-swarm

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-swarm@2660

@langchain/langgraph-ui

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-ui@2660

@langchain/langgraph-sdk

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-sdk@2660

@langchain/angular

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/angular@2660

@langchain/react

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/react@2660

@langchain/svelte

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/svelte@2660

@langchain/vue

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/vue@2660

commit: a06d0a3

[Fede Kamelhar (fede-kamel)]

Reviewed the full package and ran it end-to-end against an Oracle Database 23ai (Free, container) instance. LGTM — the core is solid (I don't have approve rights on this repo, so leaving this as a comment review). What I verified:

• Build clean (attw + publint), unit suite 132/132.
• Full integration suite: 817 passed / 1 intentional skip against a real database. One runbook note: on a small container (default processes=200) the int files must run serialized (vitest run --mode int --no-file-parallelism); run in parallel they exhaust DB processes and cascade-fail with NJS-511/ORA-12516.
• Cross-language compatibility verified live against the Python langgraph-oracledb package, both directions: checkpoints (msgpack bytes channel values, >1 MiB values routed to CHECKPOINT_BLOBS, nested metadata filters, pending writes incl. __error__), and the store — an identical index config derived the same table suffix from both languages, and each side vector-searched the other's embeddings with identical scores.
• A real StateGraph compiled with OracleCheckpointSaver resumes state across invocations, with full checkpoint history.
• Injection review: every interpolated identifier is validated, values are bound, JSON-path literals are escaped — I could not construct an injection through filter keys or index config values.

Inline comments below each include a reproduction. Two repo-level items without a good diff anchor:

1. No LICENSE file — the package ships only LICENSE-3rd-party.txt; every sibling lib includes the MIT text and package.json declares MIT.
2. Stale lockfile importer entry — pnpm-lock.yaml records @langchain/core (specifier ^1.2.1) under this package's dependencies, but package.json declares it only as a peerDependency (^1.1.44). Looks generated from an earlier package.json revision; worth regenerating the lockfile. (It does not break pnpm install --frozen-lockfile on pnpm 9.15.9 — verified.)

Nice work overall — the byte-compatible pythonJsonDumps suffix hashing and the ORA-00001 retry paths are particularly carefully done.

[Fede Kamelhar (fede-kamel)]

Stale limitation: the package supports all three metrics. ORACLE_VECTOR_DISTANCE_METRICS is ["COSINE", "EUCLIDEAN", "DOT"], constructor validation accepts EUCLIDEAN/DOT (verified), and both the generated CREATE VECTOR INDEX ... DISTANCE <metric> and the VECTOR_DISTANCE(..., <metric>) search path honor them. Nothing rejects a shared Python store configured with a non-COSINE metric — assertStoredIndexConfigMatches only requires both sides to agree.

[Elif Sema Balcioglu (fileames)]

Looks like README was stale after the latest changes, did the update.

[Fede Kamelhar (fede-kamel)]

major on a package whose package.json is already at 1.0.0 means the first npm publish will be 2.0.0 (changeset status confirms the pending major bump). Other new packages in this repo started lower (sdk-angular at 0.1.0 via a minor changeset, checkpoint-redis at 0.0.x). Consider setting version to 0.0.0 and keeping this major changeset (first publish becomes 1.0.0), or downgrading the bump.

[Elif Sema Balcioglu (fileames)]

Done

[Fede Kamelhar (fede-kamel)]

Array filter semantics diverge from the Python package this integration shares tables with. This compiles arrays to order-insensitive per-element containment, while Python's _build_metadata_predicates uses exact positional JSON_EQUAL (and its comments say so). Reproduced against the same checkpoint row (metadata {"tags": ["a", "b"]}) on 23ai:

list(filter=...)	Python	JS
{tags: ["a", "b"]}	1	1
{tags: ["b", "a"]}	0	1
{tags: ["a"]}	0	1

JS matches checkpoint-postgres's @> containment semantics, so Python is arguably the outlier — but each implementation's comments currently claim to match the other. Suggest documenting the divergence in the README's cross-language section (and possibly filing an alignment issue on the Python side).

[Fede Kamelhar (fede-kamel)]

Follow-up: the Python side is being aligned to this (containment) semantics rather than documenting the divergence — filed as oracle/langchain-oracle#296 with the repro table above, fix in oracle/langchain-oracle#293. With that change both packages return identical rows for list filters on shared tables (verified live with a seven-case typed-element matrix: dict containment/miss, null, true/false discrimination, numbers, nested arrays). So no README caveat needed here once that lands — this branch's containment behavior becomes the cross-language contract, and the Python comment claiming "lists keep exact-match semantics ... matching the JS saver" gets corrected in the same PR.

[Elif Sema Balcioglu (fileames)]

Thanks Fede Kamelhar (@fede-kamel) for the detailed review :) I did the changes requested. Hopefully all looks good now.