A completed simulation left me with a report and an ownership problem. MiroFish had built the graph, generated the agents, and run their interactions, but the useful memory still lived behind somebody else's service boundary. The gateway could display the final answer. It couldn't reliably ask its own questions of the evidence that produced it.
That distinction mattered because running a swarm covered only half the requirement. The gateway also had to retain graph entities, agent episodes, profiles, reports, and predictions under the same tenant contract as the rest of the service. A provider-controlled memory layer made every later query depend on that provider's availability, billing model, and isolation semantics. The project estimate put Zep consumption at 30,000 to 40,000 credits per simulation. Daily runs would turn memory retrieval into a recurring external dependency before the gateway had served its first reader.
I moved gateway-owned memory into PostgreSQL 16 with pgvector. I did not pretend this removed Zep from MiroFish. The upstream checkout still uses its configured graph provider while it constructs a graph. The boundary is narrower and more defensible: once MiroFish returns graph data and action logs, the gateway owns the persisted copy and every read against it.
The wrong boundary would have copied the upstream system
Replacing an external memory service sounds like a database migration. That framing invites a bad design: reproduce the provider's graph product inside the gateway, then maintain a second graph engine beside MiroFish.
I needed much less than that. The gateway has three read patterns. It retrieves entities by type, walks a bounded neighborhood, and searches agent episodes by meaning. PostgreSQL already holds tenant, scenario, simulation, report, and prediction records. Adding graph nodes, graph edges, and episodes kept the ownership boundary in one transactional store. pgvector covered the semantic query without introducing another network call.
This choice also made the tenant rule visible. Every memory query accepts tenantId as an argument. It isn't recovered from a global context and it isn't optional. The graph tables carry tenant_id and simulation_id, while unique constraints stop the same upstream entity or episode from being inserted twice for one simulation. A node can have the same upstream identifier in two tenants without either tenant seeing the other record.
The relevant comparison put one owned store against another service boundary with separate credentials, failure modes, and billing. PostgreSQL won because the required traversals were bounded and the semantic search was local. If the product later needs arbitrary path analysis across millions of graph edges, that decision deserves another review. The launch scope did not need that machinery.
One schema, two kinds of memory
Graph entities and agent episodes look similar because both can carry embeddings. They have different jobs.
graph_nodes stores named entities mirrored from the MiroFish graph. The default embedding text combines the entity type and name, which gives short labels enough context to be searchable. graph_edges stores typed relationships and their source and target identifiers. agent_episodes holds the actions produced during simulation rounds, including the agent, action type, content, metadata, and a vector derived from the content.
I kept the embedding width at 384 dimensions because the local Xenova/all-MiniLM-L6-v2 model emits exactly that shape. The model runs in process through @xenova/transformers, uses mean pooling, and normalizes the output. The database columns are vector(384), so a model swap that changes dimensions is a schema decision, not a package update hidden in an application release.
That coupling is deliberate. Silent dimensional mismatch is worse than an explicit migration. The table definition, embedding constant, and tests all name 384. A future model can be better on paper and still be the wrong choice if it forces an unplanned rewrite of every stored vector.
The embedding extractor is initialized lazily and shared through one promise. That avoids loading the ONNX model for requests that never touch semantic search and prevents concurrent callers from starting duplicate model loads. The trade-off is cold-start latency on the first embedding request. I accepted it because this gateway runs long simulations, not millisecond search ads. If search becomes an interactive first-screen feature, I would pre-warm the model during service startup and expose its readiness separately.
The query carries the security contract
Here is the actual semantic retrieval function. The important part isn't the cosine operator. It is the set of boundaries around it.
export async function searchEpisodes(
tenantId: string,
simulationId: string,
agentId: number | null,
query: string,
topK = 10,
): Promise<EpisodeSearchResult[]> {
const queryEmbedding = await generateEmbedding(query);
const vectorLiteral = `[${queryEmbedding.join(',')}]`;
const agentFilter =
agentId !== null ? sql`AND agent_id = ${agentId}` : sql``;
const safeTopK = Math.max(1, Math.min(100, Math.floor(topK)));
const result = await db.execute(sql`
SELECT id, tenant_id, simulation_id, agent_id, content,
embedding <=> ${vectorLiteral}::vector AS distance
FROM agent_episodes
WHERE tenant_id = ${tenantId}::uuid
AND simulation_id = ${simulationId}::uuid
${agentFilter}
ORDER BY distance ASC
LIMIT ${safeTopK}
`);
const rows = Array.isArray(result)
? result
: ((result as { rows?: unknown[] }).rows ?? []);
return (rows as Record<string, unknown>[]).map(rawRowToEpisodeResult);
}
The excerpt shortens the selected columns for readability, but the function and query are the ones the service executes. tenantId and simulationId are both predicates. An optional agent filter narrows the search without weakening either ownership condition. topK is clamped between 1 and 100 before it reaches SQL.
That cap is not search tuning. It is resource control. A caller cannot turn semantic retrieval into an unbounded result set, and the API doesn't need to trust every upstream parameter. The graph-neighbor query follows the same idea by clamping traversal depth between 1 and 20.
Cosine distance is converted into a similarity score by the row mapper. Keeping that conversion outside the query lets the SQL remain about ordering while the application returns a domain value. It also gives tests a single place to catch vector strings, numeric arrays, and database-driver result shapes.
I trusted mocked persistence for too long
The first graph-store tests mocked the database. They verified query construction and method behavior, which was useful while the schema was moving. They could not prove that PostgreSQL had the vector extension, that Drizzle's custom type crossed the driver boundary correctly, or that pgvector returned the expected ranking.
That was the wrong confidence level for code whose main claim was ownership of persistence.
The project rules say not to mock infrastructure we own. The progress record called out the gap directly: real pgvector integration had been deferred. I added integration coverage against Dockerized PostgreSQL and pgvector. Those tests insert real 384-value vectors, execute the store functions, verify tenant-scoped node reads, check edge traversal, and assert semantic ranking against the database operator.
What surprised me was how much of the risk sat below TypeScript. A perfectly typed number[] says nothing about whether a migration enabled the extension or whether a raw result comes back in the shape the mapper expects. The integration test catches a class of failure that a mock is structurally unable to represent.
There is still a smaller unit-test layer around deterministic behavior, including embedding generation and safe limits. I kept it because model loading is slower than testing a clamp or a mapper. The split test strategy creates two kinds of evidence: fast tests give narrow feedback, while the PostgreSQL suite carries the persistence claim. Treating either one as the whole answer would hide risk.
Mirroring is not pretending to be the source
After graph construction, storeMirofishGraph writes valid nodes before edges. Episodes arrive later from action logs. The gateway uses conflict handling to make repeated writes safe for the same simulation. That matters because orchestration can retry after a network failure even when the upstream operation actually completed.
The mirror is repairable rather than atomic. Nodes are written in parallel, then edges are written in parallel. There is no transaction around the complete graph import. A database failure can leave some nodes present and no corresponding edges.
I accepted that because the upstream graph remains available for the duration of orchestration and every local identity has a conflict key. Retrying the import updates existing nodes and fills missing records instead of multiplying them. A transaction across the full graph would give a cleaner all-or-nothing result, but it would also hold locks while embedding generation and many inserts complete. The current graph is small enough for replay to be the simpler recovery tool.
That decision needs a boundary. The gateway does not mark the local memory phase complete until graph fetch and storage return. A partial mirror from a failed run is diagnostic residue, not a successful retrieval store. At larger volumes, I would stage imported rows under an attempt ID and promote the set after validation. Readers could then ignore incomplete attempts without requiring one long transaction.
I deliberately call this a mirror. MiroFish remains the source of graph-construction output for that run. PostgreSQL becomes the source for gateway reads after ingestion. If graph import fails halfway through, the run should not be described as having durable local memory. If profile or action-log enrichment fails after the simulation itself succeeds, the orchestrator records a warning and continues toward the report. Those two failures have different business meaning, so they do not share one blanket retry policy.
The design also leaves one obvious limitation. storeMirofishGraph uses parallel writes for nodes and then edges. That is appropriate for the small verified graph, which contained 12 nodes and 12 edges. At much larger graph sizes, I would replace per-record writes with staged bulk inserts and measure index cost during ingestion. I would not add that machinery before the data proves it is needed.
The result is not a home-grown replacement for every feature in Zep. It is an owned retrieval contract. A tenant's simulation memory sits beside its scenario and predictions. Semantic search stays inside the gateway's database boundary. Upstream graph construction can change without taking gateway reads with it, provided the returned graph and action-log contracts remain valid.
That is the line I wanted: borrow computation where it saves time, own the memory that gives the computation lasting value.
