Ai Neo4J Store Laravel Package

Technical Evaluation

Architecture fit. Unchanged. This remains a thin adapter — a Neo4j vector-store bridge implementing Symfony AI's vector store contract — whose value is narrow but real: graph-aware retrieval using Neo4j's native semantic indexes, with relationship traversal available in the same query. If retrieval does not need traversal, a cheaper store still wins. v0.14.0 does nothing to change the fit calculus; notably, none of the four changelog entries are Neo4j-specific hardening, schema tooling, or documentation. They are contract-level changes propagated from the parent symfony/ai monorepo.

What v0.14.0 actually delivers.

The material read for a TPM: adding a method to a published interface is a breaking change for implementers, and we are the implementers. Our recommended posture — an internal port with our own adapter over this package — means every contract addition lands in our code. count() is trivial; the pattern is not. This is the first concrete evidence for the churn risk that the prior assessment carried as a projection. It should now be treated as observed behavior, and the exact-version pin and adapter isolation are no longer optional hygiene — they are the control that makes the dependency survivable.

Integration feasibility. Mechanics are unchanged: Composer install, Neo4j PHP client, interface binding. The three non-code gaps from the prior assessment are untouched by this release:

• Schema ownership. Still no DDL or index-creation tooling. Vector index definitions (dimensions, similarity function) remain hand-authored Cypher that must be captured as version-controlled migrations.
• No Laravel-native packaging. Still no service provider, config file, facade, or artisan command. Budget the internal adapter layer regardless.
• No migration or reindex tooling. Backfill and re-embedding remain bespoke. count() helps you observe corpus size — it does not help you migrate it.

Technical risk. Still the dominant section, still unfavorable, and now slightly better evidenced.

Key questions to resolve before committing.

1. Name the user-facing capability that requires graph traversal during retrieval. If it can't be named concretely, this is a deferred evaluation, not a build. (Unchanged — and this release did not add anything that answers it.)
2. Is Neo4j already in the estate, or is this net-new? Net-new materially changes the TCO case.
3. What is the embedding model and dimension count, and who owns the reindex path when that model changes? Dimension changes remain a full rebuild.
4. What is the p95 latency and corpus size ceiling we must hit? This still sets the benchmark gate against pgvector.
5. What is the fallback if the bridge is abandoned or breaks on upgrade — fork, vendor, or swap? Now answer this concretely, since one minor release has already touched the interface.
6. Who on-call owns Neo4j? If the answer is "nobody yet," that is a hire-or-contract line item.
7. (New) Does StoreFactory apply to this bridge at all, and does count() have defined semantics against a filtered query or only the full collection? Get both answers before designing the internal port, or you will guess twice.

Integration Approach

Stack fit and the abstraction decision. The single most leverageable decision is still to not depend on this package directly. Define an internal VectorStore port in the Laravel app, implement one adapter over symfony/ai-neo4j-store, and keep a second adapter over pgvector or the in-memory store. v0.14.0 strengthens the case: the port must now cover count() and normalize VectorDocumentInterface into an internal DTO, so that the next contract change costs one class, not a codebase.

Concretely, the port should be:

add(documents)  query(embedding, filter, topK)  count(filter)  remove(ids)

count() is welcome — it gives you a cheap index-health assertion and a corpus-size metric for capacity planning, and it is a legitimate small win. Do not, however, read it as a sign of stabilization; a contract that grows by one method per minor release is a contract that is still being designed.

Compatibility gates. Before any code: verify PHP 8.2+ and target Laravel version against the package's composer.json; Neo4j 5.12+ for semantic indexes; a pinned Neo4j PHP client major; and driver compatibility with any managed Neo4j tier. Pin the bridge and driver to exact versions in composer.lock and treat patch upgrades as reviewable events. With 0.14 shipped, assume the next minor also moves the interface.

Sequencing.

• Phase 0 — Business case (1 week). Write the three queries that justify graph context. Decision gate: proceed only if similarity search plus an application-side join cannot serve them.
• Phase 1 — Proof of concept (2 weeks). Neo4j in Docker, ~10–50K embeddings. Index DDL as a migration. Internal port + Neo4j adapter behind a feature flag. Benchmark p50/p95 latency and recall against the pgvector adapter on the same corpus. Decision gate: Neo4j wins or the program stops cheap.
• Phase 2 — Thin production slice (3–4 weeks). One bounded feature, one dataset, one read path. Backfill via queued idempotent upserts. Health check that asserts index state via count(), not just connectivity. Rollback documented to the alternate adapter.
• Phase 3 — Generalize. Second use case, reindex runbook, capacity plan, and a fork-or-vendor contingency.

Anti-pattern to avoid. Binding the Symfony interface as a singleton in AppServiceProvider and calling it from controllers. That is the fastest path to Phase 2 and the slowest path out — and as of this release, "out" now means chasing interface additions in every call site.

Operational Impact

Maintenance. Three surfaces, not one: the bridge package (moving, pre-1.0), the Neo4j PHP client (independent cadence), and Neo4j itself. v0.14.0 is a useful calibration point for the estimate: roughly a half-day per quarter of dependency review is adequate only if upgrades are batched and the adapter is genuinely thin. A minor release that adds an interface method and a document abstraction is a multi-hour change, not a zero-hour one. Index DDL and embedding-dimension constants belong in version control alongside schema migrations.

Support. Community-only, routed through the parent symfony/ai repository. No SLA, no security-response commitment specific to this package, no commercial backstop. Treat support as "we are the maintainers of last resort." The code surface remains small enough that forking is credible — that credibility is the mitigation, and it is worth confirming every release that it stays true.

Scaling. Two independent constraints: traversal cost and vector index performance. Neo4j's semantic index is not a specialized vector engine; expect practical ceilings earlier than a dedicated store at equal spend. Plan read replicas and a cache for hot queries rather than assuming vertical scale. Embedding storage grows linearly with corpus and dimension; a model upgrade that increases dimensions remains a full rebuild plus capacity re-plan.

Failure modes to instrument.

Ramp-up. 3–5 days for a mid-level Laravel engineer to become productive with Cypher indexes and the adapter pattern; 2–3 weeks to genuine fluency in Neo4j tuning and query planning. Unchanged. The non-recoverable cost remains organizational: someone must own Neo4j as a production system.

Recommendation. Unchanged in direction, firmer in tone. Fund a two-week Phase 0/1 evaluation only, behind a hard benchmark gate against pgvector and a pre-commitment to the internal port abstraction. v0.14.0 does not warrant escalation — it is not a regression, and count() is a genuine small addition — but it does confirm the dependency's defining trait: it changes to serve the parent framework's contract, on someone else's schedule, with no Neo4j-specific hardening. Do not place this package on a roadmap critical path until it clears 1.0 or gains meaningful dependent adoption. The capability it unlocks is strategically interesting; the artifact is not yet something to build a platform on.