Download the PHP package builtbyberry/laravel-swarm-memory-vector without Composer

Laravel Swarm Memory Vector

Vector-backed semantic recall for Laravel Swarm memory. This companion package implements the core MemoryStore contract, transparently embedding every memory write and letting agents recall memory by meaning — "what did we learn about the rocket?" — instead of by exact key. Semantic search runs natively on PostgreSQL with pgvector, with a portable fallback that works on any database.

Semantic search is a ranking layer, never a leak. The vector reader only ever ranks the exact set of entries the active swarm's propagation policy already permits an agent to see. A vector hit can never surface memory that the standard recall tool would withhold.

Requirements

• PHP 8.4+
• builtbyberry/laravel-swarm ^0.27 || ^0.28
• laravel/ai ^1.0 (for embeddings)
• For the native pgvector driver: a PostgreSQL connection with the vector extension available

Version 0.2.0 adopts Laravel AI 1.x and core 0.27. Applications on older core/AI lines must stay on a compatible 0.1.x companion release until they upgrade both. See UPGRADING.md. The embedding API remains text-only. Version 0.3.0 additionally admits core ^0.28 (native Laravel AI feature access) on the same AI 1.x line, with no dependency break.

The v0.2.0 compatibility work was validated against the exact core 0.27 candidate with minimum/current official AI 1.x on PHP 8.4/8.5 scan and PHP 8.4 real PostgreSQL/pgvector; v0.3.0 adds the same minimum/current scan and pgvector lanes against the frozen core 0.28 candidate 269f749. Candidate checks used temporary CI metadata and are historical prepublication evidence. A fresh Packagist-only consumer installation remains a separate shipping gate. See the compatibility evidence.

Installation

Publish the config and run the migration:

The migration creates a swarm_memory_vectors table. On PostgreSQL it enables the vector extension and creates a native vector(N) column with an HNSW cosine index; on any other database it stores embeddings as JSON for the portable scan driver.

Configure an embedding provider

Embeddings are generated through Laravel AI. Point it at your embedding provider of choice — for example Voyage AI:

SWARM_MEMORY_VECTOR_DIMENSIONS must match the vector width your provider/model returns — it fixes the width of the vector(N) column. Voyage's voyage-4 returns 1024; OpenAI's text-embedding-3-small returns 1536. A mismatch fails loudly rather than corrupting the index.

Laravel AI's HTTP-backed providers do not require an additional provider SDK. Bedrock requires the optional aws/aws-sdk-php package; selecting Bedrock without it gives installation guidance. Follow the installed Laravel AI package's optional-dependency constraints and use a supported, security-patched SDK release. This companion does not require AWS SDK or Laravel MCP. Native HTTP-wire tests cover OpenAI and Voyage; they do not establish AWS transport compatibility.

How it works

Once installed, the package rebinds the Swarm MemoryStore to a decorator around the core database store:

• Writes still land in swarm_memories exactly as before — same rows, timestamps, lifecycle events, and run_id cascade. Alongside each string-valued write, the decorator generates an embedding and upserts it into swarm_memory_vectors. The memory row and its embedding commit in a single transaction; the embedding provider call happens before the transaction opens, so a slow network round-trip never holds a database transaction open.
• Redaction stays outermost. The core RedactingMemoryStore wraps this store, so the text that gets embedded is the same capture-policy-redacted text that gets persisted — never a pre-redaction value.
• Reads are unchanged. Exact-key recall, propagation, and replay all behave identically; the embedding is purely additive.

Non-string values (arrays, numbers, booleans) are persisted normally but not embedded — they remain fully available through the exact-key recall tool.

Semantic recall in an agent

Scaffold a vector-aware memory tool with the core generator (it detects this companion via Composer):

Wire the generated tool's semanticRecall() to this package's reader:

Drop the tool into any laravel/ai agent's tools() array. When the model calls it with a free-text query, it gets back the most semantically similar memory entries, formatted exactly like the core recall tool (key: value, one per line). The scope id is resolved from the active run — never accepted from the model.

Configuration

All keys live in config/swarm-memory-vector.php:

Drivers

• pgvector — native vector(N) column ranked with PostgreSQL's <=> cosine-distance operator over an HNSW index. The headline path; scales to large memory.
• scan — stores embeddings as JSON and ranks with an in-PHP cosine similarity. Works on sqlite and mysql. Because ranking is always scoped to the small, already-authorized candidate set, the scan stays cheap.

Testing

The suite runs against sqlite (scan driver) locally and additionally against a real pgvector-enabled PostgreSQL in CI.

License

MIT © Daniel Berry / Built by Berry